Skip to content

Latest commit

 

History

History
387 lines (210 loc) · 8.68 KB

sim_watch_serv.md

File metadata and controls

387 lines (210 loc) · 8.68 KB
Raw

儿童手表服务架构与通信协议

版本号: V1.1

修改记录:

版本号 日期 更新记录 操作人
V1.0 20180429 初版 Ren
V1.1 20180502 更新终端发送指令部分 Huang

一.整体架构

App请求-应答交互时序

不论是向手表推送数据还是从手表查询数据，均由App发起请求，经由服务端处理转发到对应手表终端，手表接收并解析命令数据后，向服务端返回对应的应答数据，服务器接收到应答数据后返回给App端，至此一次从App到手表的请求-应答交互完成

手表终端向服务端上报/查询数据

二.通讯协议

1 App与服务器通信协议

App与服务器基于Http协议通信，通用请求格式:

Method:  POST

Body: JSONString({
  clientId: "xxxx",//App用户ID
  terminalId: "xxxxx",//手表终端ID
  payload: {
    data1: "xxx",
    data2: "xxx",
   ...
  }
})

通用应答格式:

Body: JSONString({
  errcode: 0,
  clientId: "xxxx",
  terminalId: "xxxxx",
  format: "binary/JSON",
  payload: {}
})

errcode指示此次请求的成功与否，0表示请求成功，非0表示失败:

1000 请求格式错误
1001 URL错误
1002 App账户不存在
1003 手表终端不存在
1004 无权限
1100 服务器错误

一旦App端识别到errcode 非0，则可不必解析其他字段，此次请求已经失败，应给予对应的出错提示或处理.

format为"binary"表示payload是Base64变换后的字符串，App端需要将其逆变换后得到原始二进制数据，再根据具体交互的指令来决定如何解析该二进制应答.

format为“JSON”表示payload是明文的JSON字符串，App根据具体的请求类型决定JSON的解析方式.

1.1 App拉取在线手表

Req =>

Method:  POST
URL: "http://SERVER_IP:SERVER_PORT/pullOnlineTerminals"

Body: JSONString({
  clientId: "xxxx",
  payload: {
    page: 0,//页码
    size: 10//每页尺寸
  }
})

Res <=

Body: JSONString({
  errcode: 0,
  clientId: "xxxx",
  format: "JSON",
  payload: [
  {
    terminalId: "xxxx",//终端ID
    phone:"xxx",//终端电话号码
    carrier:"xxx",//运营商
    firmwareVersion:"xxx",//固件版本号
    battery:0.8//电量百分比
  },...]
})

1.2 App发起文本推送

Req =>

Method:  POST
URL: "http://SERVER_IP:SERVER_PORT/pushText"

Body: JSONString({
  clientId: "xxxx",
  terminalId: "xxxxx",
  payload: {
    text: "文本内容",
  }
})

Res <=

Body: JSONString({
  errcode: 0,
  clientId: "xxxx",
  terminalId: "xxxxx",
  format: "binary",
  payload: "=65644Bdghatdeiiyty"
})

2. 手表终端与服务器通信协议

指令格式说明

本协议中所有指令数据都按照以下的格式进行传输：

指令起始符 厂商标识 设备ID 指令流水号 内容长度 指令内容 指令结束符

实例：[HW*5678901234*0001*0006*LK,100]

各个字段说明：

l 指令起始符：固定为 [ 字符；

l 厂商标识：用于标识不同厂商，固定为两个字节，本文档参考示例中厂商标识为HW；

l 设备ID：作为设备的唯一标识，长度可能为10位或15位，通常为设备的IMEI号，本文档参考实例中设备ID长度为10位；

l 指令流水号：固定为四个字节16进制的流水号，高位在前低位在后，从0000开始每发一个指令+1，超过FFFF后再从0开始；

l 内容长度：表示指令内容字段的长度，固定为四个字节16进制，高位在前地位在后,例如FFFF表示指令内容长度为65535. 如上面实例的内容长度为LK,100这个部分的长度为6，转换为16进制为0006；

l 指令内容：为指令数据的具体内容，详见文档后面提到的每个指令的具体格式；

l 指令结束符：固定为 ] 字符；

l 指令字段分隔符号：指令中间各个字段之间使用分隔符号来隔开，分隔符号为 * 字符（指令起始符后面和指令结束符前面不需要再加分隔符）

以下指令描述中的“平台”均指服务器.

2.终端发送指令

2.1 初始化[INIT]

终端发送:

[HW*YYYYYYYYYY*NNNN*LEN*INIT,本机号码,运营商类型,固件版本号,全部参数设置次数流水号,通信录设置次数流水号]

实例: [HW*5678901234*0001*003B*INIT,13800000000,0,k6_BASE_V1.00_2016_03,0001,0001]

说明：

本机号码：上报设备内的SIM卡手机号码，如未设置为FFFFFFFFFFF；

运营商类型：1表示移动、2表示联通、3表示电信、0xFF表示其他；

固件版本号：设备固件的版本信息；

全部参数设置次数流水号：预留功能，可以不用解析；

通信录设置次数流水号：预留功能，可以不用解析；

平台回复:

[HW*YYYYYYYYYY*NNNN*LEN*INIT,接收结果,]

实例:[HW*5678901234*0001*0006*INIT,1]

接收结果：

1-成功

0-失败，表示设备未在平台注册或者设备没有被用户启用，这种状况下 只发送链路保持指令。

2.2 链路保持[LK]

（1）普通设备：

终端发送:

[HW*YYYYYYYYYY*NNNN*LEN*LK,电量百分比]

实例:[HW*5678901234*0001*0006*LK,100]

（2）支持计步功能的设备

终端发送:

[HW*YYYYYYYYYY*NNNN*LEN*LK,步数,翻滚次数,电量百分比]

实例:[HW*5678901234*0001*000D*LK,50,100,100]

（3）(for customer MSTL only)

终端发送:

[HW*YYYYYYYYYY*NNNN*LEN*LK,电量百分比,设备状态] 状态为00或01

实例:[HW*5678901234*0001*0009*LK,100,00]

平台回复:

[HW*YYYYYYYYYY*NNNN*LEN*LK,YYYY-MM-DD,HH:MM:SS]

实例: [HW*5678901234*0016*LK,2015-08-18,14:30:30]

说明：

  1. 链路保持数据2分钟发一次,若终端未收到回复数据,则2分钟重新连接一次；

  2. 以上几种上报格式，根据终端的配置，会上报其中的一种；

  3. 电量百分比：正常电量范围为0-100；充电时增加0x80标志位，即充电时电量范围为128-228；

  4. 步数：设备当天计步的总步数；

  5. 翻滚次数：设备预留功能，可以不用解析；

  6. 平台回复的时间，为UTC标准时间；

    ​

2.3 获取天气[WT]

终端发送：[HW*YYYYYYYYYY*NNNN*LEN*WT,位置数据(见附录一)]

实例：

[HW*5678901234*0001*009F*WT,260916,020049,V,22.683546,N,113.9907380,E,0.00,0.0,0.0,0,

100,77,0,0,00000000,5,0,460,0,9346,4711,167,9346,4712,126,9360,4151,125,9346,4713,122,9360,4081,119]

平台回复：

[HW*YYYYYYYYYY*NNNN*LEN*WT,年-月-日,时:分:秒,天气描述,天气编号,当前温度,最低温,最高温,城市名]

[HW*5678901234*0001*009F*WT,16-09-24,11:00:00,b6e0d4c6,2,-5,-12,22,316df15733]

注：天气描述用GB2312 编码，城市名使用Unicode 编码

天气编号：0——晴1——阴2——雨3——雪

3.平台发送指令

3.1 IP端口设置[IP]

平台发送:

[HW*YYYYYYYYYY*NNNN*LEN*IP,IP或域名,端口]

实例:[HW*5678901234*0001*0014*IP,113.81.229.9,5900]

终端回复:

该指令终端无回复,直接断开当前连接,连接新服务器.

说明:设置连接平台的IP和端口.

3.2上报间隔设置

平台发送:

[HW*YYYYYYYYYY*NNNN*LEN*UPLOAD,上报间隔(分钟)]

实例:[HW*5678901234*0001*0009*UPLOAD,10]

终端回复:

[HW*YYYYYYYYYY*NNNN*LEN*UPLOAD,接收结果]

实例:[ZJ*5678901234*0001*0008*UPLOAD,1]

3.3 关机[POWEROFF]

平台发送:

[HW*YYYYYYYYYY*NNNN*LEN*POWEROFF]

实例:[HW*5678901234*0001*0008*POWEROFF]

终端回复:

[HW*YYYYYYYYYY*NNNN*LEN*POWEROFF]

实例:[HW*5678901234*0001*0008*POWEROFF]

说明:关机功能.

3.4 重启

平台发送:

[HW*YYYYYYYYYY*NNNN*LEN*RESET]

实例:[HW*5678901234*0001*0005*RESET]

终端回复:

[HW*YYYYYYYYYY*NNNN*LEN*RESET]

实例:[HW*5678901234*0001*0005*\RESET]

说明:设备重启.

3.5 文字推送指令[MESSAGE]

平台发送:

[HW*YYYYYYYYYY*NNNN*LEN*MESSAGE,文字16进制内容]

实例:[HW*5678901234*0001*000B*MESSAGE,hello你好]

终端回复:

[HW*YYYYYYYYYY*NNNN*LEN*MESSAGE]

实例:[HW*5678901234*0001*0007*MESSAGE]

说明:该指令向终端推送显示的短语.短语内容编码为UTF8格式.