Ram Gandikota / Mbed OS IOTMetronome

FRDM K64F Metronome

mbed-client/docs/Howto.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 # How to use the mbed Client API
ram54288 0:dbad57390bd1 2
ram54288 0:dbad57390bd1 3 This section explains how to use our C++ API to create and configure different types of Objects, Object Instances and Resources for mbed Client to comply with the OMA LWM2M specifications. These resources can then be communicated to mbed Device Server.
ram54288 0:dbad57390bd1 4
ram54288 0:dbad57390bd1 5 <span class="notes">**Note:** The API complies with the OMA LWM2M specifications.</span>
ram54288 0:dbad57390bd1 6
ram54288 0:dbad57390bd1 7 As per the OMA LWM2M specification:
ram54288 0:dbad57390bd1 8
ram54288 0:dbad57390bd1 9 - The client must have defined Objects, under which it can create Object Instances.
ram54288 0:dbad57390bd1 10 - The client must have created Object Instances under Objects, which will eventually contain Resources.
ram54288 0:dbad57390bd1 11 - The client must have Resources under Object Instances which belong to Objects.
ram54288 0:dbad57390bd1 12 - The client must have created Resources under Object Instance. You can create M2MResource from the M2MObjectInstance class.
ram54288 0:dbad57390bd1 13 - The client must have created Resource Instances under Resources. You can create M2MResourceInstance from the M2MObjectInstance class.
ram54288 0:dbad57390bd1 14
ram54288 0:dbad57390bd1 15 Read the API doxygen documentation [here](https://docs.mbed.com/docs/mbed-client-guide/en/latest/api/index.html).
ram54288 0:dbad57390bd1 16
ram54288 0:dbad57390bd1 17 ## How to create and configure Objects
ram54288 0:dbad57390bd1 18
ram54288 0:dbad57390bd1 19 With this API, you can create and configure the following Objects:
ram54288 0:dbad57390bd1 20
ram54288 0:dbad57390bd1 21 - [Device Objects](#device-object)
ram54288 0:dbad57390bd1 22 - [Security Objects](#security-object)
ram54288 0:dbad57390bd1 23 - [Custom Objects](#custom-object)
ram54288 0:dbad57390bd1 24
ram54288 0:dbad57390bd1 25 The M2MObject class is derived from the M2MBase class, so all the public methods can be used from the M2MObject and its derived classes.
ram54288 0:dbad57390bd1 26
ram54288 0:dbad57390bd1 27 ### Creating OMA-defined Objects
ram54288 0:dbad57390bd1 28
ram54288 0:dbad57390bd1 29 #### Device Object
ram54288 0:dbad57390bd1 30
ram54288 0:dbad57390bd1 31 To create a Device Object:
ram54288 0:dbad57390bd1 32
ram54288 0:dbad57390bd1 33 `static M2MDevice *create_device();`
ram54288 0:dbad57390bd1 34
ram54288 0:dbad57390bd1 35 Because there can be only one instance of M2MDevice, it is a static class and you can delete it as follows:
ram54288 0:dbad57390bd1 36
ram54288 0:dbad57390bd1 37 `M2MDevice::delete_instance();`
ram54288 0:dbad57390bd1 38
ram54288 0:dbad57390bd1 39 Check the [M2MDevice class documentation](https://docs.mbed.com/docs/mbed-client-guide/en/latest/api/m2mdevice_8h.html) to see how to configure the Device Object.
ram54288 0:dbad57390bd1 40
ram54288 0:dbad57390bd1 41 #### Security Object
ram54288 0:dbad57390bd1 42
ram54288 0:dbad57390bd1 43 To create a Security Object:
ram54288 0:dbad57390bd1 44
ram54288 0:dbad57390bd1 45 `static M2MSecurity *create_security(M2MSecurity::ServerType server_type);`
ram54288 0:dbad57390bd1 46
ram54288 0:dbad57390bd1 47 You can create a Bootstrap or normal mbed Device Server by passing the appropriate `enum` value.
ram54288 0:dbad57390bd1 48
ram54288 0:dbad57390bd1 49 Check the [M2MSecurity class documentation](https://docs.mbed.com/docs/mbed-client-guide/en/latest/api/m2msecurity_8h.html) to see how to configure the Security Object, as well as how to create appropriate Resources and assign values to them.
ram54288 0:dbad57390bd1 50
ram54288 0:dbad57390bd1 51 #### Custom Object
ram54288 0:dbad57390bd1 52
ram54288 0:dbad57390bd1 53 For a Custom Object, you need to pass the name of the Object that you would like to create (for example `Test`); this will create an Object with that name in mbed Device Server.
ram54288 0:dbad57390bd1 54
ram54288 0:dbad57390bd1 55 To create an M2MObject:
ram54288 0:dbad57390bd1 56
ram54288 0:dbad57390bd1 57 `static M2MObject *create_object(const String &name);`
ram54288 0:dbad57390bd1 58
ram54288 0:dbad57390bd1 59 #### Configuring the Object
ram54288 0:dbad57390bd1 60
ram54288 0:dbad57390bd1 61 Once you have created an Object (whether OMA-specific or custom), you can configure various parameters in it to control or modify communication with mbed Device Server.
ram54288 0:dbad57390bd1 62
ram54288 0:dbad57390bd1 63 ```
ram54288 0:dbad57390bd1 64 M2MObject * _object = M2MInterfaceFactory::create_object("Test");
ram54288 0:dbad57390bd1 65 if(_object) {
ram54288 0:dbad57390bd1 66 _object->set_register_uri(true); // The registration message explicitly sends this object path as registered resource such as /Test.
ram54288 0:dbad57390bd1 67 }
ram54288 0:dbad57390bd1 68 ```
ram54288 0:dbad57390bd1 69
ram54288 0:dbad57390bd1 70 Here, we discuss a few of the most important parameters, which you must configure properly to work with the Objects.
ram54288 0:dbad57390bd1 71
ram54288 0:dbad57390bd1 72 ##### Setting Operation Mode
ram54288 0:dbad57390bd1 73
ram54288 0:dbad57390bd1 74 To set the operation mode of the Objects so that they can handle `GET`, `PUT`, `POST`, `DELETE` or a combination of these requests coming from mbed Device Server:
ram54288 0:dbad57390bd1 75
ram54288 0:dbad57390bd1 76 ```
ram54288 0:dbad57390bd1 77 virtual void set_operation(M2MBase::Operation operation);
ram54288 0:dbad57390bd1 78 _object->set_operation(M2MBase::GET_PUT_POST_ALLOWED); // This defines the REST operations that can be performed on this object.
ram54288 0:dbad57390bd1 79 ```
ram54288 0:dbad57390bd1 80
ram54288 0:dbad57390bd1 81 ##### Setting Observable Mode
ram54288 0:dbad57390bd1 82
ram54288 0:dbad57390bd1 83 To set the Object to be an observable resource:
ram54288 0:dbad57390bd1 84
ram54288 0:dbad57390bd1 85 `virtual void set_observable(bool observable);`
ram54288 0:dbad57390bd1 86
ram54288 0:dbad57390bd1 87 By default, all the created objects are non-observable. You can set them to be observable or not observable using this API.
ram54288 0:dbad57390bd1 88
ram54288 0:dbad57390bd1 89 ```
ram54288 0:dbad57390bd1 90 _object->set_observable(true); // The object can be observed from server.
ram54288 0:dbad57390bd1 91 _object->set_observable(false); // The object cannot be observed from server.
ram54288 0:dbad57390bd1 92 ```
ram54288 0:dbad57390bd1 93
ram54288 0:dbad57390bd1 94 ##### Setting CoAP content type
ram54288 0:dbad57390bd1 95
ram54288 0:dbad57390bd1 96 Currently, the only available content type is the OMA TLV type. The OMA TLV type works only for Objects with a numeric value. For example, if you are creating a custom Object it must be of a numeric type such as `100`.
ram54288 0:dbad57390bd1 97
ram54288 0:dbad57390bd1 98 `M2MObject * _object = M2MInterfaceFactory::create_object("100");`
ram54288 0:dbad57390bd1 99
ram54288 0:dbad57390bd1 100 By default, all the numeric objects are assigned the CoAP content type of `99` by mbed Client but if you want your Object to assign any other CoAP content type, for example 120, you can do that by setting the object's CoAP content type as shown below:
ram54288 0:dbad57390bd1 101
ram54288 0:dbad57390bd1 102 ```
ram54288 0:dbad57390bd1 103 virtual void set_coap_content_type(const uint8_t content_type);
ram54288 0:dbad57390bd1 104 _object->set_coap_content_type(120);
ram54288 0:dbad57390bd1 105 ```
ram54288 0:dbad57390bd1 106
ram54288 0:dbad57390bd1 107 <span class="tips">**Tip:** In future releases, we will introduce support for the JSON content types.</span>
ram54288 0:dbad57390bd1 108
ram54288 0:dbad57390bd1 109 ## How to create and configure Object Instances
ram54288 0:dbad57390bd1 110
ram54288 0:dbad57390bd1 111 With this API, you can create and configure the following Object Instances:
ram54288 0:dbad57390bd1 112
ram54288 0:dbad57390bd1 113 - [Device Object Instance](#device-object-instance)
ram54288 0:dbad57390bd1 114 - [Security Object Instance](#security-object-instance)
ram54288 0:dbad57390bd1 115 - [Custom Object Instance](#custom-object-instance)
ram54288 0:dbad57390bd1 116
ram54288 0:dbad57390bd1 117 The `M2MObjectInstance` class is derived from the `M2MBase` class, so all the public methods from `M2MObjectInstance` and its derived classes can be used.
ram54288 0:dbad57390bd1 118
ram54288 0:dbad57390bd1 119 ### Creating an OMA-defined Object Instance
ram54288 0:dbad57390bd1 120
ram54288 0:dbad57390bd1 121 #### Device Object Instance
ram54288 0:dbad57390bd1 122
ram54288 0:dbad57390bd1 123 Because there can only be one instance for the Device Object, the Object Instance is automatically created when creating an M2MDevice Object.
ram54288 0:dbad57390bd1 124
ram54288 0:dbad57390bd1 125 #### Security Object Instance
ram54288 0:dbad57390bd1 126
ram54288 0:dbad57390bd1 127 Because there can only be one instance for the Security Object, the Object Instance is automatically created when creating an M2MDevice Object based on a selected server type.
ram54288 0:dbad57390bd1 128
ram54288 0:dbad57390bd1 129 #### Custom Object Instances
ram54288 0:dbad57390bd1 130
ram54288 0:dbad57390bd1 131 Object Instances need IDs. Normally, the IDs start from '0' and increment,
ram54288 0:dbad57390bd1 132 so the Object Instance structure on the mbed Device Server side would look like this:
ram54288 0:dbad57390bd1 133
ram54288 0:dbad57390bd1 134 `Object/Object Instance ID`
ram54288 0:dbad57390bd1 135
ram54288 0:dbad57390bd1 136 When you create an Object Instance, you therefore need to pass the ID that you would like to create. For example, if you pass `0`, you get an object `/Test/0` on mbed Device Server.
ram54288 0:dbad57390bd1 137
ram54288 0:dbad57390bd1 138 To create an M2M Object Instance:
ram54288 0:dbad57390bd1 139
ram54288 0:dbad57390bd1 140 `M2MObject::create_object_instance(uint16_t instance_id);`
ram54288 0:dbad57390bd1 141
ram54288 0:dbad57390bd1 142 You can pass an Object Instance ID to create appropriate Object Instances. Normally, Object Instances will start from `0` and increment. So the Object Instance structure on the mbed Device Server side would look like this:
ram54288 0:dbad57390bd1 143
ram54288 0:dbad57390bd1 144 `Object/Object Instance ID`
ram54288 0:dbad57390bd1 145
ram54288 0:dbad57390bd1 146 ```
ram54288 0:dbad57390bd1 147 M2MObjectInstance * object_instance = _object->create_object_instance(0);
ram54288 0:dbad57390bd1 148 if(object_instance) {
ram54288 0:dbad57390bd1 149 object_instance->set_register_uri(true); // The registration message explicitly sends this object instance path as registered resource such as /Test/0.
ram54288 0:dbad57390bd1 150 }
ram54288 0:dbad57390bd1 151 ```
ram54288 0:dbad57390bd1 152
ram54288 0:dbad57390bd1 153 ### Configuring the Object Instance
ram54288 0:dbad57390bd1 154
ram54288 0:dbad57390bd1 155 When you have created an Object Instance (whether OMA-specific or custom), you can configure various parameters in it to control or modify communication with mbed Device Server.
ram54288 0:dbad57390bd1 156
ram54288 0:dbad57390bd1 157 Here, we present a few of the most important parameters that you must configure properly to work with the object instances.
ram54288 0:dbad57390bd1 158
ram54288 0:dbad57390bd1 159 ##### Setting Operation Mode
ram54288 0:dbad57390bd1 160
ram54288 0:dbad57390bd1 161 To set the operation mode of the Objects so that they can handle `GET`, `PUT`, `POST`, `DELETE` or a combination of these requests coming from mbed Device Server:
ram54288 0:dbad57390bd1 162
ram54288 0:dbad57390bd1 163 ```
ram54288 0:dbad57390bd1 164 virtual void set_operation(M2MBase::Operation operation);
ram54288 0:dbad57390bd1 165 object_instance->set_operation(M2MBase::GET_PUT_POST_ALLOWED); // This defines the REST operations that can be performed on this object instance.
ram54288 0:dbad57390bd1 166 ```
ram54288 0:dbad57390bd1 167
ram54288 0:dbad57390bd1 168 ##### Setting Observable Mode
ram54288 0:dbad57390bd1 169
ram54288 0:dbad57390bd1 170 To set the Object Instance to be an observing resource:
ram54288 0:dbad57390bd1 171
ram54288 0:dbad57390bd1 172 `virtual void set_observable(bool observable);`
ram54288 0:dbad57390bd1 173
ram54288 0:dbad57390bd1 174 By default, all the created Object Instances are non-observable. You can set them to be observable or not observable using this API.
ram54288 0:dbad57390bd1 175
ram54288 0:dbad57390bd1 176 ```
ram54288 0:dbad57390bd1 177 _object_instance->set_observable(true); // This defines that the Object Instance can be observed from server.
ram54288 0:dbad57390bd1 178 _object_instance->set_observable(false); // This defines that the Object Instance cannot be observed from server.
ram54288 0:dbad57390bd1 179 ```
ram54288 0:dbad57390bd1 180
ram54288 0:dbad57390bd1 181 ##### Setting CoAP content type
ram54288 0:dbad57390bd1 182
ram54288 0:dbad57390bd1 183 Currently, the only available content type is the OMA TLV type. The OMA TLV type works only for Objects and Object Instances with a numeric value. For example, if you are creating a custom Object and Object Instances it must be of a numeric type such as `100`.
ram54288 0:dbad57390bd1 184
ram54288 0:dbad57390bd1 185 ```
ram54288 0:dbad57390bd1 186 M2MObject * _object = M2MInterfaceFactory::create_object("100");
ram54288 0:dbad57390bd1 187 M2MObjectInstance * object_instance = _object->create_object_instance(0);
ram54288 0:dbad57390bd1 188 ```
ram54288 0:dbad57390bd1 189
ram54288 0:dbad57390bd1 190 By default, all numeric objects are assigned the CoAP content type of `99` by mbed Client but if you want your Object Instance to assign any other CoAP content type, for example 120, you can do that by setting the object's CoAP content type as follows:
ram54288 0:dbad57390bd1 191
ram54288 0:dbad57390bd1 192 ```
ram54288 0:dbad57390bd1 193 virtual void set_coap_content_type(const uint8_t content_type);
ram54288 0:dbad57390bd1 194 object_instance->set_coap_content_type(120);
ram54288 0:dbad57390bd1 195 ```
ram54288 0:dbad57390bd1 196
ram54288 0:dbad57390bd1 197 <span class="tips">**Tip:** In future version, we will introduce support for the JSON content types.</span>
ram54288 0:dbad57390bd1 198
ram54288 0:dbad57390bd1 199 There are additional APIs that provide getter and remove functions for Object Instances in the `M2MObjectInstance` class; [check the API documentation](https://docs.mbed.com/docs/mbed-client-guide/en/latest/api/classM2MObjectInstance.html) for their usage.
ram54288 0:dbad57390bd1 200
ram54288 0:dbad57390bd1 201 ## How to create and configure Resources and Resource Instances
ram54288 0:dbad57390bd1 202
ram54288 0:dbad57390bd1 203 With this API, you can create and configure the following Resources and Resource Instances:
ram54288 0:dbad57390bd1 204
ram54288 0:dbad57390bd1 205 - [Device Object Resources](#device-object-resources)
ram54288 0:dbad57390bd1 206 - [Security Object Resources](#security-object-resources)
ram54288 0:dbad57390bd1 207 - [Custom Resources](#custom-resources)
ram54288 0:dbad57390bd1 208
ram54288 0:dbad57390bd1 209
ram54288 0:dbad57390bd1 210 The `M2MResource` class is derived from the `M2MResourceInstance`, which in turn is derived from the `M2MBase` class, so all the public methods can be used from `M2MResource` or `M2MResourceInstance` and their derived classes.
ram54288 0:dbad57390bd1 211
ram54288 0:dbad57390bd1 212 ### Creating OMA-defined Resources
ram54288 0:dbad57390bd1 213
ram54288 0:dbad57390bd1 214 #### Device Object Resources
ram54288 0:dbad57390bd1 215
ram54288 0:dbad57390bd1 216 There are direct APIs to create and set values for the Device Resources. You can create the required Resource and set values based on their data types.
ram54288 0:dbad57390bd1 217
ram54288 0:dbad57390bd1 218 - For Resources that take string values:
ram54288 0:dbad57390bd1 219
ram54288 0:dbad57390bd1 220 `M2MResource* create_resource(DeviceResource resource, const String &value);`
ram54288 0:dbad57390bd1 221
ram54288 0:dbad57390bd1 222 - For Resources that take integer values:
ram54288 0:dbad57390bd1 223
ram54288 0:dbad57390bd1 224 `M2MResource* create_resource(DeviceResource resource, uint32_t value);`
ram54288 0:dbad57390bd1 225
ram54288 0:dbad57390bd1 226 - There are a few Resources that can have multiple instances. To create these Resources:
ram54288 0:dbad57390bd1 227
ram54288 0:dbad57390bd1 228 `M2MResourceInstance* create_resource_instance(DeviceResource resource, uint32_t value,uint16_t instance_id);`
ram54288 0:dbad57390bd1 229
ram54288 0:dbad57390bd1 230 Where `instance_id` is the Resource Instance ID, for example `/3/0/11/0`.
ram54288 0:dbad57390bd1 231
ram54288 0:dbad57390bd1 232 Check the [M2MDevice API documentation](https://docs.mbed.com/docs/mbed-client-guide/en/latest/api/classM2MDevice.html) to find which enums are supported for `integer` or `string` value types.
ram54288 0:dbad57390bd1 233
ram54288 0:dbad57390bd1 234 There are other APIs in the `M2MDevice` class that you can use to set, remove and modify new values for the resources.
ram54288 0:dbad57390bd1 235
ram54288 0:dbad57390bd1 236 #### Security Object Resources
ram54288 0:dbad57390bd1 237
ram54288 0:dbad57390bd1 238 _Mandatory Resources_
ram54288 0:dbad57390bd1 239
ram54288 0:dbad57390bd1 240 Most of the mandatory Resources are created automatically when you create an M2MSecurity Object. You can set their values based on their data types.
ram54288 0:dbad57390bd1 241
ram54288 0:dbad57390bd1 242 Resources that are automatically created and their accepted data types:
ram54288 0:dbad57390bd1 243
ram54288 0:dbad57390bd1 244 - `SecurityMode`
ram54288 0:dbad57390bd1 245 - `ShortServerID`
ram54288 0:dbad57390bd1 246 - `M2MServerUri`
ram54288 0:dbad57390bd1 247 - `BootstrapServer`
ram54288 0:dbad57390bd1 248 - `PublicKey`
ram54288 0:dbad57390bd1 249 - `ServerPublicKey`
ram54288 0:dbad57390bd1 250 - `Secretkey`
ram54288 0:dbad57390bd1 251
ram54288 0:dbad57390bd1 252 For Resources (`SecurityMode`, `ShortServerID`) that take integer values, you can set the values as follows:
ram54288 0:dbad57390bd1 253
ram54288 0:dbad57390bd1 254 `bool set_resource_value(SecurityResource resource,uint32_t value);`
ram54288 0:dbad57390bd1 255
ram54288 0:dbad57390bd1 256 ```
ram54288 0:dbad57390bd1 257 security_object->set_resource_value(M2MSecurity::SecurityMode, 1);
ram54288 0:dbad57390bd1 258 security_object->set_resource_value(M2MSecurity::ShortServerID, 1);
ram54288 0:dbad57390bd1 259 ```
ram54288 0:dbad57390bd1 260
ram54288 0:dbad57390bd1 261 For Resources (`M2MServerUri`) that take string values, you can set the values as follows:
ram54288 0:dbad57390bd1 262
ram54288 0:dbad57390bd1 263 `bool set_resource_value(SecurityResource resource,const String &value);`
ram54288 0:dbad57390bd1 264
ram54288 0:dbad57390bd1 265 ```
ram54288 0:dbad57390bd1 266 security_object->set_resource_value(M2MSecurity::M2MServerUri, "coap://api.connector.mbed.com:5684");
ram54288 0:dbad57390bd1 267 ```
ram54288 0:dbad57390bd1 268
ram54288 0:dbad57390bd1 269 For Resources (`PublicKey`, `ServerPublicKey`, `Secretkey`) that take binary values, you can set the values as follows:
ram54288 0:dbad57390bd1 270
ram54288 0:dbad57390bd1 271 `bool set_resource_value(SecurityResource resource,onst uint8_t *value,const uint16_t length);`
ram54288 0:dbad57390bd1 272
ram54288 0:dbad57390bd1 273 ```
ram54288 0:dbad57390bd1 274 uint8_t key[] = {"key"};
ram54288 0:dbad57390bd1 275 security_object->set_resource_value(M2MSecurity::PublicKey, key, sizeof(key));
ram54288 0:dbad57390bd1 276 ```
ram54288 0:dbad57390bd1 277
ram54288 0:dbad57390bd1 278 _Optional Resources_
ram54288 0:dbad57390bd1 279
ram54288 0:dbad57390bd1 280 Optional Resources as defined in the Security Object:
ram54288 0:dbad57390bd1 281
ram54288 0:dbad57390bd1 282 - `SMSSecurityMode`
ram54288 0:dbad57390bd1 283 - `M2MServerSMSNumber`
ram54288 0:dbad57390bd1 284 - `ClientHoldOffTime`
ram54288 0:dbad57390bd1 285
ram54288 0:dbad57390bd1 286 To create and set values for the optional Resources that take an integer value:
ram54288 0:dbad57390bd1 287
ram54288 0:dbad57390bd1 288 `M2MResource* create_resource(SecurityResource resource, uint32_t value);`
ram54288 0:dbad57390bd1 289
ram54288 0:dbad57390bd1 290 `security_object->create_resource(M2MSecurity::M2MServerSMSNumber, 123542323);`
ram54288 0:dbad57390bd1 291
ram54288 0:dbad57390bd1 292
ram54288 0:dbad57390bd1 293 Check the [M2MSecurity API documentation](https://docs.mbed.com/docs/mbed-client-guide/en/latest/api/classM2MSecurity.html) to find which enums are supported for `integer`, `string` or `uint8_t*` value types.
ram54288 0:dbad57390bd1 294
ram54288 0:dbad57390bd1 295 There are more APIs in the `M2MSecurity` class that you can use to set, remove and modify Resource values.
ram54288 0:dbad57390bd1 296
ram54288 0:dbad57390bd1 297 #### Custom Resources
ram54288 0:dbad57390bd1 298
ram54288 0:dbad57390bd1 299 For Custom Objects, you can create Resources of two types:
ram54288 0:dbad57390bd1 300
ram54288 0:dbad57390bd1 301 - **M2MResource**: a resource with a single instance, for example `/Test/0/Resource`.
ram54288 0:dbad57390bd1 302
ram54288 0:dbad57390bd1 303 - **M2MResourceInstance**: a resource with multiple instances, for example `/Test/0/Resource/0`, `/Test/0/Resource/1`.
ram54288 0:dbad57390bd1 304
ram54288 0:dbad57390bd1 305 For each of these types, the Resource and Resource Instances can be either static or dynamic:
ram54288 0:dbad57390bd1 306
ram54288 0:dbad57390bd1 307 - **Static**: Resource and Resource Instances whose value does not change over time, these are not observable.
ram54288 0:dbad57390bd1 308 - **Dynamic**: Resource and Resource Instances whose value can change. These can be made observable.
ram54288 0:dbad57390bd1 309
ram54288 0:dbad57390bd1 310 **Creating dynamic and static single-instance Resources**
ram54288 0:dbad57390bd1 311
ram54288 0:dbad57390bd1 312 - To create a single-instance Resource with a static value (`/Test/0/Resource`):
ram54288 0:dbad57390bd1 313
ram54288 0:dbad57390bd1 314 ```
ram54288 0:dbad57390bd1 315 M2MObject * object = M2MInterfaceFactory::create_object("Test");
ram54288 0:dbad57390bd1 316 M2MObjectInstance * object_instance = object->create_object_instance(0);
ram54288 0:dbad57390bd1 317
ram54288 0:dbad57390bd1 318 uint8_t value[] ={"value"};
ram54288 0:dbad57390bd1 319 M2MResource* resource = object_instance->create_static_resource("Resource", "sensor",M2MResourceInstance::INTEGER,value,sizeof(value),false);
ram54288 0:dbad57390bd1 320 ```
ram54288 0:dbad57390bd1 321
ram54288 0:dbad57390bd1 322 - To create an observable single-instance Resource (`/Test/0/Resource`) with a dynamic value that can be set later on:
ram54288 0:dbad57390bd1 323
ram54288 0:dbad57390bd1 324 ```
ram54288 0:dbad57390bd1 325 M2MObject * object = M2MInterfaceFactory::create_object("Test");
ram54288 0:dbad57390bd1 326 M2MObjectInstance * object_instance = object->create_object_instance(0);
ram54288 0:dbad57390bd1 327
ram54288 0:dbad57390bd1 328 M2MResource* resource = object_instance->create_dynamic_resource("Resource", "sensor",M2MResourceInstance::INTEGER, true, false);
ram54288 0:dbad57390bd1 329 int64_t value = 1000;
ram54288 0:dbad57390bd1 330 resource->set_value(value);
ram54288 0:dbad57390bd1 331 ```
ram54288 0:dbad57390bd1 332
ram54288 0:dbad57390bd1 333 **Creating dynamic and static Resource Instances**
ram54288 0:dbad57390bd1 334
ram54288 0:dbad57390bd1 335 - To create a Resource Instance (`/Test/0/Resource/0`) with a static value:
ram54288 0:dbad57390bd1 336
ram54288 0:dbad57390bd1 337 ```
ram54288 0:dbad57390bd1 338 M2MObject * object = M2MInterfaceFactory::create_object("Test");
ram54288 0:dbad57390bd1 339 M2MObjectInstance * object_instance = object->create_object_instance(0);
ram54288 0:dbad57390bd1 340
ram54288 0:dbad57390bd1 341 uint8_t value[] ={"value"};
ram54288 0:dbad57390bd1 342 M2MResourceInstance* resource_instance = object_instance->create_static_resource_instance("Resource", "sensor",M2MResourceInstance::INTEGER,value,sizeof(value),0);
ram54288 0:dbad57390bd1 343 ```
ram54288 0:dbad57390bd1 344
ram54288 0:dbad57390bd1 345
ram54288 0:dbad57390bd1 346 - To create an observable Resource Instance (`/Test/0/Resource/0`) with a dynamic value that can be set later on:
ram54288 0:dbad57390bd1 347
ram54288 0:dbad57390bd1 348 ```
ram54288 0:dbad57390bd1 349 M2MObject * object = M2MInterfaceFactory::create_object("Test");
ram54288 0:dbad57390bd1 350 M2MObjectInstance * object_instance = object->create_object_instance(0);
ram54288 0:dbad57390bd1 351
ram54288 0:dbad57390bd1 352 uint8_t value[] ={"value"};
ram54288 0:dbad57390bd1 353 M2MResourceInstance* resource_instance = object_instance->create_dynamic_resource_instance("Resource", "sensor",M2MResourceInstance::INTEGER, true, 0);
ram54288 0:dbad57390bd1 354 int64_t value = 1000;
ram54288 0:dbad57390bd1 355 resource_instance->set_value(value);
ram54288 0:dbad57390bd1 356
ram54288 0:dbad57390bd1 357 ```
ram54288 0:dbad57390bd1 358
ram54288 0:dbad57390bd1 359 #### Configuring the Resource and Resource Instance
ram54288 0:dbad57390bd1 360
ram54288 0:dbad57390bd1 361 When you have created a Resource or Resource Instance (whether OMA-specific or custom), you can configure various parameters to control or modify communication with mbed Device Server.
ram54288 0:dbad57390bd1 362
ram54288 0:dbad57390bd1 363 Here, we present a few of the most important parameters that you must configure properly to work with the Resource and Resource Instance.
ram54288 0:dbad57390bd1 364
ram54288 0:dbad57390bd1 365 ##### Setting Operation Mode
ram54288 0:dbad57390bd1 366
ram54288 0:dbad57390bd1 367 You can set the Resource or Resource Instance operation mode so that they can handle `GET`, `PUT`, `POST`, `DELETE` or a combination of these requests coming from mbed Device Server.
ram54288 0:dbad57390bd1 368
ram54288 0:dbad57390bd1 369 To set the operation mode:
ram54288 0:dbad57390bd1 370
ram54288 0:dbad57390bd1 371 ```
ram54288 0:dbad57390bd1 372 virtual void set_operation(M2MBase::Operation operation);
ram54288 0:dbad57390bd1 373 resource->set_operation(M2MBase::GET_PUT_POST_ALLOWED); // This defines the REST operations that can be performed on this Resource.
ram54288 0:dbad57390bd1 374 resource_instance->set_operation(M2MBase::GET_PUT_POST_ALLOWED); // This defines the REST operations that can be performed on this Resource Instance.
ram54288 0:dbad57390bd1 375 ```
ram54288 0:dbad57390bd1 376
ram54288 0:dbad57390bd1 377 ##### Setting Observable Mode
ram54288 0:dbad57390bd1 378
ram54288 0:dbad57390bd1 379 To set the Resource or Resource Instance to be an observable resource:
ram54288 0:dbad57390bd1 380
ram54288 0:dbad57390bd1 381 `virtual void set_observable(bool observable);`
ram54288 0:dbad57390bd1 382
ram54288 0:dbad57390bd1 383 By default, all created static Resources or Resource Instances are non-observable. While creating a dynamic Resource or Resource Instance you can specify through API whether they are observable or not. You can change that later as well as follows:
ram54288 0:dbad57390bd1 384
ram54288 0:dbad57390bd1 385 ```
ram54288 0:dbad57390bd1 386 resource->set_observable(true); // This defines that the Resource or Resource Instance can be observed from server.
ram54288 0:dbad57390bd1 387 resource->set_observable(false); // This defines that the Resource or Resource Instance cannot be observed from server.
ram54288 0:dbad57390bd1 388 ```
ram54288 0:dbad57390bd1 389
ram54288 0:dbad57390bd1 390 ##### Setting the value of a dynamic Resource or Resource Instance
ram54288 0:dbad57390bd1 391
ram54288 0:dbad57390bd1 392 You can set the value of a dynamic Resource or Resource Instance so that they can be sent to mbed Device Server using `GET` requests.
ram54288 0:dbad57390bd1 393
ram54288 0:dbad57390bd1 394 To set the values:
ram54288 0:dbad57390bd1 395
ram54288 0:dbad57390bd1 396 ```
ram54288 0:dbad57390bd1 397 virtual bool set_value(const uint8_t *value, const uint32_t value_length);
ram54288 0:dbad57390bd1 398 uint8_t value[] = {"value"};
ram54288 0:dbad57390bd1 399 resource->set_value(value,sizeof(value));
ram54288 0:dbad57390bd1 400 ```
ram54288 0:dbad57390bd1 401
ram54288 0:dbad57390bd1 402 ##### Setting an executable function
ram54288 0:dbad57390bd1 403
ram54288 0:dbad57390bd1 404 For dynamic Resources, you can pass a function pointer to the Resource or Resource Instance. It will be executed when mbed Device Server calls a `POST` method on that resource. The Resource or Resource Instance must support the `POST` operation mode for this feature to work.
ram54288 0:dbad57390bd1 405
ram54288 0:dbad57390bd1 406 To pass the function pointer:
ram54288 0:dbad57390bd1 407
ram54288 0:dbad57390bd1 408 ```
ram54288 0:dbad57390bd1 409 virtual void set_execute_function(execute_callback callback);
ram54288 0:dbad57390bd1 410 void execute_function_example(void *) {
ram54288 0:dbad57390bd1 411 // Code
ram54288 0:dbad57390bd1 412 };
ram54288 0:dbad57390bd1 413 resource->set_execute_function(execute_callback(this,&execute_function_example));
ram54288 0:dbad57390bd1 414 ```
ram54288 0:dbad57390bd1 415
ram54288 0:dbad57390bd1 416 In case execute callback function is defined as a global function and it's outside of your class scope you can use overloaded set_execute_function:
ram54288 0:dbad57390bd1 417 ```
ram54288 0:dbad57390bd1 418 virtual void set_execute_function(execute_callback_2 callback);
ram54288 0:dbad57390bd1 419 static void c_style_function(void *) {
ram54288 0:dbad57390bd1 420 // Code
ram54288 0:dbad57390bd1 421 }
ram54288 0:dbad57390bd1 422 resource->set_execute_function(&c_style_function);
ram54288 0:dbad57390bd1 423 ```
ram54288 0:dbad57390bd1 424 There are additional APIs that provide getter and remove functions for Resource and Resource Instances in the `M2MResource` and `M2MResourceInstance` classes. Check [the API documentation](https://docs.mbed.com/docs/mbed-client-guide/en/latest/api/annotated.html) for their usage.
ram54288 0:dbad57390bd1 425
ram54288 0:dbad57390bd1 426 ##### Setting an external handler for block-wise messages
ram54288 0:dbad57390bd1 427
ram54288 0:dbad57390bd1 428 For dynamic Resources, you can pass a function pointer to the Resource Instance. It will be executed when mbed Device Server calls a `PUT` method on that resource with large payload using block-wise operation. The Resource must support the `PUT` operation mode for this feature to work. If the callback is set, the application will be notified for every incoming block-wise message and the message is not stored in mbed Client side anymore. In such case, it is application's responsibility to store each block-wise message and combine them when the last block has arrived.
ram54288 0:dbad57390bd1 429
ram54288 0:dbad57390bd1 430 <span class="notes">**Note:** Due to a limitation in the mbed-client-c library, GET request can only contain data up to 65KB.</span>
ram54288 0:dbad57390bd1 431
ram54288 0:dbad57390bd1 432 To pass the function pointer for an incoming block-wise message:
ram54288 0:dbad57390bd1 433
ram54288 0:dbad57390bd1 434 ```
ram54288 0:dbad57390bd1 435 virtual void set_incoming_block_message_callback(incoming_block_message_callback callback);
ram54288 0:dbad57390bd1 436 void block_message_received(M2MBlockMessage *argument) {
ram54288 0:dbad57390bd1 437 // Code
ram54288 0:dbad57390bd1 438 }
ram54288 0:dbad57390bd1 439 resource->set_incoming_block_message_callback(incoming_block_message_callback(this, &block_message_received));
ram54288 0:dbad57390bd1 440 ```
ram54288 0:dbad57390bd1 441
ram54288 0:dbad57390bd1 442 To pass the function pointer for an outgoing block-wise message:
ram54288 0:dbad57390bd1 443
ram54288 0:dbad57390bd1 444 ```
ram54288 0:dbad57390bd1 445 virtual void set_outgoing_block_message_callback(outgoing_block_message_callback callback);
ram54288 0:dbad57390bd1 446 void block_message_requested(const String& resource, uint8_t *&data, uint32_t &len) {
ram54288 0:dbad57390bd1 447 // Code
ram54288 0:dbad57390bd1 448 }
ram54288 0:dbad57390bd1 449 resource->set_outgoing_block_message_callback(outgoing_block_message_callback(this, &block_message_requested));
ram54288 0:dbad57390bd1 450 ```
ram54288 0:dbad57390bd1 451
ram54288 0:dbad57390bd1 452 Applications can define their own maximum incoming message size in bytes at build time. For mbed OS, create a `mbed_app.json` file in the application level and overwrite the value as described below:
ram54288 0:dbad57390bd1 453
ram54288 0:dbad57390bd1 454 ```
ram54288 0:dbad57390bd1 455 "target_overrides": {
ram54288 0:dbad57390bd1 456 "*": {
ram54288 0:dbad57390bd1 457 "mbed-client.sn-coap-max-incoming-message-size": 100000
ram54288 0:dbad57390bd1 458 }
ram54288 0:dbad57390bd1 459
ram54288 0:dbad57390bd1 460 ```
ram54288 0:dbad57390bd1 461
ram54288 0:dbad57390bd1 462 For yotta based builds, you need to create a `config.json` file in the application level:
ram54288 0:dbad57390bd1 463
ram54288 0:dbad57390bd1 464 ```
ram54288 0:dbad57390bd1 465 {
ram54288 0:dbad57390bd1 466 "coap_max_incoming_block_message_size": 100000
ram54288 0:dbad57390bd1 467 }
ram54288 0:dbad57390bd1 468 ```