An Example showing registration and usage of SMARTREST1.0 template

Knowledge base
, , , , , , ,
1

In this article, we will discuss about how to create and use SmartREST1.0 templates. One of the main uses of smartREST templates is to decrease payload size with each request, which is very much necessary in low-end microcontrollers and low bandwidth environments like communications happening via GPRS. Here, we have shown sending measurements as an example using usual REST requests without using SmartREST templates as well as using SmartREST templates. One could easily figure out by how many folds, payload size is reduced with SmartREST templates.

Prerequisite (Setup Postman for Cumulocity REST calls)

  1. Download and install Postman client 

  2. Import Postman REST collection by opening link

  3. Configure Postman with some environment variables required for requests to work.

    • Click on any request from imported collection, request URL contains a “url” variable. To make our lives easier we’ll define this variable first in Postman. Click the little eye icon in the top right corner next to the environment dropdown.

    • Click the “Add” link to add a new environment. Give your environment an arbitrary name, here “demo”. Variables can be defined as <key, value> pairs. Add a new variable with “url” as key and set the value to your ADAMOS Core tenant URL, here “https://mytenant.i40-cloud.com”. Click the “Add” button to add the environment. 

    • Then close the “Manage Environments” popup and select your demo environment from the “Environments” dropdown.

    • For authorization purposes select Basic Authentication and enter your tenant’s user credentials.

    • In order to not having to deal with adding the password again, click on the “Preview Request” button shown in the above screen shot. This will generate a new variable called Authorization in the Headers tab. Navigate to the Headers tab and copy its value.

    • Now open your environment again from the eye icon in the top right corner. Click on the Edit link. Define a new variable called auth. Paste the value that you had copied earlier into the value textbox.

    • Click on Update and then close the Manage Environments dialogue box.

    • Take a look into the Headers tab. You will notice that we have two entries for Authorization. Since we have already defined the “auth” variable we can go ahead and remove the auto generated Authorization variable. To do this, navigate back to the Authorization tab and select No Auth for the Type dropdown. This will remove the extra Authorization variable.

    • Now we have set up our environment with two variables. If there are any commonly refered variables, which doesn't change with every execution of request, define them in environments section as needed following same procedure.

Create a Device

From Inventory Folder, select 'Get device with temprature measurement support' request and provide body as below:

{
    "name": "testMeasurementDevice", 
    "c8y_IsDevice": {}, 
    "c8y_SupportedMeasurements": [
               "c8y_TemperatureMeasurement",
               "c8y_CurrentMeasurement"
               ],
    "c8y_Hardware": {
        "revision": "1.0",
        "model": "My device model",
        "serialNumber": "1234567890"
      }
}

In the Cumulocity web application, open the Device Management app and navigate to the “All devices” navigation entry in the left-hand navigation. You will see your device listed there. Click on the device to navigate to the device details. This is it, you have created your first device. Note the device ID.

Send Measurement to Device using Cumulocity REST request

You can test this by sending some measurements to device. From “Measurement” folder > use request ‘Create Multiple measurements’ and provide body as below.

Note: Please update time to current time, otherwise you can't see measurements in graphs later.

{
"measurements": [
               {
               "c8y_TemperatureMeasurement": {
               "T": { 
               "value": 60,
            "unit": "C" }
        },
    "time":"2018-11-14T19:55:14.000+05:30", 
    "source": {
               "id":"269126" }, 
    "type": "c8y_TemperatureMeasurement"
               },
               {
                              "c8y_CurrentMeasurement": { 
               "T": { 
               "value": 280,
            "unit": "V" }
        },
    "time":"2018-11-14T19:55:14.000+05:30", 
    "source": {
               "id":"269126" }, 
    "type": "c8y_CurrentMeasurement"
               }

               ]
}

From your Device Management > All Devices > your device measurement tab you can see measurement is appearing

Register a SmartREST Template

From SmartREST Folder, select 'Register Request Templates' request and provide details as below:

Header "X-Id: testMeasurementDevice"
Body as : 10,222,POST,/measurement/measurements,application/vnd.com.nsn.cumulocity.measurement+json,application/vnd.com.nsn.cumulocity.measurement+json,&&,UNSIGNED NOW UNSIGNED,"{""c8y_TemperatureMeasurement"":{""T"":{""value"":&&,""unit"":""C""}},""time"":""&&"",""source"":{""id"":""&&""},""type"":""c8y_TemperatureMeasurement""}"

To know what are registered templates, from Postman, Under Inventories Directory > use ‘Get Collection of SmartREST templates’.

Send Measurement to Device using SmartREST template

To send data (measurement) using created SmartREST teamplate, use same request "Register Request Templates", with same headers, but body as below

222,41,<Device ID of device created>
222,42,<Device ID of device created>
222,43,<Device ID of device created>
222,45,<Device ID of device created>
222,41,<Device ID of device created>
222,46,<Device ID of device created>

From your Device Management > All Devices > your device measurement tab you can see measurement is appearing. Since all events are getting sent at in same second, we can’t see this in graph in measurements tab. Instead we can go to more > Download report in same page to see all events.

A sample of downloaded report of measurements looks as below: