TS-PSMB-4088 可配置项接口文档

1. 概述和目标

本文档详细说明产品TS-PSMB-4088，基于Blufi进行通信之上，可以配置的项目接口，帮助开发者理解和实现设备配置功能。

2. 格式

数据交换使用Json格式，且每个数据包必须包含一个名为"cmd"的字段，用于指定命令类型。

{
  "cmd": "命令",
  "参数字段": "参数值"
}
  

3. 配置项参数表

3.1 命令列表

命令	说明
reboot	重启设备
ota	执行OTA升级
rconfig	读取配置
wconfig	写入配置
resetr0	矫正指令
nettest	网络测试指令
mqtttest	MQTT服务器测试指令

3.2 基础字符串配置项

配置项	默认值	说明	备注
devName	TS-PSMB-4088	设备型号	读写值
devId	TSKJ00000000	设备ID	读值
devSN	0000	设备序列号	读值
devVersion	0.0.0	设备版本号	读值
devIdPrefix	TSKJ	设备ID前缀	读写值
devSNPrefix	TS	设备序列号前缀	读写值
SSID	Carbonsens	WiFi SSID	读写值
PSW	sensor2020	WiFi 密码	读写值
mqttURL	mqtt://server.carbonsens.com	MQTT服务器地址	读写值
mqttBackupURL	mqtt://10.10.0.5	MQTT备用服务器地址	读写值
mqttUser	-	MQTT用户名	读写值
mqttPSW	-	MQTT密码	读写值
mqttBackupUser	-	MQTT备用服务器用户名	读写值
mqttBackupPSW	-	MQTT备用服务器密码	读写值
mqtts_cert	MQTT服务器证书	v3.1.0支持用于TLS加密连接
macTemperature	-	温度传感器MAC地址	读写值

3.3 基础数值配置项

配置项	取值范围	默认值	说明
maxupdatetime	1-65535	30	最大上报时间，单位秒
maxleavetime	1-65535	60	离床异常时间，单位秒
maxbreathrate	1-35	30	呼吸率高阈值，单位次数
minbreathrate	1-35	5	呼吸率低阈值，单位次数
maxheartrate	1-135	110	心率高阈值，单位次数
minheartrate	1-135	50	心率低阈值，单位次数
breathewarn-se	1-100	85	呼吸弱检测的灵敏度（1最不灵敏，100最灵敏）
bodymove-se	1-10	5	体动识别的灵敏度（1最不灵敏，10最灵敏）
humendetect	3-20	7	检测在离床的阈值（3最灵敏，20最不灵敏）
sendonlyalert	0-1	0	仅发送警报数据（0关闭，1开启）

3.4 特殊配置项

配置项	说明	备注
ota-url	用于ota升级的镜像文件地址
extradata	wconfig中携带文本功能	v3.0.4支持

4. 配置项详细说明

4.1 命令详解

reboot

重启设备命令，设备收到命令进行会回复同样命令，然后在5秒后执行重启。

例子：发送

{
  "cmd": "reboot"
}
  

设备回复

{
  "devId": "TSKJ00000000",
  "cmd": "reboot",
  "updateTime": 1729814400
}
  

ota

OTA升级命令，需要配合 ota-url 参数使用。OTA支持http/https协议。https会稍微慢一些。再回复第一个json数据包后，设备会持续回复OTA进度，如果OTA成功，设备会执行重启。如果失败会回复ERROR。

{
  "cmd": "ota",
  "ota-url": "https://example.com/firmware.bin"
}
  

设备回复

{
  "devId": "TSKJ00000000",
  "cmd": "ota",
  "ota-url": "https://example.com/firmware.bin",
  "updateTime": 1729814400,
  "updateTimeStr": "2024-10-25 08:00:00"
}
  

{
  "devId": "TSKJ00000000",
  "updateTime": 1729814400,
  "status": "5%",
  "updateTimeStr": "2024-10-25 08:00:00"
}
  

{
  "status": "Error"
}
  

rconfig

读取配置命令，可获取配置项中的值。这个命令支持全部读取和指定读取。

全部读取

{
  "cmd": "rconfig"
}
  

{
  "maxupdatetime": 60,
  "maxleavetime": 60,
  "maxbreathrate": 31,
  "minbreathrate": 5,
  "maxheartrate": 110,
  "minheartrate": 50,
  "breathewarn-se": 85,
  "bodymove-se": 5,
  "humendetect": 7,
  "sendonlyalert": 0,
  "devName": "TS-PSMB-4088",
  "devId": "TSKJ000000",
  "devSN": "TS0000",
  "devVersion": "3.0.0",
  "devIdPrefix": "TSKJ",
  "devSNPrefix": "",
  "SSID": "",
  "PSW": "",
  "mqttURL": "mqtt://server.carbonsens.com",
  "mqttBackupURL": "mqtt://10.10.0.5",
  "mqttUser": "",
  "mqttPSW": "",
  "macTemperature": "",
  "cmd": "rconfig",
  "updateTime": "1729814400"
}
  

指定读取

{
  "cmd": "rconfig",
  "maxupdatetime": "",
  "maxleavetime": ""
}
  

{
  "devId": "TSKJ00000000",
  "cmd": "rconfig",
  "maxupdatetime": 60,
  "maxleavetime": 60,
  "updateTime": 1729814400
}
  

wconfig

写入配置命令，用于更新一个或多个配置项的值。回复中会处理可配置字段，如果回复中会回传设置值的"新值"，如果回复中没有回传字段，证明字段名称写错了，或者值错误。

{
  "cmd": "wconfig",
  "maxupdatetime": 60,
  "maxleavetime": 60
}
  

成功回复：

{
  "devId": "TSKJ00000000",
  "cmd": "wconfig",
  "status": "success",
  "maxupdatetime": 60,
  "maxleavetime": 60,
  "updateTime": 1729814400
}
  

失败回复(maxupdatetime成功，maxleavetime失败)：

{
  "devId": "TSKJ00000000",
  "cmd": "wconfig",
  "status": "error",
  "updateTime": 1729814400,
  "maxupdatetime": 60
}
  

extradata 参数（v3.0.4支持）

{
"cmd": "wconfig",
"extradata": "你想携带的文本"
}
  

回复：

{
"devId": "TSKJ00000000",
"cmd": "wconfig",
"status": "success",
"extradata": "你想携带的文本",
"updateTime": 1729814400
}
  

resetr0

矫正指令，用于设备校准。产品在不同厚度、不同弯曲度等情况下，由于物理特性原因参考值会不同。在正常使用产品时，产品会自动校准，通常是静止5分钟就会校准。如果长途运输、掉电时间过长，通常建议要静止5分钟以上再使用。如果人为能确保静止，也可以立即使用命令进行校准。

发送

{
  "cmd": "resetr0"
}
  

设备回复

{
  "devId": "TSKJ00000000",
  "cmd": "resetr0",
  "updateTime": 1729814400
}
  

nettest

网络测试指令，用于测试设备网络连接状态。该命令会执行一系列网络测试，包括WiFi信号强度测试和目标服务器的连通性测试。

指令格式：

{
  "cmd": "nettest",
  "items": ["wifi", "ping"],  // 可选项：测试项目列表，可选wifi和ping，或者不带items表示全部测试
  "ping": {
    "hosts": ["8.8.8.8", "server.carbonsens.com"],  // 可选项：ping测试的目标主机列表，最多支持5个主机
    "count": 4  // 可选项：每个主机的ping次数，默认为4次，范围1-10
  }
}
  

指令实现逻辑：

设备收到nettest命令后，先检查是否已经在执行测试
解析测试配置，包括测试项目和参数
保存配置并记录命令来源（蓝牙或MQTT）
创建一个单独的任务执行网络测试
测试任务会根据配置执行选择的测试项目：
- WiFi测试：检查当前连接的WiFi信号强度、信道等
- Ping测试：ping指定的主机，计算成功率和延迟时间
测试完成后，将结果通过相应通道返回给客户端
清理资源并重置测试标志

使用示例：

示例1：仅测试WiFi

{
  "cmd": "nettest",
  "items": ["wifi"]
}
  

设备回复（两次回复）

第一次回复（立即回复，确认接收命令）：

{
  "devId": "TSKJ00000000",
  "updateTime": 1729814400,
  "updateTimeStr": "2024-10-25 08:00:00",
  "cmd": "nettest",
  "status": "success",
  "message": "Network test scheduled"
}
  

第二次回复（测试完成后回复，包含测试结果）：

{
  "cmd": "nettest",
  "status": "success",
  "results": {
    "wifi": {
      "status": "connected",
      "ssid": "Carbonsens",
      "bssid": "AA:BB:CC:DD:EE:FF",
      "signal_strength": "-65dBm",
      "rssi": -65,
      "quality": 70,
      "quality_desc": "good",
      "channel": 6,
      "ip": "192.168.1.100",
      "gateway": "192.168.1.1"
    }
  },
  "devId": "TSKJ00000000",
  "updateTime": 1729814405,
  "updateTimeStr": "2024-10-25 08:00:05"
}
  

示例2a：仅测试Ping（不指定Ping参数，使用默认值）

{
  "cmd": "nettest",
  "items": ["ping"]
}
  

设备回复（两次回复）

第一次回复（立即回复，确认接收命令）：

{
  "devId": "TSKJ00000000",
  "updateTime": 1729814400,
  "updateTimeStr": "2024-10-25 08:00:00",
  "cmd": "nettest",
  "status": "success",
  "message": "Network test scheduled"
}
  

第二次回复（使用默认的ping目标主机和次数）：

{
  "cmd": "nettest",
  "status": "success",
  "results": {
    "ping_results": [
      {
        "host": "8.8.8.8", // 默认使用Google DNS服务器作为ping目标
        "ip": "8.8.8.8",
        "result": "success",
        "latency": "22.4 ms",
        "sent": 4, // 默认发送4个ping包
        "received": 4,
        "min_ms": "18.2",
        "max_ms": "30.5",
        "avg_ms": "22.4",
        "loss_percent": "0.0%",
        "loss_value": 0
      }
    ]
  },
  "devId": "TSKJ00000000",
  "updateTime": 1729814406,
  "updateTimeStr": "2024-10-25 08:00:06"
}
  

示例2b：仅测试Ping（指定Ping参数）

{
  "cmd": "nettest",
  "items": ["ping"],
  "ping": {
    "hosts": ["8.8.8.8"], // 可指定最多5个目标主机
    "count": 3 // 自定义ping次数，范围1-10
  }
}
  

设备回复（两次回复）

第一次回复（立即回复，确认接收命令）：

{
  "devId": "TSKJ00000000",
  "updateTime": 1729814400,
  "updateTimeStr": "2024-10-25 08:00:00",
  "cmd": "nettest",
  "status": "success",
  "message": "Network test scheduled"
}
  

第二次回复（使用自定义配置）：

{
  "cmd": "nettest",
  "status": "success",
  "results": {
    "ping_results": [
      {
        "host": "8.8.8.8",
        "ip": "8.8.8.8",
        "result": "success",
        "latency": "18.9 ms",
        "sent": 3, // 按照自定义配置发送3个ping包
        "received": 3,
        "min_ms": "15.6",
        "max_ms": "28.4",
        "avg_ms": "18.9",
        "loss_percent": "0.0%",
        "loss_value": 0
      }
    ]
  },
  "devId": "TSKJ00000000",
  "updateTime": 1729814405,
  "updateTimeStr": "2024-10-25 08:00:05"
}
  

示例3：测试WiFi和多个Ping目标

{
  "cmd": "nettest",
  "items": ["wifi", "ping"],
  "ping": {
    "hosts": ["8.8.8.8", "server.carbonsens.com"],
    "count": 4
  }
}
  

设备回复（两次回复）

第一次回复（立即回复，确认接收命令）：

{
  "devId": "TSKJ00000000",
  "updateTime": 1729814400,
  "updateTimeStr": "2024-10-25 08:00:00",
  "cmd": "nettest",
  "status": "success",
  "message": "Network test scheduled"
}
  

第二次回复（测试完成后回复，包含测试结果）：

{
  "cmd": "nettest",
  "status": "success",
  "results": {
    "wifi": {
      "status": "connected",
      "ssid": "Carbonsens",
      "bssid": "AA:BB:CC:DD:EE:FF",
      "signal_strength": "-65dBm",
      "rssi": -65,
      "quality": 70,
      "quality_desc": "good",
      "channel": 6,
      "ip": "192.168.1.100",
      "gateway": "192.168.1.1"
    },
    "ping_results": [
      {
        "host": "8.8.8.8",
        "ip": "8.8.8.8",
        "result": "success",
        "latency": "18.9 ms",
        "sent": 4,
        "received": 4,
        "min_ms": "15.6",
        "max_ms": "28.4",
        "avg_ms": "18.9",
        "loss_percent": "0.0%",
        "loss_value": 0
      },
      {
        "host": "server.carbonsens.com",
        "ip": "203.107.45.132",
        "result": "success",
        "latency": "95.6 ms",
        "sent": 4,
        "received": 3,
        "min_ms": "85.3",
        "max_ms": "125.7",
        "avg_ms": "95.6",
        "loss_percent": "25.0%",
        "loss_value": 0.25
      }
    ]
  },
  "devId": "TSKJ00000000",
  "updateTime": 1729814408,
  "updateTimeStr": "2024-10-25 08:00:08"
}
  

示例4：执行所有测试（不指定items）

{
  "cmd": "nettest"
}
  

设备回复（两次回复）

第一次回复（立即回复，确认接收命令）：

{
  "devId": "TSKJ00000000",
  "updateTime": 1729814400,
  "updateTimeStr": "2024-10-25 08:00:00",
  "cmd": "nettest",
  "status": "success",
  "message": "Network test scheduled"
}
  

第二次回复（测试完成后回复，包含测试结果）：

{
  "cmd": "nettest",
  "status": "success",
  "results": {
    "wifi": {
      "status": "connected",
      "ssid": "Carbonsens",
      "bssid": "AA:BB:CC:DD:EE:FF",
      "signal_strength": "-58dBm",
      "rssi": -58,
      "quality": 84,
      "quality_desc": "good",
      "channel": 11,
      "ip": "192.168.1.100",
      "gateway": "192.168.1.1"
    },
    "ping_results": [
      {
        "host": "8.8.8.8",
        "ip": "8.8.8.8",
        "result": "success",
        "latency": "29.4 ms",
        "sent": 4,
        "received": 4,
        "min_ms": "25.3",
        "max_ms": "35.8",
        "avg_ms": "29.4",
        "loss_percent": "0.0%",
        "loss_value": 0
      }
    ]
  },
  "devId": "TSKJ00000000",
  "updateTime": 1729814407,
  "updateTimeStr": "2024-10-25 08:00:07"
}
  

mqtttest

MQTT服务器测试指令，用于测试与MQTT服务器的连接状态。此命令会测试设备与当前连接的MQTT服务器之间的通信质量，包括丢包率和延迟。

指令格式：

{
  "cmd": "mqtttest"
}
  

指令实现逻辑：

设备收到mqtttest命令后，检查是否已经在执行测试
记录命令来源（蓝牙或MQTT），以便测试完成后通过相同通道返回结果
在MQTT主任务循环中检测到测试请求时：
- 检查MQTT连接状态，未连接则返回错误
- 创建测试结果对象
- 执行MQTT测试，使用固定的测试参数：
  - 发送10个测试消息到特定主题（TOPIC_TEST格式：/dev/{设备ID}/test/{序号}）
  - 发送间隔为1秒
  - 每个消息包含时间戳及序列号
  - 计算消息往返时间作为延迟
  - 统计发送和接收的消息数量，计算丢包率
- 格式化结果并通过指定通道发送回客户端
测试完成后重置mqtttest标志

使用示例：

{
  "cmd": "mqtttest"
}
  

设备回复（两次回复）

第一次回复（立即回复，确认接收命令）：

{
  "devId": "TSKJ00000000",
  "updateTime": 1729814400,
  "updateTimeStr": "2024-10-25 08:00:00",
  "cmd": "mqtttest",
  "status": "success",
  "message": "MQTT test scheduled"
}
  

第二次回复（测试完成后回复，包含测试结果）：

{
  "cmd": "mqtttest",
  "status": "success",
  "result": {
    "server": "mqtt://server.carbonsens.com",
    "status": "success",
    "packets_sent": 10,
    "packets_received": 10,
    "packet_loss": "0.0%",
    "min_latency": "45.2 ms",
    "max_latency": "78.6 ms",
    "avg_latency": "58.3 ms",
    "timeouts": 0
  },
  "devId": "TSKJ00000000",
  "updateTime": 1729814415,
  "updateTimeStr": "2024-10-25 08:00:15"
}
  

错误情况回复（MQTT服务器未连接）:

{
  "cmd": "mqtttest",
  "status": "error",
  "error": "MQTT not connected",
  "devId": "TSKJ00000000",
  "updateTime": 1729814405,
  "updateTimeStr": "2024-10-25 08:00:05"
}
  

4.2 基础字符串配置项详解

devName

设备型号标识，可读写，适用于二次开发更替为自己识别设备。

devId

设备唯一标识符，只读。限制长度14位。

生成逻辑：

设备ID由前缀和MAC地址的一部分组成，总长度不超过14个字符
前缀从NVS中的"devIdPrefix"键读取，读取失败则设为空字符串
根据前缀长度决定使用多少个MAC地址字节（每个字节产生2个十六进制字符）
如果前缀过长（>=14），则只使用前缀（截断至最大长度）
MAC地址字节从尾部开始选择，确保设备ID唯一性
如果无法获取MAC地址或设置失败，则使用默认设备ID（TSKJ00000000）

devSN

设备序列号，只读。限制长度63位。

生成逻辑：

设备序列号由前缀和MAC地址的后4个字节组成
前缀从NVS中的"devSNPrefix"键读取，读取失败或获取错误时前缀设为空
MAC地址使用后4个字节(字节2-5)，确保序列号唯一性
总长度不超过32个字符，超过则自动截断
如果无法获取MAC地址或设置失败，则使用默认设备序列号（TS0000）

devVersion

设备固件版本号，只读。

devIdPrefix

设备ID前缀，可读写。可以设置该值，重启后，设备会使用该值作为devId的前缀。适用于二次开发定义自己设备设别符。注意devId不超过14位的限制。

devSNPrefix

设备序列号前缀，可读写。可以设置该值，重启后，设备会使用该值作为devSN的前缀。适用于二次开发定义自己设备序列号。注意devSN不超过63位的限制。

SSID

WiFi网络名称，可读写。

设备wifi连接逻辑：优先连接已成功连接的wifi。在一定时间（1分钟）内，如果连接不上上次成功的WiFi，会尝试连接该设置WiFi。通常用于出厂批量烧录设置，也可以交付客户前预先设置。立即设置连接WIFI可以选则使用blufi的方式，会重置已成功连接的wifi。

PSW

WiFi密码，可读写。

mqttURL、mqttBackupURL、mqttUser、mqttPSW、mqttBackupUser、mqttBackupPSW、mqtts_cert

这些配置项与MQTT连接相关，详细信息请参考MQTT连接配置部分。

macTemperature

温度传感器MAC地址，可读写。用于绑定特定的温度传感器。需要对应产品支持。

maxupdatetime

设备通过MQTT发送状态包的最大上报间隔，范围1-65535秒，默认30秒。设备发送状态包的逻辑，只有有数值变化，立刻发送。没有数值变化，则按照该设置的间隔发送。

maxleavetime

离床异常判定时间，范围1-65535秒，默认60秒。设备会检查无用户在床垫上的状态，然后记录下离开那一刻的时间。如果当前时间距离离开时间，超过该设置的时间，则将状态设置为离床异常。意思就是疑似用户离开床位过久，有风险。若设备静止5分钟以上，设备会重置为无人在床状态，不会再发送离床异常状态。

maxbreathrate

设定呼吸率不正常状态的阈值，范围1-35次/分钟，对应设置其min/max值，默认高阈值30，低阈值5。当用户呼吸率不在这两个值之间，则将状态设置为呼吸率过高或呼吸率过低状态（不是呼吸异常）。

minbreathrate

maxheartrate

设定心率不正常状态的阈值，范围1-135次/分钟，对应设置其min/max值，默认高阈值110，低阈值50。当用户心率不在这两个值之间，则将状态设置为心率过高或心率过低状态。

minheartrate

breathewarn-se

呼吸弱检测检测功能的灵敏度配置，范围1-100，默认85。数值越高越灵敏。

呼吸弱检测检测功能是检测用户呼吸变弱是发出标志，这个标志是提示用户可能需要关注，但不代表一定有问题。

bodymove-se

体动检测灵敏度配置，范围1-10，默认5。用于调节体动检测灵敏度。

humendetect

在检测用户躺上去触发在床的灵敏程度，范围3-20，默认7。对于体重较轻的用户，可以考虑将这值降低。

sendonlyalert

仅发送警报数据配置，范围0-1，默认0（关闭）。

实现逻辑：

当设置为0（默认）时，设备会在状态发生任何变化时上报状态数据
当设置为1时，设备仅在以下情况下发送状态数据：
- 状态变化且包含警报信息（如下列异常情况之一）：
  - 离床过久警告（emptyWarn）
  - 呼吸异常警告（breatheWarn）
  - 心率过低警告（heartRateLow）
  - 心率过高警告（heartRateHigh）
  - 呼吸率过低警告（breatheRateLow）
  - 呼吸率过高警告（breatheRateHigh）
- 超过maxupdatetime设定的最大上报时间间隔

这可以大幅减少设备发送的数据量，适用于需要节约流量或仅关注异常情况的场景。

4.3 特殊配置项详解

ota-url

用于ota升级的镜像文件地址，必须是有效的HTTP/HTTPS URL，见ota命令。

extradata

wconfig中携带文本功能，见wconfig命令。

4.4 MQTT连接配置

设备支持多种MQTT连接方式，包括普通连接和TLS加密连接，并支持主备服务器自动切换。本节汇总了所有MQTT连接相关配置项，以便于统一配置。

MQTT服务器配置

配置项	说明	格式	示例
mqttURL	主MQTT服务器地址	支持mqtt://或mqtts://前缀	"mqtt://server.example.com" 或 "mqtts://secure.example.com"
mqttBackupURL	备用MQTT服务器地址	仅支持mqtt://前缀	"mqtt://backup.example.com"
mqttUser	主服务器用户名（可选）	字符串，可缺省	"username"
mqttPSW	主服务器密码（可选）	字符串，可缺省	"password"
mqttBackupUser	备用服务器用户名（可选）	字符串，可缺省	"backup_user"
mqttBackupPSW	备用服务器密码（可选）	字符串，可缺省	"backup_password"
mqtts_cert	TLS服务器证书（可选）	PEM格式，最大2K字节	"—–BEGIN CERTIFICATE—–\n…\n—–END CERTIFICATE—–"

MQTT连接逻辑

设备优先连接主服务器(mqttURL)
如果主服务器连接失败，设备会尝试连接上次连接成功的服务器
如果上次连接的服务器也无法连接，或者累积断开时间超过阈值（约60秒），设备将尝试连接备用服务器(mqttBackupURL)
即使连接到备用服务器，设备也会定期尝试恢复与主服务器的连接
一旦主服务器恢复连接，设备会断开与备用服务器的连接
如果设备在一段稳定连接时间（约60秒）后，会重置累积断开时间计数器，此机制可有效防止网络抖动导致频繁切换服务器

TLS加密连接配置

设备支持TLS加密连接以提高通信安全性。当mqttURL使用mqtts://前缀时，设备会使用TLS加密连接。

服务器证书验证（单向认证）：

设备默认包含了常见CA根证书，可用于验证由知名CA机构签发的服务器证书
如果服务器使用自签名证书或非标准CA签发的证书，需要通过wconfig命令设置证书：

{
  "cmd": "wconfig",
  "mqtts_cert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
}
  

设备回复：

{
  "devId": "TSKJ00000000",
  "cmd": "wconfig",
  "status": "success",
  "mqtts_cert": "stored",
  "updateTime": 1729814400,
  "updateTimeStr": "2024-10-25 08:00:00"
}
  

注意事项：

备用服务器(mqttBackupURL)不支持TLS加密连接
如果证书不存在或加载失败，设备会降级为不安全连接
证书必须为PEM格式，最大支持2K字节
目前仅支持服务器证书验证（单向认证），不支持客户端证书（双向认证）
如需双向认证支持，需在设备生产前告知，或通过售后服务更新设备证书，设备不支持离厂后自行更新客户端证书/密钥（符合设备通信安全认证的生产方式）