乐联网手机APP控制 arduino 协议暂行版--20130107

2013-01-07 10:33
关闭窗口

 

 

介绍：本文档主要包括两部分内容：

1：app如何获取arduino ip地址（同一wifi 网络）。

2：app如何控制arduino进行相关操作。
 
相关arduino里程参考 open.lewei50.com/home/news/81
 
 
 
一、获得备API地址
a)         每个设备启动后都需要在9959端口进行UDP监听。
b)        客户端需要检索设备信息时先打开9960端口进行UDP监听，然后使用9959端口进行UDP广播，内容为username。
c)         设备接收到UDP请求后，判断设备所设置的username是否和请求一致，一致的话以端口9960端口像请求设备发送设备信息，格式为JSON：
{
   "deviceName":"01",
   "username":"laoliu1982",
   "port":80,
   "api":"api"
}
d)        客户端接收到UDP消息，解析出username是否和当前一致，一致的话就可以根据数据获得API地址：发送方IP+端口+api路径，举例：http://192.168.1.101:80/api。
 
 
 
 
二、安全机制
a)         设备和手机客户端都共同持有相同的username和userkey。
b)        手机客户端首次广播时需要发送username，这样设备就不会响应无用的请求。
c)         手机客户端收到设备的广播消息也需要通过username来判断是否对应的设备。
d)        手机客户端每次调用API，都需要以GET方式传递userkey，设备端API在接收客户端请求时会验证userkey是否有效，防止他人操作设备。
三、API说明
为了简化设备编程，对于API调用方式规定如下：
a)         只需要1个API地址，通过传递不同的方法名（f）来获知用户要调用的方法，传递的参数通过p1、p2、p3......
b)        手机端请求均为GET方式，服务器返回均为JSON格式
c)         返回的格式固定由三部分组成
i.          successful 是否成功
ii.        message 返回消息
iii.      data 返回值
举例说明：
其中：
l userkey：每次调用都需要传递
l f：要调用的方法
l p(x)：要调用方法对应的参数列表
 
四、API规范
a) getAllSensors   获取设备所有传感器
举例：
返回值：
{
   "successful":true,
   "message":null,
   "data":[
      {
         "id":"1",
         "type":"jdq",
         "name":"s1",
         "value":"1",
         "status":"ok"
      },
      {
         "id":"2",
         "type":"jdq",
         "name":"s2",
         "value":"1",
         "status":"ok"
      },
      {
         "id":"3",
         "type":"jdq",
         "name":"s3",
         "value":"0",
         "status":"ok"
      }
   ]
}
b) getSensor(string sensorid) 获取某个设备传感器信息
举例：
参数：p1为sensor的标识id
返回值：
{
   "data":{
      "id":"1",
      "type":"jdq",
      "name":"s1",
      "value":"1",
      "status":"ok"
   },
   "successful":true,
   "message":null
}
c) updateSensor(string sensorid,string value) 更新传感器数据
举例：
参数：p1为sensor的标识id;p2为要更新的value
返回值：
{
   "data":{
      "id":"1",
      "type":"jdq",
      "name":"s1",
      "value":"1",
      "status":"ok"
   },
   "successful":true,
   "message":null
}
 
五、数据格式参考
a)         API返回值
{
   "successful":true,
   "message":null,
   "data":null
}
b)        设备信息
{
   "deviceName":"01",
   "username":"laoliu1982",
   "port":80,
   "api":"api"                                  ----api路径
}
c)         传感器信息
{
      "id":"1",
      "type":"jdq",
      "name":"s1",
      "value":"1",
      "status":"ok"
   }