目录
一、概述
二、通讯地址
三、通讯数据格式
四、命令列表
1、设备登录 2、发送实时数据 3、用户和设备上线通知 4、用户和设备下线通知 5、用户与设备、设备与设备、用户与用户间沟通指令数据 6、查询设备或用户是否在线 7、查询当前设备状态 8、发送报警信息 9、查询服务器时间 10、强制目标设备下线
五、PC端模拟测试
六、用户相关指令
一、概述
贝壳物联云平台采用以TCP协议为主，UDP协议为辅的形式进行通讯，两种协议间信息互通（主要为UDP可以发送指令给TCP在线设备）。
在TCP协议的基础上，可以直接使用TCP或者websocket建立长连接，定时发送心跳数据，保持用户、设备在线，在线期间与服务器可进行Json字符串格式数据进行通讯，也可采用http(s)通讯协议获取用户资源、向设备发送指令、上传图片等。
以UDP协议为基础的通讯，设备可不必保持在线，随时在需要的时候向服务器发送指令进行相关操作。
TCP（websocket）长连接协议，如下。
二、通讯地址
通讯方式：TCP或websocket
地址：www.bigiot.net
TCP端口：8181、8282、8585（ssl加密）
Websocket端口：8383、8484（ssl加密）
8181端口——服务器不主动发送心跳包，靠客户端主动发送心跳包保持在线，心跳间隔以40~50s为佳；
8282端口——服务器主动向客户端发送心跳包
{"M":"b"}\n每40s发送一次，如果两次没有应答（即在80s内没有向服务器发送有效数据），服务将自动与客户端断开连接。
8383端口(ws://)——服务器主动向客户端发送心跳包
{"M":"ping"}每30s发送一次，如果两次没有应答（即在60s内没有向服务器发送有效数据），服务将自动与客户端断开连接。
8484端口（wss://）——心跳同8383
8585端口（tcp+ssl）——心跳同8181
心跳包格式：任何符合通讯数据格式的字符串均可（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说明：此命令无返回信息，两次发送间隔不得小于5s，发送数据前应确保该设备已登录在线。
M —— 固定(Method)
update —— 固定，实时更新数据指令（可用 u 代替 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 —— 固定，沟通指令（可用 s 代替 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、"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"}\nM —— 固定(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 —— 固定，查询当前设备状态指令（可用 t 代替 status，减小命令长度）
返回结果：
{"M":"xx1"}\nM —— 固定(Method)
xx1 —— 可变(connected/checked)，当前设备状态，connected代表已连接服务器尚未登录，checked代表已连接且登录成功
8、发送报警信息
{"M":"alert","ID":"xx1","C":"xx2"}\n说明：（设备主动发送报警信息，通过触发已在用户中心设置的报警提示，可通过邮件、微博、钉钉机器人、微信（方糖）、webhook等方式，对外发送指定提示内容。两次发送间隔不得小于10min，无返回）
M —— 固定(Method)
alert —— 固定，设备主动发送报警指令
ID —— 固定
xx1 —— 可变，要触发的报警提示ID，可在用户中心查看或添加。
C —— 固定(Content)
xx1 —— 可变，自定义的报警内容。
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"}\nM —— 固定(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"}\nM —— 固定(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连接测试教程》
Windows测试工具见：https://www.bigiot.net/talk/1140.html
六、用户相关指令
用户相关指令另起一章说明，详见：《贝壳物联用户通讯协议》