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