Difference between revisions of "Connectivity/Agent Communication Protocol in MQTT"
From ESS-WIKI
Eric.liang (talk | contribs) |
Eric.liang (talk | contribs) (→EventNotify) |
||
| (20 intermediate revisions by 2 users not shown) | |||
| Line 62: | Line 62: | ||
} | } | ||
} | } | ||
| + | |||
| + | == 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: /cagent/admin/devId/willmessage | ||
| + | *QoS: 0 | ||
| + | *Retained: 0 | ||
| + | *Payload: | ||
| + | |||
| + | { | ||
| + | "susiCommData": { | ||
| + | "devID": "000014DAE996BE04", | ||
| + | "hostname": "PC001104", | ||
| + | "sn": "14DAE996BE04", | ||
| + | "mac": "14DAE996BE04", | ||
| + | "version": "1.0.0.0", | ||
| + | "type": "IPC", | ||
| + | "product": "", | ||
| + | "manufacture": "", | ||
| + | "account": "anonymous", | ||
| + | "password": "", | ||
| + | "status": 0, | ||
| + | "commCmd": 1, | ||
| + | "requestID": 21, | ||
| + | "agentID": "000014DAE996BE04", | ||
| + | "handlerName": "general", | ||
| + | "sendTS": 1423536737 | ||
| + | } | ||
| + | } | ||
| + | |||
| + | == OS Info == | ||
| + | |||
| + | *Description: Agent Client sends the OS Info" to RMM Server for device OS information. | ||
| + | *Type: Info | ||
| + | *Direction: Agent -> Server | ||
| + | *Topic: /cagent/admin/<devID>/agentactionreq | ||
| + | *QoS: 0 | ||
| + | *Retained: 0 | ||
| + | *Payload: | ||
| + | <pre>{ | ||
| + | "susiCommData":{ | ||
| + | "osInfo": | ||
| + | { | ||
| + | "cagentVersion":"3.1.23", | ||
| + | "cagentType":"IoTGW", | ||
| + | "osVersion":"SnailOS", | ||
| + | "biosVersion":"", | ||
| + | "platformName":"", | ||
| + | "processorName":"SnailGW", | ||
| + | "osArch":"SnailX86", | ||
| + | "totalPhysMemKB":123, | ||
| + | "macs":"000E40ABCDEF", | ||
| + | "IP":"192.168.0.100" | ||
| + | }, | ||
| + | "commCmd":116, | ||
| + | "requestID":109, | ||
| + | "agentID":"0000000E40ABCDEF", | ||
| + | "handlerName":"general", | ||
| + | "sendTS":1466730390 | ||
| + | } | ||
| + | }</pre> | ||
| + | |||
| + | |||
== Info or Update Device's Capability == | == Info or Update Device's Capability == | ||
| Line 71: | Line 136: | ||
*QoS: 0 | *QoS: 0 | ||
*Retained: 0 | *Retained: 0 | ||
| − | *Payload: | + | *Payload: |
| + | |||
| + | Example: SenHub's Capability | ||
{ | { | ||
| Line 103: | Line 170: | ||
"sendTS":160081024 | "sendTS":160081024 | ||
} | } | ||
| + | } | ||
| + | |||
| + | == Eable Auto Update == | ||
| + | |||
| + | *Description: Server can send start auto report command to Agent | ||
| + | *Type: Auto report | ||
| + | *Direction: Server -> Agent | ||
| + | *Topic: /cagent/admin/<device>/agentcallbackreq | ||
| + | *Broadcast Topic: /cagent/admin/broadcast/agentctrl | ||
| + | *QoS: 0 | ||
| + | *Retained: 0 | ||
| + | *Payload: | ||
| + | |||
| + | { | ||
| + | "susiCommData": { | ||
| + | "commCmd": 2053, | ||
| + | "requestItems": {"All":{}}, | ||
| + | "autoUploadIntervalSec": 10, | ||
| + | "handlerName": "general" | ||
| + | } | ||
| + | } | ||
| + | |||
| + | *Description: Agent reply | ||
| + | *Type: Reply of auto report command | ||
| + | *Direction: Server -> Agent | ||
| + | *Topic: /cagent/admin/<device>/agentactionreq | ||
| + | *QoS: 0 | ||
| + | *Retained: 0 | ||
| + | *Payload: | ||
| + | <pre>{ | ||
| + | "susiCommData": { | ||
| + | "result": "SUCCESS", | ||
| + | "dataFlow": "general/NetMonitor", | ||
| + | "seq": "70_1611629702692", | ||
| + | "srcTs": 1611629702692, | ||
| + | "commCmd": 2054, | ||
| + | "agentID": "NetMonitor", | ||
| + | "handlerName": "general", | ||
| + | "sendTS": : 1611629702692 | ||
| + | } | ||
| + | }</pre> | ||
| + | |||
| + | == Stope Auto Update == | ||
| + | |||
| + | *Description: Server can send stop auto report command to Agent | ||
| + | *Type: Auto update | ||
| + | *Direction: Server -> Agent | ||
| + | *Topic: /cagent/admin/<device>/agentcallbackreq | ||
| + | *Broadcast Topic: /cagent/admin/broadcast/agentctrl | ||
| + | *QoS: 0 | ||
| + | *Retained: 0 | ||
| + | *Payload: | ||
| + | |||
| + | { | ||
| + | "susiCommData": { | ||
| + | "requestID": 1001, | ||
| + | "catalogID": 4, | ||
| + | "commCmd": 2056, | ||
| + | "handlerName": "general", | ||
| + | "requestItems": { | ||
| + | "All": {} | ||
| + | } | ||
| + | } | ||
} | } | ||
| Line 120: | Line 250: | ||
"SenHub":{ | "SenHub":{ | ||
"SenData":{ | "SenData":{ | ||
| − | "e":[ | + | "e":[{"n":"Temperature","v":1}, |
| − | + | {"n":"Humidity","v":57}, | |
| − | + | {"n":"GPIO1","bv":0}, | |
| − | + | {"n":"GPIO2","bv":0}], | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
"bn":"SenData" | "bn":"SenData" | ||
}, | }, | ||
| Line 150: | Line 266: | ||
} | } | ||
} | } | ||
| + | |||
| + | == Start Monitor Request == | ||
| + | |||
| + | *Description: Server send the start monitor requestto Agent to trigger a plugin to report data with reply topic. | ||
| + | *Type: Auto update | ||
| + | *Direction: Server -> Agent | ||
| + | *Topic: /cagent/admin/<devID>/agentcallbackreq | ||
| + | *QoS: 0 | ||
| + | *Retained: 0 | ||
| + | *Payload: | ||
| + | |||
| + | { | ||
| + | "susiCommData": { | ||
| + | "commCmd": 533, | ||
| + | "catalogID": 4, | ||
| + | "requestID": 10, | ||
| + | "autoUploadIntervalMs": 10000, | ||
| + | "autoUploadTimeoutMs": 30000 | ||
| + | } | ||
| + | } | ||
| + | |||
| + | *Description: Agent will reply sensor data every autoUploadIntervalMs ( millisecond ) duration autoUploadTimeoutMs. | ||
| + | *Type: Reply | ||
| + | *Direction: Agent -> Server | ||
| + | *Topic: /cagent/admin/<devID>/agentactionreq | ||
| + | *QoS: 0 | ||
| + | *Retained: 0 | ||
| + | *Payload: Refer to Auto Update Sensor Data Value | ||
| + | <pre>{ | ||
| + | "susiCommData": { | ||
| + | "OPCUAClient": { | ||
| + | "info": { | ||
| + | "bn": "info", | ||
| + | "e": [ | ||
| + | { | ||
| + | "n": "type", | ||
| + | "sv": "Protocol-Converter", | ||
| + | "asm": "r" | ||
| + | }, | ||
| + | { | ||
| + | "n": "name", | ||
| + | "sv": "OPCUAClient", | ||
| + | "asm": "r" | ||
| + | } | ||
| + | ] | ||
| + | } | ||
| + | }, | ||
| + | "commCmd": 534, | ||
| + | "requestID": 30002, | ||
| + | "agentID": "OPCUAClient", | ||
| + | "handlerName": "OPCUAClient", | ||
| + | "sendTS": 1587353254699 | ||
| + | } | ||
| + | }</pre> | ||
== Get Sensor Data == | == Get Sensor Data == | ||
| Line 250: | Line 420: | ||
{ | { | ||
"n":"/Info/Name", | "n":"/Info/Name", | ||
| − | "sv":" | + | "sv":"SenHub1", |
"StatusCode":200 | "StatusCode":200 | ||
} | } | ||
| Line 257: | Line 427: | ||
} | } | ||
} | } | ||
| − | |||
| − | |||
== EventNotify == | == EventNotify == | ||
| − | *Description: | + | *Description:Event Notify |
*Type: Auto update | *Type: Auto update | ||
*Direction: Agent -> Server | *Direction: Agent -> Server | ||
| Line 276: | Line 444: | ||
"handlerName":"general", | "handlerName":"general", | ||
"sendTS":1453356274, | "sendTS":1453356274, | ||
| − | "eventnotify":{ | + | "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" | |
| − | |||
| − | |||
| − | |||
} | } | ||
| − | + | } | |
| − | + | } | |
| − | |||
}</pre> | }</pre> | ||
| Line 304: | Line 468: | ||
subtype: | subtype: | ||
| − | + | THRESHOLD_CHECK_INFO | |
| − | + | THRESHOLD_CHECK_ERROR | |
| + | </pre> | ||
| − | == | + | == [[Connectivity/AdvHeartBeat|AdvHeartBeat]] == |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
Latest revision as of 06:56, 17 February 2023
Contents
Overview
- Introduction for "WISEAgent communication protocol". WISEAgent 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: /cagent/admin/<devID>/agentinfoack
- QoS: 2
- Retained: 0
- Payload:
{
"susiCommData": {
"devID":"0017000E40000001",
"hostname":"AAA",
"sn":"0017000E40000001",
"mac":"0017000E40000001",
"version":"3.1.23",
"type":"SenHub",
"product":"WISE-1020",
"manufacture":"",
"status":"1",
"commCmd":1,
"requestID":30002,
"agentID":"0017000E40000001",
"handlerName":"general",
"sendTS":160081026
}
}
Disconnect
- Description: Agent Client sends the "Disconnect Info" to Server for off-line notification.
- Type: Info
- Direction: Agent -> Server
- Topic: /cagent/admin/<devID>/agentinfoack
- QoS: 2
- Retained: 0
- Payload:
{
"susiCommData": {
"devID":"0017000E40000001",
"hostname":"AAA",
"sn":"0017000E40000001",
"mac":"0017000E40000001",
"version":"3.1.23",
"type":"SenHub",
"product":"WISE-1020",
"manufacture":"",
"status":"0",
"commCmd":1,
"requestID":30002,
"agentID":"0017000E40000001",
"handlerName":"general",
"sendTS":160081026
}
}
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: /cagent/admin/devId/willmessage
- QoS: 0
- Retained: 0
- Payload:
{
"susiCommData": {
"devID": "000014DAE996BE04",
"hostname": "PC001104",
"sn": "14DAE996BE04",
"mac": "14DAE996BE04",
"version": "1.0.0.0",
"type": "IPC",
"product": "",
"manufacture": "",
"account": "anonymous",
"password": "",
"status": 0,
"commCmd": 1,
"requestID": 21,
"agentID": "000014DAE996BE04",
"handlerName": "general",
"sendTS": 1423536737
}
}
OS Info
- Description: Agent Client sends the OS Info" to RMM Server for device OS information.
- Type: Info
- Direction: Agent -> Server
- Topic: /cagent/admin/<devID>/agentactionreq
- QoS: 0
- Retained: 0
- Payload:
{
"susiCommData":{
"osInfo":
{
"cagentVersion":"3.1.23",
"cagentType":"IoTGW",
"osVersion":"SnailOS",
"biosVersion":"",
"platformName":"",
"processorName":"SnailGW",
"osArch":"SnailX86",
"totalPhysMemKB":123,
"macs":"000E40ABCDEF",
"IP":"192.168.0.100"
},
"commCmd":116,
"requestID":109,
"agentID":"0000000E40ABCDEF",
"handlerName":"general",
"sendTS":1466730390
}
}
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
}
}
Eable Auto Update
- Description: Server can send start auto report command to Agent
- Type: Auto report
- Direction: Server -> Agent
- Topic: /cagent/admin/<device>/agentcallbackreq
- Broadcast Topic: /cagent/admin/broadcast/agentctrl
- QoS: 0
- Retained: 0
- Payload:
{
"susiCommData": {
"commCmd": 2053,
"requestItems": {"All":{}},
"autoUploadIntervalSec": 10,
"handlerName": "general"
}
}
- Description: Agent reply
- Type: Reply of auto report command
- Direction: Server -> Agent
- Topic: /cagent/admin/<device>/agentactionreq
- QoS: 0
- Retained: 0
- Payload:
{
"susiCommData": {
"result": "SUCCESS",
"dataFlow": "general/NetMonitor",
"seq": "70_1611629702692",
"srcTs": 1611629702692,
"commCmd": 2054,
"agentID": "NetMonitor",
"handlerName": "general",
"sendTS": : 1611629702692
}
}
Stope Auto Update
- Description: Server can send stop auto report command to Agent
- Type: Auto update
- Direction: Server -> Agent
- Topic: /cagent/admin/<device>/agentcallbackreq
- Broadcast Topic: /cagent/admin/broadcast/agentctrl
- QoS: 0
- Retained: 0
- Payload:
{
"susiCommData": {
"requestID": 1001,
"catalogID": 4,
"commCmd": 2056,
"handlerName": "general",
"requestItems": {
"All": {}
}
}
}
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
}
}
Start Monitor Request
- Description: Server send the start monitor requestto Agent to trigger a plugin to report data with reply topic.
- Type: Auto update
- Direction: Server -> Agent
- Topic: /cagent/admin/<devID>/agentcallbackreq
- QoS: 0
- Retained: 0
- Payload:
{
"susiCommData": {
"commCmd": 533,
"catalogID": 4,
"requestID": 10,
"autoUploadIntervalMs": 10000,
"autoUploadTimeoutMs": 30000
}
}
- Description: Agent will reply sensor data every autoUploadIntervalMs ( millisecond ) duration autoUploadTimeoutMs.
- Type: Reply
- Direction: Agent -> Server
- Topic: /cagent/admin/<devID>/agentactionreq
- QoS: 0
- Retained: 0
- Payload: Refer to Auto Update Sensor Data Value
{
"susiCommData": {
"OPCUAClient": {
"info": {
"bn": "info",
"e": [
{
"n": "type",
"sv": "Protocol-Converter",
"asm": "r"
},
{
"n": "name",
"sv": "OPCUAClient",
"asm": "r"
}
]
}
},
"commCmd": 534,
"requestID": 30002,
"agentID": "OPCUAClient",
"handlerName": "OPCUAClient",
"sendTS": 1587353254699
}
}
Get Sensor Data
- Description: Server can send mqtt message to get sensor data value.
- Type: Request
- Direction: Server -> Agent
- Topic: /cagent/admin/<devID>/agentcallbackreq
- QoS: 0
- Retained: 0
- Payload:
{
"susiCommData":{
"sessionID":"2746E3B65BAB115338B9668CDC5C35C4",
"sensorIDList":{
"e":[
{
"n":"SenHub/Info/sw"
}
]
},
"commCmd":523,
"requestID":0,
"agentID":"",
"handlerName":"SenHub",
"sendTS":1466057267
}
}
- Description: Agent will reply its data value.
- Type: Reply
- Direction: Agent -> Server
- Topic: /cagent/admin/<devID>/agentactionreq
- QoS: 0
- Retained: 0
- Payload:
{
"susiCommData":{
"commCmd":524,
"handlerName":"SenHub",
"sessionID":"2746E3B65BAB115338B9668CDC5C35C4",
"sensorInfoList":{
"e":[
{
"n":"/Info/sw",
"sv":"1.0.00",
"StatusCode":200
}
]
}
}
}
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:Event Notify
- 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