This section describes how to add/create, delete, provision and deprovision devices.

Starting with SmartServer 3.4+, after you add or create a device you must wait until the new device is licensed before trying to provision the new device. It takes a time for the SmartServer to license a new device. If you try to provision a device that is not licensed then provisioning process will fail. Prior to SmartServer 3.4 you could provision the new device after the new device is created.

IAP/MQ Operations

Devices are created using the do action with the create method which provides arguments for basic device creation. A client application may elect to store the handle used to create the device and associated user presentation information in a persistent database. Additional information can potentially be added to the device cfg object to name and describe the device created. After you create a device you must wait until the new device is licensed (device lic object needs to show licensed = true) before trying to provision the new device

This section provides examples of managing devices using mosquitto_sub and mosquitto_pub, as well as a sample Node.js app.

Performing Actions on a Device (Creating, Deleting, Provisioning, Deprovisioning, etc)

You publish an action object to the object's do endpoint to invoke the action. The supported do actions are: add, create, deprovision, delete, file action, load, message, provision, remove, repair, replace, reset, routing, test, and wink. (See Device Do Action for more information.)

glp/0/{SID}/rq/dev/{Edge_Protocol_ID}/{Handle}/do

Handles are unique and are typically defined using the handle allocation methods described in Handle Allocation.

Examples of all the actions on the device[IAP/MQ Device Actions]

IAP/MQ Device Do Action Examples

DEVICE INFORMATION:
name = "Sensor1"
protocol = lon
device type = 6kEvbMultiSensor
handle = 2   // From Handle Allocation, created devices will use 2.1, 2.2 and so on

CREATE:

mosquitto_pub -t glp/0/17q2d9v/rq/dev/lon/2.2/do -m '{
    "action":"create",
    "args": {
       "unid":"256",
       "type":"6kEvbMultiSensor"
    }  
}'

CHANGE CONFIGURATION: change device name

mosquitto_pub -t glp/0/17q2d9v/rq/dev/lon/2.2/cfg -m '{
    "name":"Sensor1",
    "Loc": {
       "desc":"",
       "lat":"37.3847",
       "lng":"-121.9847"
       "ele":"null"
    }  
}'

CHECK LICENSE: 

mosquitto_sub -t -v glp/0/17q2d9v/rq/dev/lon/2.2/lic
Response:
{
    "licensed":true
}

PROVISION: Wait for device to be licensed before trying to provision a device

mosquitto_pub -t glp/0/17q2d9v/rq/dev/lon/2.2/do -m '{
    "action":"provision"
     
}'

DEPROVISION:

mosquitto_pub -t glp/0/17q2d9v/rq/dev/lon/2.2/do -m '{
    "action":"deprovision"
     
}'

WINK:(we don't support this for IOX)

mosquitto_pub -t glp/0/17q2d9v/rq/dev/lon/2.2/do -m '{
    "action":"wink"
     
}'

DEVICE TEST:(we don't support this for IOX)

mosquitto_pub -t glp/0/17q2d9v/rq/dev/lon/2.2/do -m '{
    "action":"test"
     
}'

DELETE:(we don't support this for IOX)

mosquitto_pub -t glp/0/17q2d9v/rq/dev/lon/2.2/do -m '{
    "action":"delete"
     
}'

Obtaining Device Configuration

You publish a request for device configuration information on this topic (See Device Configuration for more information):

glp/0/{SID}/rq/dev/{Edge_Protocol_ID}/{Handle}/cfg

The CMS publishes device configuration information in this feedback channel:

glp/0/{SID}/fb/dev/{Edge_Protocol_ID}/{Handle}/cfg

Device Configuration Examples

$ mosquitto_sub -v -t glp/0/17q2eh2/fb/dev/+/+/cfg

glp/0/17q2eh2/fb/dev/iox.1/dio/cfg {
	"name":	"dio",
	"desc":	"IOX Digital IO Device",
	"motion_zone":	0,
	"motion_radius":	0,
	"motion_timeout":	0,
	"loc":	{
		"desc":	"",
		"lat":	0,
		"lng":	0
	}
}
glp/0/17q2eh2/fb/dev/iox.1/meter/cfg {
	"name":	"meter",
	"desc":	"IOX Metering Device",
	"motion_zone":	0,
	"motion_radius":	0,
	"motion_timeout":	0,
	"loc":	{
		"desc":	"",
		"lat":	0,
		"lng":	0
	}
}
glp/0/17q2eh2/fb/dev/iox.2/dio/cfg {
	"name":	"dio",
	"desc":	"IOX Digital IO Device",
	"motion_zone":	0,
	"motion_radius":	0,
	"motion_timeout":	0,
	"loc":	{
		"desc":	"",
		"lat":	0,
		"lng":	0
	}
}

Obtaining Device Implementation Data

The CMS subscribe device implementation data on this topic (See Implementation Detail Object for more information):

glp/0/{SID}/fb/dev/{Edge_Protocol_ID}/{Handle}/impl

Obtaining Device Implementation Data Example

{
  "meta": {
    "status": {},
    "address": {
      "UseExtendedCommandSet": "false",
      "BindingConstraints": "1",
      "domain": {
        "0": {
          "domainId": "3C",
          "domainLength": 1,
          "subnet": 200,
          "nodeId": 99
        }
      }
    },
    "id": 3,
    "link": {
      "channel": "/~/-3",
      "host": "/~/1"
    },
    "programId": "9000010500C08500",
    "type": "/~/type/dev/LON/Echelon/SmartServer IoT/system.xif",
    "uniqueId": "00 D0 73 06 5E 64"
  },
  "mru": "2019-04-12 09:15:19.910 UTC"
}

Obtaining Device Status

The CMS subscribe device status data on this topic (See Device Status for more information):

glp/0/{SID}/fb/dev/{Edge_Protocol_ID}/{Handle}/sts

Obtaining Device Status Examples

$ mosquitto_sub -v -t glp/0/17q2eh2/fb/dev/+/+/sts
glp/0/17q2eh2/fb/dev/iox.1/dio/sts {
	"state":	"provisioned",
	"unid":	"256",
	"health":	"normal",
	"cat":	"i/o",
	"type":	"dio",
	"interfaceType":	"static",
	"usage":	"mixed",
	"version":	"1.0.0"
}
glp/0/17q2eh2/fb/dev/iox.1/meter/sts {
	"state":	"provisioned",
	"unid":	"257",
	"health":	"normal",
	"cat":	"metering",
	"type":	"meter",
	"interfaceType":	"static",
	"usage":	"mixed",
	"version":	"1.0.0"
}
glp/0/17q2eh2/fb/dev/iox.2/dio/sts {
	"state":	"unprovisioned",
	"unid":	"256",
	"health":	"normal",
	"cat":	"i/o",
	"type":	"dio",
	"interfaceType":	"static",
	"usage":	"mixed",
	"version":	"1.0.0"
}

Sample Node.js App

/* jshint esversion: 6 */
/* jslint node: true, maxerr: 10000 */

"use strict";
const mqtt = require("mqtt");
const client = mqtt.connect("mqtt://localhost:1883");
const SID = "17q3ak7"; // SID to be used in the topics

/**
*
* @param {String} protocol protocol of the device
* @param {String} deviceHandle handle of the device
* @param {String} action action such as create, delete, provision etc
* @param {Object} args arguments required for the action
*/

function publishAction(
protocol, deviceHandle, action, args
) {

// do topic used for publishing action glp/0/SID/rq/dev/P/H/do where P is the protocol and H is the device Handle

   let topic = "glp/0/" + SID + "/rq/dev/" + protocol + "/" + deviceHandle + "/do";
   let actionObj = {
       "action": action
   };
   if (args) {
       actionObj.args = args;
   }
   client.publish(topic, JSON.stringify(actionObj));
}

client.on("connect", function () {
   let createDeviceArgs = {
       "unid": "256",
       "type": "dio"
   };

   // create a device

   publishAction(
       "iox.2", "dio", "create", createDeviceArgs    // protocol , deviceHandle, action, arguments
   );

   // provision a device

   publishAction(
       "iox.2", "dio", "provision"
   );

   // wink action

   publishAction(
       "iox.2", "dio", "wink"
   );

   // deprovision a device

   publishAction(
       "iox.2", "dio", "deprovision"
   );

   // delete a device

   publishAction(
       "iox.2", "dio", "delete"
   );

client.end();

});

IAP/REST Operations

Details of these operations are provided in the API Reference under Devices.

After you add or create a device you must wait until the new device is licensed (device status.state object shows "unprovisioned") before trying to provision the new device.

Getting a List of Devices

Returns all devices that you have permission to read.

GET	/iap/devs

Example

URL: https://192.168.100.3:8443/iap/devs?gn=true&name=&pg=1&short=true&sortBy=name
Request: GET

Response:
[
    {
        "name": "SmartServer IoT",
        "category": "SC",
        "id": "T6tWyga",
        "latitude": 18.5333,
        "longitude": 73.8667,
        "capabilities": {
            "replacement": {}
        },
        "status": {
            "state": "provisioned", 
            "connection": "connected",
            "connectionStatusSince": "2019-03-20T03:40:35.845Z[Etc/UTC]",
            "action": null,
            "pingTime": "2019-03-20T14:50:00"
        }
    },
    {
        "name": "amik",
        "category": "EDGE",
        "id": "amik",
        "latitude": 0,
        "longitude": 0,
        "capabilities": {
            "replacement": {},
            "commissioning": {
                "commissionMethod": "MANUAL"
            }
        },
        "status": {
            "state": "provisioned",
            "health": "down",
            "connection": "connected",
            "connectionStatusSince": "2019-02-25T05:53:21Z[Etc/UTC]",
            "action": null,
            "product": "AMIK Series Digital Power Meter",
            "wasProvisioned": true
        },
        "scName": "SmartServer IoT",
        "scId": "T6tWyga",
        "scState": "provisioned",
        "uid": "01:1",
        "protocol": "modbus",
        "typeId": 1323,
        "createdOnGlp": true,
        "gpsEnabled": false
    },
    {
        "name": "lon.sys",
        "category": "EDGE",
        "id": "lon.sys",
        "latitude": 0,
        "longitude": 0,
        "capabilities": {
            "replacement": {},
            "commissioning": {
                "commissionMethod": "MANUAL"
            }
        },
        "status": {
            "state": "provisioned",
            "health": "normal",
            "connection": "connected",
            "connectionStatusSince": "2019-02-15T09:04:58.348Z[Etc/UTC]",
            "action": null,
            "product": "system",
            "wasProvisioned": true
        },
        "scName": "SmartServer IoT",
        "scId": "T6tWyga",
        "scState": "provisioned",
        "uid": "00D071065D17",
        "protocol": "lon",
        "typeId": 124,
        "createdOnGlp": true,
        "gpsEnabled": false
    },
    {
        "name": "rv-test-cfg",
        "category": "EDGE",
        "id": "T6tWyga.484",
        "latitude": 27.68353,
        "longitude": 76.64063,
        "capabilities": {
            "replacement": {},
            "commissioning": {
                "commissionMethod": "MANUAL"
            }
        },
        "status": {
            "state": "unprovisioned",
            "health": "down",
            "connectionStatusSince": "2019-03-19T07:46:07Z[Etc/UTC]",
            "action": null,
            "product": "AMIK201RTU",
            "wasProvisioned": true
        },
        "scName": "SmartServer IoT",
        "scId": "T6tWyga",
        "scState": "provisioned",
        "uid": "01:05",
        "protocol": "modbus",
        "typeId": 1323,
        "createdOnGlp": true,
        "gpsEnabled": false
    }
]

Returns the device for the specified ID.

GET	/iap/devs/{id}

Example

GET    /iap/devs/17q2d9v.17
[
    {
        "name":"lh_14",
        "category":"EDGE",
        "id":"17q2d9v.17",
        "geozoneId":44,
        "geozoneName":"World",
        "customerId":43,
        "latitude":21.916,
        "longitude":72.43175,
        "capabilities":{
            "replacement":{
                
            },
            "commissioning":{
                "commissionMethod":"MANUAL"
            }
        },
        "status":{
            "state":"provisioned",
            "health":"normal",
            "connection":"connected",
            "connectionStatusSince":"2019-04-09T15:30:52.22+03:00[Europe/Kirov]",
            "action":null,
            "product":"LH-PM100E_6k",
            "wasProvisioned":true
        },
        "scName":"SmartServer IoT3",
        "scId":"17q2d9v",
        "scState":"provisioned",
        "uid":"00D075065E62",
        "discoveryMethod":"manual",
        "protocol":"lon",
        "typeId":3331,
        "createdOnGlp":true,
        "deviceTypeName":"LH-PM100E_S6k",
        "gpsLatitude":null,
        "gpsLongitude":null,
        "gpsDilution":null,
        "gpsEnabled":false,
        "installationDate":"2019-04-04",
        "ownerMAC":"00-D0-71-06-5E-63",
        "DID":"17q2d9v.17"
    }
]

Returns all devices assigned to the specified geozone.

GET	/iap/devs/gz/{id}

Example of GET /iap/devs/gz/44

GET    /iap/devs/gz/44

[
    {
        "name":"lh_14",
        "category":"EDGE",
        "id":"17q2d9v.17",
        "geozoneId":44,
        "geozoneName":"World",
        "customerId":43,
        "latitude":21.916,
        "longitude":72.43175,
        "capabilities":{
            "replacement":{
                
            },
            "commissioning":{
                "commissionMethod":"MANUAL"
            }
        },
        "status":{
            "state":"provisioned",
            "health":"normal",
            "connection":"connected",
            "connectionStatusSince":"2019-04-09T15:30:52.22+03:00[Europe/Kirov]",
            "action":null,
            "product":"LH-PM100E_6k",
            "wasProvisioned":true
        },
        "scName":"SmartServer IoT3",
        "scId":"17q2d9v",
        "scState":"provisioned",
        "uid":"00D075065E62",
        "discoveryMethod":"manual",
        "protocol":"lon",
        "typeId":3331,
        "createdOnGlp":true,
        "deviceTypeName":"LH-PM100E_S6k",
        "gpsLatitude":null,
        "gpsLongitude":null,
        "gpsDilution":null,
        "gpsEnabled":false,
        "installationDate":"2019-04-04",
        "ownerMAC":"00-D0-71-06-5E-63",
        "DID":"17q2d9v.17"
    },
    {
        "name":"lon.sys",
        "category":"EDGE",
        "id":"lon.sys",
        "geozoneId":44,
        "geozoneName":"World",
        "customerId":43,
        "latitude":0.0,
        "longitude":0.0,
        "capabilities":{
            "replacement":{
                
            },
            "commissioning":{
                "commissionMethod":"MANUAL"
            }
        },
        "status":{
            "state":"provisioned",
            "health":"normal",
            "connection":"connected",
            "connectionStatusSince":"2019-04-10T08:08:54.079+03:00[Europe/Kirov]",
            "action":null,
            "product":"system",
            "wasProvisioned":true
        },
        "scName":"SmartServer IoT3",
        "scId":"17q2d9v",
        "scState":"provisioned",
        "uid":"00D071065D19",
        "discoveryMethod":"manual",
        "protocol":"lon",
        "typeId":155,
        "createdOnGlp":true,
        "deviceTypeName":"system",
        "gpsLatitude":null,
        "gpsLongitude":null,
        "gpsDilution":null,
        "gpsEnabled":false,
        "installationDate":"2019-03-28",
        "ownerMAC":"00-D0-71-06-5E-63",
        "DID":"lon.sys"
    },
    {
        "name":"lh_15",
        "category":"EDGE",
        "id":"17q2d9v.19",
        "geozoneId":44,
        "geozoneName":"World",
        "customerId":43,
        "latitude":26.01072,
        "longitude":72.77344,
        "capabilities":{
            "replacement":{
                
            },
            "commissioning":{
                "commissionMethod":"MANUAL"
            }
        },
        "status":{
            "state":"provisioned",
            "health":"normal",
            "connection":"connected",
            "connectionStatusSince":"2019-04-09T15:30:52.225+03:00[Europe/Kirov]",
            "action":null,
            "product":"LH-PM100E_6k",
            "wasProvisioned":true
        },
        "scName":"SmartServer IoT3",
        "scId":"17q2d9v",
        "scState":"provisioned",
        "uid":"00D076065E62",
        "discoveryMethod":"manual",
        "protocol":"lon",
        "typeId":3331,
        "createdOnGlp":true,
        "deviceTypeName":"LH-PM100E_S6k",
        "gpsLatitude":null,
        "gpsLongitude":null,
        "gpsDilution":null,
        "gpsEnabled":false,
        "installationDate":"2019-04-04",
        "ownerMAC":"00-D0-71-06-5E-63",
        "DID":"17q2d9v.19"
    },
    {
        "name":"lh_10",
        "category":"EDGE",
        "id":"17q2d9v.13",
        "geozoneId":44,
        "geozoneName":"World",
        "customerId":43,
        "latitude":21.915960000000002,
        "longitude":72.43171,
        "capabilities":{
            "replacement":{
                
            },
            "commissioning":{
                "commissionMethod":"MANUAL"
            }
        },
        "status":{
            "state":"provisioned",
            "health":"normal",
            "connection":"connected",
            "connectionStatusSince":"2019-04-09T15:30:50.261+03:00[Europe/Kirov]",
            "action":null,
            "product":"LH-PM100E_6k",
            "wasProvisioned":true
        },
        "scName":"SmartServer IoT3",
        "scId":"17q2d9v",
        "scState":"provisioned",
        "uid":"00D072065E62",
        "discoveryMethod":"manual",
        "protocol":"lon",
        "typeId":3331,
        "createdOnGlp":true,
        "deviceTypeName":"LH-PM100E_S6k",
        "gpsLatitude":null,
        "gpsLongitude":null,
        "gpsDilution":null,
        "gpsEnabled":false,
        "installationDate":"2019-04-04",
        "ownerMAC":"00-D0-71-06-5E-63",
        "DID":"17q2d9v.13"
    },
    {
        "name":"SmartServer IoT3",
        "category":"SC",
        "id":"17q2d9v",
        "geozoneId":44,
        "geozoneName":"World",
        "customerId":43,
        "latitude":18.5332,
        "longitude":73.8626,
        "capabilities":{
            "replacement":{
                
            }
        },
        "datapoints":{
            "ScRtsmTiming":{
                "datapointValueType":"SC_RTSM_TIMING",
                "name":"ScRtsmTiming"
            },
            "about":{
                "datapointValueType":"SC_ABOUT",
                "datapointValue":{
                    "product":"SmartServer IoT",
                    "model":"SmartServer IoT Professional Edition",
                    "version":"2.40.504"
                },
                "name":"about"
            },
            "location":{
                "datapointValueType":"LOCATION",
                "datapointValue":{
                    "desc":"",
                    "lat":18.5332,
                    "lng":73.8626,
                    "elevation":null
                },
                "name":"location"
            },
            "ScScheduleAndClockUpdate":{
                "datapointValueType":"SC_SCHEDULE_CLOCK_UPDATE",
                "datapointValue":{
                    "sendsched":null,
                    "ncup":null
                },
                "name":"ScScheduleAndClockUpdate"
            },
            "ScMessaging":{
                "datapointValueType":"SC_MESSAGING",
                "name":"ScMessaging"
            }
        },
        "timezone":"Europe/Kirov",
        "rtsm":"2019-04-10T08:08:54.813+03:00[Europe/Kirov]",
        "firmwareVersion":"2.40.504",
        "status":{
            "state":"provisioned",
            "health":"unknown",
            "connection":"connected",
            "connectionStatusSince":"2019-04-10T08:10:27.379+03:00[Europe/Kirov]",
            "action":null,
            "pingTime":"2019-04-10T05:49:47"
        },
        "MACaddress":"00-D0-71-06-5E-63",
        "SID":"17q2d9v"
    },
    {
        "name":"lh_11",
        "category":"EDGE",
        "id":"17q2d9v.14",
        "geozoneId":44,
        "geozoneName":"World",
        "customerId":43,
        "latitude":21.91597,
        "longitude":72.43172,
        "capabilities":{
            "replacement":{
                
            },
            "commissioning":{
                "commissionMethod":"MANUAL"
            }
        },
        "status":{
            "state":"provisioned",
            "health":"normal",
            "connection":"connected",
            "connectionStatusSince":"2019-04-09T15:30:50.916+03:00[Europe/Kirov]",
            "action":null,
            "product":"LH-PM100E_6k",
            "wasProvisioned":true
        },
        "scName":"SmartServer IoT3",
        "scId":"17q2d9v",
        "scState":"provisioned",
        "uid":"00D073065E62",
        "discoveryMethod":"manual",
        "protocol":"lon",
        "typeId":3331,
        "createdOnGlp":true,
        "deviceTypeName":"LH-PM100E_S6k",
        "gpsLatitude":null,
        "gpsLongitude":null,
        "gpsDilution":null,
        "gpsEnabled":false,
        "installationDate":"2019-04-04",
        "ownerMAC":"00-D0-71-06-5E-63",
        "DID":"17q2d9v.14"
    },
    {
        "name":"lh_12",
        "category":"EDGE",
        "id":"17q2d9v.15",
        "geozoneId":44,
        "geozoneName":"World",
        "customerId":43,
        "latitude":21.91598,
        "longitude":72.43173,
        "capabilities":{
            "replacement":{
                
            },
            "commissioning":{
                "commissionMethod":"MANUAL"
            }
        },
        "status":{
            "state":"provisioned",
            "health":"normal",
            "connection":"connected",
            "connectionStatusSince":"2019-04-09T15:30:50.259+03:00[Europe/Kirov]",
            "action":null,
            "product":"LH-PM100E_6k",
            "wasProvisioned":true
        },
        "scName":"SmartServer IoT3",
        "scId":"17q2d9v",
        "scState":"provisioned",
        "uid":"00D071065E62",
        "discoveryMethod":"manual",
        "protocol":"lon",
        "typeId":3331,
        "createdOnGlp":true,
        "deviceTypeName":"LH-PM100E_S6k",
        "gpsLatitude":null,
        "gpsLongitude":null,
        "gpsDilution":null,
        "gpsEnabled":false,
        "installationDate":"2019-04-04",
        "ownerMAC":"00-D0-71-06-5E-63",
        "DID":"17q2d9v.15"
    },
    {
        "name":"test5",
        "category":"SC",
        "id":"BEcBT2YY",
        "geozoneId":44,
        "geozoneName":"World",
        "customerId":43,
        "latitude":-39.39092,
        "longitude":-70.30276,
        "capabilities":{
            "replacement":{
                
            }
        },
        "datapoints":{
            "ScRtsmTiming":{
                "datapointValueType":"SC_RTSM_TIMING",
                "name":"ScRtsmTiming"
            },
            "about":{
                "datapointValueType":"SC_ABOUT",
                "name":"about"
            },
            "location":{
                "datapointValueType":"LOCATION",
                "name":"location"
            },
            "ScScheduleAndClockUpdate":{
                "datapointValueType":"SC_SCHEDULE_CLOCK_UPDATE",
                "name":"ScScheduleAndClockUpdate"
            },
            "ScMessaging":{
                "datapointValueType":"SC_MESSAGING",
                "name":"ScMessaging"
            }
        },
        "timezone":"America/Argentina/Salta",
        "status":{
            "state":"unprovisioned",
            "action":null
        },
        "MACaddress":"12-34-56-78-AB-CD",
        "SID":"BEcBT2YY"
    },
    {
        "name":"test6",
        "category":"EDGE",
        "id":"17q2d9v.12",
        "geozoneId":44,
        "geozoneName":"World",
        "customerId":43,
        "latitude":27.65758,
        "longitude":80.86912,
        "capabilities":{
            "replacement":{
                
            },
            "commissioning":{
                "commissionMethod":"MANUAL"
            }
        },
        "status":{
            "state":"unprovisioned",
            "action":null,
            "wasProvisioned":false
        },
        "scName":"SmartServer IoT3",
        "scId":"17q2d9v",
        "scState":"provisioned",
        "uid":"3",
        "discoveryMethod":"manual",
        "protocol":"modbus",
        "typeId":1586,
        "createdOnGlp":false,
        "deviceTypeName":"HHG 42 Series Digital Power Meter RTU",
        "gpsLatitude":null,
        "gpsLongitude":null,
        "gpsDilution":null,
        "gpsEnabled":false,
        "installationDate":"2019-04-03",
        "ownerMAC":"00-D0-71-06-5E-63",
        "DID":"17q2d9v.12"
    },
    {
        "name":"test3",
        "category":"EDGE",
        "id":"17q2d9v.5",
        "geozoneId":44,
        "geozoneName":"World",
        "customerId":43,
        "latitude":18.61849,
        "longitude":74.54099,
        "capabilities":{
            "replacement":{
                
            },
            "commissioning":{
                "commissionMethod":"MANUAL"
            }
        },
        "status":{
            "state":"unprovisioned",
            "action":null,
            "wasProvisioned":false
        },
        "scName":"SmartServer IoT3",
        "scId":"17q2d9v",
        "scState":"provisioned",
        "uid":"2",
        "discoveryMethod":"manual",
        "protocol":"modbus",
        "typeId":1586,
        "createdOnGlp":false,
        "deviceTypeName":"HHG 42 Series Digital Power Meter RTU",
        "gpsLatitude":null,
        "gpsLongitude":null,
        "gpsDilution":null,
        "gpsEnabled":false,
        "installationDate":"2019-04-03",
        "ownerMAC":"00-D0-71-06-5E-63",
        "DID":"17q2d9v.5"
    },
    {
        "name":"lh_13",
        "category":"EDGE",
        "id":"17q2d9v.16",
        "geozoneId":44,
        "geozoneName":"World",
        "customerId":43,
        "latitude":21.91599,
        "longitude":72.43173999999999,
        "capabilities":{
            "replacement":{
                
            },
            "commissioning":{
                "commissionMethod":"MANUAL"
            }
        },
        "status":{
            "state":"provisioned",
            "health":"normal",
            "connection":"connected",
            "connectionStatusSince":"2019-04-09T15:30:51.887+03:00[Europe/Kirov]",
            "action":null,
            "product":"LH-PM100E_6k",
            "wasProvisioned":true
        },
        "scName":"SmartServer IoT3",
        "scId":"17q2d9v",
        "scState":"provisioned",
        "uid":"00D074065E62",
        "discoveryMethod":"manual",
        "protocol":"lon",
        "typeId":3331,
        "createdOnGlp":true,
        "deviceTypeName":"LH-PM100E_S6k",
        "gpsLatitude":null,
        "gpsLongitude":null,
        "gpsDilution":null,
        "gpsEnabled":false,
        "installationDate":"2019-04-04",
        "ownerMAC":"00-D0-71-06-5E-63",
        "DID":"17q2d9v.16"
    },
    {
        "name":"test2",
        "category":"EDGE",
        "id":"17q2d9v.4",
        "geozoneId":44,
        "geozoneName":"World",
        "customerId":43,
        "latitude":-13.9234,
        "longitude":-59.0625,
        "capabilities":{
            "replacement":{
                
            },
            "commissioning":{
                "commissionMethod":"MANUAL"
            }
        },
        "firmwareVersion":"HHG 42 Series Digital Power Met",
        "status":{
            "state":"provisioned",
            "health":"down",
            "connection":"connected",
            "connectionStatusSince":"2019-04-10T08:08:01+03:00[Europe/Kirov]",
            "action":null,
            "product":"PM42RTU",
            "wasProvisioned":true
        },
        "scName":"SmartServer IoT3",
        "scId":"17q2d9v",
        "scState":"provisioned",
        "uid":"01:1",
        "discoveryMethod":"manual",
        "protocol":"modbus",
        "typeId":1586,
        "createdOnGlp":true,
        "deviceTypeName":"HHG 42 Series Digital Power Meter RTU",
        "gpsLatitude":null,
        "gpsLongitude":null,
        "gpsDilution":null,
        "gpsEnabled":false,
        "installationDate":"2019-04-03",
        "ownerMAC":"00-D0-71-06-5E-63",
        "DID":"17q2d9v.4"
    }
]

Returns a CSV file with the specified devices, if the current user has permission to read those devices. Throws an AuthorizationException if
the current user doesn't have permission to read these devices.

PUT

/iap/devs/exportByIDs

exportByIDs Example

Request URL: https://192.168.10.8:8443/iap/devs/exportByIDs
Request Payload: ["17q3kbz.15"]

success Response:
	Returns the device.csv file for specified device.

Following are the contents of the device.csv for Modbus device.

protocol,uid,longitude,latitude,timezone,name,deviceType,category,discoveryMethod,installationDate,
customerName,ownerMAC modbus,01:1,0.0,0.0,America/Los_Angeles,modbus_1,"AMIK 201 Series Digital Power Meter RTU",
EDGE,manual,2019-05-17,"Customer 1",00-D0-71-07-08-D1

Change a Device's Edge Server

Changes the segment controller of the specified EDGE device to another specified segment controller.

If the device was in a group the information about this group will be transferred to the new segment controller.

PUT	/iap/devs/{devId}/changeScTo/{scid}

Required params are:

devid: Device ID of the edge device for which changing operation will be performed.

scid: sid of the new segment controller

Change a device's segment controller Example

PUT  /iap/devs/Ab93fcpn.13/changeScTo/2bzzwZs

Response :
{
"name": "LHP_sim1",
"category": "EDGE",
"id": "Ab93fcpn.13",
"geozoneId": 88,
"geozoneName": "World",
"customerId": 81,
"latitude": 40.9799,
"longitude": -103.35937,
"capabilities": {
"replacement": {},
"commissioning": {
"commissionMethod": "MANUAL"
}
},
"status": {
"state": "unprovisioned",
"action": null,
"wasProvisioned": false
},
"scName": "sc239",
"scId": "2bzzwZs",
"scState": "provisioned",
"uid": null,
"discoveryMethod": "manual",
"protocol": "lon",
"typeId": 128,
"createdOnGlp": false,
"deviceTypeName": "LH-PM100E_S6k",
"gpsLatitude": null,
"gpsLongitude": null,
"gpsDilution": null,
"gpsEnabled": false,
"installationDate": "2019-04-04",
"ownerMAC": "00-0C-E3-74-4F-89",
"DID": "Ab93fcpn.13"
}

Creating Devices

Creates a new edge server or Edge device in the CMS.

PUT	/iap/devs

Creating Devices Examples

Edge Device Create:

Request:	
Method: PUT
URL: https://192.168.77.6:8443/iap/devs
Payload:
{"name":"test3","category":"EDGE","latitude":18.61849,"longitude":74.54099,
"status":{},"olcProfiles":[{}],"uid":"1","discoveryMethod":"manual",
"ownerMAC":"00-D0-71-06-5E-63","scId":"17q2d9v","protocol":"modbus","typeId":1586}

Response:
{"name":"test3","category":"EDGE","id":"17q2d9v.5","geozoneId":44,"geozoneName":"World",
"customerId":43,"latitude":18.61849,"longitude":74.54099,"capabilities":{"replacement":{},
"commissioning":{"commissionMethod":"MANUAL"}},"status":{"state":"unprovisioned",
"action":null,"wasProvisioned":false},"scName":"SmartServer IoT3","scId":"17q2d9v",
"scState":"provisioned","uid":"1","discoveryMethod":"manual","protocol":"modbus",
"typeId":1586,"createdOnGlp":false,"deviceTypeName":"HHG 42 Series Digital Power Meter RTU",
"gpsLatitude":null,"gpsLongitude":null,"gpsDilution":null,"gpsEnabled":false,
"installationDate":"2019-04-03","ownerMAC":"00-D0-71-06-5E-63","DID":"17q2d9v.5"}


Segment Controller Device Create:

Request:	
Method: PUT	
URL: https://192.168.77.6:8443/iap/devs
Payload:
{"name":"test5","category":"SC","timezone":"America/Argentina/Salta","latitude":-39.39092,
"longitude":-70.30276,"status":{},"olcProfiles":[{}],"MACaddress":"12-34-56-78-AB-CD"}

Response:
{"name":"test5","category":"SC","id":"BEcBT2YY","geozoneId":44,"geozoneName":"World",
"customerId":43,"latitude":-39.39092,"longitude":-70.30276,"capabilities":{"replacement":{}},
"datapoints":{"ScRtsmTiming":{"datapointValueType":"SC_RTSM_TIMING","name":"ScRtsmTiming"},
"about":{"datapointValueType":"SC_ABOUT","name":"about"},"location":{"datapointValueType":"LOCATION",
"name":"location"},"ScScheduleAndClockUpdate":{"datapointValueType":"SC_SCHEDULE_CLOCK_UPDATE",
"name":"ScScheduleAndClockUpdate"},"ScMessaging":{"datapointValueType":"SC_MESSAGING",
"name":"ScMessaging"}},"timezone":"America/Argentina/Salta","status":{"state":"unprovisioned",
"action":null},"MACaddress":"12-34-56-78-AB-CD","SID":"BEcBT2YY"}

The CMS also supports bulk device creation.

POST	/iap/devs/bulk

Bulk Device Creation

POST: https://192.168.77.6:8443/iap/devs/bulk
Payload:
{"namePrefix":"Test_Modbus_","count":4,"from":6,"deviceTemplate":{"category":"EDGE",
"latitude":54.55508,"longitude":63.99412,"status":{},"olcProfiles":[{}],"discoveryMethod":"manual",
"ownerMAC":"12-34-56-78-AB-CD","scId":"BEcBT2YY","protocol":"modbus","typeId":1586}}

Response:
[{"name":"Test_Modbus_6","category":"EDGE","id":"BEcBT2YY.8","geozoneId":44,"geozoneName":"World",
"customerId":43,"latitude":54.55513,"longitude":63.994170000000004,"capabilities":{"replacement":{},
"commissioning":{"commissionMethod":"MANUAL"}},"status":{"state":"unprovisioned","action":null,
"wasProvisioned":false},"scName":"test5","scId":"BEcBT2YY","scState":"unprovisioned","uid":null,
"discoveryMethod":"manual","protocol":"modbus","typeId":1586,"createdOnGlp":false,
"deviceTypeName":"HHG 42 Series Digital Power Meter RTU","gpsLatitude":null,"gpsLongitude":null,
"gpsDilution":null,"gpsEnabled":false,"installationDate":"2019-04-03","ownerMAC":"12-34-56-78-AB-CD",
"DID":"BEcBT2YY.8"},{"name":"Test_Modbus_7","category":"EDGE","id":"BEcBT2YY.9","geozoneId":44,
"geozoneName":"World","customerId":43,"latitude":54.555139999999994,"longitude":63.99418,
"capabilities":{"replacement":{},"commissioning":{"commissionMethod":"MANUAL"}},"status":{"state":"unprovisioned",
"action":null,"wasProvisioned":false},"scName":"test5","scId":"BEcBT2YY","scState":"unprovisioned",
"uid":null,"discoveryMethod":"manual","protocol":"modbus","typeId":1586,"createdOnGlp":false,
"deviceTypeName":"HHG 42 Series Digital Power Meter RTU","gpsLatitude":null,"gpsLongitude":null,
"gpsDilution":null,"gpsEnabled":false,"installationDate":"2019-04-03","ownerMAC":"12-34-56-78-AB-CD","DID":"BEcBT2YY.9"},
{"name":"Test_Modbus_8","category":"EDGE","id":"BEcBT2YY.10","geozoneId":44,"geozoneName":"World","customerId":43,
"latitude":54.55515,"longitude":63.99419,"capabilities":{"replacement":{},"commissioning":{"commissionMethod":"MANUAL"}},
"status":{"state":"unprovisioned","action":null,"wasProvisioned":false},"scName":"test5","scId":"BEcBT2YY",
"scState":"unprovisioned","uid":null,"discoveryMethod":"manual","protocol":"modbus","typeId":1586,"createdOnGlp":false,
"deviceTypeName":"HHG 42 Series Digital Power Meter RTU","gpsLatitude":null,"gpsLongitude":null,"gpsDilution":null,
"gpsEnabled":false,"installationDate":"2019-04-03","ownerMAC":"12-34-56-78-AB-CD","DID":"BEcBT2YY.10"},{"name":"Test_Modbus_9",
"category":"EDGE","id":"BEcBT2YY.11","geozoneId":44,"geozoneName":"World","customerId":43,"latitude":54.555159999999994,
"longitude":63.9942,"capabilities":{"replacement":{},"commissioning":{"commissionMethod":"MANUAL"}},
"status":{"state":"unprovisioned","action":null,"wasProvisioned":false},"scName":"test5","scId":"BEcBT2YY",
"scState":"unprovisioned","uid":null,"discoveryMethod":"manual","protocol":"modbus","typeId":1586,"createdOnGlp":false,
"deviceTypeName":"HHG 42 Series Digital Power Meter RTU","gpsLatitude":null,"gpsLongitude":null,"gpsDilution":null,
"gpsEnabled":false,"installationDate":"2019-04-03","ownerMAC":"12-34-56-78-AB-CD","DID":"BEcBT2YY.11"}]

Deleting Devices

Deletes a collection of the specified devices from the CMS.

PUT	/iap/devs/delete

Delete Devices Example

PUT: https://192.168.77.6:8443/iap/devs/delete
Payload:
["BEcBT2YY.8","BEcBT2YY.9","BEcBT2YY.10","BEcBT2YY.11"]

Response:
["BEcBT2YY.8","BEcBT2YY.9","BEcBT2YY.10","BEcBT2YY.11"]

Managing Floor Assignments

Creates a new device on the specified floor.

POST	/iap/floorplans

Create Floor Plan Example

POST: https://192.168.77.6:8443/iap/floorplans
Pyaload:
{"geozoneId":44,"name":"Floor1","description":"First floor devices","latitude":20.31258,"longitude":73.82804}

Response:
{"id":2239,"name":"Floor1","description":"First floor devices","geozoneId":44,"latitude":20.31258,"longitude":73.82804}

Get the floor plan of the current user.

GET	/iap/floorplans

Getting Floor Plan Example

GET    /iap/floorplans
[
    {
        "id":698,
        "name":"Floor1",
        "description":"First floor plan",
        "geozoneId":44,
        "latitude":17.30869,
        "longitude":73.125
    },
    {
        "id":699,
        "name":"FloorPlan1",
        "description":"FloorPlan1",
        "geozoneId":44,
        "latitude":13.23995,
        "longitude":76.64063
    }
]

Get the specified floor plan by floor id.

GET	/iap/floorplans/699/floors

Get Specified Floor Plan Example

GET    /iap/floorplans/699/floors
[
    {
        "id":700,
        "name":"First_Floor",
        "description":"First Floor plan create",
        "floorNumber":"1",
        "floorplanId":699,
        "image":"/9j/4QAYRXhpZgAASUkqAAgAAAAAAAAAAAAAAP/
		bPxeLrG85PAbPxeLrG85bCIPKO3ghJdFEyMnYSxoaae0vVEQEREBERA
		REQEREBERAREQEREBERAREQEREBERAREQEREBERAREQEREBERAREQEREBERARE
		QEREBERAREQEREBERAREQEREBERAREQEREBERAREQEREBERAREQEREBERAREQERE
		BERAREQEREBERAREQEREBERAREQEREBERAREQEREBERAREQEREBERAREQEREBERAREQ
		EREBERAREQEREBERAREQEREBERAREQEREBERB//9k=",
        "devicesCount":0
    }
]

Get a collection of floor plans with coordinates for specified ids

PUT	/iap/floorplans/listByIDs

Floorplan listByIDs Example

PUT    /iap/floorplans/listByIDs
Payload: [698, 699]

[
    {
        "id":698,
        "name":"Floor1",
        "description":"First floor plan",
        "geozoneId":44,
        "latitude":17.30869,
        "longitude":73.125
    },
    {
        "id":699,
        "name":"FloorPlan1",
        "description":"FloorPlan1",
        "geozoneId":44,
        "latitude":13.23995,
        "longitude":76.64063
    }
]

Update already existed floor plan with specified properties

PUT	/iap/floorplans/{id}

Update floor plan Example

PUT    /iap/floorplans/699
Payload: {"id":699,"name":"FloorPlan1","description":"FloorPlan1 Updated","geozoneId":44,"latitude":13.23995,"longitude":76.64063}

{
    "id":699,
    "name":"FloorPlan1",
    "description":"FloorPlan1 Updated",
    "geozoneId":44,
    "latitude":13.23995,
    "longitude":76.64063
}

Deletes specified floor plan from the CMS

Delete floor by id

DELETE    /iap/floorplans/698
Payload: {"id":699,"name":"FloorPlan1","description":"FloorPlan1 Updated","geozoneId":44,"latitude":13.23995,"longitude":76.64063}

{
    "value":true
}

Updating Devices

Updates the specified device's properties.

PUT	/iap/devs/updateProperties

Update Device Properties Payload Example

{
  "id": "17q2d9v.4",
  "name": "test2",
  "latitude": -13.9234,
  "longitude": -59.0625,
  "category": "EDGE",
  "scId": "17q2d9v",
  "capabilities": {
    "replacement": {},
    "commissioning": {
      "commissionMethod": "MANUAL"
    }
  },
  "protocol": "modbus",
  "scState": "provisioned",
  "scName": "SmartServer IoT3",
  "uid": "01:1",
  "typeId": 1586,
  "firmwareVersion": "HHG 42 Series Digital Power Met",
  "installationDate": "2019-04-03",
  "geozoneId": 44,
  "customerId": 43,
  "gpsEnabled": false,
  "gpsLatitude": null,
  "gpsLongitude": null,
  "gpsDilution": null,
  "geozoneName": "World",
  "ownerMAC": "00-D0-71-06-5E-63",
  "discoveryMethod": "manual",
  "DID": "17q2d9v.4",
  "olcProfiles": [
    {}
  ],
  "createdOnGlp": true,
  "metadata": {
    "stateClass": "device on-background provisioned health-normal",
    "sc": {
      "id": "17q2d9v",
      "name": "SmartServer IoT3",
      "latitude": 18.5332,
      "longitude": 73.8626,
      "category": "SC",
      "status": {
        "state": "provisioned",
        "health": "normal",
        "connection": "connected",
        "connectionStatusSince": "2019-04-03T09:54:28.991+03:00[Europe/Kirov]",
        "action": null,
        "pingTime": "2019-04-03T09:04:29"
      },
      "capabilities": {
        "replacement": {}
      },
      "firmwareVersion": "2.40.504",
      "geozoneId": 44,
      "customerId": 43,
      "datapoints": {
        "ScRtsmTiming": {
          "datapointValueType": "SC_RTSM_TIMING",
          "name": "ScRtsmTiming"
        },
        "about": {
          "datapointValueType": "SC_ABOUT",
          "datapointValue": {
            "product": "SmartServer IoT",
            "model": "SmartServer IoT Professional Edition",
            "version": "2.40.504"
          },
          "name": "about"
        },
        "location": {
          "datapointValueType": "LOCATION",
          "datapointValue": {
            "desc": "",
            "lat": 18.5332,
            "lng": 73.8626,
            "elevation": null
          },
          "name": "location"
        },
        "ScScheduleAndClockUpdate": {
          "datapointValueType": "SC_SCHEDULE_CLOCK_UPDATE",
          "datapointValue": {
            "sendsched": null,
            "ncup": null
          },
          "name": "ScScheduleAndClockUpdate"
        },
        "ScMessaging": {
          "datapointValueType": "SC_MESSAGING",
          "name": "ScMessaging"
        }
      },
      "rtsm": "2019-04-03T10:04:04.011+03:00[Europe/Kirov]",
      "geozoneName": "World",
      "MACaddress": "00-D0-71-06-5E-63",
      "timezone": "Europe/Kirov",
      "SID": "17q2d9v",
      "metadata": {
        "stateClass": "device on-background provisioned health-normal"
      }
    }
  }
}

Response Example for Update Device Properties

{
  "name": "test2",
  "category": "EDGE",
  "id": "17q2d9v.4",
  "geozoneId": 44,
  "geozoneName": "World",
  "customerId": 43,
  "latitude": -13.9234,
  "longitude": -59.0625,
  "capabilities": {
    "replacement": {},
    "commissioning": {
      "commissionMethod": "MANUAL"
    }
  },
  "firmwareVersion": "HHG 42 Series Digital Power Met",
  "status": {
    "state": "provisioned",
    "health": "normal",
    "connection": "connected",
    "connectionStatusSince": "2019-04-03T11:56:33+03:00[Europe/Kirov]",
    "action": null,
    "product": "PM42RTU",
    "wasProvisioned": true
  },
  "scName": "SmartServer IoT3",
  "scId": "17q2d9v",
  "scState": "provisioned",
  "uid": "01:1",
  "discoveryMethod": "manual",
  "protocol": "modbus",
  "typeId": 1586,
  "createdOnGlp": true,
  "deviceTypeName": "HHG 42 Series Digital Power Meter RTU",
  "gpsLatitude": null,
  "gpsLongitude": null,
  "gpsDilution": null,
  "gpsEnabled": false,
  "installationDate": "2019-04-03",
  "ownerMAC": "00-D0-71-06-5E-63",
  "DID": "17q2d9v.4"
}

Device Firmware Upgrade

We can perform a firmware upgrade for devices from the CMS portal. Valid application image file is required to upgrade the firmware image.
Below example shows the firmware upgrade for LON device.

Following are the steps to perform LON device firmware upgrade from CMS portal:

From widget devices select the LON device "LH-0" Edge Device
Select load image from drop down menu
Provide the new LON device application image file
CMS will load the application image file and send it to LON device.

Following are the API's which involve for firmware upgrade:

Updates the firmware for the device with device id {id} which is the target for the update.

PUT	/iap/devs/load/{id}

Updates firmware or file of the specified device. For the moment this method has the
following limitations: only manifest files with an external link to an image can be processed. Content-type for /iap/devs/load REST API is multipart/form-data.

Request payload will be a zip file containing the valid manifest file.

Device Firmware Upgrade Example

Get the list of available firmware images before device firmware upgrade.

Request URL: https://192.168.10.3:8443/iap/devs/firmwareImgList?deviceId=17q2eh2.2
Request Method: GET
Query String Parameter:
deviceId: 17q2eh2.2

Response:
[]


Upgrade the device with device id: "17q2eh2.2"

Request URL: https://192.168.10.3:8443/iap/devs/load/17q2eh2.2
Request Method: PUT

Request payload:

------WebKitFormBoundarypN8G6kytdOfSMjQs
Content-Disposition: form-data; name="metafile"; filename="LH-PM100E_6k.APB"
Content-Type: application/octet-stream


------WebKitFormBoundarypN8G6kytdOfSMjQs--


Verify the newly loaded firmware image shown in the /iap/devs/firmwareImgList REST api.

Request URL: https://192.168.10.3:8443/iap/devs/firmwareImgList?deviceId=17q2eh2.2
Request Method: GET
Query String parameter:
deviceId: 17q2eh2.2


Response:
[{"id":5836,"fileName":"LH-PM100E_6k.APB","mimeType":{"primaryType":"application","subType":"octet-stream","parameters":{"names":{},"empty":true},"baseType":"application/octet-stream"},"metafileHashtags":[{"id":5838,"hashtagId":42,"name":"deviceType","value":"LH-PM100E_S6k"},{"id":5837,"hashtagId":38,"name":"firmwareImage","value":"true"}],"dataUrlPrefix":"data:application/octet-stream;base64,"}]

EnOcean Edge Portal

Managing Devices