Ram Gandikota / Mbed OS metronome

FRDM K64F Metronome

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

Committer:
ram54288
Date:
Sun May 14 18:35:07 2017 +0000
Revision:
0:a2cb7295a1f7
Initial commit

Who changed what in which revision?

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