Ram Gandikota / Mbed OS ABCD

A metronome using the FRDM K64F board

mbed-client/docs/Howto.md@0:a7a43371b306, 2017-05-14 (annotated)

Committer:
ram54288
Date:
Sun May 14 18:40:18 2017 +0000
Revision:
0:a7a43371b306
Initial commit

Who changed what in which revision?

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