Identity API

Identity API

On the success of the Discovery Call, you will get the URL of the Identity API. This API will provide additional values that will be required to establish the device connection, send telemetry data, etc.

Example:

Request:
     Base_Url : URL_PROVIDED_BY_DISCOVERY_API
     Endpoint : [BASE_URL]/sync
     Method : POST
     Header accept : application/json
     Header Content-Type : application/json-patch+json

body Request:
{
     "cpId": "string", // A string represents CPID of company
     "uniqueId": "string", // A string represents uniqueid of device
     "option": {
               "attribute": true, // true/false – to receive attribute information
               "setting": true, // true/false – to receive setting/twin information
               "rule": true, // true/false – to receive rule information [for Edge]
               "protocol": true, // true/false – to receive protocol information
               "device": true, // true/false – to receive device information
               "sdkConfig": true // true/false – to receive sdk configuration
               }
}

Identity Response:
{
     "dtg": "", // A unique identifier represents the Device Template guid [DTG]
     "cpId": "", // A string represents the CPID of company
     "rc": 0, // An integer represents the response code [Ref: Table 1]
     "ee": 1, // An integer represents if supports Edge is enabled or not [Ref: Table 2]
     "at": 1, // An integer represents the device authentication type [Ref: Table 3]
     "ota": {}, // An object represents the OTA information [Ref: Section 2.2]
     "sc": {}, // An object represents the SDK configuration [Ref: Section 2.3]
     "p": {}, // An object represents the Protocol information [Ref: Section 2.4]
     "d": [], // An array of object represents the Device(s) information [Ref: Section 2.5]
     "att": [], // An array of object represents the Attribute(s) information [Ref: Section 2.6]
     "set": [], // An array of object represents the Setting/Twin(s) information [Ref: Section 2.7]
     "r": [] // An array of object represents the Rules defined on template [Ref: Section 2.8]
}

Reference Tables

Table 1 [Possible values for rc]

Table 2 [Possible values for ee]

Table 3 [Possible values for at]

Section 2.2 Object represents OTA information in OTA tag

{
     "force": false, // A Boolean value to identify if ota is force update or not
     "guid": "", // A unique identifier represents the ota update item guid
     "urls": [] // A string array represents the ota files
}

Force OTA update

As platform IoTConnect have a feature that without getting the latest update device will not send data back to
cloud. For this “force” will be set to true and URLs for getting firmware update will be mentioned in “url”
tag.

As part of sending an acknowledgement of valid update, you need to send an acknowledgement back to
IoTConnect cloud to sync up the OTA status of the device in the cloud. Please refer this section on how to send
OTA Update status back to IoTConnect Cloud

Section 2.3 Object represents SDK Configuration in sc tag

{
     "hb": 
          { // Configuration to send Heart Beat
               "fq": 99, // An integer represents the frequency of sending heart beat
               "h": "", // A string represents mqtt host name
               "un": "", // A string represents mqtt user name to connect host
               "pwd": "", // A string represents mqtt password name to connect host
               "pub": "" // A string represents pub topic to send heart beat message
          },
     "log": { // Configuration to send device log information
               "h": "", // A string represents mqtt host name
               "un": "", // A string represents mqtt user name to connect host
               "pwd": "", // A string represents mqtt password name to connect host
               "pub": "" // A string represents pub topic to send heart beat message
          },
     "sf": 99, // A number represents the identity api call frequency.
     "df": 60  // A number represents the Data sednd frequency in seconds configured in template 
}

The above configuration is used to send additional information back to IoTConnect. In some cases, the device
wants to send a heartbeat or sending log files. They can use this information and send a message back to
IoTConnect. Sf will be the number that stands for sync frequency like if sync call failed then what will next
time sync needs to be initiated again.

Section 2.4 Object represents Protocol information in p tag

{
     "n": "", // A string represents the name of protocol [Ref: Table 4]
     "h": "" // A string represents the mqtt host name to connect
     "p": 8883 // A fixed integer represents port to connect mqtt host [
     "id": "", // A string represents the mqtt client id
     "un": "", // A string represents the user name for mqtt connection
     "pwd": "", // A string represents the password for mqtt connection [Only AuthType 1]
     "pub": "", // A string represents mqtt publish topic to send D2C data [PUB_TOPIC]
     "sub": "" // A string represents mqtt publish topic to receive D2C data [SUB_TOPIC]
}

Reference tables
Table 4 [Possible values for n]

Section 2.5 Array of object represents Device information in d tag

{
     "tg": "", // A string represents the device tag
     "id": "", // A string represents the device uniqueid / identity
     "s": 0 // A integer represents the device status [Ref: Table 5]
}

Reference Tables
Table 5 [Possible values for s]

Section 2.6 Array of object represents Attribute(s) information in att tag

{
     "ln": "", // A string represents the local name of attribute
     "dt": 0, // An integer represents data type of attribute [Ref: Table 7]
     "dv": "", // A string contains the data validation [Ref: Table 8]
     "tg": "", // A string represents the tag of attribute
     "sq": 1, // An integer represents the sequence of attribute
     "agt": 0, // An integer represents the aggregation type [Ref: Table 9]
     "tw": "" // A string represents the tumbling window [Ref: Table 10]
}

Reference tables
Table 6 [Possible values for dt]

Table 7 [Possible values for dt]

Table 8 [Possible values for dv]

Table 9 [Possible values for agt]
Sum of following integer.

If value is 14 then aggregation on Average, Sum & Max
If value is 20 then aggregation on Count & Sum

Table 10 [Possible values for tw]

Section 2.6.1 Array of object represents Attribute(s) information in d tag

{
     "ln": "", // A string represents the local name of attribute
     "dt": 0, // An integer represents data type of attribute [Ref: Table 7]
     "dv": "", // A string contains the data validation [Ref: Table 8]
     "tg": "", // A string represents the tag of attribute
     "sq": 1, // An integer represents the sequence of attribute
     "agt": 0, // An integer represents the aggregation type [Ref: Table 9]
     "tw": "" // A string represents the tumbling window [Ref: Table 10]
}

Section 2.7: Array of object represents Setting/Twin(s) information in set tag

{
     "ln": "", // A string represents the name of Setting or Twin
     "dt": 0, // An integer represents the data type of Setting or Twin [Ref: Table 7]
     "dv": "" // A string represents the data validation for Setting or Twin [Ref: Table 8]
}

Section 2.8: Array of object represents Rule information in r tag [Only for Edge Enabled device]

{
     "g": "", // A unique identifier represents the rule guid
     "es": "", // A unique identifier represents the subscription guid
     "con": "", // A string represents the condition for rule evaluation
     "att": [ // An array of attribute guid, on which condition is going to applied
              {
               "g": []
              }
          ],
     "cmd": "" // A string contains command to execute if rule matched
}