EI-Connect to EI-PaaS Protocol

From ESS-WIKI
Jump to: navigation, search

Overview

Introduction for "EI-Agent communication protocol". EI-Agent communication protocol is base on standard MQTT protocol. We also define Advantech IoT Topic and message in JSON format. Follow standard to design our [Sensor Format in JSON ]

Protocol

Connect

  • Description: Agent Client sends the "Connect Info" to RMM Server for on-line notification.
  • Type: Info
  • Direction: Agent -> Server
  • Topic: /wisepaas/<tenantId>/device/<agentId>/agentinfoack
  • QoS: 0
  • Retained: 0
  • Payload:
{
    "content":{
        "parentID":"",
        "hostname":"WISECoreSample",
        "sn":"305A3A77B1CC",
        "mac":"305A3A77B1CC",
        "version":"1.0.1",
        "type":"IPC",
        "product":"Sample",
        "manufacture":"Sample",
        "account":"",
        "passwd":"",
        "status":1,
        "tag":"device"
    },
    "commCmd":1,
    "agentID":"00000001-0000-0000-0000-305A3A770020",
    "handlerName":"general",
    "sendTS":{
        "$date":1504508254652
    }
}

OS Info

  • Description: Agent Client sends the OS Info" to RMM Server for device OS information.
  • Type: Info
  • Direction: Agent -> Server
  • Topic: /wisepaas/<tenantId>/RMM/<agentId>/agentactionack
  • QoS: 0
  • Retained: 0
  • Payload:
{
    "content":{
        "cagentVersion":"3.1.23",
        "cagentType":"IoTGW",
        "osVersion":"SnailOS",
        "biosVersion":"",
        "platformName":"",
        "processorName":"Snail",
        "osArch":"Snail",
        "totalPhysMemKB":123,
        "macs":"F4B85E4A9B9E",
        "IP":""
    },
    "commCmd":116,
    "agentID":"00000001-0000-0000-0000-305A3A770020",
    "handlerName":"general",
    "sendTS":{
        "$date":1466730390
    }
}


Disconnect

  • Description: Agent Client sends the "Disconnect Info" to Server for off-line notification.
  • Type: Info
  • Direction: Agent -> Server
  • Topic: /wisepaas/<tenantId>/device/<agentId>/agentinfoack
  • QoS: 0
  • Retained: 0
  • Payload:
{
    "content":{
        "parentID":"",
        "hostname":"WISECoreSample",
        "sn":"305A3A77B1CC",
        "mac":"305A3A77B1CC",
        "version":"1.0.1",
        "type":"IPC",
        "product":"Sample",
        "manufacture":"Sample",
        "account":"",
        "passwd":"",
        "status":0,
        "tag":"device"
    },
    "commCmd":1,
    "agentID":"00000001-0000-0000-0000-305A3A770020",
    "handlerName":"general",
    "sendTS":{
        "$date":1504508254652
    }
}

Will Message

  • Description: While Client lost connection or keep-alive timeout, the will message will send to the client that subscribe the topic
  • Type: Info
  • Direction: Agent -> Broker
  • Topic: /wisepaas/<tenantId>/device/<agentId>/willmessage
  • QoS: 0
  • Retained: 0
  • Payload:
{
    "content":{
        "parentID":"",
        "hostname":"WISECoreSample",
        "sn":"305A3A77B1CC",
        "mac":"305A3A77B1CC",
        "version":"1.0.1",
        "type":"IPC",
        "product":"Sample",
        "manufacture":"Sample",
        "account":"",
        "passwd":"",
        "status":0,
        "tag":"device"
    },
    "commCmd":1,
    "agentID":"00000001-0000-0000-0000-305A3A770020",
    "handlerName":"general",
    "sendTS":{
        "$date":1504514942534
    }
}

Info or Update Device's Capability

  • Description: Agent will send it's capability to Server for description all resource.
  • Type: Auto update
  • Direction: Agent-> Server
  • Topic: /wisepaas/<tenantId>/device/<agentId>/agentactionreq
  • QoS: 0
  • Retained: 0
  • Payload: 

Example: SenHub's Capability

{
    "content":{
        "SenHub":{
            "SenData":{
                "e":[
                    {
                        "n":"Temperature",
                        "u":"Cel",
                        "v":0,
                        "min":-100,
                        "max":200,
                        "asm":"r",
                        "type":"d",
                        "rt":"ucum.Cel",
                        "st":"ipso",
                        "exten":""
                    },
                    {
                        "n":"Humidity",
                        "u":"%",
                        "v":0,
                        "min":0,
                        "max":100,
                        "asm":"r",
                        "type":"d",
                        "rt":"ucum.%",
                        "st":"ipso",
                        "exten":""
                    },
                    {
                        "n":"GPIO1",
                        "u":"",
                        "bv":false,
                        "min":false,
                        "max":true,
                        "asm":"rw",
                        "type":"b",
                        "rt":"",
                        "st":"ipso",
                        "exten":""
                    },
                    {
                        "n":"GPIO2",
                        "u":"",
                        "bv":false,
                        "min":false,
                        "max":true,
                        "asm":"r",
                        "type":"b",
                        "rt":"",
                        "st":"ipso",
                        "exten":""
                    },
                    {
                        "n":"RAW",
                        "u":"",
                        "sv":"QUJDREU=",
                        "min":0,
                        "max":1,
                        "asm":"rw",
                        "type":"s",
                        "rt":"",
                        "st":"ipso",
                        "exten":"",
                        "format":"base64"
                    }
                ],
                "bn":"SenData"
            },
            "Info":{
                "e":[
                    {
                        "n":"SenHubList",
                        "u":"",
                        "sv":"",
                        "min":0,
                        "max":0,
                        "asm":"r",
                        "type":"s",
                        "rt":"",
                        "st":"ipso",
                        "exten":""
                    },
                    {
                        "n":"Neighbor",
                        "u":"",
                        "sv":"",
                        "min":0,
                        "max":0,
                        "asm":"r",
                        "type":"s",
                        "rt":"",
                        "st":"ipso",
                        "exten":""
                    },
                    {
                        "n":"Name",
                        "u":"",
                        "sv":"SenHub1",
                        "min":0,
                        "max":0,
                        "asm":"r",
                        "type":"s",
                        "rt":"",
                        "st":"ipso",
                        "exten":""
                    },
                    {
                        "n":"Health",
                        "u":"",
                        "v":100,
                        "min":0,
                        "max":0,
                        "asm":"r",
                        "type":"d",
                        "rt":"",
                        "st":"ipso",
                        "exten":""
                    },
                    {
                        "n":"sw",
                        "u":"",
                        "sv":"1.2.1.12",
                        "min":0,
                        "max":0,
                        "asm":"r",
                        "type":"s",
                        "rt":"",
                        "st":"ipso",
                        "exten":""
                    },
                    {
                        "n":"reset",
                        "u":"",
                        "bv":false,
                        "min":false,
                        "max":true,
                        "asm":"rw",
                        "type":"b",
                        "rt":"",
                        "st":"ipso",
                        "exten":""
                    }
                ],
                "bn":"Info"
            },
            "Net":{
                "e":[
                ],
                "bn":"Net"
            },
            "Action":{
                "e":[
                ],
                "bn":"Action"
            },
            "ver":1
        }
    },
    "commCmd":2052,
    "agentID":"00000001-0000-0000-0000-305A3A770020",
    "handlerName":"general",
    "sendTS":{
        "$date":1504510177735
    }
}


Auto Update Sensor Data Value

  • Description: Agent will update latest value to server.
  • Type: Auto update
  • Direction: Agent-> Server
  • Topic: /wisepaas/<tenantId>/device/<agentId>/devinfoack
  • QoS: 0
  • Retained: 0
  • Payload:
{
    "content":{
        "opTS":{
            "$date":1504510177742
        },
        "IoTGW":{
            "Ethernet":{
                "00000000-0000-0000-0000-111122220666":{
                    "SenData":{
                        "e":[
                            {
                                "n":"Temperature",
                                "v":0
                            },
                            {
                                "n":"Humidity",
                                "v":56
                            },
                            {
                                "n":"GPIO1",
                                "bv":false
                            },
                            {
                                "n":"GPIO2",
                                "bv":false
                            },
                            {
                                "n":"RAW",
                                "sv":"QUJDREU=",
                                "format":"base64"
                            }
                        ],
                        "bn":"SenData"
                    },
                    "bn":"00000000-0000-0000-0000-111122220666",
                    "ver":1
                },
                "bn":"Ethernet"
            },
            "ver":1
        }
    },
    "commCmd":2055,
    "agentID":"00000001-0000-0000-0000-305A3A770020",
    "handlerName":"general",
    "sendTS":{
        "$date":1504510177742
    }
}

Get Sensor Data

  • Description: Server can send mqtt message to get sensor data value.
  • Type: Request
  • Direction: Server -> Agent
  • Topic: /wisepaas/<tenantId>/device/<agentId>/agentactionreq
  • QoS: 0
  • Retained: 0
  • Payload:
{
    "agentId": "00000001-0000-0000-0000-305A3A770020",
    "handlerName": "SenHub",
    "commCmd": 523,
    "content": {
        "sensorIDList": {
            "e": [
                {"n": "SenHub/Info/sw"}
            ]
        },
        "sessionID": "2A1FBCA22A64C2E27341DB5FA7E83FBF"
    }
}
  • Description: Agent will reply its data value.
  • Type: Reply
  • Direction: Agent -> Server
  • Topic: /wisepaas/<tenantId>/device/<agentId>/agentactionack
  • QoS: 0
  • Retained: 0
  • Payload:
{
    "agentID": "00000001-0000-0000-0000-305A3A770020",
    "commCmd": 524,
    "handlerName": "SenHub",
    "content": {
        "sessionID": "2746E3B65BAB115338B9668CDC5C35C4",
        "sensorIDList": {
            "e": [
                {
                    "n": "/Info/sw",
                    "v": "1.0.00",
                    "StatusCode": 200
                }
            ]
        }
    },
    "sendTS": {"$date": 1499328934471}
}

Set Sensor Data

  • Description: Server can send mqtt message to set sensor data value.
  • Type: Request
  • Direction: Server -> Agent
  • Topic: /wisepaas/<tenantId>/device/<agentId>/agentactionreq
  • QoS: 0
  • Retained: 0
  • Payload:
{
    "agentId": "00000001-0000-0000-0000-305A3A770020",
    "handlerName": "SenHub",
    "commCmd": 525,
    "content": {
        "sensorIDList": {
            "e": [
                {
                    "sv":"SenHub1",
                    "n":"SenHub/Info/Name"
                }
            ]
        },
        "sessionID": "4DDF0B6DE2773176095F55E8C930507A"
    }
}
  • Description: Agent will reply its result.
  • Type: Reply
  • Direction: Agent -> Server
  • Topic: /wisepaas/<tenantId>/device/<agentId>/agentactionreq
  • QoS: 0
  • Retained: 0
  • Payload:
{
    "agentID": "00000001-0000-0000-0000-305A3A770020",
    "commCmd": 526,
    "handlerName": "SenHub",
    "content": {
        "sessionID": "4DDF0B6DE2773176095F55E8C930507A",
        "sensorIDList":{
            "e": [
                {
                    "n": "/Info/Name",
                    "sv": "SenHub1",
                    "StatusCode": 200
                }
            ]
        },
    },
    "sendTS": {"$date": 1499329284038}
}

EventNotify

  • Description: 
  • Type: Auto update
  • Direction: Agent -> Server
  • Topic: /wisepaas/<tenantId>/device/<agentId>/eventnotifyack
  • QoS: 0
  • Retained: ?
  • Payload:
{  
    "content": {
        "eventnotify": {
            "subtype": "predict",
            "msg": "Hard disk long-term operation in more than 40°C or vibration environment.",
            "severity": 4,
            "handler": "HDD_PMQ",
            "extMsg": {
                "n": "WDC WD3200BUCT-63TWBY0",
                "eventID":"e2"
            }
        }
    },
    "agentID":"00000001-0000-0000-0000-305A3A770020",
    "commCmd":2059,
    "handlerName":"general",
    "sendTS":{
        "$date":1504510177742
    }    
}


severity:
     Severity_Emergency = 0,
     Severity_Alert     = 1,
     Severity_Critical  = 2,
     Severity_Error     = 3,
     Severity_Warning   = 4,
     Severity_Informational = 5,
     Severity_Debug     = 6,

subtype: 
    THRESHOLD_CHECK_INFO
    THRESHOLD_CHECK_ERROR