跳到主要内容

指令响应使用指南

about

ESP RainMaker 的指令响应框架为客户端（如手机应用）向设备发送数据提供了可靠方式，可作为设置参数工作流的替代方案。该框架允许设备从云端查询最后接收到的指令，实现了断电后设备状态的无缝恢复，且提升了可靠性，即使设备离线也能执行请求，并通过识别用户角色（管理员用户、主要用户、次要用户）增强了访问控制。

  • 了解更多关于指令响应，请查阅此文档。
  • 在 RainMaker CLI 上测试指令响应，请查阅此文档。

使用指南​

启用指令响应​

在 sdkconfig 中设置 CONFIG_ESP_RMAKER_CMD_RESP_ENABLE=y 启用指令响应。之后，只需调用 API esp_rmaker_cmd_register() 即可注册指令。

API 和回调原型定义如下：

esp_err_t esp_rmaker_cmd_register(uint16_t cmd, uint8_t access, esp_rmaker_cmd_handler_t handler, bool free_on_return, void *priv);
typedef esp_err_t (*esp_rmaker_cmd_handler_t)(const void *in_data, size_t in_len, void **out_data, size_t *out_len, esp_rmaker_cmd_ctx_t *ctx, void *priv);
参数说明
cmd指令标识符。
自定义指令应使用
ESP_RMAKER_CMD_CUSTOM_START (0x1000) 之后的 ID。
access指令的用户访问权限。
可以是各类 用户角色标志 的逻辑或，如：
ESP_RMAKER_USER_ROLE_SUPER_ADMIN
ESP_RMAKER_USER_ROLE_PRIMARY_USER
ESP_RMAKER_USER_ROLE_SECONDARY_USER
handler接收到指定指令时调用的处理函数。
free_on_return标志，指示框架在响应发送后是否释放输出。
priv注册指令时传递的可选私有数据。

处理函数 esp_rmaker_cmd_handler_t 的参数如下：

参数说明
in_data输入数据指针。
in_len数据长度。
out_data输出数据指针，由处理函数设置。
out_len生成的输出长度。
ctx指令上下文。
包含指令 ID、请求 ID 及发起指令用户的角色。
priv注册指令时指定的私有数据。

使用示例​

#define LIGHT_CMD   ESP_RMAKER_CMD_CUSTOM_START /* 自定义指令应从这里开始 */

/* 指令回调 */
esp_err_t led_light_cmd_handler(const void *in_data, size_t in_len, void **out_data, size_t *out_len, esp_rmaker_cmd_ctx_t *ctx, void *priv)
{
    ESP_LOGI(TAG, "Got command: %.*s", in_len, (char *)in_data);
    /* 发送虚拟响应 */
    static char resp_data[100];
    snprintf(resp_data, sizeof(resp_data), "{\"status\":\"success\"}");
    *out_data = resp_data;
    *out_len = strlen(resp_data);
    return ESP_OK;
}

void app_main()
{
    ...
    /* 注册主要用户和次要用户可访问（管理员用户不可访问）的指令 */
    esp_rmaker_cmd_register(LIGHT_CMD, ESP_RMAKER_USER_ROLE_PRIMARY_USER | ESP_RMAKER_USER_ROLE_SECONDARY_USER, led_light_cmd_handler, false, NULL);
    ...
}

更多信息​

固件使用示例可参考 led_light 示例。此处为指令处理函数示例代码，摘自 led_light 示例。

On this page