sandbox
/
mbed-client
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.
Fork of
mbed-client
by 
Christopher Haster
docs/Introduction.md@1:79b6cc67d8b4, 2016-01-22 (annotated)
- Committer:
- Christopher Haster
- Date:
- Fri Jan 22 14:57:00 2016 -0600
- Revision:
- 1:79b6cc67d8b4
- Child:
- 4:ae5178938864
Initial move of mbed-client to mercurial
Who changed what in which revision?
| User | Revision | Line number | New contents of line |
|---|---|---|---|
| Christopher Haster |
1:79b6cc67d8b4 | 1 | # mbed Client API |
| Christopher Haster |
1:79b6cc67d8b4 | 2 | |
| Christopher Haster |
1:79b6cc67d8b4 | 3 | ## Introduction |
| Christopher Haster |
1:79b6cc67d8b4 | 4 | |
| Christopher Haster |
1:79b6cc67d8b4 | 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). |
| Christopher Haster |
1:79b6cc67d8b4 | 6 | |
| Christopher Haster |
1:79b6cc67d8b4 | 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. |
| Christopher Haster |
1:79b6cc67d8b4 | 8 | |
| Christopher Haster |
1:79b6cc67d8b4 | 9 | The API is written in C++ to allow quick application development. |
| Christopher Haster |
1:79b6cc67d8b4 | 10 | |
| Christopher Haster |
1:79b6cc67d8b4 | 11 | ## mbed Client interfaces |
| Christopher Haster |
1:79b6cc67d8b4 | 12 | |
| Christopher Haster |
1:79b6cc67d8b4 | 13 | There are three interfaces between mbed DS and mbed Client: |
| Christopher Haster |
1:79b6cc67d8b4 | 14 | |
| Christopher Haster |
1:79b6cc67d8b4 | 15 | - Client registration and deregistration |
| Christopher Haster |
1:79b6cc67d8b4 | 16 | - Device management and service enablement |
| Christopher Haster |
1:79b6cc67d8b4 | 17 | - Information reporting |
| Christopher Haster |
1:79b6cc67d8b4 | 18 | |
| Christopher Haster |
1:79b6cc67d8b4 | 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). |
| Christopher Haster |
1:79b6cc67d8b4 | 20 | |
| Christopher Haster |
1:79b6cc67d8b4 | 21 | To create an interface for your endpoint: |
| Christopher Haster |
1:79b6cc67d8b4 | 22 | |
| Christopher Haster |
1:79b6cc67d8b4 | 23 | ``` |
| Christopher Haster |
1:79b6cc67d8b4 | 24 | #include "mbed-client/m2minterfacefactory.h" |
| Christopher Haster |
1:79b6cc67d8b4 | 25 | #include "mbed-client/m2minterface.h" |
| Christopher Haster |
1:79b6cc67d8b4 | 26 | |
| Christopher Haster |
1:79b6cc67d8b4 | 27 | M2MInterface* interface = M2MInterfaceFactory::create_interface(*this, |
| Christopher Haster |
1:79b6cc67d8b4 | 28 | "mbed-endpoint", |
| Christopher Haster |
1:79b6cc67d8b4 | 29 | "test", |
| Christopher Haster |
1:79b6cc67d8b4 | 30 | 3600, |
| Christopher Haster |
1:79b6cc67d8b4 | 31 | 5684, |
| Christopher Haster |
1:79b6cc67d8b4 | 32 | "", |
| Christopher Haster |
1:79b6cc67d8b4 | 33 | M2MInterface::UDP, |
| Christopher Haster |
1:79b6cc67d8b4 | 34 | M2MInterface::LwIP_IPv4, |
| Christopher Haster |
1:79b6cc67d8b4 | 35 | ""); |
| Christopher Haster |
1:79b6cc67d8b4 | 36 | ``` |
| Christopher Haster |
1:79b6cc67d8b4 | 37 | |
| Christopher Haster |
1:79b6cc67d8b4 | 38 | When you have created the interface, you can proceed to execute operations. |
| Christopher Haster |
1:79b6cc67d8b4 | 39 | |
| Christopher Haster |
1:79b6cc67d8b4 | 40 | ### Client Registration Interface |
| Christopher Haster |
1:79b6cc67d8b4 | 41 | |
| Christopher Haster |
1:79b6cc67d8b4 | 42 | The client uses the Client Registration Interface to register with mbed DS, update registration and deregister. |
| Christopher Haster |
1:79b6cc67d8b4 | 43 | |
| Christopher Haster |
1:79b6cc67d8b4 | 44 | Currently, only one-to-one client-server registration is supported. One-to-many client-server registrations will be supported in an upcoming release. |
| Christopher Haster |
1:79b6cc67d8b4 | 45 | |
| Christopher Haster |
1:79b6cc67d8b4 | 46 | The Client Registration Interface includes multiple sub-features. Currently supported: |
| Christopher Haster |
1:79b6cc67d8b4 | 47 | |
| Christopher Haster |
1:79b6cc67d8b4 | 48 | - Register |
| Christopher Haster |
1:79b6cc67d8b4 | 49 | - Update |
| Christopher Haster |
1:79b6cc67d8b4 | 50 | - Deregister |
| Christopher Haster |
1:79b6cc67d8b4 | 51 | |
| Christopher Haster |
1:79b6cc67d8b4 | 52 | ### The Register feature |
| Christopher Haster |
1:79b6cc67d8b4 | 53 | |
| Christopher Haster |
1:79b6cc67d8b4 | 54 | This API enables the client registration functionality. |
| Christopher Haster |
1:79b6cc67d8b4 | 55 | |
| Christopher Haster |
1:79b6cc67d8b4 | 56 | When registering, the client: |
| Christopher Haster |
1:79b6cc67d8b4 | 57 | |
| Christopher Haster |
1:79b6cc67d8b4 | 58 | * Performs the **Register** operation and provides parameters that mbed DS requires to register the client (for example End Point Name). |
| Christopher Haster |
1:79b6cc67d8b4 | 59 | |
| Christopher Haster |
1:79b6cc67d8b4 | 60 | * Maintains the registration and session (for example Lifetime, Queue Mode). |
| Christopher Haster |
1:79b6cc67d8b4 | 61 | |
| Christopher Haster |
1:79b6cc67d8b4 | 62 | * Provides information on the Objects the client supports and existing Object Instances in the client. |
| Christopher Haster |
1:79b6cc67d8b4 | 63 | |
| Christopher Haster |
1:79b6cc67d8b4 | 64 | #### Registering your client |
| Christopher Haster |
1:79b6cc67d8b4 | 65 | |
| Christopher Haster |
1:79b6cc67d8b4 | 66 | To provide information to mbed DS and issue the register command: |
| Christopher Haster |
1:79b6cc67d8b4 | 67 | |
| Christopher Haster |
1:79b6cc67d8b4 | 68 | First you need to create an mbed DS object. This object contains information about mbed DS, such as its address and security mode. |
| Christopher Haster |
1:79b6cc67d8b4 | 69 | |
| Christopher Haster |
1:79b6cc67d8b4 | 70 | ``` |
| Christopher Haster |
1:79b6cc67d8b4 | 71 | #include "mbed-client/m2msecurity.h" |
| Christopher Haster |
1:79b6cc67d8b4 | 72 | M2MSecurity *security = M2MInterfaceFactory::create_security(M2MSecurity::M2MServer); |
| Christopher Haster |
1:79b6cc67d8b4 | 73 | if(security) { |
| Christopher Haster |
1:79b6cc67d8b4 | 74 | security->set_resource_value(M2MSecurity::M2MServerUri, LWM2M_SERVER_ADDRESS); |
| Christopher Haster |
1:79b6cc67d8b4 | 75 | security->set_resource_value(M2MSecurity::BootstrapServer, 0); |
| Christopher Haster |
1:79b6cc67d8b4 | 76 | security->set_resource_value(M2MSecurity::SecurityMode, M2MSecurity::NoSecurity); |
| Christopher Haster |
1:79b6cc67d8b4 | 77 | } |
| Christopher Haster |
1:79b6cc67d8b4 | 78 | ``` |
| Christopher Haster |
1:79b6cc67d8b4 | 79 | |
| Christopher Haster |
1:79b6cc67d8b4 | 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. |
| Christopher Haster |
1:79b6cc67d8b4 | 81 | |
| Christopher Haster |
1:79b6cc67d8b4 | 82 | Create a secure mode operation as follows: |
| Christopher Haster |
1:79b6cc67d8b4 | 83 | |
| Christopher Haster |
1:79b6cc67d8b4 | 84 | ``` |
| Christopher Haster |
1:79b6cc67d8b4 | 85 | #include "mbed-client/m2msecurity.h" |
| Christopher Haster |
1:79b6cc67d8b4 | 86 | M2MSecurity *security = M2MInterfaceFactory::create_security(M2MSecurity::M2MServer); |
| Christopher Haster |
1:79b6cc67d8b4 | 87 | if(security) { |
| Christopher Haster |
1:79b6cc67d8b4 | 88 | security->set_resource_value(M2MSecurity::M2MServerUri, LWM2M_SERVER_ADDRESS); |
| Christopher Haster |
1:79b6cc67d8b4 | 89 | security->set_resource_value(M2MSecurity::BootstrapServer, 0); |
| Christopher Haster |
1:79b6cc67d8b4 | 90 | security->set_resource_value(M2MSecurity::SecurityMode, M2MSecurity::Certificate); |
| Christopher Haster |
1:79b6cc67d8b4 | 91 | security->set_resource_value(M2MSecurity::ServerPublicKey,<SERVER_CERT>,sizeof(<SERVER_CERT>)); |
| Christopher Haster |
1:79b6cc67d8b4 | 92 | security->set_resource_value(M2MSecurity::PublicKey,<CERT>,sizeof(<CERT>)); |
| Christopher Haster |
1:79b6cc67d8b4 | 93 | security->set_resource_value(M2MSecurity::Secretkey,<KEY>,sizeof(<KEY>)); |
| Christopher Haster |
1:79b6cc67d8b4 | 94 | } |
| Christopher Haster |
1:79b6cc67d8b4 | 95 | ``` |
| Christopher Haster |
1:79b6cc67d8b4 | 96 | |
| Christopher Haster |
1:79b6cc67d8b4 | 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. |
| Christopher Haster |
1:79b6cc67d8b4 | 98 | |
| Christopher Haster |
1:79b6cc67d8b4 | 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: |
| Christopher Haster |
1:79b6cc67d8b4 | 100 | |
| Christopher Haster |
1:79b6cc67d8b4 | 101 | ``` |
| Christopher Haster |
1:79b6cc67d8b4 | 102 | #include "mbed-client/m2mdevice.h" |
| Christopher Haster |
1:79b6cc67d8b4 | 103 | M2MDevice *device = M2MInterfaceFactory::create_device(); |
| Christopher Haster |
1:79b6cc67d8b4 | 104 | if(device) { |
| Christopher Haster |
1:79b6cc67d8b4 | 105 | device->create_resource(M2MDevice::Manufacturer,MANUFACTURER); |
| Christopher Haster |
1:79b6cc67d8b4 | 106 | device->create_resource(M2MDevice::DeviceType,TYPE); |
| Christopher Haster |
1:79b6cc67d8b4 | 107 | device->create_resource(M2MDevice::ModelNumber,MODEL_NUMBER); |
| Christopher Haster |
1:79b6cc67d8b4 | 108 | device->create_resource(M2MDevice::SerialNumber,SERIAL_NUMBER); |
| Christopher Haster |
1:79b6cc67d8b4 | 109 | } |
| Christopher Haster |
1:79b6cc67d8b4 | 110 | ``` |
| Christopher Haster |
1:79b6cc67d8b4 | 111 | |
| Christopher Haster |
1:79b6cc67d8b4 | 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. |
| Christopher Haster |
1:79b6cc67d8b4 | 113 | |
| Christopher Haster |
1:79b6cc67d8b4 | 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: |
| Christopher Haster |
1:79b6cc67d8b4 | 115 | |
| Christopher Haster |
1:79b6cc67d8b4 | 116 | ``` |
| Christopher Haster |
1:79b6cc67d8b4 | 117 | M2MInterface::register_object(M2MSecurity* register_object, M2MObjectList object_list); |
| Christopher Haster |
1:79b6cc67d8b4 | 118 | ``` |
| Christopher Haster |
1:79b6cc67d8b4 | 119 | |
| Christopher Haster |
1:79b6cc67d8b4 | 120 | **Success or failure callback** |
| Christopher Haster |
1:79b6cc67d8b4 | 121 | |
| Christopher Haster |
1:79b6cc67d8b4 | 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. |
| Christopher Haster |
1:79b6cc67d8b4 | 123 | |
| Christopher Haster |
1:79b6cc67d8b4 | 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: |
| Christopher Haster |
1:79b6cc67d8b4 | 125 | |
| Christopher Haster |
1:79b6cc67d8b4 | 126 | ``` |
| Christopher Haster |
1:79b6cc67d8b4 | 127 | void object_registered(M2MSecurity *server_object, const M2MServer& server) |
| Christopher Haster |
1:79b6cc67d8b4 | 128 | ``` |
| Christopher Haster |
1:79b6cc67d8b4 | 129 | |
| Christopher Haster |
1:79b6cc67d8b4 | 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. |
| Christopher Haster |
1:79b6cc67d8b4 | 131 | |
| Christopher Haster |
1:79b6cc67d8b4 | 132 | If the registration operation fails for some reason, you will receive the following callback: |
| Christopher Haster |
1:79b6cc67d8b4 | 133 | |
| Christopher Haster |
1:79b6cc67d8b4 | 134 | ``` |
| Christopher Haster |
1:79b6cc67d8b4 | 135 | void error(M2MInterface::Error error) |
| Christopher Haster |
1:79b6cc67d8b4 | 136 | ``` |
| Christopher Haster |
1:79b6cc67d8b4 | 137 | |
| Christopher Haster |
1:79b6cc67d8b4 | 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. |
| Christopher Haster |
1:79b6cc67d8b4 | 139 | |
| Christopher Haster |
1:79b6cc67d8b4 | 140 | ### Update |
| Christopher Haster |
1:79b6cc67d8b4 | 141 | |
| Christopher Haster |
1:79b6cc67d8b4 | 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. |
| Christopher Haster |
1:79b6cc67d8b4 | 143 | |
| Christopher Haster |
1:79b6cc67d8b4 | 144 | To update your registration: |
| Christopher Haster |
1:79b6cc67d8b4 | 145 | |
| Christopher Haster |
1:79b6cc67d8b4 | 146 | ``` |
| Christopher Haster |
1:79b6cc67d8b4 | 147 | M2MInterface::update_registration(M2MSecurity* security_object, const uint32_t lifetime) |
| Christopher Haster |
1:79b6cc67d8b4 | 148 | ``` |
| Christopher Haster |
1:79b6cc67d8b4 | 149 | |
| Christopher Haster |
1:79b6cc67d8b4 | 150 | Normally, the enabler will update the registration automatically, but if you want to renew the registration before that, you can use this API. |
| Christopher Haster |
1:79b6cc67d8b4 | 151 | |
| Christopher Haster |
1:79b6cc67d8b4 | 152 | **Success or failure callback** |
| Christopher Haster |
1:79b6cc67d8b4 | 153 | |
| Christopher Haster |
1:79b6cc67d8b4 | 154 | If the update operation is successful, your application will receive the following callback: |
| Christopher Haster |
1:79b6cc67d8b4 | 155 | |
| Christopher Haster |
1:79b6cc67d8b4 | 156 | ``` |
| Christopher Haster |
1:79b6cc67d8b4 | 157 | void registration_updated(M2MSecurity *const M2MServer& server) |
| Christopher Haster |
1:79b6cc67d8b4 | 158 | ``` |
| Christopher Haster |
1:79b6cc67d8b4 | 159 | |
| Christopher Haster |
1:79b6cc67d8b4 | 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. |
| Christopher Haster |
1:79b6cc67d8b4 | 161 | |
| Christopher Haster |
1:79b6cc67d8b4 | 162 | If the update operation fails for some reason, you will receive the following callback: |
| Christopher Haster |
1:79b6cc67d8b4 | 163 | |
| Christopher Haster |
1:79b6cc67d8b4 | 164 | ``` |
| Christopher Haster |
1:79b6cc67d8b4 | 165 | void error(M2MInterface::Error error) |
| Christopher Haster |
1:79b6cc67d8b4 | 166 | ``` |
| Christopher Haster |
1:79b6cc67d8b4 | 167 | |
| Christopher Haster |
1:79b6cc67d8b4 | 168 | ### Deregister |
| Christopher Haster |
1:79b6cc67d8b4 | 169 | |
| Christopher Haster |
1:79b6cc67d8b4 | 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. |
| Christopher Haster |
1:79b6cc67d8b4 | 171 | |
| Christopher Haster |
1:79b6cc67d8b4 | 172 | To deregister your endpoint client: |
| Christopher Haster |
1:79b6cc67d8b4 | 173 | |
| Christopher Haster |
1:79b6cc67d8b4 | 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. |
| Christopher Haster |
1:79b6cc67d8b4 | 175 | |
| Christopher Haster |
1:79b6cc67d8b4 | 176 | ``` |
| Christopher Haster |
1:79b6cc67d8b4 | 177 | M2MInterface::unregister_object(M2MSecurity *object); |
| Christopher Haster |
1:79b6cc67d8b4 | 178 | ``` |
| Christopher Haster |
1:79b6cc67d8b4 | 179 | |
| Christopher Haster |
1:79b6cc67d8b4 | 180 | **Success or failure callback** |
| Christopher Haster |
1:79b6cc67d8b4 | 181 | |
| Christopher Haster |
1:79b6cc67d8b4 | 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. |
| Christopher Haster |
1:79b6cc67d8b4 | 183 | |
| Christopher Haster |
1:79b6cc67d8b4 | 184 | If the client is successfully deregistered from mbed DS, your application will receive the following callback: |
| Christopher Haster |
1:79b6cc67d8b4 | 185 | |
| Christopher Haster |
1:79b6cc67d8b4 | 186 | ``` |
| Christopher Haster |
1:79b6cc67d8b4 | 187 | void object_unregistered(M2MSecurity *server_object) |
| Christopher Haster |
1:79b6cc67d8b4 | 188 | ``` |
| Christopher Haster |
1:79b6cc67d8b4 | 189 | |
| Christopher Haster |
1:79b6cc67d8b4 | 190 | The `M2MSecurity *server_object` specifies from which mbed DS instance the client has just deregistered. |
| Christopher Haster |
1:79b6cc67d8b4 | 191 | |
| Christopher Haster |
1:79b6cc67d8b4 | 192 | If the deregistration operation fails for some reason, you will receive the following callback: |
| Christopher Haster |
1:79b6cc67d8b4 | 193 | |
| Christopher Haster |
1:79b6cc67d8b4 | 194 | ``` |
| Christopher Haster |
1:79b6cc67d8b4 | 195 | void error(M2MInterface::Error error) |
| Christopher Haster |
1:79b6cc67d8b4 | 196 | ``` |
| Christopher Haster |
1:79b6cc67d8b4 | 197 | |
| Christopher Haster |
1:79b6cc67d8b4 | 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. |
| Christopher Haster |
1:79b6cc67d8b4 | 199 | |
| Christopher Haster |
1:79b6cc67d8b4 | 200 | ### Device Management and Service Enabler Interface |
| Christopher Haster |
1:79b6cc67d8b4 | 201 | |
| Christopher Haster |
1:79b6cc67d8b4 | 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: |
| Christopher Haster |
1:79b6cc67d8b4 | 203 | |
| Christopher Haster |
1:79b6cc67d8b4 | 204 | - **Create** |
| Christopher Haster |
1:79b6cc67d8b4 | 205 | - **Delete** |
| Christopher Haster |
1:79b6cc67d8b4 | 206 | - **Read** |
| Christopher Haster |
1:79b6cc67d8b4 | 207 | - **Write** |
| Christopher Haster |
1:79b6cc67d8b4 | 208 | - **Execute** |
| Christopher Haster |
1:79b6cc67d8b4 | 209 | - **Write Attributes** |
| Christopher Haster |
1:79b6cc67d8b4 | 210 | |
| Christopher Haster |
1:79b6cc67d8b4 | 211 | Currently, support for the Create and Delete actions is limited to Object Instances. |
| Christopher Haster |
1:79b6cc67d8b4 | 212 | |
| Christopher Haster |
1:79b6cc67d8b4 | 213 | The Device Management and Service Enabler Interface supports the following data types: |
| Christopher Haster |
1:79b6cc67d8b4 | 214 | |
| Christopher Haster |
1:79b6cc67d8b4 | 215 | - Text - for Resources. |
| Christopher Haster |
1:79b6cc67d8b4 | 216 | - TLV - for Object and Object Instances. |
| Christopher Haster |
1:79b6cc67d8b4 | 217 | |
| Christopher Haster |
1:79b6cc67d8b4 | 218 | ### Read |
| Christopher Haster |
1:79b6cc67d8b4 | 219 | |
| Christopher Haster |
1:79b6cc67d8b4 | 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. |
| Christopher Haster |
1:79b6cc67d8b4 | 221 | |
| Christopher Haster |
1:79b6cc67d8b4 | 222 | **Creating Resources** |
| Christopher Haster |
1:79b6cc67d8b4 | 223 | |
| Christopher Haster |
1:79b6cc67d8b4 | 224 | There are two types of resources you can create: |
| Christopher Haster |
1:79b6cc67d8b4 | 225 | |
| Christopher Haster |
1:79b6cc67d8b4 | 226 | - Static: you set the value of the resource once and it does not change during the course of operations. |
| Christopher Haster |
1:79b6cc67d8b4 | 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. |
| Christopher Haster |
1:79b6cc67d8b4 | 228 | |
| Christopher Haster |
1:79b6cc67d8b4 | 229 | Here is an example of creating a custom static Resource: |
| Christopher Haster |
1:79b6cc67d8b4 | 230 | |
| Christopher Haster |
1:79b6cc67d8b4 | 231 | ``` |
| Christopher Haster |
1:79b6cc67d8b4 | 232 | #include "mbed-client/m2mobject.h" |
| Christopher Haster |
1:79b6cc67d8b4 | 233 | #include "mbed-client/m2mobjectinstance.h" |
| Christopher Haster |
1:79b6cc67d8b4 | 234 | #include "mbed-client/m2mresource.h" |
| Christopher Haster |
1:79b6cc67d8b4 | 235 | _object = M2MInterfaceFactory::create_object("Test"); |
| Christopher Haster |
1:79b6cc67d8b4 | 236 | if(_object) { |
| Christopher Haster |
1:79b6cc67d8b4 | 237 | M2MObjectInstance* inst = _object->create_object_instance(); |
| Christopher Haster |
1:79b6cc67d8b4 | 238 | if(inst) { |
| Christopher Haster |
1:79b6cc67d8b4 | 239 | inst->create_static_resource("S", |
| Christopher Haster |
1:79b6cc67d8b4 | 240 | "ResourceTest", |
| Christopher Haster |
1:79b6cc67d8b4 | 241 | STATIC_VALUE, |
| Christopher Haster |
1:79b6cc67d8b4 | 242 | sizeof(STATIC_VALUE)-1); |
| Christopher Haster |
1:79b6cc67d8b4 | 243 | ``` |
| Christopher Haster |
1:79b6cc67d8b4 | 244 | |
| Christopher Haster |
1:79b6cc67d8b4 | 245 | And here is an example of creating a custom dynamic Resource: |
| Christopher Haster |
1:79b6cc67d8b4 | 246 | |
| Christopher Haster |
1:79b6cc67d8b4 | 247 | ``` |
| Christopher Haster |
1:79b6cc67d8b4 | 248 | #include "mbed-client/m2mobject.h" |
| Christopher Haster |
1:79b6cc67d8b4 | 249 | #include "mbed-client/m2mobjectinstance.h" |
| Christopher Haster |
1:79b6cc67d8b4 | 250 | #include "mbed-client/m2mresource.h" |
| Christopher Haster |
1:79b6cc67d8b4 | 251 | _object = M2MInterfaceFactory::create_object("Test"); |
| Christopher Haster |
1:79b6cc67d8b4 | 252 | if(_object) { |
| Christopher Haster |
1:79b6cc67d8b4 | 253 | M2MObjectInstance* inst = _object->create_object_instance(); |
| Christopher Haster |
1:79b6cc67d8b4 | 254 | if(inst) { |
| Christopher Haster |
1:79b6cc67d8b4 | 255 | M2MResource* res = inst->create_dynamic_resource("D","ResourceTest",true); |
| Christopher Haster |
1:79b6cc67d8b4 | 256 | char buffer[20]; |
| Christopher Haster |
1:79b6cc67d8b4 | 257 | int size = sprintf(buffer,"%d",_value); |
| Christopher Haster |
1:79b6cc67d8b4 | 258 | res->set_operation(M2MBase::GET_PUT_ALLOWED); |
| Christopher Haster |
1:79b6cc67d8b4 | 259 | res->set_value((const uint8_t*)buffer, |
| Christopher Haster |
1:79b6cc67d8b4 | 260 | (const uint32_t)size); |
| Christopher Haster |
1:79b6cc67d8b4 | 261 | ``` |
| Christopher Haster |
1:79b6cc67d8b4 | 262 | |
| Christopher Haster |
1:79b6cc67d8b4 | 263 | For more information on different resource functionalities, please check the API documentation for the M2MObject, M2MObjectInstance and M2MResource classes. |
| Christopher Haster |
1:79b6cc67d8b4 | 264 | |
| Christopher Haster |
1:79b6cc67d8b4 | 265 | ### Write |
| Christopher Haster |
1:79b6cc67d8b4 | 266 | |
| Christopher Haster |
1:79b6cc67d8b4 | 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. |
| Christopher Haster |
1:79b6cc67d8b4 | 268 | |
| Christopher Haster |
1:79b6cc67d8b4 | 269 | Whenever there is a valid `PUT` operation for any of the resources, the application will receive a callback: |
| Christopher Haster |
1:79b6cc67d8b4 | 270 | |
| Christopher Haster |
1:79b6cc67d8b4 | 271 | ``` |
| Christopher Haster |
1:79b6cc67d8b4 | 272 | void value_updated(M2MBase *base, M2MBase::BaseType type) |
| Christopher Haster |
1:79b6cc67d8b4 | 273 | ``` |
| Christopher Haster |
1:79b6cc67d8b4 | 274 | |
| Christopher Haster |
1:79b6cc67d8b4 | 275 | Where `M2MBase` is the object whose value has been updated and `M2MBase::BaseType` is the object type. |
| Christopher Haster |
1:79b6cc67d8b4 | 276 | |
| Christopher Haster |
1:79b6cc67d8b4 | 277 | ### Write Attributes |
| Christopher Haster |
1:79b6cc67d8b4 | 278 | |
| Christopher Haster |
1:79b6cc67d8b4 | 279 | Any readable Resource can have attributes that are considered during the **Observe** operation (explained below). The following attributes are used: |
| Christopher Haster |
1:79b6cc67d8b4 | 280 | |
| Christopher Haster |
1:79b6cc67d8b4 | 281 | - Minimum Period (pmin) |
| Christopher Haster |
1:79b6cc67d8b4 | 282 | - Maximum Period (pmax) |
| Christopher Haster |
1:79b6cc67d8b4 | 283 | - Greater Than (gt) |
| Christopher Haster |
1:79b6cc67d8b4 | 284 | - Less Than (lt) |
| Christopher Haster |
1:79b6cc67d8b4 | 285 | - Step (st) |
| Christopher Haster |
1:79b6cc67d8b4 | 286 | |
| Christopher Haster |
1:79b6cc67d8b4 | 287 | mbed DS sets the endpoint attribute values that are used to determine when the endpoint sends the Resource value to the server. |
| Christopher Haster |
1:79b6cc67d8b4 | 288 | |
| Christopher Haster |
1:79b6cc67d8b4 | 289 | Check the LWM2M specification for details of all the possible **Write Attributes** defined for different types of Objects and Resources. |
| Christopher Haster |
1:79b6cc67d8b4 | 290 | |
| Christopher Haster |
1:79b6cc67d8b4 | 291 | ### Execute |
| Christopher Haster |
1:79b6cc67d8b4 | 292 | |
| Christopher Haster |
1:79b6cc67d8b4 | 293 | mbed DS uses the **Execute** operation to perform an action. This operation can only be performed on individual Resources. |
| Christopher Haster |
1:79b6cc67d8b4 | 294 | |
| Christopher Haster |
1:79b6cc67d8b4 | 295 | **Note:** The client **must** return an error when the **Execute** operation is received for Object Instances or Resource Instances. |
| Christopher Haster |
1:79b6cc67d8b4 | 296 | |
| Christopher Haster |
1:79b6cc67d8b4 | 297 | Here is an implementation example for the **Execute** operation: |
| Christopher Haster |
1:79b6cc67d8b4 | 298 | |
| Christopher Haster |
1:79b6cc67d8b4 | 299 | ``` |
| Christopher Haster |
1:79b6cc67d8b4 | 300 | #include "mbed-client/m2mobject.h" |
| Christopher Haster |
1:79b6cc67d8b4 | 301 | #include "mbed-client/m2mobjectinstance.h" |
| Christopher Haster |
1:79b6cc67d8b4 | 302 | #include "mbed-client/m2mresource.h" |
| Christopher Haster |
1:79b6cc67d8b4 | 303 | |
| Christopher Haster |
1:79b6cc67d8b4 | 304 | void M2MLWClient::execute_function(void */*argument*/) { |
| Christopher Haster |
1:79b6cc67d8b4 | 305 | } |
| Christopher Haster |
1:79b6cc67d8b4 | 306 | |
| Christopher Haster |
1:79b6cc67d8b4 | 307 | _object = M2MInterfaceFactory::create_object("Test"); |
| Christopher Haster |
1:79b6cc67d8b4 | 308 | if(_object) { |
| Christopher Haster |
1:79b6cc67d8b4 | 309 | M2MObjectInstance* inst = _object->create_object_instance(); |
| Christopher Haster |
1:79b6cc67d8b4 | 310 | if(inst) { |
| Christopher Haster |
1:79b6cc67d8b4 | 311 | M2MResource* res = inst->create_dynamic_resource("D","ResourceTest",true); |
| Christopher Haster |
1:79b6cc67d8b4 | 312 | char buffer[20]; |
| Christopher Haster |
1:79b6cc67d8b4 | 313 | int size = sprintf(buffer,"%d",_value); |
| Christopher Haster |
1:79b6cc67d8b4 | 314 | res->set_operation(M2MBase::GET_PUT_POST_ALLOWED); |
| Christopher Haster |
1:79b6cc67d8b4 | 315 | res->set_value((const uint8_t*)buffer, |
| Christopher Haster |
1:79b6cc67d8b4 | 316 | (const uint32_t)size); |
| Christopher Haster |
1:79b6cc67d8b4 | 317 | res->set_execute_function(execute_callback(this,&M2MLWClient::execute_function)); |
| Christopher Haster |
1:79b6cc67d8b4 | 318 | ``` |
| Christopher Haster |
1:79b6cc67d8b4 | 319 | |
| Christopher Haster |
1:79b6cc67d8b4 | 320 | When the client receives the `POST` request for Execute from mbed DS for this resource, this function will be called and executed. |
| Christopher Haster |
1:79b6cc67d8b4 | 321 | |
| Christopher Haster |
1:79b6cc67d8b4 | 322 | ### Information Reporting Interface |
| Christopher Haster |
1:79b6cc67d8b4 | 323 | |
| Christopher Haster |
1:79b6cc67d8b4 | 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. |
| Christopher Haster |
1:79b6cc67d8b4 | 325 | |
| Christopher Haster |
1:79b6cc67d8b4 | 326 | The interface supports the following sub-features: |
| Christopher Haster |
1:79b6cc67d8b4 | 327 | |
| Christopher Haster |
1:79b6cc67d8b4 | 328 | - Observe |
| Christopher Haster |
1:79b6cc67d8b4 | 329 | - Notify |
| Christopher Haster |
1:79b6cc67d8b4 | 330 | - Cancel |
| Christopher Haster |
1:79b6cc67d8b4 | 331 | |
| Christopher Haster |
1:79b6cc67d8b4 | 332 | ### Observe |
| Christopher Haster |
1:79b6cc67d8b4 | 333 | |
| Christopher Haster |
1:79b6cc67d8b4 | 334 | mbed DS initiates an observation request to change the value of a dynamic Resource. |
| Christopher Haster |
1:79b6cc67d8b4 | 335 | |
| Christopher Haster |
1:79b6cc67d8b4 | 336 | **Tip:** Related parameters for the **Observe** operation are described in the [Write Attributes](#write-attributes) section. |
| Christopher Haster |
1:79b6cc67d8b4 | 337 | |
| Christopher Haster |
1:79b6cc67d8b4 | 338 | To make your Resource observable, you need to set the Observable parameter of your object to `true`: |
| Christopher Haster |
1:79b6cc67d8b4 | 339 | |
| Christopher Haster |
1:79b6cc67d8b4 | 340 | ``` |
| Christopher Haster |
1:79b6cc67d8b4 | 341 | object->set_observable(true); |
| Christopher Haster |
1:79b6cc67d8b4 | 342 | ``` |
| Christopher Haster |
1:79b6cc67d8b4 | 343 | |
| Christopher Haster |
1:79b6cc67d8b4 | 344 | If you want a dynamic resource to be observable, do the following when creating the resource: |
| Christopher Haster |
1:79b6cc67d8b4 | 345 | |
| Christopher Haster |
1:79b6cc67d8b4 | 346 | ``` |
| Christopher Haster |
1:79b6cc67d8b4 | 347 | M2MResource* create_dynamic_resource(const String &resource_name, |
| Christopher Haster |
1:79b6cc67d8b4 | 348 | const String &resource_type, |
| Christopher Haster |
1:79b6cc67d8b4 | 349 | M2MResourceInstance::ResourceType type, |
| Christopher Haster |
1:79b6cc67d8b4 | 350 | bool observable, |
| Christopher Haster |
1:79b6cc67d8b4 | 351 | bool multiple_instance =false); |
| Christopher Haster |
1:79b6cc67d8b4 | 352 | ``` |
| Christopher Haster |
1:79b6cc67d8b4 | 353 | |
| Christopher Haster |
1:79b6cc67d8b4 | 354 | The mbed Client will handle the observation part once you have defined the Resources to be observable. |
| Christopher Haster |
1:79b6cc67d8b4 | 355 | |
| Christopher Haster |
1:79b6cc67d8b4 | 356 | ### Notify |
| Christopher Haster |
1:79b6cc67d8b4 | 357 | |
| Christopher Haster |
1:79b6cc67d8b4 | 358 | The client sends the **Notify** operation to mbed DS during a valid observation on a Resource, when the notification conditions are met. |
| Christopher Haster |
1:79b6cc67d8b4 | 359 | |
| Christopher Haster |
1:79b6cc67d8b4 | 360 | ### Cancel |
| Christopher Haster |
1:79b6cc67d8b4 | 361 | |
| Christopher Haster |
1:79b6cc67d8b4 | 362 | mbed DS sends the **Cancel Observation** operation to the client to end an observation relationship for an Object Instance or a Resource. |
| Christopher Haster |
1:79b6cc67d8b4 | 363 | |
| Christopher Haster |
1:79b6cc67d8b4 | 364 | ## More Information |
| Christopher Haster |
1:79b6cc67d8b4 | 365 | |
| Christopher Haster |
1:79b6cc67d8b4 | 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). |
| Christopher Haster |
1:79b6cc67d8b4 | 367 | |
| Christopher Haster |
1:79b6cc67d8b4 | 368 | ## How to use the API |
| Christopher Haster |
1:79b6cc67d8b4 | 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). |
| Christopher Haster |
1:79b6cc67d8b4 | 370 | |
| Christopher Haster |
1:79b6cc67d8b4 | 371 | ## API documentation |
| Christopher Haster |
1:79b6cc67d8b4 | 372 | |
| Christopher Haster |
1:79b6cc67d8b4 | 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. |
| Christopher Haster |
1:79b6cc67d8b4 | 374 | |
| Christopher Haster |
1:79b6cc67d8b4 | 375 | ## Example application |
| Christopher Haster |
1:79b6cc67d8b4 | 376 | |
| Christopher Haster |
1:79b6cc67d8b4 | 377 | An example application running on mbedOS is available [here](https://github.com/ARMmbed/mbed-client-examples). |
| Christopher Haster |
1:79b6cc67d8b4 | 378 | |
| Christopher Haster |
1:79b6cc67d8b4 | 379 | An example application running on Ubuntu is available [here](https://github.com/ARMmbed/mbed-client-linux-example). |
| Christopher Haster |
1:79b6cc67d8b4 | 380 |