设备命令

在 ThingsCloud 平台中，设备命令用于由云平台向设备发起一次“远程调用”（RPC），让设备执行某个明确的动作或流程，例如：重启设备、修改工作模式、触发一次自检、发起 OTA 升级等。

与属性下发相比，命令更适合表达“让设备做一件事”。与事件上报相比，命令由平台主动发起，并且通常需要设备侧按约定返回处理结果（可选）。

什么是设备命令？

从业务角度理解，设备命令常见于以下场景：

• 控制类：开关机、切换模式、执行一次动作（例如开阀、关阀、鸣笛）。
• 维护类：重启、自检、日志上传、清缓存、恢复出厂设置。
• 升级类：触发 OTA 升级检查或启动升级流程。
• 请求类：让设备上报一次“即时数据”（设备收到命令后主动上报属性/事件）。

如何向设备下发命令

ThingsCloud 支持多种方式下发命令，可按使用场景选择：

控制台下发

在控制台的设备详情页的“命令”和“调试”中，可以直接对设备下发命令（适合开发调试与小规模运维场景）。下发后的命令与回复记录，建议在“设备消息日志”中统一查看与排查。

在看板中下发

在可视化看板中，可直接拖拽「命令下发」组件，绑定设备，设置命令标识符和参数集合，即可通过点击按钮来下发命令。

在用户应用中下发

在用户应用 ThingsX 编辑器中，支持「命令下发」组件，可实现用户点击按钮来下发命令。

使用项目 HTTP API 下发

当您需要在“应用端”（例如业务后台、运维平台）里统一下发命令，推荐使用 ThingsCloud HTTP API。

使用应用端 API 下发

当您需要在“应用端”以设备身份（AccessToken）下发命令，可使用应用端设备访问 API。

通过规则或任务自动下发

如果命令不是人工触发，而是希望在某些条件下自动下发（例如：收到设备故障事件后联动其它设备，或者每日定时下发命令），可以使用消息规则或定时任务。

命令消息结构

设备命令消息采用 JSON 格式，包含以下核心字段：

{
  "method": "{command_identifier}",
  "params": {
    "key1": "{value1}",
    "key2": "{value2}",
    ...
  },
  "id": 1000
}

字段说明

命令回复（可选）

设备端执行完特定的逻辑后，可以向平台上报命令回复，用于返回执行结果（成功/失败原因、当前状态等）。是否需要回复由业务决定。

典型命令消息示例

为了帮助您更好地设计命令，以下列举了几种常见的命令消息示例，涵盖了从带参数控制到复杂任务下发的场景。

示例 1：带延时的开关控制（点动模式）

在控制设备开关的同时，附加延时自动关闭的参数，常用于门禁开锁、自动灌溉等场景。

场景：打开 1 号继电器，并设定 10 秒后自动关闭。

{
  "method": "pulse_relay",
  "params": {
    "channel": 1,
    "action": "on",
    "duration": 10
  },
  "id": 1001
}

示例 2：多参数情景模式设置

用于一次性设置多个相关联的参数，避免分多次下发造成设备状态不一致。

场景：将智能空调设定为“睡眠模式”，并同时指定目标温度、风速等级和定时关机时间（分钟）。

{
  "method": "set_sleep_mode",
  "params": {
    "target_temp": 26.5,
    "fan_speed": "low",
    "timer_off": 480
  },
  "id": 1002
}

示例 3：下发显示内容与样式

向具备显示能力的设备（如电子价签、广告屏）下发内容及显示样式。

场景：更新电子墨水屏显示的会议室状态，指定文本内容、字体大小及是否反色显示。

{
  "method": "update_screen",
  "params": {
    "text": "会议中\n请勿打扰",
    "font_size": 32,
    "style": {
        "invert": true,
        "refresh_mode": "partial"
    }
  },
  "id": 1003
}

示例 4：下发一组定时任务

命令参数支持数组嵌套，适合下发复杂的任务列表。

场景：下发一组定时灌溉任务，包含多个时间段和对应的水量。

{
  "method": "set_irrigation_task",
  "params": {
    "tasks": [
      { "start_time": "06:00", "duration": 300, "zone": "A" },
      { "start_time": "18:00", "duration": 600, "zone": "B" }
    ],
    "enable": true
  },
  "id": 1004
}

示例 5：带有对应回复的完整交互

展示一次完整的“平台下发 -> 设备回复”过程。

平台下发 OTA 升级指令：

{
  "method": "ota_upgrade",
  "params": {
    "version": "v1.2.0",
    "url": "http://download.example.com/firmware/v1.2.0.bin"
  },
  "id": 2001
}

设备收到并校验通过后，返回成功回复：

{
  "method": "ota_upgrade",
  "params": {
    "result": "success",
    "message": "Download started"
  },
  "id": 2001
}

如何查看命令下发与回复

在控制台设备详情页查看

在控制台设备详情页查看

在控制台中，进入任意设备的详情页，点击「命令」标签页，即可查看该设备的所有已下发命令记录。

在控制台设备日志中查看

命令下发与命令回复属于设备消息，在设备详情页的“调试日志”中也可以查看，便于按时间线排查：

• 是否下发命令到设备
• 下发的命令消息内容是否符合预期
• 是否有设备端回复命令的消息
• 回复消息内容是否符合预期

设备端如何接收与回复命令

设备端对接平台下发的命令时，关键点是：

• 订阅命令下发 Topic
• 解析命令结构
• 执行特定本地逻辑
• 按需回复命令

对于网关/子设备场景（网关代子设备接收与回复命令），请参考网关 MQTT 协议说明：

对于使用通信模组 AT 指令接入的设备，也有专门示例可以直接照着实现：

在应用端实时接收命令回复

如果您的应用需要实时接收设备命令回复（例如展示执行结果、更新 UI 状态），可以使用项目 MQTT 应用端订阅能力，来订阅“命令回复”实时消息。

常见问题

设备不回复命令可以吗？

可以。命令回复不是必须的。很多场景下，设备执行命令后可以选择：

• 回复命令，返回处理结果（推荐用于强交互/可观测性要求高的场景）。
• 上报属性或事件，让平台侧看到“执行后的状态变化”。
• 不上报任何消息。

id 有什么用？需要注意什么？

id 用于将“命令下发”与“命令回复”进行一一对应。

设备收到命令后，回复的消息中必须携带与下发消息相同的 id，这样平台才能知道这条回复对应的是哪一次下发。

相关文档

• 设备类型 - 功能定义
• 设备消息
• 设备消息调试
• MQTT 设备接入
• 网关 MQTT 接入
• 项目 HTTP API 参考
• 应用端设备访问 API
• MQTT 应用端订阅
• 消息规则
• 命令下发类任务