代码基础

提示

本节概述了如何使用 ESP RainMaker agent 构建应用程序。该 agent 运行在 ESP-IDF 框架之上，提供简化的 API 用于云端连接设备开发。通过基础版 Switch 示例展示典型应用流程：初始化 Wi-Fi、设置 RainMaker 节点和设备、添加参数和回调、启动 agent 以及管理 Wi-Fi 配网。该示例演示了如何构建实现设备与云端交互的固件。

信息

如需开始固件开发并了解如何搭建 ESP RainMaker 项目，请先查阅此文档获取基础信息，再继续阅读本节内容。

ESP RainMaker 代码解析

ESP RainMaker agent 基于 ESP-IDF 构建，提供符合 ESP RainMaker 规范的简易应用开发 API。

SDK Structure

C API 文档详见此处。

示例代码

以下通过 Switch 示例解析 ESP RainMaker 固件的实现方式
(esp-rainmaker/examples/switch/main/app_main.c)。相关代码如下：

    /* 初始化 Wi-Fi，请在 esp_rmaker_init() 前调用。
     */
    app_wifi_init();

    /* 初始化 ESP RainMaker Agent。
     * 注意，应在 app_wifi_init() 后，app_wifi_start() 前调用。
     * */
    esp_rmaker_config_t rainmaker_cfg = {
        .enable_time_sync = false,
    };
    esp_rmaker_node_t *node = esp_rmaker_node_init(&rainmaker_cfg, "ESP RainMaker Device", "Switch");
    if (!node) {
        ESP_LOGE(TAG, "Could not initialise node. Aborting!!!");
        vTaskDelay(5000/portTICK_PERIOD_MS);
        abort();
    }

    /* 创建 Switch 设备。
     * 也可使用辅助 API esp_rmaker_switch_device_create()。
     * 避免手动添加名称和电源参数。
     */
    switch_device = esp_rmaker_device_create("Switch", ESP_RMAKER_DEVICE_SWITCH, NULL);

    /* 添加设备写回调。
     * 暂不注册读回调以供后续扩展。
     */
    esp_rmaker_device_add_cb(switch_device, write_cb, NULL);

    /* 添加标准名称参数（类型：esp.param.name），允许通过手机应用设置持久且用户友好的自定义名称。
     * 推荐所有设备都具备此参数。
     */

    esp_rmaker_device_add_param(switch_device, esp_rmaker_name_param_create("name", "Switch"));

    /* 添加标准电源参数（类型：esp.param.power），该参数为布尔类型，
     * 并带有切换开关的 UI 类型。
     */
    esp_rmaker_param_t *power_param = esp_rmaker_power_param_create("power", DEFAULT_POWER);
    esp_rmaker_device_add_param(switch_device, power_param);

    /* 将电源参数设为主参数，以便可通过
     * 手机应用主界面进行控制。
     */
    esp_rmaker_device_assign_primary_param(switch_device, power_param);

    /* 将该设备添加到节点中 */
    esp_rmaker_node_add_device(node, switch_device);

    /* 启动 ESP RainMaker Agent */
    esp_rmaker_start();

    /* 启动 Wi-Fi。
     * 如果节点已配网，将开始连接尝试；
     * 否则，将启动 Wi-Fi 配网。
     * 该函数将在成功建立连接后返回。
     */
    app_wifi_start(POP_TYPE_RANDOM);

任何基于 ESP RainMaker 的应用程序的典型代码流程如下：

初始化 Wi-Fi（app_wifi_init()），同时初始化 MAC 地址，作为 ESP32-S2 自主认证的唯一节点标识符（node_id）。
初始化 ESP RainMaker 节点（esp_rmaker_node_init()），传入配置（esp_rmaker_config_t）、节点名称和类型。
创建设备（esp_rmaker_device_create()）。RainMaker 节点本身没有具体意义，除非其下有设备。本例创建了名为 "Switch" 的设备，并配置了写回调。当收到 Switch 设备下任意参数的写请求时，将调用该回调。
添加参数及其他元数据。一个 Switch 设备至少应包含标准电源参数。将某个参数设为主参数，可在手机应用中突出显示。
将设备添加到节点下。
启动 RainMaker Agent（esp_rmaker_start()）。这将启动 RainMaker 核心任务，等待 Wi-Fi，进行认证（如有需要），通过 MQTT 连接到 RainMaker 云端，报告节点配置和参数值，然后等待指令。
启动 Wi-Fi（app_wifi_start()）。如果 ESP32 已配网，将加入已配置的 Wi-Fi 网络，否则将启动 Wi-Fi 配网。注意，RainMaker 应在此调用前完成初始化和启动。

ESP RainMaker 代码解析​

示例代码​

ESP RainMaker 代码解析

示例代码