sandbox / mbed-client

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Fork of mbed-client by Christopher Haster

docs/Howto.md@4:ae5178938864, 2016-04-02 (annotated)

Committer:
Yogesh Pande
Date:
Sat Apr 02 00:31:13 2016 +0300
Revision:
4:ae5178938864
Parent:
1:79b6cc67d8b4 
Latest updated sources from Github and some trace group refactor.

Who changed what in which revision?

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