Rooive 底座与项圈 MQTT 接口文档, 该MQTT payload仅使用语义化 JSON,不接受 payload_hex、BLE/UART 帧或本地 CRC 字段。
测试环境 Host 为 rooive.weavemeta.cn。本契约仅固定 Host,MQTT 协议与端口、HTTPS 路径以部署配置为准,该 Host 不代表生产环境地址。
操作方向以IoT后端平台为视角:receive 表示设备到云端,send 表示云端到设备。
底座首次归属使用独立 HTTPS 配网会话:出厂固定 bootstrap password 只用于首次激活, 后端激活成功后生成并返回每设备独立 mqttToken,设备后续仅使用该 mqttToken 连接 MQTT。 详见配网流程说明与HTTP OpenAPI。该目标流程当前代码尚未实现, 待后端开发、硬件团队同步及真机联调;本次 MQTT Topic、消息结构和 ACK 语义保持不变。
本地开发 MQTT 网关;量产必须配置 MQTT/TLS、校验服务端证书,不能使用明文 1883。
MQTT 网关主机地址,测试环境为rooive.weavemeta.cn
MQTT 网关端口;非TLS为1883,仅限测试环境使用,TLS使用 8883
用户名和 clientId 均为设备 SN,密码为设备激活后由后端生成的私有 mqttToken,禁止匿名。 出厂固定 bootstrap password 只用于 HTTPS 首次激活,严禁用于 MQTT。配网会话 token 也不得当作 MQTT 密码。MQTT CONNECT 只验证设备身份,不创建或变更账号归属。 固定 password 激活并更新一机一密的目标流程当前代码尚未实现。 HTTP 契约见配网 HTTP API;TLS 部署必须校验云端证书。
设备上报,包括底座转发的项圈上报。
Available only on servers:
设备中配置的 MQTT 身份类型。
设备序列号,必须与 clientId 和用户名一致。
Accepts one of the following messages:
设备可靠状态上报。
稳定的业务幂等与命令关联标识。
{
"ver": 1,
"msg_id": "collar-status-45",
"command_id": "17F3A2C100000001",
"seq": 45,
"sequence": 45,
"ts": 1783050000,
"src": "collar",
"dst": "cloud",
"cmd": "status_report",
"record_type": 1,
"device_id": "00112233445566778899AABBCCDDEEFF",
"ack_required": true,
"payload": {
"mode": "normal",
"battery_state": "normal",
"battery_percent": 80,
"battery_mv": 4050,
"charge_state": "not_charging",
"active_link": "lte",
"home_wifi_present": false,
"base_ble_connected": false,
"pending_count": 0,
"timestamp_s": 1783050000
}
}
{
"ver": 1,
"msg_id": "base-relay-collar-status-46",
"command_id": "17F3A2C100000002",
"seq": 46,
"sequence": 46,
"ts": 1783050005,
"src": "base",
"dst": "cloud",
"cmd": "status_report",
"relay": true,
"collar_sn": "00112233445566778899AABBCCDDEEFF",
"source_link": "base_ble",
"record_type": 1,
"device_id": "00112233445566778899AABBCCDDEEFF",
"ack_required": true,
"payload": {
"active_link": "base_ble",
"home_wifi_present": true,
"base_ble_connected": true,
"timestamp_s": 1783050005
}
}
稳定的业务幂等与命令关联标识。
{
"ver": 1,
"msg_id": "base-relay-45-17F3",
"command_id": "17F3A2C10000000B",
"seq": 45,
"sequence": 45,
"ts": 1783050000,
"src": "base",
"dst": "cloud",
"base_sn": "BSN202607240001",
"collar_sn": "CSN202607240001",
"relay": true,
"source_link": "base_ble",
"cmd": "location_report",
"record_type": 0,
"device_id": "00112233445566778899AABBCCDDEEFF",
"ack_required": true,
"payload": {
"source": "gnss",
"lat_e7": 223456789,
"lon_e7": 1139876543,
"accuracy_m": 12,
"valid": true,
"timestamp_s": 1783050000
}
}
可靠上报活动、睡眠、步态和吠叫窗口统计数据。
稳定的业务幂等与命令关联标识。
信封 ts 是 UTC Unix 秒;报文不携带业务时区,云端按绑定宠物创建时固化的 IANA 时区归属自然日。
行为窗口按信封 UTC ts 定位瞬时;自然日由云端使用绑定宠物的固定 IANA 时区计算。
{
"ver": 1,
"msg_id": "string",
"ts": 0,
"src": "base",
"dst": "cloud",
"relay": true,
"base_sn": "string",
"collar_sn": "string",
"source_link": "base_ble",
"target": "collar",
"command_id": "string",
"seq": 1,
"sequence": 0,
"record_type": 0,
"device_id": "string",
"ack_required": true,
"cmd": "behavior_report",
"payload": {
"step_count": 120,
"walk_seconds": 300,
"run_seconds": 90,
"play_seconds": 60,
"awake_seconds": 600,
"core_sleep_seconds": 1200,
"deep_sleep_seconds": 300,
"activity_intensity": 82,
"heart_rate_bpm": 96,
"resting": true,
"bark_count": 3,
"scratch_count": 2,
"head_shake_count": 1,
"behavior_events": [
{
"event_id": "scratch-20260928-001",
"type": "scratch",
"start_ts": 1790553600,
"end_ts": 1790553608,
"count": 2
}
]
}
}
稳定的业务幂等与命令关联标识。
{
"ver": 1,
"msg_id": "string",
"ts": 0,
"src": "base",
"dst": "cloud",
"relay": true,
"base_sn": "string",
"collar_sn": "string",
"source_link": "base_ble",
"target": "collar",
"command_id": "string",
"seq": 1,
"sequence": 0,
"record_type": 0,
"device_id": "string",
"ack_required": true,
"cmd": "fault_report",
"payload": {
"fault_code": 0,
"module": "string",
"severity": "info",
"recovery": 0,
"count": 0,
"timestamp_ms": 0
}
}
设备上报,包括底座转发的项圈上报。
Available only on servers:
设备中配置的 MQTT 身份类型。
设备序列号,必须与 clientId 和用户名一致。
Accepts the following message:
{
"ver": 1,
"msg_id": "live-loc-42000",
"ts": 0,
"src": "collar",
"dst": "cloud",
"cmd": "location_report",
"ack_required": false,
"online": true,
"location": {
"valid": false,
"state": "searching",
"source": "gnss",
"lat_e7": 0,
"lon_e7": 0,
"accuracy_m": 0,
"utc": 0
}
}
云端下发给设备的控制、配置和文件任务元数据。
Available only on servers:
设备中配置的 MQTT 身份类型。
设备序列号,必须与 clientId 和用户名一致。
Accepts one of the following messages:
稳定的业务幂等与命令关联标识。
{
"ver": 1,
"msg_id": "string",
"ts": 0,
"src": "cloud",
"dst": "base",
"relay": true,
"base_sn": "string",
"collar_sn": "string",
"source_link": "base_ble",
"target": "collar",
"command_id": "string",
"seq": 1,
"ack_required": true,
"cmd": "time_sync",
"payload": {
"op": null,
"utc_s": 0,
"utc_ms": 0,
"tz_offset_min": -840,
"source": null
}
}
稳定的业务幂等与命令关联标识。
{
"ver": 1,
"msg_id": "CLOUD-88",
"command_id": "17F3A2C10000000B",
"seq": 88,
"ts": 1783050001,
"src": "cloud",
"dst": "collar",
"cmd": "lost_mode_set",
"ack_required": true,
"payload": {
"enable": true,
"interval_s": 5
}
}
稳定的业务幂等与命令关联标识。
{
"ver": 1,
"msg_id": "string",
"ts": 0,
"src": "cloud",
"dst": "base",
"relay": true,
"base_sn": "string",
"collar_sn": "string",
"source_link": "base_ble",
"target": "collar",
"command_id": "string",
"seq": 1,
"ack_required": true,
"cmd": "location_request",
"payload": {
"source": "phone"
}
}
稳定的业务幂等与命令关联标识。
{
"ver": 1,
"msg_id": "string",
"ts": 0,
"src": "cloud",
"dst": "base",
"relay": true,
"base_sn": "string",
"collar_sn": "string",
"source_link": "base_ble",
"target": "collar",
"command_id": "string",
"seq": 1,
"ack_required": true,
"cmd": "light_set",
"payload": {
"mode": "off",
"brightness": 0,
"duration_s": 0
}
}
稳定的业务幂等与命令关联标识。
{
"ver": 1,
"msg_id": "cloud-audio-1",
"command_id": "0102030405060708",
"ts": 1780000000,
"src": "cloud",
"dst": "collar",
"cmd": "audio_play",
"ack_required": true,
"payload": {
"resource_id": 1,
"duration_s": 0,
"volume": 2
}
}
稳定的业务幂等与命令关联标识。
{
"ver": 1,
"msg_id": "string",
"ts": 0,
"src": "cloud",
"dst": "base",
"relay": true,
"base_sn": "string",
"collar_sn": "string",
"source_link": "base_ble",
"target": "collar",
"command_id": "string",
"seq": 1,
"ack_required": true,
"cmd": "home_presence_config",
"payload": {
"bssids": [
"string"
]
}
}
MQTT 仅传输任务元数据,固件通过 HTTPS 下载。
稳定的业务幂等与命令关联标识。
{
"ver": 1,
"msg_id": "string",
"ts": 0,
"src": "cloud",
"dst": "base",
"relay": true,
"base_sn": "string",
"collar_sn": "string",
"source_link": "base_ble",
"target": "collar",
"command_id": "string",
"seq": 1,
"ack_required": true,
"cmd": "dfota_start",
"payload": {
"url": "string",
"target_version": "string",
"file_size": 0,
"crc32": "string",
"signature": "string"
}
}
MQTT 仅传输查询元数据,日志文件通过 HTTP/HTTPS 文件路径传输。
稳定的业务幂等与命令关联标识。
{
"ver": 1,
"msg_id": "string",
"ts": 0,
"src": "cloud",
"dst": "base",
"relay": true,
"base_sn": "string",
"collar_sn": "string",
"source_link": "base_ble",
"target": "collar",
"command_id": "string",
"seq": 1,
"ack_required": true,
"cmd": "log_query",
"payload": {
"scope": "string",
"since_ts": 0,
"until_ts": 0
}
}
MQTT 仅传输任务元数据,底座通过 HTTPS 下载并经 Pogo UART 写入。
稳定的业务幂等与命令关联标识。
{
"ver": 1,
"msg_id": "cloud-audio-resource-1",
"command_id": "0102030405060709",
"ts": 1780000000,
"src": "cloud",
"dst": "base",
"cmd": "audio_resource_task",
"ack_required": true,
"payload": {
"resource_id": 1,
"action": "upsert",
"url": "https://api.example.invalid/file/audio.opus?token=short-lived",
"size": 4096,
"crc32": "89ABCDEF",
"codec": "opus"
}
}
Available only on servers:
设备中配置的 MQTT 身份类型。
设备序列号,必须与 clientId 和用户名一致。
Accepts the following message:
阶段 1 为中间状态;阶段 2 完成云端功能调用。
稳定的业务幂等与命令关联标识。
{
"ver": 1,
"cmd": "delivery_ack",
"msg_id": "collar-ack-88",
"ack_for": "CLOUD-88",
"command_id": "17F3A2C10000000B",
"seq": 88,
"ts": 1783050002,
"src": "collar",
"dst": "cloud",
"status": "EXECUTED",
"code": 0,
"stage": 2
}
Available only on servers:
设备中配置的 MQTT 身份类型。
设备序列号,必须与 clientId 和用户名一致。
Accepts the following message:
阶段 3 表示允许设备删除对应的可靠记录。
稳定的业务幂等与命令关联标识。
{
"ver": 1,
"cmd": "delivery_ack",
"msg_id": "CLOUD-ACK-1",
"ack_for": "collar-45-17F3",
"command_id": "17F3A2C10000000B",
"seq": 45,
"ts": 1783050002,
"src": "cloud",
"dst": "collar",
"status": "COMMITTED",
"code": 0,
"stage": 3,
"commit_ts_s": 1783050002
}
Available only on servers:
设备中配置的 MQTT 身份类型。
设备序列号,必须与 clientId 和用户名一致。
Accepts the following message:
{
"ver": 1,
"msg_id": "string",
"ts": 0,
"src": "base",
"dst": "cloud",
"type": "shadow_update",
"state": {
"reported": {
"base_sn": "string",
"collar_sn": "string",
"online": true,
"active_link": "none",
"battery_percent": 0,
"mode": "string",
"firmware_version": "string",
"applied_desired_version": 0,
"desired_apply_status": "string",
"desired_apply_error": 0,
"report_interval_s": 0,
"lost_mode": true,
"lost_interval_s": 0,
"location": {
"source": "none",
"lat_e7": -900000000,
"lon_e7": -1800000000,
"accuracy_m": 0,
"timestamp_s": 0,
"valid": true,
"utc": 0,
"state": null
}
}
}
}
Available only on servers:
设备中配置的 MQTT 身份类型。
设备序列号,必须与 clientId 和用户名一致。
Accepts the following message:
{
"ver": 1,
"msg_id": "string",
"ts": 0,
"src": "base",
"dst": "cloud"
}
Available only on servers:
设备中配置的 MQTT 身份类型。
设备序列号,必须与 clientId 和用户名一致。
Accepts the following message:
{
"ver": 1,
"msg_id": "string",
"ts": 0,
"src": "cloud",
"dst": "base",
"relay": true,
"base_sn": "string",
"collar_sn": "string",
"source_link": "base_ble",
"target": "collar",
"type": "shadow_desired",
"state": {
"desired": {
"version": 1,
"base_sn": "string",
"report_interval_s": 0,
"desired_link": "string",
"lost_mode": {
"enabled": true,
"interval_s": 5
}
}
}
}
设备可靠状态上报。
稳定的业务幂等与命令关联标识。
稳定的业务幂等与命令关联标识。
可靠上报活动、睡眠、步态和吠叫窗口统计数据。
稳定的业务幂等与命令关联标识。
信封 ts 是 UTC Unix 秒;报文不携带业务时区,云端按绑定宠物创建时固化的 IANA 时区归属自然日。
行为窗口按信封 UTC ts 定位瞬时;自然日由云端使用绑定宠物的固定 IANA 时区计算。
稳定的业务幂等与命令关联标识。
稳定的业务幂等与命令关联标识。
稳定的业务幂等与命令关联标识。
稳定的业务幂等与命令关联标识。
稳定的业务幂等与命令关联标识。
稳定的业务幂等与命令关联标识。
稳定的业务幂等与命令关联标识。
MQTT 仅传输任务元数据,固件通过 HTTPS 下载。
稳定的业务幂等与命令关联标识。
MQTT 仅传输查询元数据,日志文件通过 HTTP/HTTPS 文件路径传输。
稳定的业务幂等与命令关联标识。
MQTT 仅传输任务元数据,底座通过 HTTPS 下载并经 Pogo UART 写入。
稳定的业务幂等与命令关联标识。
阶段 1 为中间状态;阶段 2 完成云端功能调用。
稳定的业务幂等与命令关联标识。
阶段 3 表示允许设备删除对应的可靠记录。
稳定的业务幂等与命令关联标识。
使用 16 位十六进制字符表示的稳定 u64 业务 ID。
行为窗口按信封 UTC ts 定位瞬时;自然日由云端使用绑定宠物的固定 IANA 时区计算。
窗口增量统计,并非原始 IMU 数据。扩展健康字段为乙方预设契约,硬件尚待对齐; 时长单位均为秒,计数字段均为非负整数。
可在宠物日常中直接使用的稳定行为事件。event_id 在同一设备内必须稳定唯一,重传不得换号; start_ts/end_ts 均为 UTC Unix 秒。