Ram Gandikota / Mbed OS IOTMetronome

FRDM K64F Metronome

mbed-client/docs/client_reg_dereg.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 # The Client Registration feature
ram54288 0:dbad57390bd1 2
ram54288 0:dbad57390bd1 3 The client uses the Client Registration to register with mbed Device Server, update registration and deregister.
ram54288 0:dbad57390bd1 4
ram54288 0:dbad57390bd1 5 Currently, only one-to-one client-server registration is supported. One-to-many client-server registrations will be supported in an upcoming release.
ram54288 0:dbad57390bd1 6
ram54288 0:dbad57390bd1 7 The Client Registration includes multiple sub-features. Currently supported:
ram54288 0:dbad57390bd1 8
ram54288 0:dbad57390bd1 9 - [Register](#the-register-feature)
ram54288 0:dbad57390bd1 10 - [Update](#the-update-feature)
ram54288 0:dbad57390bd1 11 - [Deregister](#the-deregister-feature)
ram54288 0:dbad57390bd1 12
ram54288 0:dbad57390bd1 13 ## The Register feature
ram54288 0:dbad57390bd1 14
ram54288 0:dbad57390bd1 15 This API enables the client registration functionality.
ram54288 0:dbad57390bd1 16
ram54288 0:dbad57390bd1 17 When registering, the client:
ram54288 0:dbad57390bd1 18
ram54288 0:dbad57390bd1 19 * Performs the **Register** operation and provides parameters that mbed Device Server requires to register the client (for example Endpoint Name).
ram54288 0:dbad57390bd1 20
ram54288 0:dbad57390bd1 21 * Maintains the registration and session (for example, it sets the Lifetime and Queue Mode towards mbed Device Server).
ram54288 0:dbad57390bd1 22
ram54288 0:dbad57390bd1 23 * Provides information on the Objects the client supports and existing Object Instances in the client.
ram54288 0:dbad57390bd1 24
ram54288 0:dbad57390bd1 25 ### Registering your client
ram54288 0:dbad57390bd1 26
ram54288 0:dbad57390bd1 27 To provide information to mbed Device Server and issue the register command:
ram54288 0:dbad57390bd1 28
ram54288 0:dbad57390bd1 29 **Step 1.** Create an mbed DS Object. This object contains information about mbed Device Server, such as its address and security mode.
ram54288 0:dbad57390bd1 30
ram54288 0:dbad57390bd1 31 ```
ram54288 0:dbad57390bd1 32 #include "mbed-client/m2msecurity.h"
ram54288 0:dbad57390bd1 33 M2MSecurity *security = M2MInterfaceFactory::create_security(M2MSecurity::M2MServer);
ram54288 0:dbad57390bd1 34 if(security) {
ram54288 0:dbad57390bd1 35 security->set_resource_value(M2MSecurity::M2MServerUri, LWM2M_SERVER_ADDRESS);
ram54288 0:dbad57390bd1 36 security->set_resource_value(M2MSecurity::BootstrapServer, 0);
ram54288 0:dbad57390bd1 37 security->set_resource_value(M2MSecurity::SecurityMode, M2MSecurity::NoSecurity);
ram54288 0:dbad57390bd1 38 }
ram54288 0:dbad57390bd1 39 ```
ram54288 0:dbad57390bd1 40
ram54288 0:dbad57390bd1 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.
ram54288 0:dbad57390bd1 42
ram54288 0:dbad57390bd1 43 To create a secure mode operation:
ram54288 0:dbad57390bd1 44
ram54288 0:dbad57390bd1 45 ```
ram54288 0:dbad57390bd1 46 #include "mbed-client/m2msecurity.h"
ram54288 0:dbad57390bd1 47 M2MSecurity *security = M2MInterfaceFactory::create_security(M2MSecurity::M2MServer);
ram54288 0:dbad57390bd1 48 if(security) {
ram54288 0:dbad57390bd1 49 security->set_resource_value(M2MSecurity::M2MServerUri, LWM2M_SERVER_ADDRESS);
ram54288 0:dbad57390bd1 50 security->set_resource_value(M2MSecurity::BootstrapServer, 0);
ram54288 0:dbad57390bd1 51 security->set_resource_value(M2MSecurity::SecurityMode, M2MSecurity::Certificate);
ram54288 0:dbad57390bd1 52 security->set_resource_value(M2MSecurity::ServerPublicKey,<SERVER_CERT>,sizeof(<SERVER_CERT>));
ram54288 0:dbad57390bd1 53 security->set_resource_value(M2MSecurity::PublicKey,<CERT>,sizeof(<CERT>));
ram54288 0:dbad57390bd1 54 security->set_resource_value(M2MSecurity::Secretkey,<KEY>,sizeof(<KEY>));
ram54288 0:dbad57390bd1 55 }
ram54288 0:dbad57390bd1 56 ```
ram54288 0:dbad57390bd1 57
ram54288 0:dbad57390bd1 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.
ram54288 0:dbad57390bd1 59
ram54288 0:dbad57390bd1 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:
ram54288 0:dbad57390bd1 61
ram54288 0:dbad57390bd1 62 ```
ram54288 0:dbad57390bd1 63 #include "mbed-client/m2mdevice.h"
ram54288 0:dbad57390bd1 64 M2MDevice *device = M2MInterfaceFactory::create_device();
ram54288 0:dbad57390bd1 65 if(device) {
ram54288 0:dbad57390bd1 66 device->create_resource(M2MDevice::Manufacturer,MANUFACTURER);
ram54288 0:dbad57390bd1 67 device->create_resource(M2MDevice::DeviceType,TYPE);
ram54288 0:dbad57390bd1 68 device->create_resource(M2MDevice::ModelNumber,MODEL_NUMBER);
ram54288 0:dbad57390bd1 69 device->create_resource(M2MDevice::SerialNumber,SERIAL_NUMBER);
ram54288 0:dbad57390bd1 70 }
ram54288 0:dbad57390bd1 71 ```
ram54288 0:dbad57390bd1 72
ram54288 0:dbad57390bd1 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>
ram54288 0:dbad57390bd1 74
ram54288 0:dbad57390bd1 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:
ram54288 0:dbad57390bd1 76
ram54288 0:dbad57390bd1 77 ```
ram54288 0:dbad57390bd1 78 M2MInterface::register_object(M2MSecurity* register_object, M2MObjectList object_list);
ram54288 0:dbad57390bd1 79 ```
ram54288 0:dbad57390bd1 80
ram54288 0:dbad57390bd1 81 **Success or failure callback**
ram54288 0:dbad57390bd1 82
ram54288 0:dbad57390bd1 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.
ram54288 0:dbad57390bd1 84
ram54288 0:dbad57390bd1 85 _Success_
ram54288 0:dbad57390bd1 86
ram54288 0:dbad57390bd1 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:
ram54288 0:dbad57390bd1 88
ram54288 0:dbad57390bd1 89 ```
ram54288 0:dbad57390bd1 90 void object_registered(M2MSecurity *server_object, const M2MServer& server)
ram54288 0:dbad57390bd1 91 ```
ram54288 0:dbad57390bd1 92
ram54288 0:dbad57390bd1 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.
ram54288 0:dbad57390bd1 94
ram54288 0:dbad57390bd1 95 _Failure_
ram54288 0:dbad57390bd1 96
ram54288 0:dbad57390bd1 97 If the registration operation fails for some reason, you will receive the following callback:
ram54288 0:dbad57390bd1 98
ram54288 0:dbad57390bd1 99 ```
ram54288 0:dbad57390bd1 100 void error(M2MInterface::Error error)
ram54288 0:dbad57390bd1 101 ```
ram54288 0:dbad57390bd1 102
ram54288 0:dbad57390bd1 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.
ram54288 0:dbad57390bd1 104
ram54288 0:dbad57390bd1 105 ## The Update feature
ram54288 0:dbad57390bd1 106
ram54288 0:dbad57390bd1 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.
ram54288 0:dbad57390bd1 108
ram54288 0:dbad57390bd1 109 Normally, the enabler will update the registration automatically, but if you want to renew the registration before that, you can use this API.
ram54288 0:dbad57390bd1 110
ram54288 0:dbad57390bd1 111 To update your registration:
ram54288 0:dbad57390bd1 112
ram54288 0:dbad57390bd1 113 ```
ram54288 0:dbad57390bd1 114 M2MInterface::update_registration(M2MSecurity* security_object, const uint32_t lifetime)
ram54288 0:dbad57390bd1 115 ```
ram54288 0:dbad57390bd1 116
ram54288 0:dbad57390bd1 117 To update your registration and publish newly created objects to mbed Device Server:
ram54288 0:dbad57390bd1 118
ram54288 0:dbad57390bd1 119 ```
ram54288 0:dbad57390bd1 120 M2MInterface::update_registration(M2MSecurity *security_object, const M2MObjectList &object_list, const uint32_t lifetime);
ram54288 0:dbad57390bd1 121 ```
ram54288 0:dbad57390bd1 122
ram54288 0:dbad57390bd1 123 **Success or failure callback**
ram54288 0:dbad57390bd1 124
ram54288 0:dbad57390bd1 125 _Success_
ram54288 0:dbad57390bd1 126
ram54288 0:dbad57390bd1 127 If the update operation is successful, your application will receive the following callback:
ram54288 0:dbad57390bd1 128
ram54288 0:dbad57390bd1 129 ```
ram54288 0:dbad57390bd1 130 void registration_updated(M2MSecurity *const M2MServer& server)
ram54288 0:dbad57390bd1 131 ```
ram54288 0:dbad57390bd1 132
ram54288 0:dbad57390bd1 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.
ram54288 0:dbad57390bd1 134
ram54288 0:dbad57390bd1 135 _Failure_
ram54288 0:dbad57390bd1 136
ram54288 0:dbad57390bd1 137 If the update operation fails for some reason, you will receive the following callback:
ram54288 0:dbad57390bd1 138
ram54288 0:dbad57390bd1 139 ```
ram54288 0:dbad57390bd1 140 void error(M2MInterface::Error error)
ram54288 0:dbad57390bd1 141 ```
ram54288 0:dbad57390bd1 142
ram54288 0:dbad57390bd1 143 ## The Deregister feature
ram54288 0:dbad57390bd1 144
ram54288 0:dbad57390bd1 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.
ram54288 0:dbad57390bd1 146
ram54288 0:dbad57390bd1 147 To deregister your endpoint client:
ram54288 0:dbad57390bd1 148
ram54288 0:dbad57390bd1 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.
ram54288 0:dbad57390bd1 150
ram54288 0:dbad57390bd1 151 ```
ram54288 0:dbad57390bd1 152 M2MInterface::unregister_object(M2MSecurity *object);
ram54288 0:dbad57390bd1 153 ```
ram54288 0:dbad57390bd1 154
ram54288 0:dbad57390bd1 155 **Success or failure callback**
ram54288 0:dbad57390bd1 156
ram54288 0:dbad57390bd1 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.
ram54288 0:dbad57390bd1 158
ram54288 0:dbad57390bd1 159 _Success_
ram54288 0:dbad57390bd1 160
ram54288 0:dbad57390bd1 161 If the client is successfully deregistered from mbed Device Server, your application will receive the following callback:
ram54288 0:dbad57390bd1 162
ram54288 0:dbad57390bd1 163 ```
ram54288 0:dbad57390bd1 164 void object_unregistered(M2MSecurity *server_object)
ram54288 0:dbad57390bd1 165 ```
ram54288 0:dbad57390bd1 166
ram54288 0:dbad57390bd1 167 The `M2MSecurity *server_object` specifies from which mbed Device Server instance the client has just deregistered.
ram54288 0:dbad57390bd1 168
ram54288 0:dbad57390bd1 169 _Failure_
ram54288 0:dbad57390bd1 170
ram54288 0:dbad57390bd1 171 If the deregistration operation fails for some reason, you will receive the following callback:
ram54288 0:dbad57390bd1 172
ram54288 0:dbad57390bd1 173 ```
ram54288 0:dbad57390bd1 174 void error(M2MInterface::Error error)
ram54288 0:dbad57390bd1 175 ```
ram54288 0:dbad57390bd1 176
ram54288 0:dbad57390bd1 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.