Difference between revisions of "Connectivity/Agent Communication Protocol in MQTT"

From ESS-WIKI
Jump to: navigation, search
Line 71: Line 71:
 
*QoS: 0
 
*QoS: 0
 
*Retained: 0
 
*Retained: 0
−
*Payload:
+
*Payload: 
 +
 
 +
Example: SenHub's Capability
  
 
  {
 
  {
Line 104: Line 106:
 
   }
 
   }
 
  }
 
  }
 +
<div>Example: ML HDD Predicitaion&nbsp;Capability<br/></div><pre>{ 
 +
  "susiCommData":{ 
 +
      "infoSpec":{ 
 +
        "ML":{ 
 +
            "HDD_Predition":{ 
 +
              "0085458221447854589":{ 
 +
                  "Info":{
 +
                        "e":[{"n":"Name","sv":"HDD Machine Learning Predition,"asm":"r"},
 +
                            {"n":"Accuracy","v":83,"u":"%"}
 +
                            {"n":"version","sv":"v2.0.1"}],
 +
                    "bn":"Info"
 +
                  },
 +
                  "Input":{
 +
                        "e":[{"n":"Name","sv":"disk0","asm":"w"},
 +
                            {"n":"SMART1","v":10,"asm":"w","require":"MUST"},
 +
                            {"n":"SMART2","v":20,"asm":"w","require":"SHOULD"},
 +
                            {"n":"SMART3","v":20,"asm":"w","require":"MAY"}],
 +
                    "bn":"Input"
 +
                  },
 +
                  "Output":{
 +
                        "e":[{"n":"Name","sv":"disk0","asm":"r"},
 +
                            {"n":"Health","bv":1,"asm":"r"},
 +
                            {"n":"Alert1","sv":"","asm":"r"},
 +
                            {"n":"Alert2","sv":"","asm":"r"},
 +
                            {"n":"Alert3","sv":"","asm":"r"}],
 +
                    "bn":"Output"
 +
                  }
 +
                  "bn":"0085458221447854589",
 +
                  "ver":1
 +
              },
 +
              "bn":"HDD_Predition",
 +
              "ver":1
 +
            },
 +
            "ver":1
 +
        }
 +
      },
 +
      "commCmd":2052,
 +
      "requestID":2001,
 +
      "agentID":"0085458221447854589",
 +
      "handlerName":"general",
 +
      "sendTS":160081020
 +
  }
 +
}</pre>
 +
<div><br/></div><pre>require:
 +
        MUST : This word, or the words "REQUIRED" and "SHALL" mean that
 +
        the item is an absolute requirement of the specification
 +
       
 +
        SHOULD: This word or the adjective "RECOMMENDED" means that
 +
        there may exist valid reasons in particular circumstances to
 +
        ignore this item, but the full implications should be
 +
        understood and the case carefully weighed before choosing a
 +
        different course
 +
       
 +
        MAY: This word or the adjective "OPTIONAL" means that this
 +
        item is truly optional.  One vendor may choose to include the
 +
        item because a particular marketplace requires it or because it
 +
        enhances the product, for example; another vendor may omit the
 +
        same item</pre>
 +
 +
==  ==
  
 
== Auto Update Sensor Data Value ==
 
== Auto Update Sensor Data Value ==
Line 307: Line 369:
 
&nbsp;    THRESHOLD_CHECK_ERROR</pre>
 
&nbsp;    THRESHOLD_CHECK_ERROR</pre>
  
−
== ==
+
== Service Discover ==
 +
 
 +
== Interactive Communication ==
 +
 
 +
*Description: Request Communication protocol to others service (agent)
 +
*Type: Request
 +
*Direction: Service-1 -> Service-2
 +
*Topic: /cagent/admin/&lt;devID&gt;/Input
 +
*QoS: 0
 +
*Retained: 0
 +
*Payload:
 +
<pre>{ 
 +
  "susiCommData":{ 
 +
    "Input":{ 
 +
        "e":[{"n":"Name","sv":"disk2"},
 +
            {"n":"SMART1","v":68},
 +
            {"n":"SMART2","v":10}]
 +
        ]
 +
    },
 +
    "sessionID":"4DDF0B6DE2773176095F55E8C930507A",
 +
    "commCmd":525,
 +
    "requestID":0,
 +
    "agentID":"",
 +
    "handlerName":"ML",
 +
    "sendTS":1466088605
 +
  }
 +
}</pre>
 +
 
 +
*Description: Service will response
 +
*Type: Request
 +
*Direction: Service-2&nbsp;-> Service-1
 +
*Topic: /cagent/admin/&lt;devID&gt;/Output
 +
*QoS: 0
 +
*Retained: 0
 +
*Payload:
 +
<pre>{ 
 +
  "susiCommData":{ 
 +
    "data":{ 
 +
        "ML":{ 
 +
            "HDD_Predition":{ 
 +
              "0085458221447854589":{ 
 +
                  "Output":{
 +
                        "e":[{"n":"Name","sv":"disk2"},
 +
                            {"n":"Health","bv":0}],
 +
                    "bn":"Output"
 +
                  }
 +
                  "bn":"0085458221447854589",
 +
                  "ver":1
 +
              },
 +
              "bn":"HDD_Predition",
 +
              "ver":1
 +
            },
 +
            "ver":1
 +
        }
 +
    },
 +
    "sessionID":"4DDF0B6DE2773176095F55E8C930507A",
 +
    "commCmd":2055,
 +
    "requestID":2001,
 +
    "agentID":"0085458221447854589",
 +
    "handlerName":"general",
 +
    "sendTS":160081031
 +
  }
 +
}</pre>
  
 
== Action ==
 
== Action ==

Revision as of 10:32, 23 December 2016

Overview

Introduction for "WISEAgent communication protocol". WISEAgent communication protocol is base on standard MQTT protocol. We also define Advantech IoT Topic and message in JSON format. Follow standard to design our [Sensor Format in JSON ]

Protocol

Connect

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

Disconnect

  • Description: Agent Client sends the "Disconnect Info" to Server for off-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":"0",
    	"commCmd":1,
    	"requestID":30002,
    	"agentID":"0017000E40000001",
    	"handlerName":"general",
    	"sendTS":160081026
   }
}

Info or Update Device's Capability

  • Description: Agent will send it's capability to Server for description all resource.
  • Type: Auto update
  • Direction: Agent-> Server
  • Topic: /cagent/admin/<devID>/agentactionreq
  • QoS: 0
  • Retained: 0
  • Payload: 

Example: SenHub's Capability 

{
  "susiCommData":{
    "infoSpec": {
        "SenHub": {
            "SenData": {"e":[ {"n":"Temperature","u":"Cel","v":0.000000,"min":-100.000000,"max":200.000000,"asm":"r","type":"d","rt":"ucum.Cel","st":"ipso","exten":""},
                              {"n":"Humidity","u":"%","v":0.000000,"min":0.000000,"max":100.000000,"asm":"r","type":"d","rt":"ucum.%","st":"ipso","exten":""},
                              {"n":"GPIO1","u":"","bv":0,"min":0.000000,"max":1.000000,"asm":"r","type":"b","rt":"","st":"ipso","exten":""},
                              {"n":"GPIO2","u":"","bv":0,"min":0.000000,"max":1.000000,"asm":"r","type":"b","rt":"","st":"ipso","exten":""}
                            ],
            "bn":"SenData"
            },
            "Info": {"e":[{"n":"Name","sv":"SenHub1","asm":"rw"},
                          {"n":"sw","sv":"1.0.00","asm":"r"}
                         ],
            "bn":"Info"
           },
           "Net": {"e":[{"n":"sw","sv":"1.0.00","asm":"r"},
                        {"n":"Neighbor","sv":"","asm":"r"},
                        {"n":"Health","v":"100.000000","asm":"r"}
                       ],
            "bn":"Net"
           }
       }
   },
   "commCmd":2052,
   "requestID":2001,
   "agentID":"0017000E40000001",
   "handlerName":"general",
   "sendTS":160081024
  }
}
Example: ML HDD Predicitaion Capability
{  
   "susiCommData":{  
      "infoSpec":{  
         "ML":{  
            "HDD_Predition":{  
               "0085458221447854589":{  
                  "Info":{
                        "e":[{"n":"Name","sv":"HDD Machine Learning Predition,"asm":"r"},
                             {"n":"Accuracy","v":83,"u":"%"}
                             {"n":"version","sv":"v2.0.1"}],
                    "bn":"Info"
                   },
                   "Input":{
                        "e":[{"n":"Name","sv":"disk0","asm":"w"},
                             {"n":"SMART1","v":10,"asm":"w","require":"MUST"},
                             {"n":"SMART2","v":20,"asm":"w","require":"SHOULD"},
                             {"n":"SMART3","v":20,"asm":"w","require":"MAY"}],
                    "bn":"Input"
                   },
                   "Output":{
                        "e":[{"n":"Name","sv":"disk0","asm":"r"},
                             {"n":"Health","bv":1,"asm":"r"},
                             {"n":"Alert1","sv":"","asm":"r"},
                             {"n":"Alert2","sv":"","asm":"r"},
                             {"n":"Alert3","sv":"","asm":"r"}],
                    "bn":"Output"
                   }
                  "bn":"0085458221447854589",
                  "ver":1
               },
               "bn":"HDD_Predition",
               "ver":1
            },
            "ver":1
         }
      },
      "commCmd":2052,
      "requestID":2001,
      "agentID":"0085458221447854589",
      "handlerName":"general",
      "sendTS":160081020
   }
}

require: 
        MUST : This word, or the words "REQUIRED" and "SHALL" mean that
         the item is an absolute requirement of the specification
         
        SHOULD: This word or the adjective "RECOMMENDED" means that
         there may exist valid reasons in particular circumstances to
         ignore this item, but the full implications should be
         understood and the case carefully weighed before choosing a
         different course
         
        MAY: This word or the adjective "OPTIONAL" means that this
         item is truly optional.  One vendor may choose to include the
         item because a particular marketplace requires it or because it
         enhances the product, for example; another vendor may omit the
         same item

Auto Update Sensor Data Value

  • Description: Agent will update latest value to server.
  • Type: Auto update
  • Direction: Agent-> Server
  • Topic: /cagent/admin/<devID>/deviceinfo
  • QoS: 0
  • Retained: 0
  • Payload:
{  
  "susiCommData":{  
     "data":{  
        "SenHub":{  
           "SenData":{  
              "e":[  
                 {  
                    "n":"Temperature",
                    "v":1
                 },
                 {  
                    "n":"Humidity",
                    "v":57
                 },
                 {  
                    "n":"GPIO1",
                    "bv":0
                 },
                 {  
                    "n":"GPIO2",
                    "bv":0
                 }
              ],
              "bn":"SenData"
           },
           "ver":1
        }
     },
     "commCmd":2055,
     "requestID":2001,
     "agentID":"0017000E40000001",
     "handlerName":"general",
     "sendTS":160081031
  }
}

Get Sensor Data

  • Description: Server can send mqtt message to get sensor data value.
  • Type: Request
  • Direction: Server -> Agent
  • Topic: /cagent/admin/<devID>/agentcallbackreq
  • QoS: 0
  • Retained: 0
  • Payload:
{  
  "susiCommData":{  
     "sessionID":"2746E3B65BAB115338B9668CDC5C35C4",
     "sensorIDList":{  
        "e":[  
           {  
              "n":"SenHub/Info/sw"
           }
        ]
     },
     "commCmd":523,
     "requestID":0,
     "agentID":"",
     "handlerName":"SenHub",
     "sendTS":1466057267
  }
}
  • Description: Agent will reply its data value.
  • Type: Reply
  • Direction: Agent -> Server
  • Topic: /cagent/admin/<devID>/agentactionreq
  • QoS: 0
  • Retained: 0
  • Payload:
{  
  "susiCommData":{  
     "commCmd":524,
     "handlerName":"SenHub",
     "sessionID":"2746E3B65BAB115338B9668CDC5C35C4",
     "sensorInfoList":{  
        "e":[  
           {  
              "n":"/Info/sw",
              "sv":"1.0.00",
              "StatusCode":200
           }
        ]
     }
  }
}

Set Sensor Data

  • Description: Server can send mqtt message to set sensor data value.
  • Type: Request
  • Direction: Server -> Agent
  • Topic: /cagent/admin/<devID>/agentcallbackreq
  • QoS: 0
  • Retained: 0
  • Payload:
{  
  "susiCommData":{  
     "sensorIDList":{  
        "e":[  
           {  
              "sv":"SenHub1",
              "n":"SenHub/Info/Name"
           }
        ]
     },
     "sessionID":"4DDF0B6DE2773176095F55E8C930507A",
     "commCmd":525,
     "requestID":0,
     "agentID":"",
     "handlerName":"SenHub",
     "sendTS":1466088605
  }
}
  • Description: Agent will reply its result.
  • Type: Reply
  • Direction: Agent -> Server
  • Topic: /cagent/admin/<devID>/agentactionreq
  • QoS: 0
  • Retained: 0
  • Payload:
{  
  "susiCommData":{  
     "commCmd":526,
     "handlerName":"SenHub",
     "sessionID":"4DDF0B6DE2773176095F55E8C930507A",
     "sensorInfoList":{  
        "e":[  
           {  
              "n":"/Info/Name",
              "sv":"Success",
              "StatusCode":200
           }
        ]
     }
  }
}


EventNotify

  • Description: 
  • Type: Auto update
  • Direction: Agent -> Server
  • Topic: /cagent/admin/<devID>/eventnotify
  • QoS: ?
  • Retained: ?
  • Payload:
{  
   "susiCommData":{  
      "commCmd":2059,
      "requestID":2001,
      "agentID":"000014DAE996BE04",
      "handlerName":"general",
      "sendTS":1453356274,
      "eventnotify":{  
      "subtype":"MsgGen",
      "msg":"My MsgGenTest",
      "severity":2,
      "handler":"MsgGen",
      "extMsg":{  
            "predictMsg":{
             "Healthy":"Good",
             "Model Accuracy":"83%",
             "Suggestion":"...",
             "Model Version":"1.0.8"
            }
         }
      }
   }
}


severity:
     Severity_Emergency = 0,
     Severity_Alert     = 1,
     Severity_Critical  = 2,
     Severity_Error     = 3,
     Severity_Warning   = 4,
     Severity_Informational = 5,
     Severity_Debug     = 6,

subtype: 
     THRESHOLD_CHECK_INFO
     THRESHOLD_CHECK_ERROR

Service Discover

Interactive Communication

  • Description: Request Communication protocol to others service (agent)
  • Type: Request
  • Direction: Service-1 -> Service-2
  • Topic: /cagent/admin/<devID>/Input
  • QoS: 0
  • Retained: 0
  • Payload:
{  
  "susiCommData":{  
     "Input":{  
        "e":[{"n":"Name","sv":"disk2"},
             {"n":"SMART1","v":68},
             {"n":"SMART2","v":10}]
        ]
     },
     "sessionID":"4DDF0B6DE2773176095F55E8C930507A",
     "commCmd":525,
     "requestID":0,
     "agentID":"",
     "handlerName":"ML",
     "sendTS":1466088605
  }
}
  • Description: Service will response
  • Type: Request
  • Direction: Service-2 -> Service-1
  • Topic: /cagent/admin/<devID>/Output
  • QoS: 0
  • Retained: 0
  • Payload:
{  
  "susiCommData":{  
     "data":{  
         "ML":{  
            "HDD_Predition":{  
               "0085458221447854589":{  
                   "Output":{
                        "e":[{"n":"Name","sv":"disk2"},
                             {"n":"Health","bv":0}],
                    "bn":"Output"
                   }
                  "bn":"0085458221447854589",
                  "ver":1
               },
               "bn":"HDD_Predition",
               "ver":1
            },
            "ver":1
         }
     },
     "sessionID":"4DDF0B6DE2773176095F55E8C930507A",
     "commCmd":2055,
     "requestID":2001,
     "agentID":"0085458221447854589",
     "handlerName":"general",
     "sendTS":160081031
  }
}

Action

  • Description: 
  • Type: ?
  • Direction: Agent -> Server
  • Topic: ????
  • QoS: ?
  • Retained: ?
  • Payload:?
???
Retrieved from "https://ess-wiki.advantech.com.tw/wiki/index.php?title=Connectivity/Agent_Communication_Protocol_in_MQTT&oldid=4852"