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/client_reg_dereg.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 # The Client Registration feature
edamame22 0:29983394c6b6 2
edamame22 0:29983394c6b6 3 The client uses the Client Registration to register with mbed Device Server, update registration and deregister.
edamame22 0:29983394c6b6 4
edamame22 0:29983394c6b6 5 Currently, only one-to-one client-server registration is supported. One-to-many client-server registrations will be supported in an upcoming release.
edamame22 0:29983394c6b6 6
edamame22 0:29983394c6b6 7 The Client Registration includes multiple sub-features. Currently supported:
edamame22 0:29983394c6b6 8
edamame22 0:29983394c6b6 9 - [Register](#the-register-feature)
edamame22 0:29983394c6b6 10 - [Update](#the-update-feature)
edamame22 0:29983394c6b6 11 - [Deregister](#the-deregister-feature)
edamame22 0:29983394c6b6 12
edamame22 0:29983394c6b6 13 ## The Register feature
edamame22 0:29983394c6b6 14
edamame22 0:29983394c6b6 15 This API enables the client registration functionality.
edamame22 0:29983394c6b6 16
edamame22 0:29983394c6b6 17 When registering, the client:
edamame22 0:29983394c6b6 18
edamame22 0:29983394c6b6 19 * Performs the **Register** operation and provides parameters that mbed Device Server requires to register the client (for example Endpoint Name).
edamame22 0:29983394c6b6 20
edamame22 0:29983394c6b6 21 * Maintains the registration and session (for example, it sets the Lifetime and Queue Mode towards mbed Device Server).
edamame22 0:29983394c6b6 22
edamame22 0:29983394c6b6 23 * Provides information on the Objects the client supports and existing Object Instances in the client.
edamame22 0:29983394c6b6 24
edamame22 0:29983394c6b6 25 ### Registering your client
edamame22 0:29983394c6b6 26
edamame22 0:29983394c6b6 27 To provide information to mbed Device Server and issue the register command:
edamame22 0:29983394c6b6 28
edamame22 0:29983394c6b6 29 **Step 1.** Create an mbed DS Object. This object contains information about mbed Device Server, such as its address and security mode.
edamame22 0:29983394c6b6 30
edamame22 0:29983394c6b6 31 ```
edamame22 0:29983394c6b6 32 #include "mbed-client/m2msecurity.h"
edamame22 0:29983394c6b6 33 M2MSecurity *security = M2MInterfaceFactory::create_security(M2MSecurity::M2MServer);
edamame22 0:29983394c6b6 34 if(security) {
edamame22 0:29983394c6b6 35 security->set_resource_value(M2MSecurity::M2MServerUri, LWM2M_SERVER_ADDRESS);
edamame22 0:29983394c6b6 36 security->set_resource_value(M2MSecurity::BootstrapServer, 0);
edamame22 0:29983394c6b6 37 security->set_resource_value(M2MSecurity::SecurityMode, M2MSecurity::NoSecurity);
edamame22 0:29983394c6b6 38 }
edamame22 0:29983394c6b6 39 ```
edamame22 0:29983394c6b6 40
edamame22 0:29983394c6b6 41 **Step 2.** mbed Client supports both non-secure and secure mode operations. For secure mode, you need to provide a certificate, private key and server public key through the API.
edamame22 0:29983394c6b6 42
edamame22 0:29983394c6b6 43 To create a secure mode operation:
edamame22 0:29983394c6b6 44
edamame22 0:29983394c6b6 45 ```
edamame22 0:29983394c6b6 46 #include "mbed-client/m2msecurity.h"
edamame22 0:29983394c6b6 47 M2MSecurity *security = M2MInterfaceFactory::create_security(M2MSecurity::M2MServer);
edamame22 0:29983394c6b6 48 if(security) {
edamame22 0:29983394c6b6 49 security->set_resource_value(M2MSecurity::M2MServerUri, LWM2M_SERVER_ADDRESS);
edamame22 0:29983394c6b6 50 security->set_resource_value(M2MSecurity::BootstrapServer, 0);
edamame22 0:29983394c6b6 51 security->set_resource_value(M2MSecurity::SecurityMode, M2MSecurity::Certificate);
edamame22 0:29983394c6b6 52 security->set_resource_value(M2MSecurity::ServerPublicKey,<SERVER_CERT>,sizeof(<SERVER_CERT>));
edamame22 0:29983394c6b6 53 security->set_resource_value(M2MSecurity::PublicKey,<CERT>,sizeof(<CERT>));
edamame22 0:29983394c6b6 54 security->set_resource_value(M2MSecurity::Secretkey,<KEY>,sizeof(<KEY>));
edamame22 0:29983394c6b6 55 }
edamame22 0:29983394c6b6 56 ```
edamame22 0:29983394c6b6 57
edamame22 0:29983394c6b6 58 **Step 3.** Register all the resources that you would like to monitor or follow using mbed Device Server. To do this, create the resource objects and pass them to the Register API for registration purposes.
edamame22 0:29983394c6b6 59
edamame22 0:29983394c6b6 60 For example, if you want to register your OMA LWM2M based Device object, you need to create the object and set the values for mandatory resources as follows:
edamame22 0:29983394c6b6 61
edamame22 0:29983394c6b6 62 ```
edamame22 0:29983394c6b6 63 #include "mbed-client/m2mdevice.h"
edamame22 0:29983394c6b6 64 M2MDevice *device = M2MInterfaceFactory::create_device();
edamame22 0:29983394c6b6 65 if(device) {
edamame22 0:29983394c6b6 66 device->create_resource(M2MDevice::Manufacturer,MANUFACTURER);
edamame22 0:29983394c6b6 67 device->create_resource(M2MDevice::DeviceType,TYPE);
edamame22 0:29983394c6b6 68 device->create_resource(M2MDevice::ModelNumber,MODEL_NUMBER);
edamame22 0:29983394c6b6 69 device->create_resource(M2MDevice::SerialNumber,SERIAL_NUMBER);
edamame22 0:29983394c6b6 70 }
edamame22 0:29983394c6b6 71 ```
edamame22 0:29983394c6b6 72
edamame22 0:29983394c6b6 73 <span class="notes">**Note:** You can register other resources, including custom resources. Please check the [API documentation](https://docs.mbed.com/docs/mbed-client-guide/en/latest/api/annotated.html) for a detailed description of the M2MObject, M2MObjectInstance and M2MResource classes.</span>
edamame22 0:29983394c6b6 74
edamame22 0:29983394c6b6 75 **Step 4.** You have the registration server object and resources that you want to register. Now, you need to call the register API and pass the following objects as parameters:
edamame22 0:29983394c6b6 76
edamame22 0:29983394c6b6 77 ```
edamame22 0:29983394c6b6 78 M2MInterface::register_object(M2MSecurity* register_object, M2MObjectList object_list);
edamame22 0:29983394c6b6 79 ```
edamame22 0:29983394c6b6 80
edamame22 0:29983394c6b6 81 **Success or failure callback**
edamame22 0:29983394c6b6 82
edamame22 0:29983394c6b6 83 Because this is an asynchronous operation, you will receive the result of this operation through a callback defined in `m2minterfaceobserver.h` in your application.
edamame22 0:29983394c6b6 84
edamame22 0:29983394c6b6 85 _Success_
edamame22 0:29983394c6b6 86
edamame22 0:29983394c6b6 87 If the register operation is successful and the client can register all your resources to mbed DS, your application will receive the following callback:
edamame22 0:29983394c6b6 88
edamame22 0:29983394c6b6 89 ```
edamame22 0:29983394c6b6 90 void object_registered(M2MSecurity *server_object, const M2MServer& server)
edamame22 0:29983394c6b6 91 ```
edamame22 0:29983394c6b6 92
edamame22 0:29983394c6b6 93 The `M2MSecurity *server_object` specifies to which mbed Device Server instance the client has just registered and `M2MServer &server` contains the data related to mbed Device Server, including the Short ServerID and the client registration period.
edamame22 0:29983394c6b6 94
edamame22 0:29983394c6b6 95 _Failure_
edamame22 0:29983394c6b6 96
edamame22 0:29983394c6b6 97 If the registration operation fails for some reason, you will receive the following callback:
edamame22 0:29983394c6b6 98
edamame22 0:29983394c6b6 99 ```
edamame22 0:29983394c6b6 100 void error(M2MInterface::Error error)
edamame22 0:29983394c6b6 101 ```
edamame22 0:29983394c6b6 102
edamame22 0:29983394c6b6 103 You will get more information about the error from the `error` parameter passed with the callback; use it to fix the source of the error.
edamame22 0:29983394c6b6 104
edamame22 0:29983394c6b6 105 ## The Update feature
edamame22 0:29983394c6b6 106
edamame22 0:29983394c6b6 107 Periodically, or in response to events within the client or as initiated by mbed Device Server, the client updates its registration information with mbed Device Server by sending it an **Update** operation.
edamame22 0:29983394c6b6 108
edamame22 0:29983394c6b6 109 Normally, the enabler will update the registration automatically, but if you want to renew the registration before that, you can use this API.
edamame22 0:29983394c6b6 110
edamame22 0:29983394c6b6 111 To update your registration:
edamame22 0:29983394c6b6 112
edamame22 0:29983394c6b6 113 ```
edamame22 0:29983394c6b6 114 M2MInterface::update_registration(M2MSecurity* security_object, const uint32_t lifetime)
edamame22 0:29983394c6b6 115 ```
edamame22 0:29983394c6b6 116
edamame22 0:29983394c6b6 117 To update your registration and publish newly created objects to mbed Device Server:
edamame22 0:29983394c6b6 118
edamame22 0:29983394c6b6 119 ```
edamame22 0:29983394c6b6 120 M2MInterface::update_registration(M2MSecurity *security_object, const M2MObjectList &object_list, const uint32_t lifetime);
edamame22 0:29983394c6b6 121 ```
edamame22 0:29983394c6b6 122
edamame22 0:29983394c6b6 123 **Success or failure callback**
edamame22 0:29983394c6b6 124
edamame22 0:29983394c6b6 125 _Success_
edamame22 0:29983394c6b6 126
edamame22 0:29983394c6b6 127 If the update operation is successful, your application will receive the following callback:
edamame22 0:29983394c6b6 128
edamame22 0:29983394c6b6 129 ```
edamame22 0:29983394c6b6 130 void registration_updated(M2MSecurity *const M2MServer& server)
edamame22 0:29983394c6b6 131 ```
edamame22 0:29983394c6b6 132
edamame22 0:29983394c6b6 133 The `M2MSecurity *server_object` specifies with which mbed Device Server instance the client has just updated the registration and `M2MServer &server` contains the data related to mbed Device Server, including the Short ServerID and the client registration period.
edamame22 0:29983394c6b6 134
edamame22 0:29983394c6b6 135 _Failure_
edamame22 0:29983394c6b6 136
edamame22 0:29983394c6b6 137 If the update operation fails for some reason, you will receive the following callback:
edamame22 0:29983394c6b6 138
edamame22 0:29983394c6b6 139 ```
edamame22 0:29983394c6b6 140 void error(M2MInterface::Error error)
edamame22 0:29983394c6b6 141 ```
edamame22 0:29983394c6b6 142
edamame22 0:29983394c6b6 143 ## The Deregister feature
edamame22 0:29983394c6b6 144
edamame22 0:29983394c6b6 145 The client can deregister from mbed Device Server when it no longer requires access to the server. When mbed Device Server receives the **Deregister** message it removes the device's registration information from its database. When the client needs mbed Device Server again, it has to register again.
edamame22 0:29983394c6b6 146
edamame22 0:29983394c6b6 147 To deregister your endpoint client:
edamame22 0:29983394c6b6 148
edamame22 0:29983394c6b6 149 If the endpoint has multiple server registrations, you need to provide the `server_object` of the server from which would like to deregister. If there is only one registration, you can pass `NULL` and the client will deregister from the default registration.
edamame22 0:29983394c6b6 150
edamame22 0:29983394c6b6 151 ```
edamame22 0:29983394c6b6 152 M2MInterface::unregister_object(M2MSecurity *object);
edamame22 0:29983394c6b6 153 ```
edamame22 0:29983394c6b6 154
edamame22 0:29983394c6b6 155 **Success or failure callback**
edamame22 0:29983394c6b6 156
edamame22 0:29983394c6b6 157 Because this is an asynchronous operation, you will receive the result of this operation through a callback defined in `m2minterfaceobserver.h` in your application.
edamame22 0:29983394c6b6 158
edamame22 0:29983394c6b6 159 _Success_
edamame22 0:29983394c6b6 160
edamame22 0:29983394c6b6 161 If the client is successfully deregistered from mbed Device Server, your application will receive the following callback:
edamame22 0:29983394c6b6 162
edamame22 0:29983394c6b6 163 ```
edamame22 0:29983394c6b6 164 void object_unregistered(M2MSecurity *server_object)
edamame22 0:29983394c6b6 165 ```
edamame22 0:29983394c6b6 166
edamame22 0:29983394c6b6 167 The `M2MSecurity *server_object` specifies from which mbed Device Server instance the client has just deregistered.
edamame22 0:29983394c6b6 168
edamame22 0:29983394c6b6 169 _Failure_
edamame22 0:29983394c6b6 170
edamame22 0:29983394c6b6 171 If the deregistration operation fails for some reason, you will receive the following callback:
edamame22 0:29983394c6b6 172
edamame22 0:29983394c6b6 173 ```
edamame22 0:29983394c6b6 174 void error(M2MInterface::Error error)
edamame22 0:29983394c6b6 175 ```
edamame22 0:29983394c6b6 176
edamame22 0:29983394c6b6 177 You will get more information about the error from the `error` parameter passed with the callback; use it to fix the source of the problem.