跳到主要内容

指令响应

概述

ESP RainMaker 的指令响应 (Command-Response) 框架是替代参数设置工作流的方案，用于从客户端（如手机应用）向设备发送数据。该功能可供管理员和终端用户使用。

使用场景​

在 ESP RainMaker 系统中，指令响应可作为断电恢复的容错机制。例如：一个通过 ESP RainMaker 控制的智能灯泡通常依赖云端实时指令运行。若设备遭遇断电重启，可能会丢失最后状态。通过指令响应框架，设备重启时可主动查询云端最后接收的指令，确保恢复正确的灯光设置（如亮度、色彩），而非默认关闭状态。这能保障运行连续性，避免电力中断后的异常行为。

框架优势：

  • 可靠地获取任意请求的状态。
  • 可设置请求有效期，即使设备离线仍能触发。
  • 提供更完善的权限控制——节点知晓触发命令的用户角色（超级管理员用户、主要用户、次要用户）。
前置说明

若已熟悉 ESP RainMaker 的指令响应，请直接跳转使用指南：

  • 固件端指令响应使用指南请点击此处。
  • RainMaker CLI 指令响应测试指南请点击此处。

若不熟悉，请继续阅读以下内容。

下图展示了指令响应的工作流程。

alt text

客户端​

客户端与云端通过 JSON 格式的 REST API 通信。触发指令需调用 POST API，载荷示例如下：

JSON 载荷（展开/收起）
  {
  "node_ids": [
      "6jyMKuFuAq3xxxxxxxxyBQ"
  ],
  "cmd": 1,
  "data": {
      "brightness": 10
  },
  "timeout": 30
  }
  • node_ids: 目标设备节点 ID 列表。
  • cmd: 指令 ID。
  • data: 指令数据载荷。
  • timeout: 指令有效期（以秒计）。

传输二进制数据，需转换为 base64 字符串。
添加 is_based64 标识。例如：

JSON 载荷（展开/收起）
: {
"node_ids": [
    "6jyMKuFuAq3xxxxxxxxyBQ"
],
"cmd": 1,
"data": "YWJjZAo="
"timeout": 30,
"is_base64": true
}

云端后台会分配请求 ID 并返回如下响应：

JSON 载荷（展开/收起）
{
"request_id": "6jyMKuFxxxxxxxxStTKyBQ",
"status": "success"
}

客户端可通过 GET API 查询请求状态，将上述 request_id 作为查询参数。可能的状态包括：

状态
requested
in_progress
success
timed_out
failure
提示

对于 success 和 failure 状态，将同步返回对应的响应值。

设备端​

设备与云端采用 TLV8 编码通信（基于 TLV 的 8 位长度字段变体）。这种通信方式具有较强的灵活性，支持 JSON、XML、二进制等多种应用数据格式。

类型​

类型值代码宏定义说明长度
1ESP_RMAKER_TLV_TYPE_REQ_ID请求 ID可变长度字符串（最长 32 字符）
2ESP_RMAKER_TLV_TYPE_USER_ROLE用户角色1 字节
3ESP_RMAKER_TLV_TYPE_STATUS状态1 字节
4ESP_RMAKER_TLV_TYPE_TIMESTAMP时间戳待定（暂未使用）
5ESP_RMAKER_TLV_TYPE_CMD指令2 字节（小端序）
6ESP_RMAKER_TLV_TYPE_DATA数据可变长度

角色​

角色定义采用位映射方式。

值代码宏定义说明
1ESP_RMAKER_USER_ROLE_SUPER_ADMIN超级管理员用户
2ESP_RMAKER_USER_ROLE_PRIMARY_USER主要用户
4ESP_RMAKER_USER_ROLE_SECONDARY_USER次要用户

状态值定义

值代码宏定义说明
0ESP_RMAKER_CMD_STATUS_SUCCESS成功
1ESP_RMAKER_CMD_STATUS_FAILED通用失败
2ESP_RMAKER_CMD_STATUS_CMD_INVALID无效指令
3ESP_RMAKER_CMD_STATUS_AUTH_FAIL鉴权失败
4ESP_RMAKER_CMD_STATUS_NOT_FOUND未找到指令

使用指南​

固件​

本指南主要涵盖固件端的指令响应启用与使用。
详细使用说明请点击此处。

用 RainMaker CLI 测试指令响应功能​

指令响应测试指南请点击此处。

API 扩展信息

REST API 使用文档详见 Swagger 接口说明。

On this page