EI-Connect to EI-PaaS Protocol

From ESS-WIKI
Revision as of 12:19, 4 September 2017 by Sam35.lin (talk | contribs)
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: 2
  • 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>/device/<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: 2
  • 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: /cagent/admin/<devID>/agentactionreq
  • QoS: 0
  • Retained: 0
  • Payload: 

Example: SenHub's Capability 

{
  "susiCommData":{
    "infoSpec": {
        "SenHub": {
            "SenData": {"e":[ {"n":"Temperature","u":"Cel","v":0.000000,"min":-100.000000,"max":200.000000,"asm":"r","type":"d","rt":"ucum.Cel","st":"ipso","exten":""},
                              {"n":"Humidity","u":"%","v":0.000000,"min":0.000000,"max":100.000000,"asm":"r","type":"d","rt":"ucum.%","st":"ipso","exten":""},
                              {"n":"GPIO1","u":"","bv":0,"min":0.000000,"max":1.000000,"asm":"r","type":"b","rt":"","st":"ipso","exten":""},
                              {"n":"GPIO2","u":"","bv":0,"min":0.000000,"max":1.000000,"asm":"r","type":"b","rt":"","st":"ipso","exten":""}
                            ],
            "bn":"SenData"
            },
            "Info": {"e":[{"n":"Name","sv":"SenHub1","asm":"rw"},
                          {"n":"sw","sv":"1.0.00","asm":"r"}
                         ],
            "bn":"Info"
           },
           "Net": {"e":[{"n":"sw","sv":"1.0.00","asm":"r"},
                        {"n":"Neighbor","sv":"","asm":"r"},
                        {"n":"Health","v":"100.000000","asm":"r"}
                       ],
            "bn":"Net"
           }
       }
   },
   "commCmd":2052,
   "requestID":2001,
   "agentID":"0017000E40000001",
   "handlerName":"general",
   "sendTS":160081024
  }
}


Auto Update Sensor Data Value

  • Description: Agent will update latest value to server.
  • Type: Auto update
  • Direction: Agent-> Server
  • Topic: /cagent/admin/<devID>/deviceinfo
  • QoS: 0
  • Retained: 0
  • Payload:
{  
  "susiCommData":{  
     "data":{  
        "SenHub":{  
           "SenData":{  
              "e":[  
                 {  
                    "n":"Temperature",
                    "v":1
                 },
                 {  
                    "n":"Humidity",
                    "v":57
                 },
                 {  
                    "n":"GPIO1",
                    "bv":0
                 },
                 {  
                    "n":"GPIO2",
                    "bv":0
                 }
              ],
              "bn":"SenData"
           },
           "ver":1
        }
     },
     "commCmd":2055,
     "requestID":2001,
     "agentID":"0017000E40000001",
     "handlerName":"general",
     "sendTS":160081031
  }
}

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: /cagent/admin/<devID>/agentactionreq
  • 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: /cagent/admin/<devID>/agentcallbackreq
  • QoS: 0
  • Retained: 0
  • Payload:
{  
  "susiCommData":{  
     "sensorIDList":{  
        "e":[  
           {  
              "sv":"SenHub1",
              "n":"SenHub/Info/Name"
           }
        ]
     },
     "sessionID":"4DDF0B6DE2773176095F55E8C930507A",
     "commCmd":525,
     "requestID":0,
     "agentID":"",
     "handlerName":"SenHub",
     "sendTS":1466088605
  }
}
  • Description: Agent will reply its result.
  • Type: Reply
  • Direction: Agent -> Server
  • Topic: /cagent/admin/<devID>/agentactionreq
  • QoS: 0
  • Retained: 0
  • Payload:
{  
  "susiCommData":{  
     "commCmd":526,
     "handlerName":"SenHub",
     "sessionID":"4DDF0B6DE2773176095F55E8C930507A",
     "sensorInfoList":{  
        "e":[  
           {  
              "n":"/Info/Name",
              "sv":"SenHub1",
              "StatusCode":200
           }
        ]
     }
  }
}

EventNotify

  • Description: 
  • Type: Auto update
  • Direction: Agent -> Server
  • Topic: /cagent/admin/<devID>/eventnotify
  • QoS: ?
  • Retained: ?
  • Payload:
{  
   "susiCommData":{  
      "commCmd":2059,
      "requestID":2001,
      "agentID":"000014DAE996BE04",
      "handlerName":"general",
      "sendTS":1453356274,
      "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"
            }
        }  
    }
}


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
Retrieved from "https://ess-wiki.advantech.com.tw/wiki/index.php?title=EI-Connect_to_EI-PaaS_Protocol&oldid=8256"