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 with its AdvHeartBeat Table( NoSQL ).
- Server need to check update time from 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 it is timeout & status is connected => then change status to disconnect & send a "Re-Connect" message to this device
- If server check there is latest AdvHeartBeat message in table but there are not device information in device list table ( SQL ).
- Server sends a re-connect message to this device.
- Server needs to send "Get Capability" message to client after receiving a connect info message. Agent will send its OS info and all handlers' capability to server.
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
Description: Server can get agent's capability by "Get Capability" 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 back 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"
}
}
}
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
Server Site
- 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