Rooive MQTT 设备接口 0.2.2

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 语义保持不变。

Servers

  • mqtt://{host}:{port}/mqtt 3.1.1development

    本地开发 MQTT 网关;量产必须配置 MQTT/TLS、校验服务端证书,不能使用明文 1883。

    object
    string
    required

    MQTT 网关主机地址,测试环境为rooive.weavemeta.cn

    string
    required

    MQTT 网关端口;非TLS为1883,仅限测试环境使用,TLS使用 8883

    Security:
    • User/Password

      用户名和 clientId 均为设备 SN,密码为设备激活后由后端生成的私有 mqttToken,禁止匿名。 出厂固定 bootstrap password 只用于 HTTPS 首次激活,严禁用于 MQTT。配网会话 token 也不得当作 MQTT 密码。MQTT CONNECT 只验证设备身份,不创建或变更账号归属。 固定 password 激活并更新一机一密的目标流程当前代码尚未实现。 HTTP 契约见配网 HTTP API;TLS 部署必须校验云端证书。

    object

Operations

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

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

    Operation IDreceiveReliableReports

    Available only on servers:

    object
    string
    required

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

    snstring
    required

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

    object

    Accepts one of the following messages:

    • #0状态上报

      设备可靠状态上报。

      Message IDstatusReport
      Correlation ID$message.payload#/command_id

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

      allOf

      Examples

    • #1可靠定位上报
      Message IDreliableLocationReport
      Correlation ID$message.payload#/command_id

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

      allOf

      Examples

    • #2行为上报

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

      Message IDbehaviorReport
      Correlation ID$message.payload#/command_id

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

      信封 ts 是 UTC Unix 秒;报文不携带业务时区,云端按绑定宠物创建时固化的 IANA 时区归属自然日。

      allOf

      行为窗口按信封 UTC ts 定位瞬时;自然日由云端使用绑定宠物的固定 IANA 时区计算。

      Examples

    • #3故障上报
      Message IDfaultReport
      Correlation ID$message.payload#/command_id

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

      allOf

      Examples

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

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

    Operation IDreceiveLiveLocation

    Available only on servers:

    object
    string
    required

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

    snstring
    required

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

    object

    Accepts the following message:

    实时定位上报

    每秒最多上报一条 QoS 0 消息,不写入设备闪存。

    Message IDliveLocationReport
    allOf

    Examples

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

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

    Operation IDsendCommands

    Available only on servers:

    object
    string
    required

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

    snstring
    required

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

    object

    Accepts one of the following messages:

    • #0时间同步
      Message IDtimeSync
      Correlation ID$message.payload#/command_id

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

      allOf

      Examples

    • #1设置走失模式
      Message IDlostModeSet
      Correlation ID$message.payload#/command_id

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

      allOf

      Examples

    • #2请求定位
      Message IDlocationRequest
      Correlation ID$message.payload#/command_id

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

      allOf

      Examples

    • #3设置项圈灯光
      Message IDlightSet
      Correlation ID$message.payload#/command_id

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

      allOf

      Examples

    • #4播放已有音频资源
      Message IDaudioPlay
      Correlation ID$message.payload#/command_id

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

      allOf

      Examples

    • #5配置家庭 AP 在家检测
      Message IDhomePresenceConfig
      Correlation ID$message.payload#/command_id

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

      allOf

      Examples

    • #6启动蜂窝网络 DFOTA 任务

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

      Message IDdfotaStart
      Correlation ID$message.payload#/command_id

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

      allOf

      Examples

    • #7请求设备日志

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

      Message IDlogQuery
      Correlation ID$message.payload#/command_id

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

      allOf

      Examples

    • #8下发音频资源任务

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

      Message IDaudioResourceTask
      Correlation ID$message.payload#/command_id

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

      allOf

      Examples

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

    Operation IDreceiveDeviceAcknowledgements

    Available only on servers:

    object
    string
    required

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

    snstring
    required

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

    object

    Accepts the following message:

    设备交付确认

    阶段 1 为中间状态;阶段 2 完成云端功能调用。

    Message IDdeviceDeliveryAck
    Correlation ID$message.payload#/command_id

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

    allOf

    Examples

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

    Operation IDsendCloudAcknowledgements

    Available only on servers:

    object
    string
    required

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

    snstring
    required

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

    object

    Accepts the following message:

    云端交付确认

    阶段 3 表示允许设备删除对应的可靠记录。

    Message IDcloudDeliveryAck
    Correlation ID$message.payload#/command_id

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

    allOf

    Examples

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

    Operation IDreceiveShadowUpdate

    Available only on servers:

    object
    string
    required

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

    snstring
    required

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

    object

    Accepts the following message:

    上报设备影子状态
    Message IDshadowUpdate
    allOf

    Examples

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

    Operation IDreceiveShadowGet

    Available only on servers:

    object
    string
    required

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

    snstring
    required

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

    object

    Accepts the following message:

    请求期望影子状态
    Message IDshadowGet
    allOf

    Examples

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

    Operation IDsendShadowDesired

    Available only on servers:

    object
    string
    required

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

    snstring
    required

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

    object

    Accepts the following message:

    返回期望影子状态
    Message IDshadowDesired
    allOf

    Examples

Messages

  • #1状态上报

    设备可靠状态上报。

    Message IDstatusReport
    Correlation ID$message.payload#/command_id

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

    allOf
  • #2可靠定位上报
    Message IDreliableLocationReport
    Correlation ID$message.payload#/command_id

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

    allOf
  • #3实时定位上报

    每秒最多上报一条 QoS 0 消息,不写入设备闪存。

    Message IDliveLocationReport
    allOf
  • #4行为上报

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

    Message IDbehaviorReport
    Correlation ID$message.payload#/command_id

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

    信封 ts 是 UTC Unix 秒;报文不携带业务时区,云端按绑定宠物创建时固化的 IANA 时区归属自然日。

    allOf

    行为窗口按信封 UTC ts 定位瞬时;自然日由云端使用绑定宠物的固定 IANA 时区计算。

  • #5故障上报
    Message IDfaultReport
    Correlation ID$message.payload#/command_id

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

    allOf
  • #6时间同步
    Message IDtimeSync
    Correlation ID$message.payload#/command_id

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

    allOf
  • #7设置走失模式
    Message IDlostModeSet
    Correlation ID$message.payload#/command_id

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

    allOf
  • #8请求定位
    Message IDlocationRequest
    Correlation ID$message.payload#/command_id

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

    allOf
  • #9设置项圈灯光
    Message IDlightSet
    Correlation ID$message.payload#/command_id

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

    allOf
  • #10播放已有音频资源
    Message IDaudioPlay
    Correlation ID$message.payload#/command_id

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

    allOf
  • #11配置家庭 AP 在家检测
    Message IDhomePresenceConfig
    Correlation ID$message.payload#/command_id

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

    allOf
  • #12启动蜂窝网络 DFOTA 任务

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

    Message IDdfotaStart
    Correlation ID$message.payload#/command_id

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

    allOf
  • #13请求设备日志

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

    Message IDlogQuery
    Correlation ID$message.payload#/command_id

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

    allOf
  • #14下发音频资源任务

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

    Message IDaudioResourceTask
    Correlation ID$message.payload#/command_id

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

    allOf
  • #15设备交付确认

    阶段 1 为中间状态;阶段 2 完成云端功能调用。

    Message IDdeviceDeliveryAck
    Correlation ID$message.payload#/command_id

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

    allOf
  • #16云端交付确认

    阶段 3 表示允许设备删除对应的可靠记录。

    Message IDcloudDeliveryAck
    Correlation ID$message.payload#/command_id

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

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

Schemas

  • object
  • string

    使用 16 位十六进制字符表示的稳定 u64 业务 ID。

  • object
  • allOf
  • allOf
  • allOf
  • object
  • allOf
  • allOf
  • object
  • allOf

    行为窗口按信封 UTC ts 定位瞬时;自然日由云端使用绑定宠物的固定 IANA 时区计算。

  • object

    窗口增量统计,并非原始 IMU 数据。扩展健康字段为乙方预设契约,硬件尚待对齐; 时长单位均为秒,计数字段均为非负整数。

  • object

    可在宠物日常中直接使用的稳定行为事件。event_id 在同一设备内必须稳定唯一,重传不得换号; start_ts/end_ts 均为 UTC Unix 秒。

  • allOf
  • object
  • allOf
  • allOf
  • allOf
  • allOf
  • allOf
  • allOf
  • allOf
  • allOf
  • allOf
  • allOf
  • allOf
  • allOf
  • allOf
  • allOf
  • allOf
  • object
  • object