贝壳物联平台通讯协议

贝壳物联平台通讯协议

贝壳物联平台通讯协议TCP、UDP、HTTP、Websocket说明，设备登录服务器，收发命令，发送实时数据，上传图片等协议。

1. 首页
2. 帮助文档
3. API文档

一、概述

贝壳物联云平台采用以TCP协议为主，UDP协议为辅的形式进行通讯，两种协议间信息互通。

在TCP协议的基础上，可以直接使用TCP或者websocket建立长连接，定时发送心跳数据，保持设备在线，在线期间设备与服务器可进行Json字符串格式数据进行通讯，也可采用http通讯协议进行图片上传，并实现实时更新。

以UDP协议为基础的通讯，设备可不必保持在线，随时在需要的时候向服务器发送指令进行相关操作。

1. http上传图片协议

2. UDP通讯协议

3. TCP（websocket）长连接协议，如下。
   

二、通讯地址

通讯方式：TCP或websocket

地址：www.bigiot.net（或IP：121.42.180.30）

TCP端口：8181、8282

Websocket端口：8383

8181端口——服务器不主动发送心跳包，靠客户端主动发送心跳包保持在线，心跳间隔以30~60s为佳；

8282端口——服务器主动向客户端发送心跳包

{"M":"b"}\n

每40s发送一次，如果两次没有应答（即在80s内没有向服务器发送有效数据），服务将自动与客户端断开连接。

8383端口——服务器主动向客户端发送心跳包

{"M":"ping"}

每30s发送一次，如果两次没有应答（即在60s内没有向服务器发送有效数据），服务将自动与客户端断开连接。

心跳包格式：任何符合通讯数据格式的字符串均可（websocket可不带\n），如：

{"M":"beat"}\n

三、通讯数据格式

Json字符串+换行符
形如：{"M":"beat"}\n
称之为Json New Line。

四、命令列表

1、设备登录 （加密）

{"M":"checkin","ID":"xx1","K":"xx2"}\n

说明：
M —— 固定(Method)
checkin —— 固定，登录指令
ID —— 固定
xx1 —— 可变，设备ID，在会员中心查看
K —— 固定(apiKey)
xx2 —— 可变，设备apikey，在会员中心查看
设备登录后，如果在1分钟内无数据传送，连接将被自动关闭。
若保持设备长期在线，可每隔50秒向服务器发送一次信息，任何信息均可。

返回结果（登录信息正确时返回，错误无任何返回，如果设备已登录，也将无任何返回信息，且不会登录成功）：

{"M":"checkinok","ID":"xx1","NAME":"xx2","T":"xx3"}\n

说明：
M —— 固定(Method)
checkinok —— 固定，设备登录成功指令
ID —— 固定
xx1 —— 可变，设备登录成功后，用于通讯的唯一ID，其组成为字符“D"+设备ID，如D24

NAME —— 固定
xx2 —— 可变，该设备的名称
T —— 固定(time)
xx3 —— 可变，服务器发送信息时的时间戳，自从 Unix 纪元（格林威治时间 1970 年 1 月 1 日 00:00:00）到当前时间的秒数。

2、发送实时数据

{"M":"update","ID":"xx1","V":{"id1":"value1",...}}\n

说明：此命令无返回信息，两次发送间隔不得小于4s，发送数据前应确保该设备已登录在线。

M —— 固定(Method)
update —— 固定，实时更新数据指令
ID —— 固定
xx1 —— 可变，设备ID，在会员中心查看
V —— 固定(Value)
    id1 —— 可变，数据接口ID，在会员中心查看
    value1 —— 可变（数值型），本地数据（譬如：传感器测量数据）
    ... —— 可以更新该设备下多个数据接口的数据

示例

一次上传单个接口数据示例：

{"M":"update","ID":"2","V":{"2":"120"}}\n

同时上传多个接口数据示例：

{"M":"update","ID":"112","V":{"6":"1","36":"116"}}\n

实时上传定位接口数据示例：

{"M":"update","ID":"112","V":{"36":"116,40"}}\n

其中116为经度值，40是为维度值，详见：定位数据上传说明。

3、用户和设备上线通知数据

{"M":"login","ID":"xx1","NAME":"xx2","T":"xx3"}\n

说明：用户和设备登录成功后，贝壳服务器会向所属用户，及该用户名下所有其他设备发此信息

M —— 固定(Method)
login —— 固定，用户或设备登录成功指令
ID —— 固定
xx1 —— 可变，用户登录成功后，用于通讯的唯一ID，其组成为字符“U"+用户ID，如U23
NAME —— 固定
xx2 —— 可变，用户的名称
T —— 固定(time)
xx3 —— 可变，服务器发送信息时的时间戳，自从 Unix 纪元（格林威治时间 1970 年 1 月 1 日 00:00:00）到当前时间的秒数。

4、用户或设备下线通知数据

{"M":"logout","ID":"xx1","NAME":"xx2","T":"xx3"}\n

说明：设备和用户离线后，贝壳服务器会向所属用户，及该用户名下其他所有设备发此信息

M —— 固定(Method)

logout —— 固定，用户或设备下线指令

ID —— 固定

xx1 —— 可变，下线设备或用户的唯一通讯ID，其组成为字符"D"+设备ID、"U"+用户ID、"P"+游客ID，如D24、U23

NAME —— 固定

xx2 —— 可变，下线设备或用户的名称

T —— 固定(time)
xx3 —— 可变，服务器发送信息时的时间戳，自从 Unix 纪元（格林威治时间 1970 年 1 月 1 日 00:00:00）到当前时间的秒数

5、用户与设备、设备与设备、用户与用户间沟通指令数据

发送指令格式：

{"M":"say","ID":"xx1","C":"xx2","SIGN":"xx3"}\n

提醒：此命令发送目标不受限制，无论目标是否属于自己，无论是用户、游客还是设备，只要对方在线都将收到此指令(设置为不公开监听的除外)。

M —— 固定(Method)
say —— 固定，沟通指令
ID —— 固定

xx1 —— 可变，发送目标的唯一通讯ID，其组成为字符"D"+设备ID、"U"+用户ID、"G"+群组ID、"P"+游客ID，如D24、U23，当xx1为“ALL”时，将向该用户及其名下所有设备发送该消息

              xx1也可以是多个通讯ID组成的数组，用于同时向多个设备发送信息，此时的写法为 "ID":["U2","D112","D21","G11"] ，方括号及其内容替代"xx1"

              注：当发送目标是群组时，只有当前登录设备或用户属于目标群组，才能发送成功。

C —— 固定(content)

xx2 —— 可变(数据类型自定，符合Json字符穿要求即可)，发送指令内容

SIGN —— 固定（可选）

xx3 —— 可变（可选），自定义字符串，可用于对指令的签名标识

对方接受到的指令格式：

{"M":"say","ID":"xx1","NAME":"xx2","C":"xx3","SIGN":"xx4","T":"xx5","G":"xx6"}\n

提醒：此指令不管设备公开还是隐藏都将收到，可能来自游客、其他用户或其他用户的设备，重要操作请对指令来源ID进行判断。任何人都可以对你说话，但是听不听他的，你说了算。设备设置为不公开监听，可拒绝接收非同一用户名下设备发来的消息（当信息来自群组消息时，不受此限制）。

M —— 固定(Method)

say —— 固定，沟通指令

ID —— 固定

xx1 —— 可变，指令来源的唯一通讯ID，其组成为字符"D"+设备ID、"U"+用户ID、"G"+分组ID、"P"+游客ID，如D24、U23

NAME —— 固定

xx2 —— 可变，指令来源的名称

C —— 固定(content)

xx3 —— 可变(数据类型自定，符合Json字符穿要求即可)，发送指令内容

SIGN —— 固定（可选）

xx4 —— 可变（可选），来自指令发送方的签名标识

T —— 固定(time)
xx5 —— 可变，服务器发送信息时的时间戳，自从 Unix 纪元（格林威治时间 1970 年 1 月 1 日 00:00:00）到当前时间的秒数

G —— 固定（可选），当信息来自群组时，会有此项

xx6 —— 可变，群组ID，形如"G20"

6、查询设备或用户是否在线

{"M":"isOL","ID":["xx1",...]}\n

说明：可以查询设备自身和其他设备及用户在线状态，两次查询间隔不得小于10s，此命令使用前需登录。

M —— 固定(Method)

isOL —— 固定，是否在线查询指令

ID —— 固定

    xx1 —— 可变，目标设备或用户的唯一通讯ID，其组成为字符"D"+设备ID、"U"+用户ID、"P"+游客ID，如D24、U23

    ... —— 可以同时查询多个目标

返回结果：

{"M":"isOL","R":{"XX1":"xx1",...},"T"":"xx3"}\n

M —— 固定(Method)

isOL —— 固定，是否在线查询指令

R —— 固定(Respone)

    XX1 —— 可变，查询目标设备或用户的唯一通讯ID，其组成为字符"D"+设备ID、"U"+用户ID、"P"+游客ID，如D24、U23

    xx1 —— 可变，XX1的查询结果0或1，0代表不在线，1代表在线

    ... —— 多个查询结果

T —— 固定(time)
xx2—— 可变，服务器发送信息时的时间戳，自从 Unix 纪元（格林威治时间 1970 年 1 月 1 日 00:00:00）到当前时间的秒数

7、查询当前设备状态

{"M":"status"}\n

说明：（两次查询间隔不得小于10s）

M —— 固定(Method)

status —— 固定，查询当前设备状态指令

返回结果：

{"M":"xx1"}\n

M —— 固定(Method)

xx1 —— 可变(connected/checked)，当前设备状态，connected代表已连接服务器尚未登录，checked代表已连接且登录成功

8、发送报警信息

{"M":"alert","C":"xx1","B":"xx2"}\n

说明：（设备主动发送报警信息，两次发送间隔不得小于10min，无返回）

M —— 固定(Method)

alert —— 固定，设备主动发送报警指令

C —— 固定(Content)

xx1 —— 可变，自定义的报警内容

B —— 固定(By)

xx2 —— 可变，报警发送方式，目前支持email、weibo、qq，三种选择其中一种，微博和qq需进行绑定后方能使用

9、查询服务器时间

{"M":"time","F":"xx1"}\n

说明：（需在设备登录后进行查询，两次查询间隔不得小于10s）

M —— 固定(Method)

time —— 固定，查询服务器时间指令

F —— 固定(Format)

xx1 —— 可变，定义返回格式stamp（返回：1466659300）、Y-m-d（返回：2016-06-21）、Y.m.d(返回：2016.06.21)、Y-m-d H:i:s(返回：2016-06-21 10:25:30)

返回结果

说明：查询过快或格式错误无返回

{"M":"time","T":"xx1"}\n

M —— 固定(Method)

time —— 固定，查询服务器时间返回指令

T —— 固定(Time)

xx1 —— 可变，根据查询格式返回服务器的时间

10、强制目标设备下线

{"M":"checkout","ID":"xx1","K":"xx2"}\n

说明：发送此命令无需登录，只需与服务建立连接即可。用于清除设备在极端情况掉线（断电、断网等）后，有一分多钟在线滞留，在这段时间内无法checkin成功，如果无法接受一分钟等待，可使用此命令消除滞留，消除后即可登录。也可用于在其他地方强制目标设备下线。

M —— 固定(Method)

checkout —— 固定，强制目标设备下线指令

ID —— 固定
xx1 —— 可变，设备ID，在会员中心查看
K —— 固定(apiKey)
xx2 —— 可变，设备apikey，在会员中心查看

发送命令端返回结果

说明：发送频率过快或apikey错误无返回，目标设备不在线无返回。

{"M":"checkout","ID":"xx1","T":"xx2"}\n

M —— 固定(Method)

checkout —— 固定，强制目标设备下线成功返回指令

ID —— 固定
xx1 —— 可变，成功下线设备ID，可在会员中心查看

T —— 固定(time)
xx2—— 可变，服务器发送信息时的时间戳，自从 Unix 纪元（格林威治时间 1970 年 1 月 1 日 00:00:00）到当前时间的秒数

被强制下线设备在下线前收到信息

{"M":"checkout","IP":"xx1","T":"xx2"}\n

说明：可根据此命令判断是否人为强制下线，从而决定是否需要继续自动重连、登录。

M —— 固定(Method)

checkout —— 固定，强制目标设备下线成功返回指令

IP —— 固定
xx1 —— 可变，发送强制命令设备IP地址

T —— 固定(time)
xx2—— 可变，服务器发送信息时的时间戳，自从 Unix 纪元（格林威治时间 1970 年 1 月 1 日 00:00:00）到当前时间的秒数

五、PC端模拟测试

PC模拟测试TCP长连接教程见：《贝壳物联通讯协议TCP连接测试教程》

转载于：

http://www.bigiot.net/help/1.html