Donald Meyers / Mbed OS evan

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

mbed-client/docs/Introduction.md@0:06ee5f8a484a, 2017-03-18 (annotated)

Committer:
djmeyers
Date:
Sat Mar 18 22:37:16 2017 +0000
Revision:
0:06ee5f8a484a
Initial commit

Who changed what in which revision?

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