Ram Gandikota / Mbed OS metronome

FRDM K64F Metronome

mbed-client/docs/Introduction.md@0:a2cb7295a1f7, 2017-05-14 (annotated)

Committer:
ram54288
Date:
Sun May 14 18:35:07 2017 +0000
Revision:
0:a2cb7295a1f7
Initial commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
ram54288 0:a2cb7295a1f7 1 # ARM mbed Client overview
ram54288 0:a2cb7295a1f7 2
ram54288 0:a2cb7295a1f7 3 ARM mbed Client is a library that provides the means to connect constrained embedded devices to mbed Device Connector Service, mbed Device Server and to mbed-enabled cloud services from our partners.
ram54288 0:a2cb7295a1f7 4
ram54288 0:a2cb7295a1f7 5 The mbed Client high-level APIs allow mbed OS developers to create applications with LWM2M features as described in the [Lightweight Machine to Machine Technical Specification](http://technical.openmobilealliance.org/Technical/technical-information/release-program/current-releases/oma-lightweightm2m-v1-0):
ram54288 0:a2cb7295a1f7 6
ram54288 0:a2cb7295a1f7 7 - Manage devices on mbed Device Server.
ram54288 0:a2cb7295a1f7 8 - Securely communicate with internet services over the industry standard TLS/DTLS.
ram54288 0:a2cb7295a1f7 9 - Fully control the endpoint and application logic.
ram54288 0:a2cb7295a1f7 10
ram54288 0:a2cb7295a1f7 11 The API is written in C++ to allow quick application development.
ram54288 0:a2cb7295a1f7 12
ram54288 0:a2cb7295a1f7 13 ## Managing devices on mbed Device Server
ram54288 0:a2cb7295a1f7 14
ram54288 0:a2cb7295a1f7 15 mbed Client supports the following three features introduced in the subsequent chapters:
ram54288 0:a2cb7295a1f7 16
ram54288 0:a2cb7295a1f7 17 - [Client Registration and Deregistration](client_reg_dereg.md)
ram54288 0:a2cb7295a1f7 18 - [Device Management and Service Enablement](dev_man_serv_enable.md)
ram54288 0:a2cb7295a1f7 19 - [Information Reporting](info_reporting.md)
ram54288 0:a2cb7295a1f7 20
ram54288 0:a2cb7295a1f7 21 The API also provides an interface to define the application endpoint information. This information will be delivered to mbed Device Server during the registration operation.
ram54288 0:a2cb7295a1f7 22
ram54288 0:a2cb7295a1f7 23 First, you need to create an interface for mbed Client:
ram54288 0:a2cb7295a1f7 24
ram54288 0:a2cb7295a1f7 25 ```
ram54288 0:a2cb7295a1f7 26 #include "mbed-client/m2minterfacefactory.h"
ram54288 0:a2cb7295a1f7 27 #include "mbed-client/m2minterface.h"
ram54288 0:a2cb7295a1f7 28
ram54288 0:a2cb7295a1f7 29 M2MInterface* interface = M2MInterfaceFactory::create_interface(*this,
ram54288 0:a2cb7295a1f7 30 "mbed-endpoint",
ram54288 0:a2cb7295a1f7 31 "test",
ram54288 0:a2cb7295a1f7 32 3600,
ram54288 0:a2cb7295a1f7 33 5684,
ram54288 0:a2cb7295a1f7 34 "",
ram54288 0:a2cb7295a1f7 35 M2MInterface::UDP,
ram54288 0:a2cb7295a1f7 36 M2MInterface::LwIP_IPv4,
ram54288 0:a2cb7295a1f7 37 "");
ram54288 0:a2cb7295a1f7 38 ```
ram54288 0:a2cb7295a1f7 39
ram54288 0:a2cb7295a1f7 40 ### Setting up own random number generator function
ram54288 0:a2cb7295a1f7 41
ram54288 0:a2cb7295a1f7 42 To provide a stronger security mechanism, mbed Client requires a random number generator to feed a random number into the underlying SSL library. There is a default PRNG seeded with RTC for security but some platforms do not have RTC, and for some, time value seeded PRNG is not secure enough.
ram54288 0:a2cb7295a1f7 43
ram54288 0:a2cb7295a1f7 44 Now, an application can pass its own RNG implementation to mbed Client as function pointer callback through an API, `set_random_number_callback(random_number_cb callback)`.
ram54288 0:a2cb7295a1f7 45
ram54288 0:a2cb7295a1f7 46 Here is an example on how you can use it from an application:
ram54288 0:a2cb7295a1f7 47
ram54288 0:a2cb7295a1f7 48 ```
ram54288 0:a2cb7295a1f7 49 #include "mbed-client/m2minterfacefactory.h"
ram54288 0:a2cb7295a1f7 50 #include "mbed-client/m2minterface.h"
ram54288 0:a2cb7295a1f7 51
ram54288 0:a2cb7295a1f7 52 uint32_t get_random_number(void)
ram54288 0:a2cb7295a1f7 53 {
ram54288 0:a2cb7295a1f7 54 uint32_t i = 0;
ram54288 0:a2cb7295a1f7 55 printf("\Your application's RNG logic\n");
ram54288 0:a2cb7295a1f7 56 return i;
ram54288 0:a2cb7295a1f7 57 }
ram54288 0:a2cb7295a1f7 58
ram54288 0:a2cb7295a1f7 59 _interface->set_random_number_callback(&get_random_number);
ram54288 0:a2cb7295a1f7 60
ram54288 0:a2cb7295a1f7 61 ```
ram54288 0:a2cb7295a1f7 62
ram54288 0:a2cb7295a1f7 63 ### Setting up own entropy function for additional secure connectivity
ram54288 0:a2cb7295a1f7 64
ram54288 0:a2cb7295a1f7 65 mbed Client provides an API to add your own entropy source into the underlying SSL library. There is a default entropy source provided by mbed Client. It uses PRNG seeded with RTC for the security but some platforms do not have RTC, and for some, this level of security may not be strong enough.
ram54288 0:a2cb7295a1f7 66
ram54288 0:a2cb7295a1f7 67 Now, an application can pass its own entropy source to mbed Client as function pointer callback through an API `set_entropy_callback(entropy_cb callback)`.
ram54288 0:a2cb7295a1f7 68
ram54288 0:a2cb7295a1f7 69 Here is an example on how you can use it from an application:
ram54288 0:a2cb7295a1f7 70
ram54288 0:a2cb7295a1f7 71 ```
ram54288 0:a2cb7295a1f7 72 #include "mbed-client/m2minterfacefactory.h"
ram54288 0:a2cb7295a1f7 73 #include "mbed-client/m2minterface.h"
ram54288 0:a2cb7295a1f7 74
ram54288 0:a2cb7295a1f7 75 entropy_cb ent_cb;
ram54288 0:a2cb7295a1f7 76
ram54288 0:a2cb7295a1f7 77 int ent_poll( void *, unsigned char *output, size_t len,
ram54288 0:a2cb7295a1f7 78 size_t *olen )
ram54288 0:a2cb7295a1f7 79 {
ram54288 0:a2cb7295a1f7 80 for(uint16_t i=0; i < len; i++){
ram54288 0:a2cb7295a1f7 81 srand(time(NULL));
ram54288 0:a2cb7295a1f7 82 output[i] = rand() % 256;
ram54288 0:a2cb7295a1f7 83 }
ram54288 0:a2cb7295a1f7 84 *olen = len;
ram54288 0:a2cb7295a1f7 85
ram54288 0:a2cb7295a1f7 86 return( 0 );
ram54288 0:a2cb7295a1f7 87 }
ram54288 0:a2cb7295a1f7 88
ram54288 0:a2cb7295a1f7 89 ent_cb.entropy_source_ptr = ent_poll;
ram54288 0:a2cb7295a1f7 90 ent_cb.p_source = NULL;
ram54288 0:a2cb7295a1f7 91 ent_cb.threshold = 128;
ram54288 0:a2cb7295a1f7 92 ent_cb.strong = 0;
ram54288 0:a2cb7295a1f7 93
ram54288 0:a2cb7295a1f7 94 _interface->set_entropy_callback(ent_cb);
ram54288 0:a2cb7295a1f7 95
ram54288 0:a2cb7295a1f7 96 ```
ram54288 0:a2cb7295a1f7 97
ram54288 0:a2cb7295a1f7 98 ### Maximum UDP message size
ram54288 0:a2cb7295a1f7 99
ram54288 0:a2cb7295a1f7 100 The maximum single UDP message size that mbed Client can receive is 1152 bytes. The actual payload size is 1137 bytes, the header information using the remaining 15 bytes.
ram54288 0:a2cb7295a1f7 101
ram54288 0:a2cb7295a1f7 102 For transferring larger amounts of data, the Blockwise feature must be deployed. When using this feature, mbed Client can handle messages up to 65KB by default. This feature is disabled by default. To receive more than 65KB, see [Setting an external handler for block-wise messages](Howto.md#setting-an-external-handler-for-block-wise-messages).
ram54288 0:a2cb7295a1f7 103
ram54288 0:a2cb7295a1f7 104 To enable the Blockwise feature in mbed OS, create a `mbed_app.json` file in the application level and overwrite Blockwise value as described below:
ram54288 0:a2cb7295a1f7 105
ram54288 0:a2cb7295a1f7 106 *Example:*
ram54288 0:a2cb7295a1f7 107 ```
ram54288 0:a2cb7295a1f7 108 "target_overrides": {
ram54288 0:a2cb7295a1f7 109 "*": {
ram54288 0:a2cb7295a1f7 110 "mbed-client.sn-coap-max-blockwise-payload-size": 1024
ram54288 0:a2cb7295a1f7 111 }
ram54288 0:a2cb7295a1f7 112
ram54288 0:a2cb7295a1f7 113 ```
ram54288 0:a2cb7295a1f7 114
ram54288 0:a2cb7295a1f7 115 To enable the Blockwise feature in yotta based builds, you need to create a `config.json` file in the application level.
ram54288 0:a2cb7295a1f7 116
ram54288 0:a2cb7295a1f7 117 *Example:*
ram54288 0:a2cb7295a1f7 118 ```
ram54288 0:a2cb7295a1f7 119 {
ram54288 0:a2cb7295a1f7 120 "coap_max_blockwise_payload_size": 1024
ram54288 0:a2cb7295a1f7 121 }
ram54288 0:a2cb7295a1f7 122 ```
ram54288 0:a2cb7295a1f7 123
ram54288 0:a2cb7295a1f7 124 Acceptable values for the `coap_max_blockwise_payload_size` flag are:
ram54288 0:a2cb7295a1f7 125 0, 16, 32, 64, 128, 256, 512 and 1024. Value 0 means that the feature is not used.
ram54288 0:a2cb7295a1f7 126
ram54288 0:a2cb7295a1f7 127 ### CoAP message deduplication
ram54288 0:a2cb7295a1f7 128
ram54288 0:a2cb7295a1f7 129 By default, message deduplication is disabled. More information about deduplication in the [CoAP specification](https://tools.ietf.org/html/rfc7252#page-24).
ram54288 0:a2cb7295a1f7 130
ram54288 0:a2cb7295a1f7 131 For mbed OS, to enable message deduplication, create a `mbed_app.json` file in the application level and overwrite the deduplication value as described below:
ram54288 0:a2cb7295a1f7 132
ram54288 0:a2cb7295a1f7 133 *Example:*
ram54288 0:a2cb7295a1f7 134 ```
ram54288 0:a2cb7295a1f7 135 "target_overrides": {
ram54288 0:a2cb7295a1f7 136 "*": {
ram54288 0:a2cb7295a1f7 137 "mbed-client.sn-coap-duplication-max-msgs-count": 1
ram54288 0:a2cb7295a1f7 138 }
ram54288 0:a2cb7295a1f7 139
ram54288 0:a2cb7295a1f7 140 ```
ram54288 0:a2cb7295a1f7 141 For yotta based builds, to enable message deduplication, you need to create a `config.json` file in the application level.
ram54288 0:a2cb7295a1f7 142
ram54288 0:a2cb7295a1f7 143 *Example:*
ram54288 0:a2cb7295a1f7 144 ```
ram54288 0:a2cb7295a1f7 145 {
ram54288 0:a2cb7295a1f7 146 "coap_duplication_max_msgs_count": 1
ram54288 0:a2cb7295a1f7 147 }
ram54288 0:a2cb7295a1f7 148 ```
ram54288 0:a2cb7295a1f7 149 Recommended values for the `coap_duplication_max_msgs_count` flag are 0 to 6. Value 0 means that the feature is not used. It is not recommended to use higher value than 6, because it increases the memory consumption.
ram54288 0:a2cb7295a1f7 150
ram54288 0:a2cb7295a1f7 151 ### Reconnectivity
ram54288 0:a2cb7295a1f7 152
ram54288 0:a2cb7295a1f7 153 Apart from standard CoAP features, mbed Client also handles reconnectivity logic on behalf of applications, thereby aiming to provide seamless connectivity experience and recovery from temporary network hiccups or service side disruptions.
ram54288 0:a2cb7295a1f7 154
ram54288 0:a2cb7295a1f7 155 The reconnection logic handles the following:
ram54288 0:a2cb7295a1f7 156
ram54288 0:a2cb7295a1f7 157 - Reconnection towards mDS; establishing the network connection and re-registration to mDS.
ram54288 0:a2cb7295a1f7 158 - CoAP message resending logic. More information about resending in [CoAP specification](https://tools.ietf.org/html/rfc7252#section-4.8).
ram54288 0:a2cb7295a1f7 159
ram54288 0:a2cb7295a1f7 160 There are two parameters in the reconnection logic, both configurable by the application:
ram54288 0:a2cb7295a1f7 161
ram54288 0:a2cb7295a1f7 162 - Reconnection Retry
ram54288 0:a2cb7295a1f7 163 - Reconnection Time Interval (in seconds)
ram54288 0:a2cb7295a1f7 164
ram54288 0:a2cb7295a1f7 165 mbed Client tries to establish a successful connection to the server by incrementing the reconnection trials every time there is a failed connection attempt.
ram54288 0:a2cb7295a1f7 166
ram54288 0:a2cb7295a1f7 167 The logic of the `Reconnection Timeout` is `Reconnection Retry count * Reconnection Time Interval` , where `Reconnection Retry count` is incremented by 1 with every failed reconnection attempt.
ram54288 0:a2cb7295a1f7 168
ram54288 0:a2cb7295a1f7 169 mbed Client continues to attempt a reconnection until `Reconnection Retry count` reaches the defined value (either by the application or the default value set in Client).
ram54288 0:a2cb7295a1f7 170
ram54288 0:a2cb7295a1f7 171 If mbed Client still cannot establish a connection and the set `Reconnection Retry count` is reached, it returns an error through a callback with an appropriate error code defining the reason for failed connection.
ram54288 0:a2cb7295a1f7 172
ram54288 0:a2cb7295a1f7 173 There are a few exceptions to the reconnection logic though. If mbed Client sends registration data that is rejected by the server, the client returns an error and does not attempt a reconnection as the server has rejected the data from the client. A typical example of such case would be passing a non-matching endpoint name or domain name against the client certificates.
ram54288 0:a2cb7295a1f7 174
ram54288 0:a2cb7295a1f7 175 Applications can define their own parameters for the reconnection logic.
ram54288 0:a2cb7295a1f7 176
ram54288 0:a2cb7295a1f7 177 For mbed OS, to overwrite the reconnection retry count and reconnection time interval, create a `mbed_app.json` file in the application level and overwrite the values as described below:
ram54288 0:a2cb7295a1f7 178
ram54288 0:a2cb7295a1f7 179 *Example:*
ram54288 0:a2cb7295a1f7 180 ```
ram54288 0:a2cb7295a1f7 181 "target_overrides": {
ram54288 0:a2cb7295a1f7 182 "*": {
ram54288 0:a2cb7295a1f7 183 "mbed-client.reconnection-count": 3,
ram54288 0:a2cb7295a1f7 184 "mbed-client.reconnection-interval": 5,
ram54288 0:a2cb7295a1f7 185 }
ram54288 0:a2cb7295a1f7 186
ram54288 0:a2cb7295a1f7 187 ```
ram54288 0:a2cb7295a1f7 188 For yotta based builds, to overwrite the reconnection retry count and reconnection time interval, you need to create a `config.json` file in the application level.
ram54288 0:a2cb7295a1f7 189
ram54288 0:a2cb7295a1f7 190 *Example:*
ram54288 0:a2cb7295a1f7 191 ```
ram54288 0:a2cb7295a1f7 192 {
ram54288 0:a2cb7295a1f7 193 "reconnection_count": 3,
ram54288 0:a2cb7295a1f7 194 "reconnection_interval": 5
ram54288 0:a2cb7295a1f7 195 }
ram54288 0:a2cb7295a1f7 196 ```
ram54288 0:a2cb7295a1f7 197
ram54288 0:a2cb7295a1f7 198 ## How to use the API
ram54288 0:a2cb7295a1f7 199 More information on how to use the API effectively to create and configure Objects, Object Instances and Resources, can be found [here](Howto.md).
ram54288 0:a2cb7295a1f7 200
ram54288 0:a2cb7295a1f7 201 ## API documentation
ram54288 0:a2cb7295a1f7 202
ram54288 0:a2cb7295a1f7 203 The documentation for this API is [available here](https://docs.mbed.com/docs/mbed-client-guide/en/latest/api/annotated.html).
ram54288 0:a2cb7295a1f7 204
ram54288 0:a2cb7295a1f7 205 ## Example application
ram54288 0:a2cb7295a1f7 206
ram54288 0:a2cb7295a1f7 207 We have an example application for
ram54288 0:a2cb7295a1f7 208
ram54288 0:a2cb7295a1f7 209 1. [mbed OS](https://github.com/ARMmbed/mbed-client-examples).
ram54288 0:a2cb7295a1f7 210
ram54288 0:a2cb7295a1f7 211 2. [Ubuntu](https://github.com/ARMmbed/mbed-client-linux-example).
ram54288 0:a2cb7295a1f7 212