boting ren / Mbed OS BLEClient_mbedDevConn

This is an example of BLE GATT Client, which receives broadcast data from BLE_Server_BME280 ( a GATT server) , then transfers values up to mbed Device Connector (cloud).

Please refer details about BLEClient_mbedDevConn below. https://github.com/soramame21/BLEClient_mbedDevConn

The location of required BLE GATT server, BLE_Server_BME280, is at here. https://developer.mbed.org/users/edamame22/code/BLE_Server_BME280/

mbed-client/docs/Introduction.md@0:29983394c6b6, 2017-04-13 (annotated)

Committer:
edamame22
Date:
Thu Apr 13 04:48:11 2017 +0000
Revision:
0:29983394c6b6
Initial commit

Who changed what in which revision?

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