Austin Blackstone / Mbed 2 deprecated client-lwip-lightswitch-demo-expanded

mbed client lightswitch demo

Dependencies:   mbed Socket lwip-eth lwip-sys lwip

Fork of mbed-client-classic-example-lwip by Austin Blackstone

mbed-client/docs/Introduction.md@11:cada08fc8a70, 2016-06-09 (annotated)

Committer:
mbedAustin
Date:
Thu Jun 09 17:08:36 2016 +0000
Revision:
11:cada08fc8a70
Commit for public Consumption

Who changed what in which revision?

UserRevisionLine numberNew contents of line
mbedAustin 11:cada08fc8a70 1 # mbed Client API
mbedAustin 11:cada08fc8a70 2
mbedAustin 11:cada08fc8a70 3 ## Introduction
mbedAustin 11:cada08fc8a70 4
mbedAustin 11:cada08fc8a70 5 mbed Client is an OS-agnostic embedded software library that provides the means to connect and manage constrained embedded devices to web applications through the mbed Device Server (mbed DS).
mbedAustin 11:cada08fc8a70 6
mbedAustin 11:cada08fc8a70 7 The mbed Device Client API allows mbed OS developers to create applications with LWM2M features. These features are described in the [Lightweight Machine to Machine Technical Specification](http://technical.openmobilealliance.org/Technical/technical-information/release-program/current-releases/oma-lightweightm2m-v1-0); they include high level APIs to manage devices on mbed DS, securely communicate with internet services over the industry standard TLS/DTLS, and fully control the endpoint and application logic.
mbedAustin 11:cada08fc8a70 8
mbedAustin 11:cada08fc8a70 9 The API is written in C++ to allow quick application development.
mbedAustin 11:cada08fc8a70 10
mbedAustin 11:cada08fc8a70 11 ## mbed Client interfaces
mbedAustin 11:cada08fc8a70 12
mbedAustin 11:cada08fc8a70 13 There are three interfaces between mbed DS and mbed Client:
mbedAustin 11:cada08fc8a70 14
mbedAustin 11:cada08fc8a70 15 - Client registration and deregistration
mbedAustin 11:cada08fc8a70 16 - Device management and service enablement
mbedAustin 11:cada08fc8a70 17 - Information reporting
mbedAustin 11:cada08fc8a70 18
mbedAustin 11:cada08fc8a70 19 The API provides an interface to define the application endpoint information. This information will be delivered to mbed DS during the registration operation (explained below).
mbedAustin 11:cada08fc8a70 20
mbedAustin 11:cada08fc8a70 21 To create an interface for your endpoint:
mbedAustin 11:cada08fc8a70 22
mbedAustin 11:cada08fc8a70 23 ```
mbedAustin 11:cada08fc8a70 24 #include "mbed-client/m2minterfacefactory.h"
mbedAustin 11:cada08fc8a70 25 #include "mbed-client/m2minterface.h"
mbedAustin 11:cada08fc8a70 26
mbedAustin 11:cada08fc8a70 27 M2MInterface* interface = M2MInterfaceFactory::create_interface(*this,
mbedAustin 11:cada08fc8a70 28 "mbed-endpoint",
mbedAustin 11:cada08fc8a70 29 "test",
mbedAustin 11:cada08fc8a70 30 3600,
mbedAustin 11:cada08fc8a70 31 5684,
mbedAustin 11:cada08fc8a70 32 "",
mbedAustin 11:cada08fc8a70 33 M2MInterface::UDP,
mbedAustin 11:cada08fc8a70 34 M2MInterface::LwIP_IPv4,
mbedAustin 11:cada08fc8a70 35 "");
mbedAustin 11:cada08fc8a70 36 ```
mbedAustin 11:cada08fc8a70 37
mbedAustin 11:cada08fc8a70 38 When you have created the interface, you can proceed to execute operations.
mbedAustin 11:cada08fc8a70 39
mbedAustin 11:cada08fc8a70 40 ### Client Registration Interface
mbedAustin 11:cada08fc8a70 41
mbedAustin 11:cada08fc8a70 42 The client uses the Client Registration Interface to register with mbed DS, update registration and deregister.
mbedAustin 11:cada08fc8a70 43
mbedAustin 11:cada08fc8a70 44 Currently, only one-to-one client-server registration is supported. One-to-many client-server registrations will be supported in an upcoming release.
mbedAustin 11:cada08fc8a70 45
mbedAustin 11:cada08fc8a70 46 The Client Registration Interface includes multiple sub-features. Currently supported:
mbedAustin 11:cada08fc8a70 47
mbedAustin 11:cada08fc8a70 48 - Register
mbedAustin 11:cada08fc8a70 49 - Update
mbedAustin 11:cada08fc8a70 50 - Deregister
mbedAustin 11:cada08fc8a70 51
mbedAustin 11:cada08fc8a70 52 ### The Register feature
mbedAustin 11:cada08fc8a70 53
mbedAustin 11:cada08fc8a70 54 This API enables the client registration functionality.
mbedAustin 11:cada08fc8a70 55
mbedAustin 11:cada08fc8a70 56 When registering, the client:
mbedAustin 11:cada08fc8a70 57
mbedAustin 11:cada08fc8a70 58 * Performs the **Register** operation and provides parameters that mbed DS requires to register the client (for example End Point Name).
mbedAustin 11:cada08fc8a70 59
mbedAustin 11:cada08fc8a70 60 * Maintains the registration and session (for example Lifetime, Queue Mode).
mbedAustin 11:cada08fc8a70 61
mbedAustin 11:cada08fc8a70 62 * Provides information on the Objects the client supports and existing Object Instances in the client.
mbedAustin 11:cada08fc8a70 63
mbedAustin 11:cada08fc8a70 64 #### Registering your client
mbedAustin 11:cada08fc8a70 65
mbedAustin 11:cada08fc8a70 66 To provide information to mbed DS and issue the register command:
mbedAustin 11:cada08fc8a70 67
mbedAustin 11:cada08fc8a70 68 First you need to create an mbed DS object. This object contains information about mbed DS, such as its address and security mode.
mbedAustin 11:cada08fc8a70 69
mbedAustin 11:cada08fc8a70 70 ```
mbedAustin 11:cada08fc8a70 71 #include "mbed-client/m2msecurity.h"
mbedAustin 11:cada08fc8a70 72 M2MSecurity *security = M2MInterfaceFactory::create_security(M2MSecurity::M2MServer);
mbedAustin 11:cada08fc8a70 73 if(security) {
mbedAustin 11:cada08fc8a70 74 security->set_resource_value(M2MSecurity::M2MServerUri, LWM2M_SERVER_ADDRESS);
mbedAustin 11:cada08fc8a70 75 security->set_resource_value(M2MSecurity::BootstrapServer, 0);
mbedAustin 11:cada08fc8a70 76 security->set_resource_value(M2MSecurity::SecurityMode, M2MSecurity::NoSecurity);
mbedAustin 11:cada08fc8a70 77 }
mbedAustin 11:cada08fc8a70 78 ```
mbedAustin 11:cada08fc8a70 79
mbedAustin 11:cada08fc8a70 80 **Note**: This API supports both non-secure and secure mode operations. For secure mode, you will also need to provide certificate, private key and server public key through the API.
mbedAustin 11:cada08fc8a70 81
mbedAustin 11:cada08fc8a70 82 Create a secure mode operation as follows:
mbedAustin 11:cada08fc8a70 83
mbedAustin 11:cada08fc8a70 84 ```
mbedAustin 11:cada08fc8a70 85 #include "mbed-client/m2msecurity.h"
mbedAustin 11:cada08fc8a70 86 M2MSecurity *security = M2MInterfaceFactory::create_security(M2MSecurity::M2MServer);
mbedAustin 11:cada08fc8a70 87 if(security) {
mbedAustin 11:cada08fc8a70 88 security->set_resource_value(M2MSecurity::M2MServerUri, LWM2M_SERVER_ADDRESS);
mbedAustin 11:cada08fc8a70 89 security->set_resource_value(M2MSecurity::BootstrapServer, 0);
mbedAustin 11:cada08fc8a70 90 security->set_resource_value(M2MSecurity::SecurityMode, M2MSecurity::Certificate);
mbedAustin 11:cada08fc8a70 91 security->set_resource_value(M2MSecurity::ServerPublicKey,<SERVER_CERT>,sizeof(<SERVER_CERT>));
mbedAustin 11:cada08fc8a70 92 security->set_resource_value(M2MSecurity::PublicKey,<CERT>,sizeof(<CERT>));
mbedAustin 11:cada08fc8a70 93 security->set_resource_value(M2MSecurity::Secretkey,<KEY>,sizeof(<KEY>));
mbedAustin 11:cada08fc8a70 94 }
mbedAustin 11:cada08fc8a70 95 ```
mbedAustin 11:cada08fc8a70 96
mbedAustin 11:cada08fc8a70 97 Next, you need to register all the resources that you would like to monitor or follow via mbed DS. To do this, create the resource objects and pass them to the Register API for registration purposes.
mbedAustin 11:cada08fc8a70 98
mbedAustin 11:cada08fc8a70 99 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:
mbedAustin 11:cada08fc8a70 100
mbedAustin 11:cada08fc8a70 101 ```
mbedAustin 11:cada08fc8a70 102 #include "mbed-client/m2mdevice.h"
mbedAustin 11:cada08fc8a70 103 M2MDevice *device = M2MInterfaceFactory::create_device();
mbedAustin 11:cada08fc8a70 104 if(device) {
mbedAustin 11:cada08fc8a70 105 device->create_resource(M2MDevice::Manufacturer,MANUFACTURER);
mbedAustin 11:cada08fc8a70 106 device->create_resource(M2MDevice::DeviceType,TYPE);
mbedAustin 11:cada08fc8a70 107 device->create_resource(M2MDevice::ModelNumber,MODEL_NUMBER);
mbedAustin 11:cada08fc8a70 108 device->create_resource(M2MDevice::SerialNumber,SERIAL_NUMBER);
mbedAustin 11:cada08fc8a70 109 }
mbedAustin 11:cada08fc8a70 110 ```
mbedAustin 11:cada08fc8a70 111
mbedAustin 11:cada08fc8a70 112 **Note:** You can register other resources, including custom resources. Please check the API documentation for a detailed description of the M2MObject, M2MObjectInstance and M2MResource classes.
mbedAustin 11:cada08fc8a70 113
mbedAustin 11:cada08fc8a70 114 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:
mbedAustin 11:cada08fc8a70 115
mbedAustin 11:cada08fc8a70 116 ```
mbedAustin 11:cada08fc8a70 117 M2MInterface::register_object(M2MSecurity* register_object, M2MObjectList object_list);
mbedAustin 11:cada08fc8a70 118 ```
mbedAustin 11:cada08fc8a70 119
mbedAustin 11:cada08fc8a70 120 **Success or failure callback**
mbedAustin 11:cada08fc8a70 121
mbedAustin 11:cada08fc8a70 122 Because this is an asynchronous operation, you will receive the result of this operation through a callback defined in `m2minterfaceobserver.h` in your application.
mbedAustin 11:cada08fc8a70 123
mbedAustin 11:cada08fc8a70 124 If the register operation is successful and the client can register all your resources to mbed DS, your application will receive the following callback:
mbedAustin 11:cada08fc8a70 125
mbedAustin 11:cada08fc8a70 126 ```
mbedAustin 11:cada08fc8a70 127 void object_registered(M2MSecurity *server_object, const M2MServer& server)
mbedAustin 11:cada08fc8a70 128 ```
mbedAustin 11:cada08fc8a70 129
mbedAustin 11:cada08fc8a70 130 The `M2MSecurity *server_object` specifies to which mbed DS instance the client has just registered and `M2MServer &server` contains the data related to mbed DS, including the Short ServerID and the client registration period.
mbedAustin 11:cada08fc8a70 131
mbedAustin 11:cada08fc8a70 132 If the registration operation fails for some reason, you will receive the following callback:
mbedAustin 11:cada08fc8a70 133
mbedAustin 11:cada08fc8a70 134 ```
mbedAustin 11:cada08fc8a70 135 void error(M2MInterface::Error error)
mbedAustin 11:cada08fc8a70 136 ```
mbedAustin 11:cada08fc8a70 137
mbedAustin 11:cada08fc8a70 138 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.
mbedAustin 11:cada08fc8a70 139
mbedAustin 11:cada08fc8a70 140 ### Update
mbedAustin 11:cada08fc8a70 141
mbedAustin 11:cada08fc8a70 142 Periodically, or in response to events within the client or as initiated by mbed DS, the client updates its registration information with mbed DS. It sends an **Update** operation to mbed DS.
mbedAustin 11:cada08fc8a70 143
mbedAustin 11:cada08fc8a70 144 To update your registration:
mbedAustin 11:cada08fc8a70 145
mbedAustin 11:cada08fc8a70 146 ```
mbedAustin 11:cada08fc8a70 147 M2MInterface::update_registration(M2MSecurity* security_object, const uint32_t lifetime)
mbedAustin 11:cada08fc8a70 148 ```
mbedAustin 11:cada08fc8a70 149
mbedAustin 11:cada08fc8a70 150 Normally, the enabler will update the registration automatically, but if you want to renew the registration before that, you can use this API.
mbedAustin 11:cada08fc8a70 151
mbedAustin 11:cada08fc8a70 152 **Success or failure callback**
mbedAustin 11:cada08fc8a70 153
mbedAustin 11:cada08fc8a70 154 If the update operation is successful, your application will receive the following callback:
mbedAustin 11:cada08fc8a70 155
mbedAustin 11:cada08fc8a70 156 ```
mbedAustin 11:cada08fc8a70 157 void registration_updated(M2MSecurity *const M2MServer& server)
mbedAustin 11:cada08fc8a70 158 ```
mbedAustin 11:cada08fc8a70 159
mbedAustin 11:cada08fc8a70 160 The `M2MSecurity *server_object` specifies to which mbed DS instance the client has just updated the registration and `M2MServer &server` contains the data related to mbed DS, including the Short ServerID and the client registration period.
mbedAustin 11:cada08fc8a70 161
mbedAustin 11:cada08fc8a70 162 If the update operation fails for some reason, you will receive the following callback:
mbedAustin 11:cada08fc8a70 163
mbedAustin 11:cada08fc8a70 164 ```
mbedAustin 11:cada08fc8a70 165 void error(M2MInterface::Error error)
mbedAustin 11:cada08fc8a70 166 ```
mbedAustin 11:cada08fc8a70 167
mbedAustin 11:cada08fc8a70 168 ### Deregister
mbedAustin 11:cada08fc8a70 169
mbedAustin 11:cada08fc8a70 170 The client can deregister from mbed DS when it no longer requires access to the server. When mbed DS receives the **Deregister** message it removes the device's registration information from its database. When the client needs mbed DS again, it will have to register again.
mbedAustin 11:cada08fc8a70 171
mbedAustin 11:cada08fc8a70 172 To deregister your endpoint client:
mbedAustin 11:cada08fc8a70 173
mbedAustin 11:cada08fc8a70 174 If the endpoint has multiple server registrations, you need to provide the `server_object` of the server where you would like to deregister your endpoint. Otherwise, if there is only one registration, you can pass `NULL` and the client will deregister the default registration.
mbedAustin 11:cada08fc8a70 175
mbedAustin 11:cada08fc8a70 176 ```
mbedAustin 11:cada08fc8a70 177 M2MInterface::unregister_object(M2MSecurity *object);
mbedAustin 11:cada08fc8a70 178 ```
mbedAustin 11:cada08fc8a70 179
mbedAustin 11:cada08fc8a70 180 **Success or failure callback**
mbedAustin 11:cada08fc8a70 181
mbedAustin 11:cada08fc8a70 182 Because this is an asynchronous operation, you will receive the result of this operation through a callback defined in `m2minterfaceobserver.h` in your application.
mbedAustin 11:cada08fc8a70 183
mbedAustin 11:cada08fc8a70 184 If the client is successfully deregistered from mbed DS, your application will receive the following callback:
mbedAustin 11:cada08fc8a70 185
mbedAustin 11:cada08fc8a70 186 ```
mbedAustin 11:cada08fc8a70 187 void object_unregistered(M2MSecurity *server_object)
mbedAustin 11:cada08fc8a70 188 ```
mbedAustin 11:cada08fc8a70 189
mbedAustin 11:cada08fc8a70 190 The `M2MSecurity *server_object` specifies from which mbed DS instance the client has just deregistered.
mbedAustin 11:cada08fc8a70 191
mbedAustin 11:cada08fc8a70 192 If the deregistration operation fails for some reason, you will receive the following callback:
mbedAustin 11:cada08fc8a70 193
mbedAustin 11:cada08fc8a70 194 ```
mbedAustin 11:cada08fc8a70 195 void error(M2MInterface::Error error)
mbedAustin 11:cada08fc8a70 196 ```
mbedAustin 11:cada08fc8a70 197
mbedAustin 11:cada08fc8a70 198 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.
mbedAustin 11:cada08fc8a70 199
mbedAustin 11:cada08fc8a70 200 ### Device Management and Service Enabler Interface
mbedAustin 11:cada08fc8a70 201
mbedAustin 11:cada08fc8a70 202 mbed DS uses the Device Management and Service Enabler Interface to access Object Instances and Resources available on the client. The interface provides this access through the following operations:
mbedAustin 11:cada08fc8a70 203
mbedAustin 11:cada08fc8a70 204 - **Create**
mbedAustin 11:cada08fc8a70 205 - **Delete**
mbedAustin 11:cada08fc8a70 206 - **Read**
mbedAustin 11:cada08fc8a70 207 - **Write**
mbedAustin 11:cada08fc8a70 208 - **Execute**
mbedAustin 11:cada08fc8a70 209 - **Write Attributes**
mbedAustin 11:cada08fc8a70 210
mbedAustin 11:cada08fc8a70 211 Currently, support for the Create and Delete actions is limited to Object Instances.
mbedAustin 11:cada08fc8a70 212
mbedAustin 11:cada08fc8a70 213 The Device Management and Service Enabler Interface supports the following data types:
mbedAustin 11:cada08fc8a70 214
mbedAustin 11:cada08fc8a70 215 - Text - for Resources.
mbedAustin 11:cada08fc8a70 216 - TLV - for Object and Object Instances.
mbedAustin 11:cada08fc8a70 217
mbedAustin 11:cada08fc8a70 218 ### Read
mbedAustin 11:cada08fc8a70 219
mbedAustin 11:cada08fc8a70 220 The Client API allows setting values to Resources, an array of Resource Instances, an Object Instance or all the Object Instances of an Object (TLV format supported). mbed DS can then read these values using the **Read** operation.
mbedAustin 11:cada08fc8a70 221
mbedAustin 11:cada08fc8a70 222 **Creating Resources**
mbedAustin 11:cada08fc8a70 223
mbedAustin 11:cada08fc8a70 224 There are two types of resources you can create:
mbedAustin 11:cada08fc8a70 225
mbedAustin 11:cada08fc8a70 226 - Static: you set the value of the resource once and it does not change during the course of operations.
mbedAustin 11:cada08fc8a70 227 - Dynamic: the value is expected to change during the course of operations. Therefore, the value is fetched from setter APIs every time the server requests a `GET` operation.
mbedAustin 11:cada08fc8a70 228
mbedAustin 11:cada08fc8a70 229 Here is an example of creating a custom static Resource:
mbedAustin 11:cada08fc8a70 230
mbedAustin 11:cada08fc8a70 231 ```
mbedAustin 11:cada08fc8a70 232 #include "mbed-client/m2mobject.h"
mbedAustin 11:cada08fc8a70 233 #include "mbed-client/m2mobjectinstance.h"
mbedAustin 11:cada08fc8a70 234 #include "mbed-client/m2mresource.h"
mbedAustin 11:cada08fc8a70 235 _object = M2MInterfaceFactory::create_object("Test");
mbedAustin 11:cada08fc8a70 236 if(_object) {
mbedAustin 11:cada08fc8a70 237 M2MObjectInstance* inst = _object->create_object_instance();
mbedAustin 11:cada08fc8a70 238 if(inst) {
mbedAustin 11:cada08fc8a70 239 inst->create_static_resource("S",
mbedAustin 11:cada08fc8a70 240 "ResourceTest",
mbedAustin 11:cada08fc8a70 241 STATIC_VALUE,
mbedAustin 11:cada08fc8a70 242 sizeof(STATIC_VALUE)-1);
mbedAustin 11:cada08fc8a70 243 ```
mbedAustin 11:cada08fc8a70 244
mbedAustin 11:cada08fc8a70 245 And here is an example of creating a custom dynamic Resource:
mbedAustin 11:cada08fc8a70 246
mbedAustin 11:cada08fc8a70 247 ```
mbedAustin 11:cada08fc8a70 248 #include "mbed-client/m2mobject.h"
mbedAustin 11:cada08fc8a70 249 #include "mbed-client/m2mobjectinstance.h"
mbedAustin 11:cada08fc8a70 250 #include "mbed-client/m2mresource.h"
mbedAustin 11:cada08fc8a70 251 _object = M2MInterfaceFactory::create_object("Test");
mbedAustin 11:cada08fc8a70 252 if(_object) {
mbedAustin 11:cada08fc8a70 253 M2MObjectInstance* inst = _object->create_object_instance();
mbedAustin 11:cada08fc8a70 254 if(inst) {
mbedAustin 11:cada08fc8a70 255 M2MResource* res = inst->create_dynamic_resource("D","ResourceTest",true);
mbedAustin 11:cada08fc8a70 256 char buffer[20];
mbedAustin 11:cada08fc8a70 257 int size = sprintf(buffer,"%d",_value);
mbedAustin 11:cada08fc8a70 258 res->set_operation(M2MBase::GET_PUT_ALLOWED);
mbedAustin 11:cada08fc8a70 259 res->set_value((const uint8_t*)buffer,
mbedAustin 11:cada08fc8a70 260 (const uint32_t)size);
mbedAustin 11:cada08fc8a70 261 ```
mbedAustin 11:cada08fc8a70 262
mbedAustin 11:cada08fc8a70 263 For more information on different resource functionalities, please check the API documentation for the M2MObject, M2MObjectInstance and M2MResource classes.
mbedAustin 11:cada08fc8a70 264
mbedAustin 11:cada08fc8a70 265 ### Write
mbedAustin 11:cada08fc8a70 266
mbedAustin 11:cada08fc8a70 267 The **Write** operation is used to overwrite the value of a Resource, an array of Resource Instances or multiple Resources from an Object Instance.
mbedAustin 11:cada08fc8a70 268
mbedAustin 11:cada08fc8a70 269 Whenever there is a valid `PUT` operation for any of the resources, the application will receive a callback:
mbedAustin 11:cada08fc8a70 270
mbedAustin 11:cada08fc8a70 271 ```
mbedAustin 11:cada08fc8a70 272 void value_updated(M2MBase *base, M2MBase::BaseType type)
mbedAustin 11:cada08fc8a70 273 ```
mbedAustin 11:cada08fc8a70 274
mbedAustin 11:cada08fc8a70 275 Where `M2MBase` is the object whose value has been updated and `M2MBase::BaseType` is the object type.
mbedAustin 11:cada08fc8a70 276
mbedAustin 11:cada08fc8a70 277 ### Write Attributes
mbedAustin 11:cada08fc8a70 278
mbedAustin 11:cada08fc8a70 279 Any readable Resource can have attributes that are considered during the **Observe** operation (explained below). The following attributes are used:
mbedAustin 11:cada08fc8a70 280
mbedAustin 11:cada08fc8a70 281 - Minimum Period (pmin)
mbedAustin 11:cada08fc8a70 282 - Maximum Period (pmax)
mbedAustin 11:cada08fc8a70 283 - Greater Than (gt)
mbedAustin 11:cada08fc8a70 284 - Less Than (lt)
mbedAustin 11:cada08fc8a70 285 - Step (st)
mbedAustin 11:cada08fc8a70 286
mbedAustin 11:cada08fc8a70 287 mbed DS sets the endpoint attribute values that are used to determine when the endpoint sends the Resource value to the server.
mbedAustin 11:cada08fc8a70 288
mbedAustin 11:cada08fc8a70 289 Check the LWM2M specification for details of all the possible **Write Attributes** defined for different types of Objects and Resources.
mbedAustin 11:cada08fc8a70 290
mbedAustin 11:cada08fc8a70 291 ### Execute
mbedAustin 11:cada08fc8a70 292
mbedAustin 11:cada08fc8a70 293 mbed DS uses the **Execute** operation to perform an action. This operation can only be performed on individual Resources.
mbedAustin 11:cada08fc8a70 294
mbedAustin 11:cada08fc8a70 295 **Note:** The client **must** return an error when the **Execute** operation is received for Object Instances or Resource Instances.
mbedAustin 11:cada08fc8a70 296
mbedAustin 11:cada08fc8a70 297 Here is an implementation example for the **Execute** operation:
mbedAustin 11:cada08fc8a70 298
mbedAustin 11:cada08fc8a70 299 ```
mbedAustin 11:cada08fc8a70 300 #include "mbed-client/m2mobject.h"
mbedAustin 11:cada08fc8a70 301 #include "mbed-client/m2mobjectinstance.h"
mbedAustin 11:cada08fc8a70 302 #include "mbed-client/m2mresource.h"
mbedAustin 11:cada08fc8a70 303
mbedAustin 11:cada08fc8a70 304 void M2MLWClient::execute_function(void */*argument*/) {
mbedAustin 11:cada08fc8a70 305 }
mbedAustin 11:cada08fc8a70 306
mbedAustin 11:cada08fc8a70 307 _object = M2MInterfaceFactory::create_object("Test");
mbedAustin 11:cada08fc8a70 308 if(_object) {
mbedAustin 11:cada08fc8a70 309 M2MObjectInstance* inst = _object->create_object_instance();
mbedAustin 11:cada08fc8a70 310 if(inst) {
mbedAustin 11:cada08fc8a70 311 M2MResource* res = inst->create_dynamic_resource("D","ResourceTest",true);
mbedAustin 11:cada08fc8a70 312 char buffer[20];
mbedAustin 11:cada08fc8a70 313 int size = sprintf(buffer,"%d",_value);
mbedAustin 11:cada08fc8a70 314 res->set_operation(M2MBase::GET_PUT_POST_ALLOWED);
mbedAustin 11:cada08fc8a70 315 res->set_value((const uint8_t*)buffer,
mbedAustin 11:cada08fc8a70 316 (const uint32_t)size);
mbedAustin 11:cada08fc8a70 317 res->set_execute_function(execute_callback(this,&M2MLWClient::execute_function));
mbedAustin 11:cada08fc8a70 318 ```
mbedAustin 11:cada08fc8a70 319
mbedAustin 11:cada08fc8a70 320 When the client receives the `POST` request for Execute from mbed DS for this resource, this function will be called and executed.
mbedAustin 11:cada08fc8a70 321
mbedAustin 11:cada08fc8a70 322 ### Information Reporting Interface
mbedAustin 11:cada08fc8a70 323
mbedAustin 11:cada08fc8a70 324 mbed DS uses the Information Reporting Interface to observe any changes in a registered Resource on the client, receiving notifications when new values are available.
mbedAustin 11:cada08fc8a70 325
mbedAustin 11:cada08fc8a70 326 The interface supports the following sub-features:
mbedAustin 11:cada08fc8a70 327
mbedAustin 11:cada08fc8a70 328 - Observe
mbedAustin 11:cada08fc8a70 329 - Notify
mbedAustin 11:cada08fc8a70 330 - Cancel
mbedAustin 11:cada08fc8a70 331
mbedAustin 11:cada08fc8a70 332 ### Observe
mbedAustin 11:cada08fc8a70 333
mbedAustin 11:cada08fc8a70 334 mbed DS initiates an observation request to change the value of a dynamic Resource.
mbedAustin 11:cada08fc8a70 335
mbedAustin 11:cada08fc8a70 336 **Tip:** Related parameters for the **Observe** operation are described in the [Write Attributes](#write-attributes) section.
mbedAustin 11:cada08fc8a70 337
mbedAustin 11:cada08fc8a70 338 To make your Resource observable, you need to set the Observable parameter of your object to `true`:
mbedAustin 11:cada08fc8a70 339
mbedAustin 11:cada08fc8a70 340 ```
mbedAustin 11:cada08fc8a70 341 object->set_observable(true);
mbedAustin 11:cada08fc8a70 342 ```
mbedAustin 11:cada08fc8a70 343
mbedAustin 11:cada08fc8a70 344 If you want a dynamic resource to be observable, do the following when creating the resource:
mbedAustin 11:cada08fc8a70 345
mbedAustin 11:cada08fc8a70 346 ```
mbedAustin 11:cada08fc8a70 347 M2MResource* create_dynamic_resource(const String &resource_name,
mbedAustin 11:cada08fc8a70 348 const String &resource_type,
mbedAustin 11:cada08fc8a70 349 M2MResourceInstance::ResourceType type,
mbedAustin 11:cada08fc8a70 350 bool observable,
mbedAustin 11:cada08fc8a70 351 bool multiple_instance =false);
mbedAustin 11:cada08fc8a70 352 ```
mbedAustin 11:cada08fc8a70 353
mbedAustin 11:cada08fc8a70 354 The mbed Client will handle the observation part once you have defined the Resources to be observable.
mbedAustin 11:cada08fc8a70 355
mbedAustin 11:cada08fc8a70 356 ### Notify
mbedAustin 11:cada08fc8a70 357
mbedAustin 11:cada08fc8a70 358 The client sends the **Notify** operation to mbed DS during a valid observation on a Resource, when the notification conditions are met.
mbedAustin 11:cada08fc8a70 359
mbedAustin 11:cada08fc8a70 360 ### Cancel
mbedAustin 11:cada08fc8a70 361
mbedAustin 11:cada08fc8a70 362 mbed DS sends the **Cancel Observation** operation to the client to end an observation relationship for an Object Instance or a Resource.
mbedAustin 11:cada08fc8a70 363
mbedAustin 11:cada08fc8a70 364 ## More Information
mbedAustin 11:cada08fc8a70 365
mbedAustin 11:cada08fc8a70 366 This API is based on OMA LWM2M specification. You can get the specification [here](http://technical.openmobilealliance.org/Technical/technical-information/release-program/current-releases/oma-lightweightm2m-v1-0).
mbedAustin 11:cada08fc8a70 367
mbedAustin 11:cada08fc8a70 368 ## How to use the API
mbedAustin 11:cada08fc8a70 369 More information on how to use the API effectively to create and configure Objects, Object Instances and Resources, can be found [here](Howto.md).
mbedAustin 11:cada08fc8a70 370
mbedAustin 11:cada08fc8a70 371 ## API documentation
mbedAustin 11:cada08fc8a70 372
mbedAustin 11:cada08fc8a70 373 You can generate Doxygen API documentation for these APIs from a doxy file present in the `doxygen` folder. You need to run the `doxygen` command from the `doxygen/` folder; it will generate a `docs` folder at the API source directory root level. The folder contains detailed documentation for each API.
mbedAustin 11:cada08fc8a70 374
mbedAustin 11:cada08fc8a70 375 ## Example application
mbedAustin 11:cada08fc8a70 376
mbedAustin 11:cada08fc8a70 377 An example application running on mbedOS is available [here](https://github.com/ARMmbed/mbed-client-examples).
mbedAustin 11:cada08fc8a70 378
mbedAustin 11:cada08fc8a70 379 An example application running on Ubuntu is available [here](https://github.com/ARMmbed/mbed-client-linux-example).
mbedAustin 11:cada08fc8a70 380