Difference between revisions of "EIS RESTfulAPI ProcWSNData"

From ESS-WIKI
Jump to: navigation, search
 
(57 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
= RESTful API Path Rule for WSNManage =
+
= <span style="color:#0000FF;">RESTful API Path Rule for WSNManage</span> =
  
−
== Connectivity ==
+
&nbsp;This document is about EIS RESTful API service of&nbsp;Wireless Sensor Manage (WSNManage). There are two major classes in WSNManage service one is&nbsp;"Connectiviy" another is&nbsp;"SenHub". Connectivity is wireless interfaces information in the EIS IoT Gateway solution. "SenHub" is short of sensor hub.&nbsp;
  
−
WSNManage/Connectivity -> All Capability ( without data )
+
== <span style="background-color:#AFEEEE;">Connectivity</span> ==
 +
 
 +
=== <span style="color:#FF0000;">GET</span> ===
 +
 
 +
'''Path: APIGw-Site:3000/restapi/WSNManage/Connectivity'''
 +
 
 +
-> All Capability ( without data )
  
 
  {
 
  {
 
   "IoTGW": {
 
   "IoTGW": {
−
"WSN": {
+
          "WSN": {  
−
"WSN0": {    
+
              "WSN0": {  
−
"Info": {
+
&nbsp;                "Info": {  
−
"e": [{"n":"SenHubList","sv":",","asm":"r"},
+
&nbsp;                          "e": [{"n":"SenHubList","sv":",","asm":"r"},
−
  {"n":"Neighbor","sv":"","asm":"r"},
+
&nbsp;                                {"n":"Neighbor","sv":"","asm":"r"},
−
  {"n":"Health","v":80,"asm":"r"},
+
&nbsp;                                {"n":"Health","v":80,"asm":"r"},
−
  {"n":"Name","sv":"WSN0","asm":"r"},
+
&nbsp;                                {"n":"Name","sv":"WSN0","asm":"r"},
−
  {"n":"sw","sv":"1.0.0.1","asm":"r"},
+
&nbsp;                                {"n":"sw","sv":"1.0.0.1","asm":"r"},
−
  {"n":"reset","bv":0,"asm":"rw"}],
+
&nbsp;                                {"n":"reset","bv":0,"asm":"rw"}],  
−
  "bn":"Info"
+
&nbsp;                "bn":"Info"  
−
},
+
&nbsp;                },  
−
  "bn":"0000852CF4B7B0E8",
+
&nbsp;            "bn":"0000852CF4B7B0E8", "ver":1  
−
  "ver":1
+
&nbsp;          },  
−
},
+
&nbsp;          "WSN1": {  
−
"WSN1": {
+
&nbsp;                "Info": {  
−
"Info": {
+
&nbsp;                          "e": [{"n":"SenHubList","sv":"","asm":"r"},  
−
"e": [{"n":"SenHubList","sv":"","asm":"r"},
+
&nbsp;                                {"n":"Neighbor","sv":"","asm":"r"},  
−
  {"n":"Neighbor","sv":"","asm":"r"},  
+
&nbsp;                                {"n":"Health","v":50,"asm":"r"},  
−
  {"n":"Health","v":50,"asm":"r"},
+
&nbsp;                                {"n":"Name","sv":"WSN1","asm":"r"},  
−
  {"n":"Name","sv":"WSN1","asm":"r"},
+
&nbsp;                                {"n":"sw","sv":"1.0.0.1","asm":"r"},  
−
  {"n":"sw","sv":"1.0.0.1","asm":"r"},
+
&nbsp;                                {"n":"reset","bv":0,"asm":"rw"}],  
−
  {"n":"reset","bv":0,"asm":"rw"}],
+
&nbsp;                  "bn":"Info"  
−
"bn":"Info"
+
&nbsp;                  },  
−
},
+
&nbsp;          "bn":"0000852CF4B7B0E7",  
−
  "bn":"0000852CF4B7B0E7",
+
&nbsp;          "ver":1  
−
  "ver":1
+
&nbsp;          },  
−
},
+
&nbsp;        "bn":"WSN"  
−
"bn":"WSN"
+
&nbsp;      },  
−
},
+
&nbsp;      "Bt": {  
−
"Bt": {
+
&nbsp;            "Bt0": {  
−
"Bt0": {
+
&nbsp;                  "Info": {  
−
"Info": {
+
&nbsp;                            "e": [{"n":"SenHubList","sv":"","asm":"r"},  
−
"e": [{"n":"SenHubList","sv":"","asm":"r"},  
+
&nbsp;                                  {"n":"Health","v":90,"asm":"r"},  
−
  {"n":"Health","v":90,"asm":"r"},
+
&nbsp;                                  {"n":"Name","sv":"Bt0","asm":"r"},  
−
  {"n":"Name","sv":"Bt0","asm":"r"},
+
&nbsp;                                  {"n":"sw","sv":"3.0.0.1","asm":"r"},  
−
  {"n":"sw","sv":"3.0.0.1","asm":"r"},
+
&nbsp;                                  {"n":"reset","bv":0,"asm":"rw"}],  
−
  {"n":"reset","bv":0,"asm":"rw"}],
+
&nbsp;                  "bn":"Info"  
−
"bn":"Info"
+
&nbsp;                  },  
−
},
+
&nbsp;              "bn":"0000802CF4B7B028",  
−
  "bn":"0000802CF4B7B028",
+
&nbsp;              "ver":1  
−
  "ver":1
+
&nbsp;              },  
−
},
+
&nbsp;        "bn":"Bt"  
−
"bn":"Bt"
+
&nbsp;      },  
−
},                      
+
&nbsp;    "ver": 1,
−
     "ver": 1,
+
      "bn":"IoTGW"
−
     "bn":"IoTGW"
+
    }
−
  }
+
  }
 +
 
 +
'''Path: '''''APIGw-Site:3000/restapi/WSNManage/Connectivity/IoTGW/WSN/0000852CF4B7B0E8/Info'''
 +
 
 +
'''Reply: with latest data value'''
 +
<pre>{
 +
     "e": [{"n":"SenHubList","sv":"xxx,0017000E40000001,ooo"},
 +
          {"n":"Neighbor","sv":"0000000EC6F0F830"},                                   
 +
          {"n":"Health","v":80},
 +
          {"n":"Name","sv":"WSN0"},
 +
          {"n":"sw","sv":"1.0.0.1"},
 +
          {"n":"reset","bv":0}],
 +
     "bn":"Info"
 +
}</pre>
 +
 
 +
=== <span style="color:#FF0000;">Put</span> ===
 +
 
 +
'''Path: APIGw-Site:3000/restapi/WSNManage/Connectivity/IoTGW/WSN/0000852CF4B7B0E8/Info/reset'''
 +
 
 +
'''Data:&nbsp;'''
 +
<pre>{"bv":1}</pre>
 +
 
 +
'''Reply:'''
 +
 
 +
'''Status Code: 200'''
 +
 
 +
'''Data:&nbsp;'''
 +
<pre>{"bv":1}</pre>
 +
 
 +
== <span style="background-color:#00FFFF;">SenHub</span> ==
 +
 
 +
=== <span style="color:#FF0000;">Get</span> ===
 +
 
 +
'''1.Path: APIGw-Site:3000/restapi/WSNManage/SenHub/AllSenHubList'''
 +
 
 +
'''Reply:'''
 +
 
 +
{"n":"AllSenHubList","sv":"xxxxxx,0017000E40000001,xxxxx"}
 +
 
 +
'''2. Path: APIGw-Site:3000/restapi/WSNManage/SenHub/&lt;DeviceID&gt;/DevInfo'''
 +
 
 +
'''Reply:'''
 +
 
 +
{
 +
    "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
 
  }
 
  }
  
−
= Event Trigger by WebSockt =
+
 
 +
 
 +
'''3. Path:&nbsp;APIGw-Site:3000/restapi/WSNManage/SenHub/&lt;DeviceID&gt;'''
 +
 
 +
'''Reply:&nbsp;Capability ( without data )'''
 +
<pre> { 
 +
 
 +
"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"
 +
      }
 +
    }   
 +
}</pre>
 +
 
 +
'''4. Path:&nbsp;APIGw-Site:3000/restapi/WSNManage/SenHub/&lt;DeviceID&gt;/SenHub'''
 +
 
 +
'''Reply: with latest&nbsp;data value&nbsp;'''
 +
<pre>{       
 +
    "SenData": {"e":[ {"n":"Temperature","v":26},
 +
                      {"n":"Humidity","v":80},
 +
                      {"n":"GPIO1","u":"","bv":0},
 +
                      {"n":"GPIO2","u":"","bv":1}                     
 +
                    ],
 +
    "bn":"SenData"
 +
    },
 +
    "Info": {"e":[{"n":"Name","sv":"SenHub1"},
 +
                  {"n":"sw","sv":"1.0.00"}
 +
                ],
 +
    "bn":"Info"
 +
  },
 +
  "Net": {"e":[{"n":"sw","sv":"1.0.00"},
 +
                {"n":"Neighbor","sv":"00017b8965"},
 +
                {"n":"Health","v":"100.000000"}
 +
              ],
 +
    "bn":"Net"
 +
  },
 +
  "bn":"SenHub"   
 +
}</pre>
 +
 
 +
'''5. Path:&nbsp;APIGw-Site:3000/restapi/WSNManage/SenHub/&lt;DeviceID&gt;/SenHub/SenData'''
 +
 
 +
'''Reply: with latest&nbsp;data'''
 +
<pre>{
 +
    "SenData": {"e":[ {"n":"Temperature","v":26},
 +
                      {"n":"Humidity","v":80},
 +
                      {"n":"GPIO1","u":"","bv":0},
 +
                      {"n":"GPIO2","u":"","bv":1}                       
 +
                    ]
 +
    },
 +
    "bn":"SenData"
 +
}</pre>
 +
 
 +
'''6. APIGw-Site:3000/restapi/WSNManage/SenHub/&lt;DeviceID&gt;/SenHub/SenData/Temperature'''
 +
 
 +
'''Reply: with latest&nbsp;data'''
 +
<pre>{"v":26}</pre>
 +
 
 +
=== <span style="color:#FF0000;">Put</span> ===
 +
 
 +
'''EIS RESTful only supports change one resource in each request.'''
 +
 
 +
'''Ex: To&nbsp;chagne SenHub's Name by 'PUT' RESTful method'''
 +
 
 +
'''Path: APIGw-Site:3000/restapi/WSNManage/SenHub/&lt;DeviceID&gt;/SenHub/SenData/GPI01'''
 +
 
 +
'''Data:&nbsp;'''
 +
<pre>{"bv":1}</pre>
 +
 
 +
'''Reply:'''
 +
 
 +
'''HTTP Code: 200 OK'''
 +
 
 +
'''Data:&nbsp;'''
 +
<pre>{"bv":1}</pre>
 +
 
 +
= <span style="color:#0000FF;">Socket.io</span> =
 +
 
 +
There are&nbsp;two&nbsp;methods ( 1. request / response, 2. auto push message to client ) to get&nbsp;information by Socket.io.&nbsp;
 +
 
 +
=== <span style="color:#FF0000;">Request</span> ===
 +
 
 +
'''Direction: '''Client -> Socket.io Server
 +
 
 +
'''Event''': request
 +
 
 +
'''Format''': {"n":"&lt;Action&gt;", "data":{obj}, "sessionId":&lt;#&gt;}
 +
 
 +
'''Action''':
 +
 
 +
*service: To qurey what services provided by Socket.io server.
 +
*subscribe: To subscribe service that you interested (ex:WSNManage). Server will auto push event and message after success to joint service.
 +
*unsubscribe: To unsubscribe service if you don't want to interested it. Server will stop to push event and message to this client.
 +
 
 +
"'''data'''": data of request in JSON object.
 +
 
 +
"'''sessionId'''": &nbsp;Unique interger&nbsp;number of&nbsp;each request for&nbsp;distinguish. Server would&nbsp;response and fill the same sessionId.
 +
 
 +
=== <span style="color:#FF0000;">Response</span> ===
 +
 
 +
'''Direction:&nbsp;'''Server -> Client
 +
 
 +
'''Event''': response
 +
 
 +
'''Format''': {"status":&lt;#&gt;, "data":{obj}, "sessionId":&lt;#&gt;}
 +
 
 +
'''"status"''': Refer to HTTP Status Code　( 200 -> OK , 404 -> Not Found )
 +
 
 +
"'''data'''": data of reply information in JSON object
 +
 
 +
"'''sessionId'''": Server need reply the same sessionId with client's request.
 +
 
 +
 
 +
 
 +
=== <span style="color:#FF0000;">Example of Action</span> ===
 +
 
 +
==== <span style="color:#0000FF;">'''service:&nbsp;'''</span>Client query which event services provided by Socket.io Server ====
 +
 
 +
==== C->S &lt;Request&gt;: {"n":"service", "data":"", "sessionId":8954} ====
 +
 
 +
S-> C &lt;Response&gt;: {"status":200,"data":{"service":{ "e":[{"n":"WSNManage"},{"n":"SUSIManage"}]}},"sessionId":8954}
 +
 
 +
 
 +
 
 +
'''<span style="color:#0000FF;">subscribe:</span>'''Client subscibe in to join to receive which event Socket.io service
 +
 
 +
==== C->S &lt;Request&gt;: {"n":"subscribe", "data":"WSNManage", "sessionId":54774} ====
 +
 
 +
S-> C &lt;Response&gt;: {"status":200,"data":[{"event":"eConnectivity_Capability"},{"event":"eConnectivity_UpdateData"}, {"event":"eSenHub_Connected"},{"event":"eSenHub_Disconnect"}, &nbsp;
 +
 
 +
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; {"event":"eSenHub_Capability"},&nbsp;{"event":"eSenHub_UpdateData"}]"sessionId":8954}
 +
 
 +
 
 +
 
 +
<span style="color:#0000FF;">'''unsubscribe'''</span>: Clinet unsubscribe to leave which event Socket.io Service
 +
 
 +
C->S &lt;Request&gt;: {"n":"unsubscribe", "data":"WSNManage", "sessionId":6666}
 +
 
 +
S-> C &lt;Response&gt;: {"status":200,"sessionId":6666}
 +
 
 +
 
 +
 
 +
 
 +
 
 +
=== <span style="color:#FF0000;">Message</span> ===
 +
 
 +
'''Direction:&nbsp;'''Server -> Client
 +
 
 +
'''Event''': message
 +
 
 +
'''Format''': {"n":"&lt;ServiceName&gt;", "event":"&lt;eventType&gt;", "data":{obj})
 +
 
 +
"'''ServiceName'''": Service Name
 +
 
 +
"'''event'''": event type of this push message
 +
 
 +
"'''data'''": push data message in JSON object.
 +
 
 +
 
 +
 
 +
Please refer to "<span style="color:#FF0000;">'''WSNManage evnent message"'''</span>&nbsp;for WSNManage's event and data format.
 +
 
 +
 
 +
 
 +
= <span style="color:#0000FF;">WebSocket Service</span> =
 +
 
 +
'''WebSocket'''&nbsp;is a computer&nbsp;[https://en.wikipedia.org/wiki/Communications_protocol communications protocol], providing&nbsp;[https://en.wikipedia.org/wiki/Full-duplex full-duplex]&nbsp;communication channels over a single&nbsp;[https://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP]&nbsp;connection. The WebSocket protocol was standardized by the&nbsp;[https://en.wikipedia.org/wiki/Internet_Engineering_Task_Force IETF]&nbsp;as&nbsp;[https://en.wikipedia.org/wiki/Request_for_Comments RFC]&nbsp;6455 in 2011, and the WebSocket&nbsp;[https://en.wikipedia.org/wiki/Application_programming_interface API]&nbsp;in&nbsp;[https://en.wikipedia.org/wiki/Web_IDL Web IDL]&nbsp;is being standardized by the&nbsp;[https://en.wikipedia.org/wiki/World_Wide_Web_Consortium W3C].
 +
 
 +
WebSocket is designed to be implemented in&nbsp;[https://en.wikipedia.org/wiki/Web_browser web browsers]&nbsp;and&nbsp;[https://en.wikipedia.org/wiki/Web_server web servers], but it can be used by any client or server application. The WebSocket Protocol is an independent TCP-based protocol. Its only relationship to&nbsp;[https://en.wikipedia.org/wiki/HTTP HTTP]&nbsp;is that its&nbsp;[https://en.wikipedia.org/wiki/Handshaking handshake]&nbsp;is interpreted by HTTP servers as an&nbsp;[https://en.wikipedia.org/wiki/HTTP/1.1_Upgrade_header Upgrade request].<sup id="cite_ref-1">[https://en.wikipedia.org/wiki/WebSocket#cite_note-1 [1]]</sup>&nbsp;The WebSocket protocol makes more interaction between a browser and a web server possible, facilitating the real-time data transfer from and to the server. This is made possible by providing a standardized way for the server to send content to the browser without being solicited by the client, and allowing for messages to be passed back and forth while keeping the connection open. In this way, a two-way (bi-directional) ongoing conversation can take place between a browser and the server. The communications are done over TCP&nbsp;[https://en.wikipedia.org/wiki/Port_(computer_networking) port]&nbsp;number 80, which is of benefit for those environments which block non-web Internet connections using a&nbsp;[https://en.wikipedia.org/wiki/Firewall_(computing) firewall]. Similar two-way browser-server communications have been achieved in non-standardized ways using stopgap technologies such as&nbsp;[https://en.wikipedia.org/wiki/Comet_(programming) Comet].
 +
 
 +
 
 +
 
 +
=== <span style="color:#FF0000;"></span><span style="color:#FF0000;">API-Manage Websocket JSON Data Format</span> ===
 +
 
 +
{"n":"&lt;GroupName&gt;","event":"event Type","data":{JSON Obj}}
 +
 
 +
 
 +
 
 +
=== <span style="color:#FF0000;">Websocket of WSNManage&nbsp;</span> ===
 +
 
 +
<span style="font-size:large;">'''Endpoint: ws://ServerIP:Port/WSNManage'''</span>
 +
 
 +
Client request Server by this Endpoint to require "WSNManage" service. Server will auto push WSNManage&nbsp;event to client.
 +
 
 +
Please refer to "<span style="color:#FF0000;">'''WSNManage evnent message"'''</span>&nbsp;for WSNManage's event and data format.
 +
 
 +
= <span style="color:#0000FF;">WSNManage evnent message</span> =
  
 
  events:[
 
  events:[
Line 65: Line 328:
 
       {"event":"eSenHub_Capability"},      // => Update a SenHub's Capability ( Without Data )
 
       {"event":"eSenHub_Capability"},      // => Update a SenHub's Capability ( Without Data )
 
       {"event":"eSenHub_UpdateData"}]      // => Update SenHub's Data
 
       {"event":"eSenHub_UpdateData"}]      // => Update SenHub's Data
 +
 +
=== Updtae Connectivity's Capability ===
 +
 +
'''event:'''&nbsp;eConnectivity_Capability
 +
 +
'''data:'''
 +
 +
{
 +
  "IoTGW": {
 +
          "WSN": {
 +
              "WSN0": {
 +
&nbsp;                "Info": {
 +
&nbsp;                          "e": [{"n":"SenHubList","sv":",","asm":"r"},
 +
&nbsp;                                {"n":"Neighbor","sv":"","asm":"r"},
 +
&nbsp;                                {"n":"Health","v":80,"asm":"r"},
 +
&nbsp;                                {"n":"Name","sv":"WSN0","asm":"r"},
 +
&nbsp;                                {"n":"sw","sv":"1.0.0.1","asm":"r"},
 +
&nbsp;                                {"n":"reset","bv":0,"asm":"rw"}],
 +
&nbsp;                "bn":"Info"
 +
&nbsp;                },
 +
&nbsp;            "bn":"0000852CF4B7B0E8", "ver":1
 +
&nbsp;          },
 +
&nbsp;          "WSN1": {
 +
&nbsp;                "Info": {
 +
&nbsp;                          "e": [{"n":"SenHubList","sv":"","asm":"r"},
 +
&nbsp;                                {"n":"Neighbor","sv":"","asm":"r"},
 +
&nbsp;                                {"n":"Health","v":50,"asm":"r"},
 +
&nbsp;                                {"n":"Name","sv":"WSN1","asm":"r"},
 +
&nbsp;                                {"n":"sw","sv":"1.0.0.1","asm":"r"},
 +
&nbsp;                                {"n":"reset","bv":0,"asm":"rw"}],
 +
&nbsp;                  "bn":"Info"
 +
&nbsp;                  },
 +
&nbsp;          "bn":"0000852CF4B7B0E7",
 +
&nbsp;          "ver":1
 +
&nbsp;          },
 +
&nbsp;        "bn":"WSN"
 +
&nbsp;      },
 +
&nbsp;      "Bt": {
 +
&nbsp;            "Bt0": {
 +
&nbsp;                  "Info": {
 +
&nbsp;                            "e": [{"n":"SenHubList","sv":"","asm":"r"},
 +
&nbsp;                                  {"n":"Health","v":90,"asm":"r"},
 +
&nbsp;                                  {"n":"Name","sv":"Bt0","asm":"r"},
 +
&nbsp;                                  {"n":"sw","sv":"3.0.0.1","asm":"r"},
 +
&nbsp;                                  {"n":"reset","bv":0,"asm":"rw"}],
 +
&nbsp;                  "bn":"Info"
 +
&nbsp;                  },
 +
&nbsp;              "bn":"0000802CF4B7B028",
 +
&nbsp;              "ver":1
 +
&nbsp;              },
 +
&nbsp;        "bn":"Bt"
 +
&nbsp;      }, 
 +
&nbsp;    "ver": 1,
 +
      "bn":"IoTGW"
 +
    }
 +
  }
 +
 +
=== Updtae data value of connectivity ===
 +
 +
'''event Type:'''&nbsp;eConnectivity_UpdateData
 +
 +
'''data:'''Update Health
 +
<pre>{
 +
  "IoTGW": {
 +
        "WSN": {
 +
            "0000852CF4B7B0E8":{           
 +
              "Info": {
 +
                        "e": [{"n":"Health","v":30}],
 +
                        "bn":"Info"
 +
              },               
 +
              "bn":"0000852CF4B7B0E8",
 +
              "ver":1
 +
          },           
 +
          "bn":"WSN"
 +
        },
 +
    "ver": 1       
 +
    }
 +
}</pre>
 +
 +
=== A new SenHub connected ===
 +
 +
'''event Type:'''&nbsp;eSenHub_Connected
 +
 +
'''data:'''
 +
<pre>{
 +
  "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
 +
  }
 +
}</pre>
 +
 +
 +
 +
=== A SenHub disconnected ===
 +
 +
'''event Type:'''&nbsp;eSenHub_Disconnect
 +
 +
'''data:'''
 +
<pre>{
 +
  "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
 +
  }
 +
}</pre>
 +
 +
 +
 +
=== Update capbaility of a SenHub ===
 +
 +
'''event Type:'''&nbsp;eSenHub_Capability
 +
 +
'''data:'''
 +
<pre>{
 +
    "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"
 +
      },
 +
    },
 +
  "agentID":"0017000E40000001"
 +
}</pre>
 +
 +
 +
 +
=== Update data value of a SenHub ===
 +
 +
'''event Type:'''&nbsp;eSenHub_UpdateData
 +
 +
'''data:'''
 +
<pre>{ 
 +
    "SenHub":{ 
 +
      "SenData":{ 
 +
          "e":[ {"n":"Temperature","v":18.6},
 +
                {"n":"Humidity","v":57},
 +
                {"n":"GPIO1","bv":0},
 +
                {"n":"GPIO2","bv":0}],
 +
          "bn":"SenData"
 +
      },
 +
      "ver":1
 +
  },
 +
  "agentID":"0017000E40000001" 
 +
}</pre>

Latest revision as of 07:09, 2 July 2018

RESTful API Path Rule for WSNManage

 This document is about EIS RESTful API service of Wireless Sensor Manage (WSNManage). There are two major classes in WSNManage service one is "Connectiviy" another is "SenHub". Connectivity is wireless interfaces information in the EIS IoT Gateway solution. "SenHub" is short of sensor hub. 

Connectivity

GET

Path: APIGw-Site:3000/restapi/WSNManage/Connectivity

-> All Capability ( without data ) 

{
 "IoTGW": {
          "WSN": { 
             "WSN0": { 
                  "Info": { 
                            "e": [{"n":"SenHubList","sv":",","asm":"r"},
                                  {"n":"Neighbor","sv":"","asm":"r"},
                                  {"n":"Health","v":80,"asm":"r"},
                                  {"n":"Name","sv":"WSN0","asm":"r"},
                                  {"n":"sw","sv":"1.0.0.1","asm":"r"},
                                  {"n":"reset","bv":0,"asm":"rw"}], 
                  "bn":"Info" 
                  }, 
              "bn":"0000852CF4B7B0E8", "ver":1 
            }, 
            "WSN1": { 
                  "Info": { 
                           "e": [{"n":"SenHubList","sv":"","asm":"r"}, 
                                 {"n":"Neighbor","sv":"","asm":"r"}, 
                                 {"n":"Health","v":50,"asm":"r"}, 
                                 {"n":"Name","sv":"WSN1","asm":"r"}, 
                                 {"n":"sw","sv":"1.0.0.1","asm":"r"}, 
                                 {"n":"reset","bv":0,"asm":"rw"}], 
                   "bn":"Info" 
                   }, 
            "bn":"0000852CF4B7B0E7", 
            "ver":1 
            }, 
         "bn":"WSN" 
       }, 
       "Bt": { 
             "Bt0": { 
                    "Info": { 
                             "e": [{"n":"SenHubList","sv":"","asm":"r"}, 
                                   {"n":"Health","v":90,"asm":"r"}, 
                                   {"n":"Name","sv":"Bt0","asm":"r"}, 
                                   {"n":"sw","sv":"3.0.0.1","asm":"r"}, 
                                   {"n":"reset","bv":0,"asm":"rw"}], 
                    "bn":"Info" 
                    }, 
               "bn":"0000802CF4B7B028", 
               "ver":1 
               }, 
         "bn":"Bt" 
        },   
     "ver": 1,
     "bn":"IoTGW"
    }
 }

'Path: APIGw-Site:3000/restapi/WSNManage/Connectivity/IoTGW/WSN/0000852CF4B7B0E8/Info

Reply: with latest data value 

{
    "e": [{"n":"SenHubList","sv":"xxx,0017000E40000001,ooo"},
          {"n":"Neighbor","sv":"0000000EC6F0F830"},                                    
          {"n":"Health","v":80},
          {"n":"Name","sv":"WSN0"},
          {"n":"sw","sv":"1.0.0.1"},
          {"n":"reset","bv":0}],
    "bn":"Info"
}

Put

Path: APIGw-Site:3000/restapi/WSNManage/Connectivity/IoTGW/WSN/0000852CF4B7B0E8/Info/reset

Data:  

{"bv":1}

Reply:

Status Code: 200

Data:  

{"bv":1}

SenHub

Get

1.Path: APIGw-Site:3000/restapi/WSNManage/SenHub/AllSenHubList

Reply: 

{"n":"AllSenHubList","sv":"xxxxxx,0017000E40000001,xxxxx"}

2. Path: APIGw-Site:3000/restapi/WSNManage/SenHub/<DeviceID>/DevInfo

Reply: 

{
   	"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
}


3. Path: APIGw-Site:3000/restapi/WSNManage/SenHub/<DeviceID>

Reply: Capability ( without data ) 

 {  

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

4. Path: APIGw-Site:3000/restapi/WSNManage/SenHub/<DeviceID>/SenHub

Reply: with latest data value  

{        
    "SenData": {"e":[ {"n":"Temperature","v":26},
                      {"n":"Humidity","v":80},
                      {"n":"GPIO1","u":"","bv":0},
                      {"n":"GPIO2","u":"","bv":1}                      
                    ],
    "bn":"SenData"
    },
    "Info": {"e":[{"n":"Name","sv":"SenHub1"},
                  {"n":"sw","sv":"1.0.00"}
                 ],
    "bn":"Info"
   },
   "Net": {"e":[{"n":"sw","sv":"1.0.00"},
                {"n":"Neighbor","sv":"00017b8965"},
                {"n":"Health","v":"100.000000"}
               ],
    "bn":"Net"
   },
   "bn":"SenHub"    
}

5. Path: APIGw-Site:3000/restapi/WSNManage/SenHub/<DeviceID>/SenHub/SenData

Reply: with latest data 

{
    "SenData": {"e":[ {"n":"Temperature","v":26},
                      {"n":"Humidity","v":80},
                      {"n":"GPIO1","u":"","bv":0},
                      {"n":"GPIO2","u":"","bv":1}                        
                    ]
    },
    "bn":"SenData"
}

6. APIGw-Site:3000/restapi/WSNManage/SenHub/<DeviceID>/SenHub/SenData/Temperature

Reply: with latest data 

{"v":26}

Put

EIS RESTful only supports change one resource in each request.

Ex: To chagne SenHub's Name by 'PUT' RESTful method

Path: APIGw-Site:3000/restapi/WSNManage/SenHub/<DeviceID>/SenHub/SenData/GPI01

Data:  

{"bv":1}

Reply:

HTTP Code: 200 OK

Data:  

{"bv":1}

Socket.io

There are two methods ( 1. request / response, 2. auto push message to client ) to get information by Socket.io. 

Request

Direction: Client -> Socket.io Server

Event: request

Format: {"n":"<Action>", "data":{obj}, "sessionId":<#>}

Action:

  • service: To qurey what services provided by Socket.io server.
  • subscribe: To subscribe service that you interested (ex:WSNManage). Server will auto push event and message after success to joint service.
  • unsubscribe: To unsubscribe service if you don't want to interested it. Server will stop to push event and message to this client.

"data": data of request in JSON object.

"sessionId":  Unique interger number of each request for distinguish. Server would response and fill the same sessionId.

Response

Direction: Server -> Client

Event: response

Format: {"status":<#>, "data":{obj}, "sessionId":<#>}

"status": Refer to HTTP Status Code　( 200 -> OK , 404 -> Not Found )

"data": data of reply information in JSON object

"sessionId": Server need reply the same sessionId with client's request.


Example of Action

service: Client query which event services provided by Socket.io Server

C->S <Request>: {"n":"service", "data":"", "sessionId":8954}

S-> C <Response>: {"status":200,"data":{"service":{ "e":[{"n":"WSNManage"},{"n":"SUSIManage"}]}},"sessionId":8954}


subscribe:Client subscibe in to join to receive which event Socket.io service

C->S <Request>: {"n":"subscribe", "data":"WSNManage", "sessionId":54774}

S-> C <Response>: {"status":200,"data":[{"event":"eConnectivity_Capability"},{"event":"eConnectivity_UpdateData"}, {"event":"eSenHub_Connected"},{"event":"eSenHub_Disconnect"},  

                                                                  {"event":"eSenHub_Capability"}, {"event":"eSenHub_UpdateData"}]"sessionId":8954}


unsubscribe: Clinet unsubscribe to leave which event Socket.io Service

C->S <Request>: {"n":"unsubscribe", "data":"WSNManage", "sessionId":6666}

S-> C <Response>: {"status":200,"sessionId":6666}



Message

Direction: Server -> Client

Event: message

Format: {"n":"<ServiceName>", "event":"<eventType>", "data":{obj})

"ServiceName": Service Name

"event": event type of this push message

"data": push data message in JSON object.


Please refer to "WSNManage evnent message" for WSNManage's event and data format.


WebSocket Service

WebSocket is a computer communications protocol, providing full-duplex communication channels over a single TCP connection. The WebSocket protocol was standardized by the IETF as RFC 6455 in 2011, and the WebSocket API in Web IDL is being standardized by the W3C.

WebSocket is designed to be implemented in web browsers and web servers, but it can be used by any client or server application. The WebSocket Protocol is an independent TCP-based protocol. Its only relationship to HTTP is that its handshake is interpreted by HTTP servers as an Upgrade request.[1] The WebSocket protocol makes more interaction between a browser and a web server possible, facilitating the real-time data transfer from and to the server. This is made possible by providing a standardized way for the server to send content to the browser without being solicited by the client, and allowing for messages to be passed back and forth while keeping the connection open. In this way, a two-way (bi-directional) ongoing conversation can take place between a browser and the server. The communications are done over TCP port number 80, which is of benefit for those environments which block non-web Internet connections using a firewall. Similar two-way browser-server communications have been achieved in non-standardized ways using stopgap technologies such as Comet.


API-Manage Websocket JSON Data Format

{"n":"<GroupName>","event":"event Type","data":{JSON Obj}}


Websocket of WSNManage 

Endpoint: ws://ServerIP:Port/WSNManage

Client request Server by this Endpoint to require "WSNManage" service. Server will auto push WSNManage event to client.

Please refer to "WSNManage evnent message" for WSNManage's event and data format.

WSNManage evnent message

events:[
     {"event":"eConnectivity_Capability"}, // => Update Connectivity Capability ( Without data )
     {"event":"eConnectivity_UpdateData"}, // => Update Connectivity's Data
     {"event":"eSenHub_Connected"},        // => A new SenHub connected
     {"event":"eSenHub_Disconnect"},       // => A SenHub is disconnected
     {"event":"eSenHub_Capability"},       // => Update a SenHub's Capability ( Without Data )
     {"event":"eSenHub_UpdateData"}]       // => Update SenHub's Data

Updtae Connectivity's Capability

event: eConnectivity_Capability

data: 

{
 "IoTGW": {
          "WSN": { 
             "WSN0": { 
                  "Info": { 
                            "e": [{"n":"SenHubList","sv":",","asm":"r"},
                                  {"n":"Neighbor","sv":"","asm":"r"},
                                  {"n":"Health","v":80,"asm":"r"},
                                  {"n":"Name","sv":"WSN0","asm":"r"},
                                  {"n":"sw","sv":"1.0.0.1","asm":"r"},
                                  {"n":"reset","bv":0,"asm":"rw"}], 
                  "bn":"Info" 
                  }, 
              "bn":"0000852CF4B7B0E8", "ver":1 
            }, 
            "WSN1": { 
                  "Info": { 
                           "e": [{"n":"SenHubList","sv":"","asm":"r"}, 
                                 {"n":"Neighbor","sv":"","asm":"r"}, 
                                 {"n":"Health","v":50,"asm":"r"}, 
                                 {"n":"Name","sv":"WSN1","asm":"r"}, 
                                 {"n":"sw","sv":"1.0.0.1","asm":"r"}, 
                                 {"n":"reset","bv":0,"asm":"rw"}], 
                   "bn":"Info" 
                   }, 
            "bn":"0000852CF4B7B0E7", 
            "ver":1 
            }, 
         "bn":"WSN" 
       }, 
       "Bt": { 
             "Bt0": { 
                    "Info": { 
                             "e": [{"n":"SenHubList","sv":"","asm":"r"}, 
                                   {"n":"Health","v":90,"asm":"r"}, 
                                   {"n":"Name","sv":"Bt0","asm":"r"}, 
                                   {"n":"sw","sv":"3.0.0.1","asm":"r"}, 
                                   {"n":"reset","bv":0,"asm":"rw"}], 
                    "bn":"Info" 
                    }, 
               "bn":"0000802CF4B7B028", 
               "ver":1 
               }, 
         "bn":"Bt" 
        },   
     "ver": 1,
     "bn":"IoTGW"
    }
 }

Updtae data value of connectivity

event Type: eConnectivity_UpdateData

data:Update Health 

{
   "IoTGW": {
        "WSN": {
            "0000852CF4B7B0E8":{            
              "Info": {
                        "e": [{"n":"Health","v":30}],
                        "bn":"Info"
              },                
              "bn":"0000852CF4B7B0E8",
              "ver":1
           },            
           "bn":"WSN" 
        },
    "ver": 1        
    }
}

A new SenHub connected

event Type: eSenHub_Connected

data: 

{
  "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
   }
}


A SenHub disconnected

event Type: eSenHub_Disconnect

data: 

{
  "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
   }
}


Update capbaility of a SenHub

event Type: eSenHub_Capability

data: 

{
    "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"
       },
    },
   "agentID":"0017000E40000001"
}


Update data value of a SenHub

event Type: eSenHub_UpdateData

data: 

{  
    "SenHub":{  
       "SenData":{  
          "e":[ {"n":"Temperature","v":18.6},
                {"n":"Humidity","v":57},
                {"n":"GPIO1","bv":0},
                {"n":"GPIO2","bv":0}],
          "bn":"SenData"
       },
       "ver":1
   },
   "agentID":"0017000E40000001"  
}
Retrieved from "https://ess-wiki.advantech.com.tw/wiki/index.php?title=EIS_RESTfulAPI_ProcWSNData&oldid=12363"