Difference between revisions of "Connectivity/AdvHeartBeat"

From ESS-WIKI
Jump to: navigation, search
(→‎Test Case)
(→‎Client Site)
Line 313: Line 313:
  
 
==<span style="color:#0070c0;">Client Site</span>==
 
==<span style="color:#0070c0;">Client Site</span>==
−
#WISEAgent's OS version must greater "3.2.5"
+
#Agent's OS version must greater "3.2.5"
−
#WISEAgent sends "AdvHeartBeat Message" to Server in period
+
#Agent sends "AdvHeartBeat Message" to Server in period
−
#WISEAgent would send "AdvHeartBeat Parameters" while receiving a "Query Parameter of AdvHeartBeat Message".
+
#Agent sends "AdvHeartBeat Parameters" after receiving a "Query Parameter of AdvHeartBeat Message".
−
#WISEAgent would change and reply its "AdvHeartBeat Parameters" after receiving a "Setting AdvHeartBeat Message".
+
#Agent will change and reply its "AdvHeartBeat Parameters" after receiving a "Setting AdvHeartBeat Message".
−
#WISEAgent would send "Connect Info Message" to Server while receiving a "Re-Connect Message".
+
#Agent sends "Connect Info Message" to Server after receiving a "Re-Connect Message".
−
#WISEAgent would send "OS Info", "Info Spec of all handler", "update values of IoTGW", and "Connect Info of all SenHub" while 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".
  
 
==<span style="color:#0070c0;">Network Environment</span>==
 
==<span style="color:#0070c0;">Network Environment</span>==

Revision as of 02:40, 19 July 2016

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. ( Send by IoTGWHandler )
  4. Update the latest data of IoTGW ( Update by IoTGWHandler )

Get Agent's Capability 

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"

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

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". The issue introduce by running order of Agent, Server, and MQTT Broker.
  4. AdvHeatBeat can fix "lost disconnect or will" message issue.

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
  3. Server can't misjudge agent to offline that doesn't support "AdvHeatBeat Protocol".
  4. Server needs take care the network/message loading to induce misjudge. ( The frequency of drop "AdvHeartBeat Message" is too high or tolerance is too lower ).

Client Site

  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".

Network Environment

  1. Unplug network cable 5 sec then plug-in.
  2. Up-plug network cable 3 mins then plug-in.
  3. Up-plug network cable 6 mins then plug-in.
  4. Limited Bandwidth -> 56KB Modem

Integration Test

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