跳到主要内容
ESP RainMaker Classic 文档

固件预生产检查清单

在确定固件之前，请完成以下事项。

创建项目​

虽然可以参照标准示例来创建项目，但建议复制示例代码后再根据具体使用场景进行改动，并单独维护，以避免在 esp-rainmaker 代码库更新时发生冲突。另外，建议使用 Git 等版本控制系统跟踪每个项目的改动。

Claiming​

私有 RainMaker 部署不支持 Claiming 功能。请使用 RainMaker Admin CLI 生成需要烧录到工厂分区的凭证。此外，为节省 flash 使用空间，请在项目的 sdkconfig.defaults 文件中禁用以下配置选项：

CONFIG_ESP_RMAKER_ASSISTED_CLAIM
CONFIG_ESP_RMAKER_SELF_CLAIM

使用预配置的模块​

乐鑫提供在制造阶段就预配置了唯一私钥和设备证书的模块。由于设备凭据已在模块上可用，产线无需生成或烧录密钥和证书，从而显著降低制造复杂度。

乐鑫为此类模块提供预配置清单文件，可通过管理面板或使用 esp-rainmaker-admin-cli 将其注册到 RainMaker 部署中。

备注

用于保护私钥的密钥类型和机制取决于 SoC：

SoC密钥类型与保护
ESP32, ESP32-C2 / ESP8684私钥存储在 esp_secure_cert 分区中，通过 Secure Boot 和 Flash Encryption 进行保护
ESP32-C3 / ESP8685, ESP32-C6, ESP32-S2, ESP32-S3通过 DS 外设保护 RSA 私钥（密钥材料使用 eFuse 加密）
ESP32-C5, ESP32-H2通过 ECDSA 外设保护 ECDSA 私钥（密钥材料位于 eFuse）

如需未在此列出的 SoC，请联系乐鑫。

要将此类模块用于 RainMaker 固件，请在项目的 sdkconfig.defaults 中设置以下配置项：

CONFIG_ESP_RMAKER_NO_CLAIM=y
CONFIG_ESP_RMAKER_USE_ESP_SECURE_CERT_MGR=y
CONFIG_ESP_RMAKER_READ_MQTT_HOST_FROM_CONFIG=y
CONFIG_ESP_RMAKER_READ_NODE_ID_FROM_CERT_CN=y
CONFIG_ESP_RMAKER_MQTT_HOST=<customer-deployment-mqtt-host>
CONFIG_APP_PROV_SECURITY_VERSION_1=y
CONFIG_MBEDTLS_SSL_PROTO_TLS1_3=y
  • CONFIG_ESP_RMAKER_NO_CLAIM：禁用 claiming 流程。模块上已存有设备凭据，无需再获取。
  • CONFIG_ESP_RMAKER_USE_ESP_SECURE_CERT_MGR：通过 esp_secure_cert_mgr 组件从预配置的 esp_secure_cert 分区读取私钥和设备证书，而不是从 RainMaker 工厂分区读取。
  • CONFIG_ESP_RMAKER_READ_MQTT_HOST_FROM_CONFIG：从固件配置中读取 MQTT 主机。预配置模块中不含特定部署的 MQTT 主机信息。
  • CONFIG_ESP_RMAKER_READ_NODE_ID_FROM_CERT_CN：使用设备证书的 Common Name (CN) 字段作为 RainMaker 节点 ID。
  • CONFIG_ESP_RMAKER_MQTT_HOST：指定 RainMaker 部署的 MQTT 主机。由于已启用上面的 CONFIG_ESP_RMAKER_READ_MQTT_HOST_FROM_CONFIG，固件会采用此处配置的值。
  • CONFIG_APP_PROV_SECURITY_VERSION_1：Wi-Fi 配网使用安全版本 1。默认的安全版本 2 需要持有凭证 (PoP)，而预配置模块通常不提供 PoP。详见下文关于 PoP 的说明。
  • CONFIG_MBEDTLS_SSL_PROTO_TLS1_3：使用 DS 外设的 SoC 必须启用该选项。在基于挑战-响应机制的用户-节点映射中，节点通过 DS 外设使用 RSA-PSS 对挑战进行签名，而 DS 驱动只有在启用 TLS 1.3 时才会编译 PSS 支持。若不启用该选项，此类模块的用户-节点映射会在运行时失败。

此外，请在应用代码中以 app_network_start(POP_TYPE_NONE) 开始配网。标准 RainMaker 模块带有 fctry 分区；该分区除存放设备凭据（私钥、证书和 MQTT 主机）外，还包含用于生成配网名称和持有证明 (PoP) 的随机字节串。预配置模块不包含已填充的 fctry 分区，因此无法使用 POP_TYPE_RANDOM。更重要的是，在制造阶段通常没有与节点 ID 关联的、可用于生成并与终端用户共享（例如以包装上的二维码形式）PoP 的每设备唯一数据，无论是 MAC 地址还是随机字节流。因此，建议使用不含 PoP 的第 1 版安全机制。若能自行管理此类映射（例如在生产时将 MAC 地址或自定义 PoP 记录到 节点 ID），则可改用 POP_TYPE_MAC 或 POP_TYPE_CUSTOM，两种安全版本均可。配网名称默认从 Wi‑Fi MAC 地址派生，因此即便将 PoP 类型设为 POP_TYPE_NONE，设备发现仍可正常工作。有关 PoP 类型的更多信息，请参阅 配网 PoP。

分区表​

在预配置模块上，esp_secure_cert 分区位于偏移 0xD000，大小为 8 KB（0x2000）。分区表必须包含相应的条目。所有 RainMaker 示例分区表都已包含它：

# 名称,           类型, 子类型, 偏移,  大小,   标志
esp_secure_cert,  0x3F, ,        0xD000,  0x2000, encrypted

encrypted 标志可确保在启用 Flash Encryption 时该分区会被加密；未启用时，该标志会被忽略。某些早期的预配置模块使用的分区名为 pre_prov。如果模块包含该分区，请参考 esp_secure_cert_app README。

验证 Secure Cert 分区​

根据 SoC（见上表），私钥会以以下三种方式之一存储在 esp_secure_cert 分区中：

  1. 明文：私钥本身存放在 esp_secure_cert 分区内，并由 Flash Encryption 保护。
  2. DS 外设：分区保存为 DS (Digital Signature) 外设加密后的私钥，以及所用 eFuse 密钥块的 ID。用于解密的密钥存储在 eFuse 中，并且只在 DS 外设内部使用，因此明文 RSA 密钥永远不会暴露。
  3. ECDSA 外设：整条 256 位私钥被烧录进一个 eFuse 密钥块中。分区仅保存该 eFuse 密钥块的 ID。

由于这些方式的分区内容不同，验证其中一种路径并不能确认其他路径是否正常。每种类型的分区都需要独立验证。esp_secure_cert_app 示例演示了如何验证这三种类型的分区。

若要专门测试 DS 或 ECDSA 外设路径：

  1. 按照 此指南 生成 esp_secure_cert 分区。对于 DS 外设，使用 此命令。对于 ECDSA 外设，使用 基于 CSV 的配置，将 priv_key_type 设为 ecdsa_peripheral。
  2. 使用 esp_secure_cert_app 示例直接验证生成的分区。
  3. 也可以直接配合 RainMaker 固件测试生成的分区，此时固件会使用 DS 或 ECDSA 外设路径。

请注意，该工具设置的密钥仅用于开发，因此同一密钥可在多次开发迭代中复用。

配网二维码​

开发环境中，配网二维码会显示在串口终端上；但在生产环境中，二维码需要在设备外部生成。RainMaker Admin CLI 能够生成这些二维码。

空中升级 (OTA)​

在 switch 和 led_light 示例中，默认启用 OTA 固件更新。代码片段如下：

esp_rmaker_ota_config_t ota_config = {
   .server_cert = ESP_RMAKER_OTA_DEFAULT_SERVER_CERT,
};
esp_rmaker_ota_enable(&ota_config, OTA_USING_PARAMS);

该配置用于基于参数的 OTA 升级，适用于开发者使用场景。若通过管理面板进行 OTA 升级，请将 OTA_USING_PARAMS 改为 OTA_USING_TOPICS：

esp_rmaker_ota_enable(&ota_config, OTA_USING_TOPICS);

更多有关 OTA 的信息，请参考本指南。请注意，只有超级管理员用户才可以通过管理面板执行 OTA 操作。

时区​

如果计划使用定时功能，请确保固件中设置了时区，或添加了时区服务以支持运行时配置时区。详情请参阅本指南。大多数示例已默认添加时区服务。

定时​

若希望固件支持定时功能，需显式添加相应的 API。详情请参阅本指南。请注意，定时功能依赖时区，时区是其正常工作的前提。大多数示例已默认添加定时服务。

定时任务数量限制​

前往 idf.py menuconfig > ESP RainMaker Config > ESP RainMaker Scheduling > Maximum Schedules，通过配置选项 CONFIG_ESP_RMAKER_SCHEDULING_MAX_SCHEDULES 来设置定时任务的最大数量限制。默认值之前为 5，现已改为 10。如果该数量不足以满足你的需求，可以自行增加。需要注意的是，由于所有定时信息均作为 RainMaker 的“参数”上传，且 RainMaker 使用 AWS IoT Shadow 在云端维护参数值，所有参数总大小限制为 8 KB。

本地控制​

ESP RainMaker 提供本地控制功能，优势有：

  • 响应更快
  • 成本更低（避免调用 REST API）

启用方法请参考本指南。启用前，请务必阅读安全注意事项。

On this page