概述

浏览器（Javascript）可以通过Web Socket API与智城云云端直接通讯。浏览器（Javascript）通过 Web Socket API，可以控制设备和实时接收设备上报的数据。

名词解释

名词	含义
client	客户端用户，可以是Android，iOS， Web端用户，指具体使用者
server	本文指的是websocket服务器，对客户端消息进行处理并反馈等
deviceId	设备唯一标识
mid	消息ID，同一会话中会产生不同的消息编号

通讯流程

浏览器（Javascript）通过Web Socket API与云端通讯主要包括以下的通讯过程。

用户登陆
接收设备推送的消息
接收服务器消息或者其他官方消息
主动控制设备，获取设备相关信息
心跳收发

注意事项

1协议阅读说明

协议格式仅支持JSON格式，输入与输出都是JSON格式数据。

2请求域名

默认请求域名为：

1 2	ws:demo.machtalk.net:9000/xcloud wss:demo.machtalk.net:9000/xcloud

3失败返回

所有请求，失败时会统一返回固定格式：

{
	"cmd": "resp",
	"mid": "123",
	"success": 0,
	"msg": "失败描述信息"
}

返回参数说明

参数名称	说明
cmd	命令类型，此处为resp
mid	消息序号
success	返回结果，success=0为失败
msg	当success=0时，会有失败描述信息

4其他注意事项

在与云端进行Web Socket交互前，用户必须已注册并已绑定了设备。
与云端交互的数据均为JSON字符串,以UTF-8的方式编码。可以通过JSON.stringify(json)把Javascript对象转化为字符串再发送给云端，或通过var res = JSON.parse(evt.data)把接收到的字符串数据转化成Javascript对象。

通讯协议

1登录协议

请求说明：客户端在连接服务器成功后应该向服务器发送的第一条消息。该消息为登录消息。第一次登录时候需要提供用户名和密码，在登录成功后会返回token字段，在30分钟之内可以用token二次鉴权。
请求消息方向：client->server
消息内容示例

{
	"cmd": "login",
	"mid": mid,
	"usr": "用户名",
	"pwd": "md5加密后的密码",
	"token": "第一次鉴权成功后返回的随机字符"
}

请求参数说明

参数名称	说明
cmd	命令类型，此处为login
mid	消息序号
usr	用户名
pwd	用户密码，md5加密
token	token是使用用户名密码登录后返回的鉴权结果中的一个字段，后期在连接session生命周期之内可以使用token来进来二次登录

返回说明

服务器收到登录命令后，将鉴权结果信息返回给客户端。

返回消息方向

server->client

返回内容

  成功时
{
	"apikey": "32位字符串",
	"cmd": "resp",
	"mid": mid,
	"success": 1,
	"token": "ws_+32位字符串"
}

返回参数说明

参数名称	说明
cmd	命令类型，此处为resp
mid	消息序号
apikey	服务器生成的一个随机数，用于其他数据接口鉴权
success	鉴权结果，success=1为成功
token	成功鉴权后返回的一个令牌信息，可以用来后期鉴权

2心跳消息

请求说明：客户端在成功连接到服务器后，需主动向服务器发送心跳信息，心跳信息暂定1分钟一次。服务器收到心跳消息后会返回心跳确认消息。服务器若是三次没收到心跳请求，则关闭和客户端的连接。
请求消息方向：client->server
消息内容示例

{
	"cmd": "hb",
	"data": "0"
}

请求参数说明

参数名称	说明
cmd	命令类型，此处为hb
data	心跳请求数据，发送为0

返回说明：服务器收到心跳请求命令后，将心跳确认结果信息返回给客户端。
返回消息方向：server->client
返回内容

{
	"cmd": "hb",
	"data": "1"
}

返回说明

参数名称	说明
cmd	cmd命令类型，此处为hb
data	心跳确认数据，发送为1

3通知消息

消息说明：用户登录成功后，服务器会主动向客户端推送推送绑定、解绑、转让权限等消息，通知用户某些信息发生变化。
请求消息方向：server->client
消息内容示例

{
	"cmd": "notify",
	"type": "type",
	"nick": "nickname",
	"uid": "userId",
	"ts": "timestamp",
	"did": "deviceId",
}

参数说明

参数名称	说明
cmd	命令类型，此处为notify
type	消息类型 1、bind：客人绑定设备时需要推送消息给主人 2、unbind：主人解绑客人与设备绑定关系时，给客人发通知 3、transfer：主人主动转让设备权限给客人，或者主人解绑设备后，服务器主动推送给客人 4、reset：设备恢复出厂设置时，会解除该设备与所有用户的绑定关系，通知相应用户 5、message：收到留言通知
nick	触发通知用户的昵称，比如某个客人绑定了某个新设备，则会向该设备的主人发送一条消息，nick就是这个客人的昵称信息。
uid	当type为reset时，携带uid,表示该uid代表的用户对设备执行恢复出厂设置操作
did	设备ID，表示用于与哪个设备绑定、解绑或者关系转移
ts	时间戳（1970年1月1日0点0分0秒到现在的秒数）

4服务器信息推送

消息说明：服务器需要向客户端推送官方消息或者其他非设备相关消息。
请求消息方向：server->client
消息内容示例

{
	"cmd": "message",
	"type": 1 / 2,
	"title": "title",
	"ts": "timestamp",
	"param": "url/msgId",
	"intro": "intro"
}

参数说明

参数名称	说明
cmd	命令类型，此处为message
type	消息的类型 1、HTML消息 2、URL消息
title	消息的标题或者消息简介
param	当type为1时，param为HTML页面的URL 当type为2时，param为消息的唯一编号
ts	时间戳（1970年1月1日0点0分0秒到现在的秒数）
intro	内容简介一般不超过30个中文字符

5设备上线通知

消息说明：当设备上线时，服务器会推送此消息给客户端，通知用户某个设备上线了。
请求消息方向：server->client
消息内容示例

{
	"cmd": "online",
	"from": "deviceid"
}

参数说明

参数名称	说明
cmd	命令类型，此处为online
from	设备ID，用于标识哪个设备上线

6设备下线通知

消息说明：当设备下线时，服务器会推送此消息给客户端，通知用户某个设备下线了。
请求消息方向：server->client
消息内容示例

{
	"cmd": "offline",
	"from": "deviceid"
}

参数说明

参数名称	说明
cmd	命令类型，此处为offline
from	设备ID，用于标识哪个设备下线

7获取设备列表

请求说明：客户请求获取用户绑定的设备列表
请求消息方向：client->server
消息内容示例

{
    "cmd": "getDevs",
    "mid": 123
}

请求参数说明

参数名称	说明
cmd	命令类型，此处为getDevs
mid	消息序号

返回说明：服务器收到获取设备列表请求命令后，将结果信息返回给客户端。
返回消息方向：server->client
返回内容

{
    "cmd": "resp",
    "mid": 123,
    "success": 1,
	"devlist":[123],
	"group":"group"
}

返回说明

参数名称	说明
cmd	命令类型，此处为resp
mid	消息序号
success	1为成功
devlist	设备列表

8设备状态查询

请求说明：当需要获取设备的当前状态时，可以通过此命令进行查询，设备会把当前状态集合按照规定的格式返回。如果恰巧此时设备出现故障，则也会返回故障码列表(fids)；当设备正在升级时，会返回升级状态和进度。
请求消息方向：client->server
消息内容示例

{
    "cmd": "query",
    "to": "deviceId",
    "mid": 123
}

请求参数说明

参数名称	说明
cmd	命令类型，此处为query
mid	消息序号
to	设备的ID，标识具体要查询哪个设备的信息

返回说明：设备收到设备查询命令时，需要作出响应，返回设备的详细信息。
返回消息方向：server->client
返回内容

{
	"cmd": "resp",
	"mid": 123,
	"code": 0,
	"as": {
		"1": 2,
		"2": 3
	},
	"asc": {
		"1": 1,
		"2": 0
	},
	"fids": [1, 23, 45],
	"ota": [0, 1, 85]
}

返回说明

参数名称	说明
cmd	命令类型，此处为resp
mid	消息序号
code	操作结果码，为0表示操作成功，非0表示错误码信息
as	设备属性集合，如{“1”:1,”2”:4}
asc	属性权限约束，目前支持两种约束类型，0：禁止读写 1：只读属性。
fids	当设备出现故障时，携带故障码列表
ota	设备的升级状态信息三元组，数组的第一个元素表示要升级的是模块还是设备，默认为0。具体取值如下：0：给模块升级1：给设备升级注意：不允许同时升级模块和设备。数组的第二个元素表示升级进度，规定如下：1：开始下载2：下载中3：下载成功4：下载失败5：开始升级6：升级中7：升级成功8：升级失败数组的第三个元素表示当前升级进度下的百分比值，默认为0

9设备状态控制

请求说明：客户端通过发送该命令来控制设备状态变化，一次命令可以控制设备的多个属性同时发生变化。设备的属性以数字编号形式表示，约定为从1开始的整数。
请求消息方向：client->server
消息内容示例

{
	"cmd": "opt",
	"mid": 123,
	"to": "deviceId",
	"as": {
		"1": 2,
		"2": 3
	}
}

请求参数说明

参数名称	说明
cmd	命令类型，此处为query
mid	消息序号
to	设备ID
as	设备属性集合，如{“1”:1,”2”:4}

返回说明：设备收到设备查询命令时，需要作出响应，返回设备的详细信息。
返回消息方向：server->client
返回内容

1 2	成功时详见设备状态上报

返回说明

参数名称	说明
cmd	命令类型，此处为resp
mid	消息序号
code	操作结果码，为0表示操作成功，非0表示错误码信息

10设备状态上报

消息说明：当设备的状态发生变化时，服务器会把该消息广播发送给该设备所属的所有用户，所以一条post消息有可能被服务器复制成几条（依赖于设备属于几个用户）消息分别转发；该消息也支持故障、升级进度的上报。
请求消息方向：server->client
消息内容示例

{
	"cmd": "post",
	"mid": 123,
	"from": "deviceId",
	"as": {
		"1": 2,
		"2": 3
	},
	"fids": [1, 23, 45],
	"ota": [0, 1, 85]
}

参数说明

参数名称	说明
cmd	命令类型，此处为offline
mid	消息ID
from	此处为设备ID，用于标识消息的来源，from的值与opt命令中的to保持一致
as	设备属性集合，如{“1”:1,”2”:4}
fids	当设备出现故障时，携带故障码列表

11设备状态告警

消息说明：当设备的某些状态发生变化，变化范围超过一定的警戒值，则需要以告警的形式发送给用户。
请求消息方向：server->client
消息内容示例

{
	"cmd": "alarm",
	"from": "deviceId",
	"aid": [10, 5, 6],
	"ts": "timestamp",
	"title": "alarm title",
	"msg": "alarm message"
}

参数说明

参数名称	说明
cmd	命令类型，此处为offline
from	此处为设备ID，用于标识消息的来源
aid	三元组的第一个元素为属性编号，第二个元素为属性值，第三个元素表示告警级别。1、2、3、4保留未使用 5：表示设备通知消息 6：表示设备告警消息
ts	时间戳（1970年1月1日0点0分0秒到现在的秒数）
title	表示告警标题，有的话带上
msg	表示告警对应的文字描述信息，用于在客户端显示告警信息

12设备故障反馈

消息说明：当设备发生故障时，会发送故障代码列表给服务器，服务器收到后会根据传递的故障ID获取故障的详细信息并组成新的消息返回给客户端;如果fids为-1，表示故障恢复，需要传给用户faults为空数组[]。
请求消息方向：server->client
消息内容示例

{
	"cmd": "fault",
	"from": "deviceId",
	"ts": "timestamp",
	"fids": [110, 119, 120]
}

参数说明

参数名称	说明
cmd	命令类型，此处为fault
from	此处为设备ID，用于标识消息的来源
fids	故障码的集合
ts	时间戳（1970年1月1日0点0分0秒到现在的秒数）