Connectivity/AdvHeartBeat

From ESS-WIKI
Revision as of 10:16, 6 July 2016 by Winston (talk | contribs) (→‎Get Capability)
Jump to: navigation, search

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.

AdvHeartBeat Protocol

Server Site

  1. Server updates latest update time after receiving a AdvHeartBeat message with its AdvHeartBeat Table( NoSQL ).
  2. Server need to check update time from AdvHeartBeat Table only.
  3. 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 ).
    1. If it is timeout & status is connected => then change status to disconnect & send a "Re-Connect" message to this device
  4. If server check there is latest AdvHeartBeat message in table but there are not device information in device list table ( SQL ).
    1. Server sends a re-connect message to this device.
    2. 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.

AdvHeartBeat Protocol 

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.

  1. OS Info
  2. All handler's capability ( ex: HWM, KVM, HDD, IoTGW...)
  3. All SenHub's "Connect Info" message
  4. Update the latest data of IoTGW

Get Agent's 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 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 send "Connect Info" for all "SenHub" devices.
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"

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"

Set parameter 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

  1. Find all devices that its update time is over timeout from "AdvHeartBeat Table" & Check these devices is existing in "Device Table"
    1. Yes -> If connection status is "On-line" change to "Off-line"
    2. No -> Do Nothing
  2. Find all devices that its update time is not over timeout from "AdvHeartBeat Table" & Check these devices is existing in "Device Table"
    1. Yes -> If connection status is "Off-line" -> Send a "Re-Connect" message to this device
    2. No -> Send a "Re-Connect" message to this device

Client Site

Network Enviroment

Retrieved from "https://ess-wiki.advantech.com.tw/wiki/index.php?title=Connectivity/AdvHeartBeat&oldid=2027"