Ram Gandikota / Mbed OS IOTMetronome

FRDM K64F Metronome

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

Committer:
ram54288
Date:
Sun May 14 18:37:05 2017 +0000
Revision:
0:dbad57390bd1
Initial commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
ram54288 0:dbad57390bd1 1 # ARM mbed Client overview
ram54288 0:dbad57390bd1 2
ram54288 0:dbad57390bd1 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:dbad57390bd1 4
ram54288 0:dbad57390bd1 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:dbad57390bd1 6
ram54288 0:dbad57390bd1 7 - Manage devices on mbed Device Server.
ram54288 0:dbad57390bd1 8 - Securely communicate with internet services over the industry standard TLS/DTLS.
ram54288 0:dbad57390bd1 9 - Fully control the endpoint and application logic.
ram54288 0:dbad57390bd1 10
ram54288 0:dbad57390bd1 11 The API is written in C++ to allow quick application development.
ram54288 0:dbad57390bd1 12
ram54288 0:dbad57390bd1 13 ## Managing devices on mbed Device Server
ram54288 0:dbad57390bd1 14
ram54288 0:dbad57390bd1 15 mbed Client supports the following three features introduced in the subsequent chapters:
ram54288 0:dbad57390bd1 16
ram54288 0:dbad57390bd1 17 - [Client Registration and Deregistration](client_reg_dereg.md)
ram54288 0:dbad57390bd1 18 - [Device Management and Service Enablement](dev_man_serv_enable.md)
ram54288 0:dbad57390bd1 19 - [Information Reporting](info_reporting.md)
ram54288 0:dbad57390bd1 20
ram54288 0:dbad57390bd1 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:dbad57390bd1 22
ram54288 0:dbad57390bd1 23 First, you need to create an interface for mbed Client:
ram54288 0:dbad57390bd1 24
ram54288 0:dbad57390bd1 25 ```
ram54288 0:dbad57390bd1 26 #include "mbed-client/m2minterfacefactory.h"
ram54288 0:dbad57390bd1 27 #include "mbed-client/m2minterface.h"
ram54288 0:dbad57390bd1 28
ram54288 0:dbad57390bd1 29 M2MInterface* interface = M2MInterfaceFactory::create_interface(*this,
ram54288 0:dbad57390bd1 30 "mbed-endpoint",
ram54288 0:dbad57390bd1 31 "test",
ram54288 0:dbad57390bd1 32 3600,
ram54288 0:dbad57390bd1 33 5684,
ram54288 0:dbad57390bd1 34 "",
ram54288 0:dbad57390bd1 35 M2MInterface::UDP,
ram54288 0:dbad57390bd1 36 M2MInterface::LwIP_IPv4,
ram54288 0:dbad57390bd1 37 "");
ram54288 0:dbad57390bd1 38 ```
ram54288 0:dbad57390bd1 39
ram54288 0:dbad57390bd1 40 ### Setting up own random number generator function
ram54288 0:dbad57390bd1 41
ram54288 0:dbad57390bd1 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:dbad57390bd1 43
ram54288 0:dbad57390bd1 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:dbad57390bd1 45
ram54288 0:dbad57390bd1 46 Here is an example on how you can use it from an application:
ram54288 0:dbad57390bd1 47
ram54288 0:dbad57390bd1 48 ```
ram54288 0:dbad57390bd1 49 #include "mbed-client/m2minterfacefactory.h"
ram54288 0:dbad57390bd1 50 #include "mbed-client/m2minterface.h"
ram54288 0:dbad57390bd1 51
ram54288 0:dbad57390bd1 52 uint32_t get_random_number(void)
ram54288 0:dbad57390bd1 53 {
ram54288 0:dbad57390bd1 54 uint32_t i = 0;
ram54288 0:dbad57390bd1 55 printf("\Your application's RNG logic\n");
ram54288 0:dbad57390bd1 56 return i;
ram54288 0:dbad57390bd1 57 }
ram54288 0:dbad57390bd1 58
ram54288 0:dbad57390bd1 59 _interface->set_random_number_callback(&get_random_number);
ram54288 0:dbad57390bd1 60
ram54288 0:dbad57390bd1 61 ```
ram54288 0:dbad57390bd1 62
ram54288 0:dbad57390bd1 63 ### Setting up own entropy function for additional secure connectivity
ram54288 0:dbad57390bd1 64
ram54288 0:dbad57390bd1 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:dbad57390bd1 66
ram54288 0:dbad57390bd1 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:dbad57390bd1 68
ram54288 0:dbad57390bd1 69 Here is an example on how you can use it from an application:
ram54288 0:dbad57390bd1 70
ram54288 0:dbad57390bd1 71 ```
ram54288 0:dbad57390bd1 72 #include "mbed-client/m2minterfacefactory.h"
ram54288 0:dbad57390bd1 73 #include "mbed-client/m2minterface.h"
ram54288 0:dbad57390bd1 74
ram54288 0:dbad57390bd1 75 entropy_cb ent_cb;
ram54288 0:dbad57390bd1 76
ram54288 0:dbad57390bd1 77 int ent_poll( void *, unsigned char *output, size_t len,
ram54288 0:dbad57390bd1 78 size_t *olen )
ram54288 0:dbad57390bd1 79 {
ram54288 0:dbad57390bd1 80 for(uint16_t i=0; i < len; i++){
ram54288 0:dbad57390bd1 81 srand(time(NULL));
ram54288 0:dbad57390bd1 82 output[i] = rand() % 256;
ram54288 0:dbad57390bd1 83 }
ram54288 0:dbad57390bd1 84 *olen = len;
ram54288 0:dbad57390bd1 85
ram54288 0:dbad57390bd1 86 return( 0 );
ram54288 0:dbad57390bd1 87 }
ram54288 0:dbad57390bd1 88
ram54288 0:dbad57390bd1 89 ent_cb.entropy_source_ptr = ent_poll;
ram54288 0:dbad57390bd1 90 ent_cb.p_source = NULL;
ram54288 0:dbad57390bd1 91 ent_cb.threshold = 128;
ram54288 0:dbad57390bd1 92 ent_cb.strong = 0;
ram54288 0:dbad57390bd1 93
ram54288 0:dbad57390bd1 94 _interface->set_entropy_callback(ent_cb);
ram54288 0:dbad57390bd1 95
ram54288 0:dbad57390bd1 96 ```
ram54288 0:dbad57390bd1 97
ram54288 0:dbad57390bd1 98 ### Maximum UDP message size
ram54288 0:dbad57390bd1 99
ram54288 0:dbad57390bd1 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:dbad57390bd1 101
ram54288 0:dbad57390bd1 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:dbad57390bd1 103
ram54288 0:dbad57390bd1 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:dbad57390bd1 105
ram54288 0:dbad57390bd1 106 *Example:*
ram54288 0:dbad57390bd1 107 ```
ram54288 0:dbad57390bd1 108 "target_overrides": {
ram54288 0:dbad57390bd1 109 "*": {
ram54288 0:dbad57390bd1 110 "mbed-client.sn-coap-max-blockwise-payload-size": 1024
ram54288 0:dbad57390bd1 111 }
ram54288 0:dbad57390bd1 112
ram54288 0:dbad57390bd1 113 ```
ram54288 0:dbad57390bd1 114
ram54288 0:dbad57390bd1 115 To enable the Blockwise feature in yotta based builds, you need to create a `config.json` file in the application level.
ram54288 0:dbad57390bd1 116
ram54288 0:dbad57390bd1 117 *Example:*
ram54288 0:dbad57390bd1 118 ```
ram54288 0:dbad57390bd1 119 {
ram54288 0:dbad57390bd1 120 "coap_max_blockwise_payload_size": 1024
ram54288 0:dbad57390bd1 121 }
ram54288 0:dbad57390bd1 122 ```
ram54288 0:dbad57390bd1 123
ram54288 0:dbad57390bd1 124 Acceptable values for the `coap_max_blockwise_payload_size` flag are:
ram54288 0:dbad57390bd1 125 0, 16, 32, 64, 128, 256, 512 and 1024. Value 0 means that the feature is not used.
ram54288 0:dbad57390bd1 126
ram54288 0:dbad57390bd1 127 ### CoAP message deduplication
ram54288 0:dbad57390bd1 128
ram54288 0:dbad57390bd1 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:dbad57390bd1 130
ram54288 0:dbad57390bd1 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:dbad57390bd1 132
ram54288 0:dbad57390bd1 133 *Example:*
ram54288 0:dbad57390bd1 134 ```
ram54288 0:dbad57390bd1 135 "target_overrides": {
ram54288 0:dbad57390bd1 136 "*": {
ram54288 0:dbad57390bd1 137 "mbed-client.sn-coap-duplication-max-msgs-count": 1
ram54288 0:dbad57390bd1 138 }
ram54288 0:dbad57390bd1 139
ram54288 0:dbad57390bd1 140 ```
ram54288 0:dbad57390bd1 141 For yotta based builds, to enable message deduplication, you need to create a `config.json` file in the application level.
ram54288 0:dbad57390bd1 142
ram54288 0:dbad57390bd1 143 *Example:*
ram54288 0:dbad57390bd1 144 ```
ram54288 0:dbad57390bd1 145 {
ram54288 0:dbad57390bd1 146 "coap_duplication_max_msgs_count": 1
ram54288 0:dbad57390bd1 147 }
ram54288 0:dbad57390bd1 148 ```
ram54288 0:dbad57390bd1 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:dbad57390bd1 150
ram54288 0:dbad57390bd1 151 ### Reconnectivity
ram54288 0:dbad57390bd1 152
ram54288 0:dbad57390bd1 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:dbad57390bd1 154
ram54288 0:dbad57390bd1 155 The reconnection logic handles the following:
ram54288 0:dbad57390bd1 156
ram54288 0:dbad57390bd1 157 - Reconnection towards mDS; establishing the network connection and re-registration to mDS.
ram54288 0:dbad57390bd1 158 - CoAP message resending logic. More information about resending in [CoAP specification](https://tools.ietf.org/html/rfc7252#section-4.8).
ram54288 0:dbad57390bd1 159
ram54288 0:dbad57390bd1 160 There are two parameters in the reconnection logic, both configurable by the application:
ram54288 0:dbad57390bd1 161
ram54288 0:dbad57390bd1 162 - Reconnection Retry
ram54288 0:dbad57390bd1 163 - Reconnection Time Interval (in seconds)
ram54288 0:dbad57390bd1 164
ram54288 0:dbad57390bd1 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:dbad57390bd1 166
ram54288 0:dbad57390bd1 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:dbad57390bd1 168
ram54288 0:dbad57390bd1 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:dbad57390bd1 170
ram54288 0:dbad57390bd1 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:dbad57390bd1 172
ram54288 0:dbad57390bd1 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:dbad57390bd1 174
ram54288 0:dbad57390bd1 175 Applications can define their own parameters for the reconnection logic.
ram54288 0:dbad57390bd1 176
ram54288 0:dbad57390bd1 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:dbad57390bd1 178
ram54288 0:dbad57390bd1 179 *Example:*
ram54288 0:dbad57390bd1 180 ```
ram54288 0:dbad57390bd1 181 "target_overrides": {
ram54288 0:dbad57390bd1 182 "*": {
ram54288 0:dbad57390bd1 183 "mbed-client.reconnection-count": 3,
ram54288 0:dbad57390bd1 184 "mbed-client.reconnection-interval": 5,
ram54288 0:dbad57390bd1 185 }
ram54288 0:dbad57390bd1 186
ram54288 0:dbad57390bd1 187 ```
ram54288 0:dbad57390bd1 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:dbad57390bd1 189
ram54288 0:dbad57390bd1 190 *Example:*
ram54288 0:dbad57390bd1 191 ```
ram54288 0:dbad57390bd1 192 {
ram54288 0:dbad57390bd1 193 "reconnection_count": 3,
ram54288 0:dbad57390bd1 194 "reconnection_interval": 5
ram54288 0:dbad57390bd1 195 }
ram54288 0:dbad57390bd1 196 ```
ram54288 0:dbad57390bd1 197
ram54288 0:dbad57390bd1 198 ## How to use the API
ram54288 0:dbad57390bd1 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:dbad57390bd1 200
ram54288 0:dbad57390bd1 201 ## API documentation
ram54288 0:dbad57390bd1 202
ram54288 0:dbad57390bd1 203 The documentation for this API is [available here](https://docs.mbed.com/docs/mbed-client-guide/en/latest/api/annotated.html).
ram54288 0:dbad57390bd1 204
ram54288 0:dbad57390bd1 205 ## Example application
ram54288 0:dbad57390bd1 206
ram54288 0:dbad57390bd1 207 We have an example application for
ram54288 0:dbad57390bd1 208
ram54288 0:dbad57390bd1 209 1. [mbed OS](https://github.com/ARMmbed/mbed-client-examples).
ram54288 0:dbad57390bd1 210
ram54288 0:dbad57390bd1 211 2. [Ubuntu](https://github.com/ARMmbed/mbed-client-linux-example).
ram54288 0:dbad57390bd1 212