贝壳物联平台通讯协议

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

目录

一、概述

二、通讯地址

三、通讯数据格式

四、命令列表

1、设备登录 2、发送实时数据 3、用户和设备上线通知 4、用户和设备下线通知 5、用户与设备、设备与设备、用户与用户间沟通指令数据 6、查询设备或用户是否在线 7、查询当前设备状态 8、发送报警信息 9、查询服务器时间 10、强制目标设备下线

五、PC端模拟测试

六、用户相关指令

一、概述

    贝壳物联云平台采用以TCP协议为主,UDP协议为辅的形式进行通讯,两种协议间信息互通(主要为UDP可以发送指令给TCP在线设备)。

    在TCP协议的基础上,可以直接使用TCP或者websocket建立长连接,定时发送心跳数据,保持用户、设备在线,在线期间与服务器可进行Json字符串格式数据进行通讯,也可采用http(s)通讯协议获取用户资源、向设备发送指令、上传图片等。

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

  1. https上传图片协议

  2. UDP通讯协议

  3. 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"}\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 —— 固定,查询当前设备状态指令(可用 t 代替 status,减小命令长度)

返回结果:

{"M":"xx1"}\n

M —— 固定(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"}\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连接测试教程

Windows测试工具见:https://www.bigiot.net/talk/1140.html

六、用户相关指令

用户相关指令另起一章说明,详见:《贝壳物联用户通讯协议


上一篇:没有了
下一篇:远程控制通讯——基于Arduino + ESP8266控制LED灯并返回控制结果
返回顶部