基础入门

ESP RainMaker 代理建立在 ESP-IDF 之上，为用户提供一些基础 API，用于构建基于 ESP RainMaker 规范的应用程序。

可前往 此处 查看 C 语言 API 的相关文档。

基础例程

用户可以通过 Switch 基础例程，进一步了解 ESP RainMaker 固件。以下为例程相关的代码片段：

    /* 初始化 Wi-Fi。需注意，调用 esp_rmaker_init() 前应首先调用此函数
     */
    app_wifi_init();

    /* 初始化 ESP RainMaker 代理
     * 应首先调用 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()
     * 使用该 API 后，无需编写添加 Name 和 Power 参数的代码
     */
    switch_device = esp_rmaker_device_create("Switch", ESP_RMAKER_DEVICE_SWITCH, NULL);

    /* 为设备添加写回调函数。此处暂不需要读回调函数
     * 所以并未注册此类函数
     */
    esp_rmaker_device_add_cb(switch_device, write_cb, NULL);

    /* 添加标准 Name 参数（类型为 esp.param.name），该参数支持
     * 通过手机应用程序设置长期且用户友好的自定义名称。
     * 推荐为所有设备添加此参数。
     */
    esp_rmaker_device_add_param(switch_device, esp_rmaker_name_param_create("name", "Switch"));

    /* 添加标准 Power 参数（类型为 esp.param.power），该参数添加了一个 Bool 参数，
     * 附带一个 Switch 类型的用户界面控件。
     */
    esp_rmaker_param_t *power_param = esp_rmaker_power_param_create("power", DEFAULT_POWER);
    esp_rmaker_device_add_param(switch_device, power_param);

    /* 将 Power 参数分配为主参数，以便通过手机应用程序的主屏幕
     * 进行控制。
     */
    esp_rmaker_device_assign_primary_param(switch_device, power_param);

    /* 将当前 Switch 设备添加到节点 */
    esp_rmaker_node_add_device(node, switch_device);

    /* 开启 ESP RainMaker 代理 */
    esp_rmaker_start();

    /* 开启 Wi-Fi
     * 如果节点已成功配网，将开始尝试连接
     * 否则，将开始进行 Wi-Fi 配网
     * 成功连接后，即返回函数
     */
    app_wifi_start(POP_TYPE_RANDOM);

以下为基于 ESP RainMaker 的应用程序的典型代码：

• 初始化 Wi-Fi (app_wifi_init())，这同时也会初始化 MAC 地址。该地址即为 ESP32-S2 Self-claiming 的唯一节点标识符 (node_id)。
• 传递配置结构体变量 (esp_rmaker_config_t)、节点名称和类型，初始化 ESP RainMaker 节点 (esp_rmaker_node_init())。
• 创建设备 (esp_rmaker_device_create())。RainMaker 节点本身并无特定值，除非节点下连接了设备。在上述例程中，我们创建了一个名为 “Switch” 的设备，并为该设备提供了写回调。如果接收到 Switch 设备下任何参数的写请求，则会调用该回调。
• 添加参数和其他元数据。比如，对 Switch 设备来说，必须添加标准的 Power 参数。将某些参数标记为主要参数，以便在手机应用程序中进行控制。
• 将设备添加到节点中。
• 启动 RainMaker 代理 (esp_rmaker_start())。这将启动 RainMaker 的一系列核心任务：等待 Wi-Fi、进行 Claiming、连接至 RainMaker 云的 MQTT 服务（如需）、报告节点配置、报告参数值、等待命令。
• 启动 Wi-Fi (app_wifi_start())。若此前已对 ESP32 进行配置，其将加入配置的 Wi-Fi 网络。否则，它将开始 Wi-Fi 配网。需注意，在调用此函数之前，应首先初始化并启动 RainMaker。