Latest revision as of 02:25, 20 February 2017

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

1. Server would send "Get Capability" and "Change AdvHeartBeat sending rate" after receiving a "Connect Info" message.
2. Server updates latest update time after receiving a AdvHeartBeat message with its AdvHeartBeat Table( NoSQL ).
3. Server checks update time of AdvHeartBeat Table only.
4. 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 ( timeout & status is connected ) => changes status to disconnect & send a "Re-Connect" message to this device
5. If there is latest AdvHeartBeat message in "AdvHeartBeat Table" but there is not device information in device list table ( SQL ).
   1. 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 sends "Re-Connect" message for asking agent re-send its "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: 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
   }
}

Connect Info

Agent Client sends the "Connect Info" to Server for on-line notification. Server would send "Get Capability" to get capability of this agent device and "Change AdvHeartBeat rate" to sync with System's sending rate.

Description: Agent Client sends the "Connect Info" to 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
   }
}

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. ( Send by IoTGWHandler )
4. 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

Overview of Testing

Expect

1. Server/Client need follow specification to implement "AdvHeartBeat Protocol".
2. Agent connection status on RMM Server must be correct in stable state.
3. AdvHeartBeat can fix "lost connect info message issue". This issue maybe introduce by running order or dropping message by broker or RMM Server.
4. AdvHeatBeat can fix "lost disconnect or will" message issue.

Server Site - Check by Self

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
3. Server can't misjudge earlier agent without "AdvHeartBeat"'s connection status to offline.
4. 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 Self

1. Agent's OS version must greater "3.2.5"
2. Agent sends "AdvHeartBeat Message" to Server in period
3. Agent sends "AdvHeartBeat Parameters" after receiving a "Query Parameter of AdvHeartBeat Message".
4. Agent will change and reply its "AdvHeartBeat Parameters" after receiving a "Setting AdvHeartBeat Message".
5. Agent sends "Connect Info Message" to Server after receiving a "Re-Connect Message".
6. 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

1. Lost first "Connect Info Msg"
2. Lost "Disconnect Msg" and "Will Msg"
3. Continue lost 1~5 "AdvHeartBeat Message"

Network Environment

1. Unplug network cable 5 sec then plug-in.
2. Up-plug network cable 3 mins then plug-in.

Test by Manual

1. Broker and Agent client are started before RMM Server.
2. RMM Server restart

Node-Red for Test Case

Send Disconnect Msg

Drop Connect / Disconnect / AdvHeartBeat Msg

Check version of Agent

Check period of AdvHeartBeat rate

Get / Set AdvHeartBeat Params Get Capability, Re-Connect

Test Result

V1 Test Result 20160801 Excel