监护垫2.0版本 - MQTT接口文档

1. 概述和目标

欢迎查阅监护垫2.0版本的MQTT协议接口文档。我们设计了这个文档，目的是为了帮助开发者更好地理解和实现监护垫2.0版本MQTT接口，实现从MQTT服务器获取和解析监护垫2.0版本设备信息。

2. 协议版本

当前使用的协议版本是2.0.x，遵循x.x.x版本格式。其中，x.x.x 版本格式表示主版本号、次版本号和修订号，分别代表协议的重大变更、功能更新和修复bug。

版本	更新说明	负责人
2.3.0	包含了连接、加密、升级、设备在离床监测、心率呼吸率、体动、体动强度、呼吸弱、呼吸弱检测灵敏度调节范围、离床阈值调节等功能	LanceChan
2.1.0	修复一些bug	LanceChan
2.0.5	修复一些bug	LanceChan
2.0.1	首次发布MQTT版本	LanceChan
1.x.x	基于UDP和HTTP通信	LanceChan
0.x.x	内部研发版本	–

3. 通信架构

在我们的架构中，设备端通过SSL与MQTT服务器建立连接，服务器进一步通过MQTT订阅获取设备信息。

4. 连接参数

服务器地址：mqtts://mqtt.watchmen.hk 端口：8883 证书下载地址：http://server.carbonsens.com:12080/f/certs/ 推荐使用MQTTX软件进行调试，数据接收

5. 消息格式

我们定义了多种类型的消息格式，以适应不同的场景需求。

5.1 设备连接信息

设备连接时，会发布如下格式的信息：类型：设备发布主题: /dev/{devId}/online 通信质量：设备与MQTT服务器QoS1

{
	"devName": "TS-PSMB-2306B",
	"devId": "TSKJA1B9A954",
	"devVersion": "2.0.1",
	"online": true,
	"updateTime": 1665285245,
}
  

字段名	类型	取值	解释
devName	字符串	"TS-PSMB-2306B"等	设备型号
devId	字符串	"TSKJxxxx"等	设备ID
devVersion	字符串	"2.0.1"等	设备软件版本
online	bool	true	设备在线状态
updateTime	整数	Unix 时间戳	数据更新时间

使用场景：发现设备上线

5.2 设备下线信息

设备下线时，会发布如下格式的信息：类型：遗嘱信息主题: /dev/{devId}/online 通信质量：设备与MQTT服务器QoS1

{
    "devId": "TSKJA1B9A954",
    "online": false
}
  

| 字段名 | 类型 | 取值 | 解释 | | — | — | — | — | | devId | 字符串 | "TSKJxxxx"等 | 设备ID | | online | bool | false | 设备离线状态 | —

使用场景：发现设备离线

5.3 设备设置

当需要对设备进行设置，具体协议如下。配置key-value会修改设备内部value数据，配置cmd会执行特殊操作，cmd是非必要填写。类型: 设备订阅主题: /dev/{devId}/config 数据大小：限制不超过384字节

{
    "{key}": {value},
    "cmd": ""
}
  

key表:

key名	取值	解释	必要性
maxupatetime	1-65535(默认30)	最大上报时间，单位秒	非必要
maxleavetime	1-65535(默认60)	离床异常时间，单位秒	非必要
maxbreathrate	1-35(默认30)	呼吸率高阈值，单位次数	非必要
minbreathrate	1-35(默认5)	呼吸率低阈值，单位次数	非必要
maxheartrate	1-135(默认110)	心率高阈值，单位次数	非必要
minheartrate	1-135(默认50)	心率低阈值，单位次数	非必要
rr-count	5-25(默认10)	RR统计数量值（会影响心率计算速率和准确性）	非必要
breathewarn-se	1-100(默认85) 1:最不灵敏 100:最灵敏	se=Sensitivity,呼吸弱检测的灵敏度	非必要
bodymove-se	1-10(默认5) 1:最不灵敏 10:最灵敏	se=Sensitivity,体动识别的灵敏度	非必要
ota-url	-	用于ota升级的镜像文件地址	非必要
mac_temperature	默认无	过滤温度贴产品的mac地址	非必要
humendetect	3-20(默认7) 3:最灵敏 20:最不灵敏	2.2.1新增检测在离床的阈值	非必要

cmd表:

cmd	解释
reboot	重启
ota	ota升级
rconfig	读取配置
wconfig	写入配置
signal	读取曲线

示例一：写配置

发送 /dev/TSKJ12345678/config

{
  "maxupatetime": 30,
  "maxleavetime": 60,
  "maxbreathrate": 30,
  "minbreathrate": 5,
  "maxheartrate": 110,
  "minheartrate": 50,
  "rr-count": 10,
  "breathewarn-se": 5,
  "bodymove-se": 5,
  "cmd":"wconfig"
}
  

回复 /dev/TSKJ12345678/config/response

{
  "devId": "TSKJ12345678",
  "maxupatetime": 30,
  "maxleavetime": 60,
  "maxbreathrate": 30,
  "minbreathrate": 5,
  "maxheartrate": 110,
  "minheartrate": 50,
  "rr-count": 10,
  "breathewarn-se": 5,
  "bodymove-se": 5,
  "cmd": "wconfig",
  "updateTime": "1689748716"
}
  

示例二：读配置

发送 /dev/TSKJ12345678/config

{
  "cmd":"rconfig"
}
  

回复 /dev/TSKJ12345678/config/response

{
  "devId": "TSKJ12345678",
  "maxupatetime": 30,
  "maxleavetime": 60,
  "maxbreathrate": 30,
  "minbreathrate": 5,
  "maxheartrate": 110,
  "minheartrate": 50,
  "rr-count": 10,
  "breathewarn-se": 5,
  "bodymove-se": 5,
  "cmd": "rconfig",
  "updateTime": "1689748842"
}
  

示例三：重启

发送 /dev/TSKJ12345678/config

{
  "cmd":"reboot"
}
  

回复 /dev/TSKJ12345678/config/response

{
  "devId": "TSKJ12345678",
  "updateTime": "1689748882",
  "cmd": "reboot"
}
  

5.4 设备设置响应

类型：设备发布主题: /dev/{devId}/config/response 通信质量：设备与MQTT服务器QoS1

{
    "devId": "TSKJA1B9A954",
    "{key}": {new value},
    "cmd": "Option",
    "updateTime": 1665285245,
}
  

将设备中更新好的设置数据，或者即将响应的命令，发出来回应；

5.5 设备上报状态

类型: 设备发布主题: /dev/{devId}/state 通信质量：设备与MQTT服务器QoS1

{
    "devId": "TSKJA1B9A954",
    "updateTime": 1665285245, //数据更新时间
    "bodymove": false, //体动标志
    "bodymoveStrength": 0.0, //体动强度
    "breathRate": 0, //呼吸率数值
    "heartRate": 0, //心率数值
    "temperature": 0, //温度数值
    "empty": true, //离床标志  true：离床  false：在床
    "leaveTime": 1685770686, //离床时间记录
    "emptyWarn": true, //离床超过设定时间标志
    "heartRateLow": false, //心率过低标志
    "heartRateHigh": false, //心率过高标志
    "breatheRateLow": false, //呼吸率过低标志
    "breatheRateHigh": false, //呼吸率高低标志
    "breatheWarn": false, //呼吸弱标志
}
  

字段名	类型	取值	解释
devId	字符串	"TSKJxxxx"等	设备ID
updateTime	整数	Unix 时间戳	数据更新时间
bodymove	bool	true：体动超设定阈值 false：体动未设定阈值	体动标志
bodymoveStrength	浮点	0.0：无体动强度 0.0~1.0：体动强度值 1.0：检测强度上限	体动强度
breathRate	整数	0：无效值 5~35：有效值	呼吸率数值
heartRate	整数	0：无效值 45~135：有效值	心率数值
temperature	浮点	0：无效值 20.0~40.0：有效值	读取附近温度贴的数值上报
empty	bool	true：离床 false：在床	离床标志
leaveTime	整数	Unix 时间戳	最近一次离床时间记录
emptyWarn	bool	true：离床时间超过设定值 false：离床时间未超过设定值	离床超过设定时间标志
heartRateLow	bool	true：心率低于设定阈值 false：心率未低于设定阈值	心率过低标志
heartRateHigh	bool	true：心率高于设定阈值 false：心率未高于设定阈值	心率过高标志
breatheRateLow	bool	true：呼吸率低于设定阈值 false：呼吸率未低于设定阈值	呼吸率过低标志
breatheRateHigh	bool	true：呼吸率高于设定阈值 false：呼吸率未高于设定阈值	呼吸率过高标志
breatheWarn	bool	true：检测到呼吸弱 false：未检测到呼吸弱	呼吸弱标志

上报频率：除了updateTime，这里有任何一个数值的更新，设备就会上报；如果超过maxupatetime没数据更新，会主动报一次数据。

6. 最佳实践

我们将在后续版本中提供使用示例，以便开发人员可以更好地理解和实施协议。

7. 错误处理

对于可能遇到的错误情况，设备将发布具体的错误代码和错误信息。我们建议在遇到错误时，重新发送请求或联系我们的技术支持。

监护垫2.0版本 - MQTT接口文档

1. 概述和目标

2. 协议版本

3. 通信架构

4. 连接参数

5. 消息格式

5.1 设备连接信息

5.2 设备下线信息

5.3 设备设置

示例一：写配置

示例二：读配置

示例三：重启

5.4 设备设置响应

5.5 设备上报状态

6. 最佳实践

7. 错误处理

8. 附录

8.1 设备规格书

8.2 MQTT协议

8.3 MQTT服务器

8.4 常见问题解答(FAQ)