Ram Gandikota / Mbed OS ABCD

A metronome using the FRDM K64F board

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