Ram Gandikota / Mbed OS ABCD

A metronome using the FRDM K64F board

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

Committer:
ram54288
Date:
Sun May 14 18:40:18 2017 +0000
Revision:
0:a7a43371b306
Initial commit

Who changed what in which revision?

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