Rooive MQTT 设备接口 0.2.0 documentation

Rooive MQTT 设备接口 0.2.0

专有许可
application/json

Rooive 底座与项圈 MQTT 接口文档，该MQTT payload仅使用语义化 JSON，不接受 payload_hex、BLE/UART 帧或本地 CRC 字段。

操作方向以IoT后端平台为视角：receive 表示设备到云端，send 表示云端到设备。

Servers

mqtt://{host}:{port}/mqtt 3.1.1development
Rooive MQTT 服务端设备网关

object
string
required
MQTT 网关主机地址

string
required
MQTT 网关端口；TLS 部署使用 8883
Security:
User/Password
用户名和 clientId 均为设备 SN，密码为设备 mqttToken。
object

Operations

RECEIVE pet/v1/{deviceType}/{sn}/up

设备上报，包括底座转发的项圈上报。

Operation IDreceiveReliableReports

Available only on servers:

development

object

string

required

设备中配置的 MQTT 身份类型。

snstring

required

设备序列号，必须与 clientId 和用户名一致。

object

Accepts one of the following messages:

#0状态上报

设备可靠状态上报。

application/json

Message IDstatusReport

Correlation ID$message.payload#/command_id

稳定的业务幂等与命令关联标识。

allOf

Examples

#1 Example - 项圈状态上报

{
  "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",
    "pending_count": 0,
    "timestamp_s": 1783050000
  }
}

#1可靠定位上报

application/json

Message IDreliableLocationReport

Correlation ID$message.payload#/command_id

稳定的业务幂等与命令关联标识。

allOf

Examples

#1 Example - 底座转发定位

{
  "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
  }
}

#2行为上报

可靠上报活动、睡眠、步态和吠叫窗口统计数据。

application/json

Message IDbehaviorReport

Correlation ID$message.payload#/command_id

稳定的业务幂等与命令关联标识。

allOf

Examples

{
  "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": {
    "activity_state": 0,
    "gait": 0,
    "active_seconds": 0,
    "rest_seconds": 0,
    "sleep_seconds": 0,
    "sample_count": 0,
    "bark_confidence": 0,
    "bark_count": 0,
    "bark_duration_100ms": 0
  }
}

This example has been generated automatically.

#3故障上报

application/json

Message IDfaultReport

Correlation ID$message.payload#/command_id

稳定的业务幂等与命令关联标识。

allOf

Examples

{
  "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
  }
}

This example has been generated automatically.

RECEIVE pet/v1/{deviceType}/{sn}/up
设备上报，包括底座转发的项圈上报。

Operation IDreceiveLiveLocation
Available only on servers:
- development
object
string
required
设备中配置的 MQTT 身份类型。

snstring
required
设备序列号，必须与 clientId 和用户名一致。

object
Accepts the following message:
实时定位上报
每秒最多上报一条 QoS 0 消息，不写入设备闪存。
application/json
Message IDliveLocationReport
allOf
Examples
#1 Example - GNSS 搜索中
{ "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 } }

SEND pet/v1/{deviceType}/{sn}/down

云端下发给设备的控制、配置和文件任务元数据。

Operation IDsendCommands

Available only on servers:

development

object

string

required

设备中配置的 MQTT 身份类型。

snstring

required

设备序列号，必须与 clientId 和用户名一致。

object

Accepts one of the following messages:

#0时间同步

application/json

Message IDtimeSync

Correlation ID$message.payload#/command_id

稳定的业务幂等与命令关联标识。

allOf

Examples

{
  "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
  }
}

This example has been generated automatically.

#1设置走失模式

application/json

Message IDlostModeSet

Correlation ID$message.payload#/command_id

稳定的业务幂等与命令关联标识。

allOf

Examples

#1 Example - 启用走失模式

{
  "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": 30
  }
}

#2请求定位

application/json

Message IDlocationRequest

Correlation ID$message.payload#/command_id

稳定的业务幂等与命令关联标识。

allOf

Examples

{
  "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"
  }
}

This example has been generated automatically.

#3设置项圈灯光

application/json

Message IDlightSet

Correlation ID$message.payload#/command_id

稳定的业务幂等与命令关联标识。

allOf

Examples

{
  "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
  }
}

This example has been generated automatically.

#4播放已有音频资源

application/json

Message IDaudioPlay

Correlation ID$message.payload#/command_id

稳定的业务幂等与命令关联标识。

allOf

Examples

{
  "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": "audio_play",
  "payload": {
    "resource_id": 0,
    "duration_s": 0
  }
}

This example has been generated automatically.

#5配置家庭 AP 在家检测

application/json

Message IDhomePresenceConfig

Correlation ID$message.payload#/command_id

稳定的业务幂等与命令关联标识。

allOf

Examples

{
  "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"
    ]
  }
}

This example has been generated automatically.

#6启动蜂窝网络 DFOTA 任务

MQTT 仅传输任务元数据，固件通过 HTTPS 下载。

application/json

Message IDdfotaStart

Correlation ID$message.payload#/command_id

稳定的业务幂等与命令关联标识。

allOf

Examples

{
  "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"
  }
}

This example has been generated automatically.

#7请求设备日志

MQTT 仅传输查询元数据，日志文件通过 HTTP/HTTPS 文件路径传输。

application/json

Message IDlogQuery

Correlation ID$message.payload#/command_id

稳定的业务幂等与命令关联标识。

allOf

Examples

{
  "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
  }
}

This example has been generated automatically.

#8下发音频资源任务

MQTT 仅传输任务元数据，底座通过 HTTPS 下载并经 Pogo UART 写入。

application/json

Message IDaudioResourceTask

Correlation ID$message.payload#/command_id

稳定的业务幂等与命令关联标识。

allOf

Examples

{
  "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": "audio_resource_task",
  "payload": {
    "resource_id": 0,
    "action": "string",
    "url": "string",
    "size": 0,
    "crc32": "string",
    "codec": "string"
  }
}

This example has been generated automatically.

RECEIVE pet/v1/{deviceType}/{sn}/ack/up
Operation IDreceiveDeviceAcknowledgements
Available only on servers:
- development
object
string
required
设备中配置的 MQTT 身份类型。

snstring
required
设备序列号，必须与 clientId 和用户名一致。

object
Accepts the following message:
设备交付确认
阶段 1 为中间状态；阶段 2 完成云端功能调用。
application/json
Message IDdeviceDeliveryAck
Correlation ID$message.payload#/command_id
稳定的业务幂等与命令关联标识。

allOf
Examples
#1 Example - 执行完成
{ "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 }
SEND pet/v1/{deviceType}/{sn}/ack/down
Operation IDsendCloudAcknowledgements
Available only on servers:
- development
object
string
required
设备中配置的 MQTT 身份类型。

snstring
required
设备序列号，必须与 clientId 和用户名一致。

object
Accepts the following message:
云端交付确认
阶段 3 表示允许设备删除对应的可靠记录。
application/json
Message IDcloudDeliveryAck
Correlation ID$message.payload#/command_id
稳定的业务幂等与命令关联标识。

allOf
Examples
#1 Example - 持久化完成
{ "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 }

RECEIVE pet/v1/{deviceType}/{sn}/shadow/update

Operation IDreceiveShadowUpdate

Available only on servers:

development

object

string

required

设备中配置的 MQTT 身份类型。

snstring

required

设备序列号，必须与 clientId 和用户名一致。

object

Accepts the following message:

上报设备影子状态

application/json

Message IDshadowUpdate

allOf

Examples

{
  "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
      }
    }
  }
}

This example has been generated automatically.

RECEIVE pet/v1/{deviceType}/{sn}/shadow/get
Operation IDreceiveShadowGet
Available only on servers:
- development
object
string
required
设备中配置的 MQTT 身份类型。

snstring
required
设备序列号，必须与 clientId 和用户名一致。

object
Accepts the following message:
请求期望影子状态
application/json
Message IDshadowGet
allOf
Examples
{ "ver": 1, "msg_id": "string", "ts": 0, "src": "base", "dst": "cloud" }

This example has been generated automatically.

SEND pet/v1/{deviceType}/{sn}/shadow/get/accepted

Operation IDsendShadowDesired

Available only on servers:

development

object

string

required

设备中配置的 MQTT 身份类型。

snstring

required

设备序列号，必须与 clientId 和用户名一致。

object

Accepts the following message:

返回期望影子状态

application/json

Message IDshadowDesired

allOf

Examples

{
  "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
      }
    }
  }
}

This example has been generated automatically.

Messages

#1状态上报
设备可靠状态上报。
- application/json
Message IDstatusReport
Correlation ID$message.payload#/command_id
稳定的业务幂等与命令关联标识。

allOf
#2可靠定位上报
- application/json
Message IDreliableLocationReport
Correlation ID$message.payload#/command_id
稳定的业务幂等与命令关联标识。

allOf
#3实时定位上报
每秒最多上报一条 QoS 0 消息，不写入设备闪存。
- application/json
Message IDliveLocationReport
allOf
#4行为上报
可靠上报活动、睡眠、步态和吠叫窗口统计数据。
- application/json
Message IDbehaviorReport
Correlation ID$message.payload#/command_id
稳定的业务幂等与命令关联标识。

allOf
#5故障上报
- application/json
Message IDfaultReport
Correlation ID$message.payload#/command_id
稳定的业务幂等与命令关联标识。

allOf
#6时间同步
- application/json
Message IDtimeSync
Correlation ID$message.payload#/command_id
稳定的业务幂等与命令关联标识。

allOf
#7设置走失模式
- application/json
Message IDlostModeSet
Correlation ID$message.payload#/command_id
稳定的业务幂等与命令关联标识。

allOf
#8请求定位
- application/json
Message IDlocationRequest
Correlation ID$message.payload#/command_id
稳定的业务幂等与命令关联标识。

allOf
#9设置项圈灯光
- application/json
Message IDlightSet
Correlation ID$message.payload#/command_id
稳定的业务幂等与命令关联标识。

allOf
#10播放已有音频资源
- application/json
Message IDaudioPlay
Correlation ID$message.payload#/command_id
稳定的业务幂等与命令关联标识。

allOf
#11配置家庭 AP 在家检测
- application/json
Message IDhomePresenceConfig
Correlation ID$message.payload#/command_id
稳定的业务幂等与命令关联标识。

allOf
#12启动蜂窝网络 DFOTA 任务
MQTT 仅传输任务元数据，固件通过 HTTPS 下载。
- application/json
Message IDdfotaStart
Correlation ID$message.payload#/command_id
稳定的业务幂等与命令关联标识。

allOf
#13请求设备日志
MQTT 仅传输查询元数据，日志文件通过 HTTP/HTTPS 文件路径传输。
- application/json
Message IDlogQuery
Correlation ID$message.payload#/command_id
稳定的业务幂等与命令关联标识。

allOf
#14下发音频资源任务
MQTT 仅传输任务元数据，底座通过 HTTPS 下载并经 Pogo UART 写入。
- application/json
Message IDaudioResourceTask
Correlation ID$message.payload#/command_id
稳定的业务幂等与命令关联标识。

allOf
#15设备交付确认
阶段 1 为中间状态；阶段 2 完成云端功能调用。
- application/json
Message IDdeviceDeliveryAck
Correlation ID$message.payload#/command_id
稳定的业务幂等与命令关联标识。

allOf
#16云端交付确认
阶段 3 表示允许设备删除对应的可靠记录。
- application/json
Message IDcloudDeliveryAck
Correlation ID$message.payload#/command_id
稳定的业务幂等与命令关联标识。

allOf
#17上报设备影子状态
- application/json
Message IDshadowUpdate
allOf
#18请求期望影子状态
- application/json
Message IDshadowGet
allOf
#19返回期望影子状态
- application/json
Message IDshadowDesired
allOf

Schemas

object
string
使用 16 位十六进制字符表示的稳定 u64 业务 ID。
object
allOf
allOf
allOf
object
allOf
allOf
object
allOf
object
窗口统计数据，并非原始 IMU 数据。
allOf
object
allOf
allOf
allOf
allOf
allOf
allOf
allOf
allOf
allOf
allOf
allOf
allOf
allOf
allOf
allOf
object
object

Rooive MQTT 设备接口 0.2.0

Servers

Security:

Operations

RECEIVE pet/v1/{deviceType}/{sn}/up

Examples

#1 Example - 项圈状态上报

Examples

#1 Example - 底座转发定位

Examples

This example has been generated automatically.

Examples

This example has been generated automatically.

RECEIVE pet/v1/{deviceType}/{sn}/up

Examples

#1 Example - GNSS 搜索中

SEND pet/v1/{deviceType}/{sn}/down

Examples

This example has been generated automatically.

Examples

#1 Example - 启用走失模式

Examples

This example has been generated automatically.

Examples

This example has been generated automatically.

Examples

This example has been generated automatically.

Examples

This example has been generated automatically.

Examples

This example has been generated automatically.

Examples

This example has been generated automatically.

Examples

This example has been generated automatically.

RECEIVE pet/v1/{deviceType}/{sn}/ack/up

Examples

#1 Example - 执行完成

SEND pet/v1/{deviceType}/{sn}/ack/down

Examples

#1 Example - 持久化完成

RECEIVE pet/v1/{deviceType}/{sn}/shadow/update

Examples

This example has been generated automatically.

RECEIVE pet/v1/{deviceType}/{sn}/shadow/get

Examples

This example has been generated automatically.

SEND pet/v1/{deviceType}/{sn}/shadow/get/accepted

Examples

This example has been generated automatically.

Messages

Schemas