绿刻度数据转发开发文档

使用须知

用户需要拥有自己的服务器以及合法域名或公网IP 。

接入指南

   第一步:开通数据转发服务

 在手机端绿刻度微信公众号-【我的】-【实用工具】-【数据转发】开通数据转发服务。


   第二步:搭建服务器数据接收环境

服务开通后,绿刻度会将设备汇报的数据以json格式转发到用户服务器,开发者可以在服务器接收到数据后进行二次开发。具体转发的参数如下(注:此表格只列出了最常用的部分字段,如开发中有疑问请联系客服):

字段名 变量名 类型 示例值 描述 必包含
时间戳 time String 20170906121120 当前数据的时间戳
设备ID deviceId String 8ECF8FB88888 作为设备的唯一ID,区分设备
信号强度 RSSI String -50 单位 : dbm
电量 voltage String 100.0 单位 : %
数据上报间隔 reportInterval Integer 600 单位 : s
外接电源 chargeState String 1 0 : 断开状态,1 : 接通状态
经度 longitude Double 116.397128 经度
纬度 latitude Double 39.916527 纬度
传感器ID sensorId String 28BBC30AC01701AB-1 同一个设备下传感器的唯一标识
传感器名称 sensorName String 温度 传感器名称
传感器标识 sensorFlag String temperature 可以通过该字段区分不同的传感器
传感器测量值 sensorVal Float 25.5
传感器测量值单位 sensorUnit String
传感器报警范围 sensorScope String 15~25

注:上表中“必包含”为“是”的字段无论任何设备都会转发,其他字段与设备类型有关。(建议开发者在接口调试成功之后,先打印出服务器接收到的json数据,以实际打印结果为依据进行开发。也可以参考C:\\lvkedu_data\\data.txt路径下的文本文件(测试Demo会将转发的json数据写入C:\\lvkedu_data\\data.txt文件中)。)

以远程温湿度计为例,其转发参数如下:

[{
      "time": "20170906121120",
      "deviceId": "8ECF8FB8",
      "RSSI": -50,
      "voltage": 80,
      "reportInterval": 600,
      "sensors": [{
            "sensorId": "28BBC30AC01701AB-1",
            "temperature": 22.5,(此字段是为了兼容旧版本,新开发的用户可忽略)
            "sensorName": "温度",
            "sensorFlag": "temperature",
            "sensorVal": 22.5,
            "sensorUnit": "℃",
            "sensorScope": "15~25"
         },
         {
            "sensorId": "28BBC30AC01701AB-2",
            "humidity": 31.7,
            "sensorName": "湿度",
            "sensorFlag": "humidity",
            "sensorVal": 31.7,
            "sensorUnit": "%",
            "sensorScope": "30~40"
         }]
}]

注:如果设备离线,监测数据会缓存到设备中,当设备上线时会将缓存的多组数据一起转发,其转发参数如下:

[{
      "time": "20170906121120",
      "deviceId": "8ECF8FB8",
      "RSSI": -50,
      "voltage": 80,
      "reportInterval": 600,
      "sensors": [{
            "sensorId": "28BBC30AC01701AB-1",
            "temperature": 22.5,(此字段是为了兼容旧版本,新开发的用户可忽略)
            "sensorName": "温度",
            "sensorFlag": "temperature",
            "sensorVal": 22.5,
            "sensorUnit": "℃",
            "sensorScope": "15~25"
         },
         {
            "sensorId": "28BBC30AC01701AB-2",
            "humidity": 31.7,
            "sensorName": "湿度",
            "sensorFlag": "humidity",
            "sensorVal": 31.7,
            "sensorUnit": "%",
            "sensorScope": "30~40"
         }]
},
{
      "time": "20170906120120",
      "deviceId": "8ECF8FB8",
      "RSSI": -52,
      "voltage": 70,
      "reportInterval": 600,
      "sensors": [{
            "sensorId": "28BBC30AC01701AB-1",
            "temperature": 23.5,(此字段是为了兼容旧版本,新开发的用户可忽略)
            "sensorName": "温度",
            "sensorFlag": "temperature",
            "sensorVal": 23.5,
            "sensorUnit": "℃",
            "sensorScope": "15~25"
         },
         {
            "sensorId": "28BBC30AC01701AB-2",
            "humidity": 37.7,
            "sensorName": "湿度",
            "sensorFlag": "humidity",
            "sensorVal": 37.7,
            "sensorUnit": "%",
            "sensorScope": "30~40"
         }]
} ]

回传结果(用户服务器接收到转发的数据后,请返回以下字段给绿刻度)

字段名 必填 类型 示例值 描述
状态码 String SUCCESS/ERROR 该字段作为绿刻度统计是否转发成功的依据

举例如下:

HttpServletResponse.getWriter().write("SUCCESS");// 接收成功回传SUCCESS
HttpServletResponse.getWriter().write("ERROR");// 接收失败回传ERROR

第三步:配置服务器数据接收地址

  用户服务器接收数据环境搭建完成之后,请到绿刻度微信公众号-【我的】-【实用工具】-【数据转发】配置服务器接收地址,测试成功后就可以正常接收绿刻度转发的数据,否则将无法正常使用。
  接收地址示例:
  域名方式 :http://www.lvkedu.com/Demo/demoServlet
  域名+端口方式 :http://www.lvkedu.com:8080/Demo/demoServlet
  IP地址+端口方式 :http://x.x.x.x:8080/Demo/demoServlet

需要注意的是:绿刻度服务器转发数据到用户服务器后,如果在五秒内收不到响应会断掉连接,这会导致数据丢失。因此,请保证服务器在接收到绿刻度转发的数据后,在五秒内做出响应。

Demo下载

       数据转发开发Demo下载        

注:测试Demo会将转发的json数据写入C:\\lvkedu_data\\data.txt文件中,方便开发者开发。