Connectivity/AdvHeartBeat
From ESS-WIKI
Contents
AdvHeartBeat Protocol
AdvHeartBeat Topic & Payload
Type: Response
Direction: Agent -> Server
Topic: /cagent/admin/<devID>/notify
QoS: 0
Retained: 0
Payload: ~ 35 character
{"hb":{"devID":"0017000E40000001"}}
Client Site
- Agent needs send "AdvHeartBeat" message ( refer to AdvHeartBeat Topic & Payload ) by period as below picture.
Server Site
- Server updates latest update time after receiving a AdvHeartBeat message at its AdvHeartBeat Table( NoSQL ).
- Server checks update time of AdvHeartBeat Table only.
- If the latest update time is over timeout ( Note: This value is depend on Server. Recommend: 3 x send rate => 3 x 60 = 180 sec => tolerate drop 2 AdvHeartBeat MSG ).
- If ( timeout & status is connected ) => changes status to disconnect & send a "Re-Connect" message to this device
- If there is latest AdvHeartBeat message in "AdvHeartBeat Table" but there IS not device information in device list table ( SQL ).
- Server sends a re-connect message to this device.
Re-Connect Message
- If Server aware any problem of a device's status/information. Server will send a "Re-Connect" Message to Agent. Agent will send a connect info to Server after receiving a re-connect message. You can refer below for detail.
Description: Server send re-connect message to agent for asking agent re-send connect info.
Type: Request
Direction: Server -> Agent
Topic: /cagent/admin/<devID>/agentcallbackreq
QoS: 0
Retained: 0
Payload:
{
"susiCommData": {
"commCmd": 125,
"handlerName": "general",
"response": {
"statuscode": 4,
"msg": "Reconnect"
}
}
}
Description: Agent will send connect info after receiving a re-connect message.
Type: Response
Direction: Agent -> Server
Topic: /cagent/admin/<devID>/agentinfoack
QoS: 0
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
}
}
Get Capability
Server will send a "Get Capability" message to Agent after receiving a "Connect Info" message.
Agent will send back below messages when receiving a "Get Capability" message.
- OS Info
- All handler's capability ( ex: HWM, KVM, HDD, IoTGW...)
- All SenHub's "Connect Info" message. ( Send by IoTGWHandler )
- Update the latest data of IoTGW ( Update by IoTGWHandler )
Description: Server will send a "Get Capability" message to Agent after receiving a "Connect Info" message
Type: Request
Direction: Server -> Agent
Topic: /cagent/admin/<agentID>/agentcallbackreq
QoS: 0
Retained: 0
Payload:
{
"susiCommData": {
"requestID":1001,
"catalogID": 4,
"commCmd":2051,
"handlerName":"general"
}
}
Description: Agent will send back OS Info to Server after receiving "Get Capability" message.
Note: This feature will be implemented in version 3.2.
Type: Response
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
}
}
Description: Agent will send all handlers' capability to server.
Type: Response
Direction: Agent -> Server
Topic: /cagent/admin/<agentID>/agentactionreq
QoS: 0
Retained: 0
Payload: ( ex: HWM )
{
"susiCommData": {
"infoSpec": {
"HWM": {
"e": [
{"n": "v01","type": "volt","u": "V","max": 20,"min": 10},
{"n": "v02","type": "volt","u": "V","max": 20,"min": 10},
{"n": "t01","type": "temp","u": "Cel","max": 100,"min": 10},
{"n": "V143360","type": "current","u": "A","max": 100,"min": 10}
],
"bn": "HWM"
},
"requestID": 2001,
"commCmd": 2052,
"catalogID": 4,
"agentID": "000014DAE996BE04",
"sendTS": 1417000000004,
"handlerName": "general"
}
}
}
Description: IoTGW Handler will update latest value of IoTGW.
Type: Response
Direction: Agent -> Server
Topic: /cagent/admin/<devID>/deviceinfo
QoS: 0
Retained: 0
Payload:
{
"susiCommData":{
"data": {
"IoTGW": {
"WSN": {
"WSN0": {
"Info":{
"e":[
{"n":"SenHubList","sv":"0017000E40000000,0017000E40000001"},
{"n":"Neighbor","sv":"0017000E40000000,0017000E40000001"},
{"n":"Name","sv":"WSN0"},
{"n":"Health","v":"100.000000"},
{"n":"sw","sv":"1.2.1.12"},
{"n":"reset","bv":"0"}
],
"bn":"Info"
},
"bn":"0007000E40ABCDEF",
"ver":1
},
"bn":"WSN"
},
"ver":1
}
},
"commCmd":2055,
"requestID":2001,
"agentID":"0000000E40ABCDEF",
"handlerName":"general",
"sendTS":160081025
}
}
Description: IoTGW Handler will send "Connect Info" for all "SenHub" devices.
Type: Response
Direction: Agent -> Server
Topic: /cagent/admin/<devID>/agentinfoack
QoS: 0
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
}
}
Parameters of "AdvHeartBeat Protocol"
Sending Rate
Unit: second
Default: 60
Range: 1 ~ 0xFFFFFFFF
-1 => Agent doesn't send "AdvHeartBeat" message
Query parameters of "AdvHeartBeat"
Type: Request
Direction: Server -> Agent
Topic: /cagent/admin/<devID>/agentcallbackreq
Payload:
{
"susiCommData": {
"commCmd": 127,
"handlerName": "general",
"sessionID": "123465"
}
}
Type: Response
Direction: Agent -> Server
Topic: /cagent/admin/<devID>/agentactionreq
Payload:
{
"susiCommData": {
"commCmd": 128,
"handlerName": "general",
"heartbeatrate": 60,
"sessionID": "123465"
}
}
Change parameters of "AdvHeartBeat"
Type: Request
Direction: Server -> Agent
Topic: /cagent/admin/<devID>/agentcallbackreq
Payload:
{
"susiCommData": {
"commCmd": 129,
"handlerName": "general",
"heartbeatrate": 20,
"sessionID": "123465"
}
}
Type: Response
Direction: Agent -> Server
Topic: /cagent/admin/<devID>/agentactionreq
Payload:
{
"susiCommData": {
"commCmd": 130,
"handlerName": "general",
"result":"SUCCESS", //or "FALSE"
"sessionID": "123465"
}
}
How to confirm the Agent supports "AdvHeartBeat" protocol?
1. Check the version in deviceinfo
Agent will support "AdvHeartBeat" in version "3.2".
>= 3.2 : Agent supports AdvHeartBeat
< 3.2 : Agent doesn't support AdvHeartBeat
2. Query the parameters of "AdvHeartBeat" by "Query parameters of "AdvHeartBeat"
Test Case
Expect
- Server/Client need follow specification to implement "AdvHeartBeat Protocol".
- Agent connection status on RMM Server must be correct in stable state.
- AdvHeartBeat can fix "lost connect info message issue". The issue introduce by running order of Agent, Server, and MQTT Broker.
- AdvHeatBeat can fix "lost disconnect or will" message issue.
Server Site - Check by Self
- Find all devices that its update time is over timeout from "AdvHeartBeat Table" & Check these devices is existing in "Device Table"
- Yes -> If connection status is "On-line" change to "Off-line"
- No -> Do Nothing
- Find all devices that its update time is not over timeout from "AdvHeartBeat Table" & Check these devices is existing in "Device Table"
- Yes -> If connection status is "Off-line" -> Send a "Re-Connect" message to this device
- No -> Send a "Re-Connect" message to this device
- Server can't misjudge earlier agent without "AdvHeartBeat"'s connection status to offline.
- Server needs take care the network and cpu loading to induce misjudge. ( The frequency of drop "AdvHeartBeat Message" is too high or tolerance is too lower ).
Client Site - Check by Sefl
- Agent's OS version must greater "3.2.5"
- Agent sends "AdvHeartBeat Message" to Server in period
- Agent sends "AdvHeartBeat Parameters" after receiving a "Query Parameter of AdvHeartBeat Message".
- Agent will change and reply its "AdvHeartBeat Parameters" after receiving a "Setting AdvHeartBeat Message".
- Agent sends "Connect Info Message" to Server after receiving a "Re-Connect Message".
- Agent sends "OS Info", "Info Spec of all handler", "update values of IoTGW", and "Connect Info of all SenHub" while receiving a "Re-Connect Message".
Integration Test
- RMM Server supports "AdvHeartBeat Protocol"
- Agent without "AdvHeartBeat"
- Agent with "AdvHeartBeat"
Test by Node-Red
- Lost first "Connect Info Msg"
- Lost "Disconnect Msg" and "Will Msg"
- Continue lost 1~5 "AdvHeartBeat Message"
Network Environment
- Unplug network cable 5 sec then plug-in.
- Up-plug network cable 3 mins then plug-in.
- Up-plug network cable 6 mins then plug-in.
- Limited Bandwidth -> 56KB Modem
Test by Manual
- Broker and Agent client are started before RMM Server.
- RMM Server restart