ESP Weaver 智能家居本地控制 SDK：基于 esp_local_ctrl 与 mDNS 的 Home Assistant 局域网设备接入指南

• 物联网
• 嵌入式
• 驱动开发
• 硬件开发

导读：本文以 ESP-IoT-Solution 中的 ESP Weaver 设备端 SDK 为核心，系统讲解如何基于 esp_local_ctrl 协议与 mDNS 服务发现，在 ESP32 系列芯片上构建可被 Home Assistant 本地发现与控制的智能家居设备。读完本文，你将掌握 Weaver 的设备/参数模型、SEC1 安全通信与 PoP 配对机制、Kconfig 配置要点，以及如何通过 LED 灯与 IMU 手势两个真实示例快速落地自己的产品。

一、ESP Weaver 是什么

ESP Weaver 是 ESP-IoT-Solution 仓库中提供的一个设备端智能家居 SDK（位于 components/esp_weaver），用于构建支持 Home Assistant 本地发现和控制的智能设备。它基于 ESP-IDF 的esp_local_ctrl组件和 mDNS 服务发现实现，具备以下核心特征：

• 低延迟本地控制：基于 mDNS 服务发现与 esp_local_ctrl 协议，实现局域网内毫秒级响应；
• 离线可用：设备与 Home Assistant 在局域网内直接通信，无需互联网连接即可正常控制；
• 端到端加密：采用 Proof of Possession（PoP，拥有证明）进行设备认证，Security1 协议基于 Curve25519 密钥交换与 AES-CTR 加密；
• 零配置发现：设备联网后通过 mDNS 自动广播服务，无需手动配置即可被 Home Assistant 发现；
• 简洁设备模型：直观的设备/参数模型用于智能家居集成，支持参数实时更新。

支持的芯片

与 ESP RainMaker 的关系（重要边界）

ESP Weaver不是ESP RainMaker 的直接替换品。虽然它使用兼容的本地控制协议和类似的设备/参数模型，但 API 命名空间（esp_weaver_*）、类型和功能集均有所不同。云端功能（MQTT、OTA、定时任务、场景等）被有意排除；同时每个进程仅支持一个 weaver 节点（单例模式）。这一点在 components/esp_weaver/README_CN.md 中有明确说明，设计 Weaver 应用时需注意这些边界。

二、系统架构与工作原理

ESP Weaver 的整体架构遵循「设备广播 + 集成发现 + 本地控制」的经典局域网智能家居模型：

+-------------------+ mDNS Discovery +-------------------+ | | <------------------- | | | Home Assistant | | ESP Device | | (ESP-Weaver) | -------------------> | (ESP Weaver) | | | Local Control | | +-------------------+ +-------------------+ | | | Local Network | +------------------------------------------+

工作流程分为四个步骤：

1. 广播：ESP 设备启动后连接 WiFi，并通过 mDNS 广播服务；
2. 发现：Home Assistant 中的 ESP-Weaver 集成自动发现局域网内的设备；
3. 配对：用户输入设备的 PoP 码完成配对认证；
4. 通信：通过 Local Control 协议进行双向通信。

从源码结构看，该架构被拆分为两个核心模块：

• esp_weaver.c：负责设备/参数模型的管理（节点、设备、参数的创建与生命周期）；
• esp_weaver_local_ctrl.c：负责将模型桥接到 esp_local_ctrl 传输层，包括 HTTP 服务、mDNS 广播、PoP 安全握手以及参数推送。

这种分层使业务开发者只需关注「定义设备与参数」，而将协议细节、安全握手与发现机制全部交给 SDK。

三、快速开始：五分钟构建一个智能灯

安装组件

推荐通过 ESP Component Registry 添加依赖：

idf.py add-dependency "espressif/esp_weaver=*"

也可以手动安装：克隆仓库后将 components/esp_weaver 整个目录复制到项目components/下。组件使用project_include.cmake与patches/idf/idf.patch（通过 tools/apply_patches.py 应用），确保其能正确集成到 ESP-IDF 构建系统。

最小可运行代码

下面这段代码来自 components/esp_weaver/README_CN.md，展示了创建一个可控智能灯的最小流程：

#include <esp_weaver.h> #include <esp_weaver_standard_types.h> #include <esp_weaver_standard_params.h> void app_main(void) { // 初始化 weaver 节点（单例） esp_weaver_config_t config = ESP_WEAVER_CONFIG_DEFAULT(); esp_weaver_node_t *node = esp_weaver_node_init(&config, "我的设备", "Lightbulb"); // 创建灯泡设备 esp_weaver_device_t *dev = esp_weaver_device_create("Light", ESP_WEAVER_DEVICE_LIGHTBULB, NULL); esp_weaver_device_add_bulk_cb(dev, my_write_cb); // 添加参数 esp_weaver_param_t *power = esp_weaver_param_create(ESP_WEAVER_DEF_POWER_NAME, ESP_WEAVER_PARAM_POWER, esp_weaver_bool(true), PROP_FLAG_READ | PROP_FLAG_WRITE | PROP_FLAG_PERSIST); esp_weaver_device_add_param(dev, power); esp_weaver_device_assign_primary_param(dev, power); esp_weaver_param_t *brightness = esp_weaver_param_create(ESP_WEAVER_DEF_BRIGHTNESS_NAME, ESP_WEAVER_PARAM_BRIGHTNESS, esp_weaver_int(50), PROP_FLAG_READ | PROP_FLAG_WRITE | PROP_FLAG_PERSIST); esp_weaver_param_add_bounds(brightness, esp_weaver_int(0), esp_weaver_int(100), esp_weaver_int(1)); esp_weaver_device_add_param(dev, brightness); esp_weaver_node_add_device(node, dev); // 启动本地控制（所有设置来自 Kconfig） esp_weaver_local_ctrl_start(); }

代码中的my_write_cb即为批量写入回调，当 Home Assistant 下发控制指令时被 SDK 调用，业务逻辑在其中完成对真实硬件的操作（详见下文「写入回调」）。

四、核心 API 详解

API 完整定义见 components/esp_weaver/include/esp_weaver.h，标准类型与标准参数见 esp_weaver_standard_types.h 与 esp_weaver_standard_params.h。

1. 节点管理（Node）

节点是设备模型的顶层容器，采用单例模式——同一进程内同时只能存在一个节点。

// 初始化 weaver 节点（返回节点句柄，失败返回 NULL） esp_weaver_node_t *esp_weaver_node_init(const esp_weaver_config_t *config, const char *name, const char *type); // 反初始化并释放所有资源（设备、参数一并释放） esp_err_t esp_weaver_node_deinit(const esp_weaver_node_t *node); // 获取节点 ID const char *esp_weaver_get_node_id(void);

配置结构体esp_weaver_config_t目前仅有一个字段node_id（自定义节点 ID，最长 32 字符），传NULL时 SDK 会根据 MAC 地址自动生成节点 ID。默认配置可直接使用宏ESP_WEAVER_CONFIG_DEFAULT()。在示例日志中可以看到自动生成的节点 ID，例如6055F9F919EC。

2. 设备管理（Device）

// 创建新设备（dev_name 需唯一，type 如 "esp.device.lightbulb"） esp_weaver_device_t *esp_weaver_device_create(const char *dev_name, const char *type, void *priv_data); // 删除设备（需先从节点移除，参数会一并释放） esp_err_t esp_weaver_device_delete(esp_weaver_device_t *device); // 向设备添加参数（一个设备最多支持 255 个参数） esp_err_t esp_weaver_device_add_param(esp_weaver_device_t *device, esp_weaver_param_t *param); // 添加批量写入回调（一次处理多个参数） esp_err_t esp_weaver_device_add_bulk_cb(esp_weaver_device_t *device, esp_weaver_device_bulk_write_cb_t write_cb); // 指定设备的主参数（供客户端优先展示） esp_err_t esp_weaver_device_assign_primary_param(esp_weaver_device_t *device, esp_weaver_param_t *param); // 将设备添加到节点 / 从节点移除设备 esp_err_t esp_weaver_node_add_device(const esp_weaver_node_t *node, esp_weaver_device_t *device); esp_err_t esp_weaver_node_remove_device(const esp_weaver_node_t *node, esp_weaver_device_t *device); // 获取设备名称 / 私有数据 const char *esp_weaver_device_get_name(const esp_weaver_device_t *device); void *esp_weaver_device_get_priv_data(const esp_weaver_device_t *device); // 按名称或类型获取参数 esp_weaver_param_t *esp_weaver_device_get_param_by_name(const esp_weaver_device_t *device, const char *param_name); esp_weaver_param_t *esp_weaver_device_get_param_by_type(const esp_weaver_device_t *device, const char *param_type);

priv_data参数允许携带任意业务上下文，会在回调中被原样传回，便于将参数与硬件驱动状态关联。

3. 参数管理（Param）

参数是 Weaver 模型的最小单元，每个参数由「名称 + 类型 + 值 + 属性标志」组成。

// 创建参数（val 同时决定了参数的数据类型） esp_weaver_param_t *esp_weaver_param_create(const char *param_name, const char *type, esp_weaver_param_val_t val, uint8_t properties); // 删除未加入设备的参数 esp_err_t esp_weaver_param_delete(esp_weaver_param_t *param); // 添加 UI 类型（供客户端渲染控件） esp_err_t esp_weaver_param_add_ui_type(esp_weaver_param_t *param, const char *ui_type); // 添加值边界（min/max/step，step 传 0 表示不限定步进） esp_err_t esp_weaver_param_add_bounds(esp_weaver_param_t *param, esp_weaver_param_val_t min, esp_weaver_param_val_t max, esp_weaver_param_val_t step); const char *esp_weaver_param_get_name(const esp_weaver_param_t *param); const esp_weaver_param_val_t *esp_weaver_param_get_val(const esp_weaver_param_t *param); // 仅更新参数值（标记待上报，供多参数批量上报场景使用） esp_err_t esp_weaver_param_update(esp_weaver_param_t *param, esp_weaver_param_val_t val); // 更新并立即推送给已连接的客户端（本地状态变化时应使用本接口） esp_err_t esp_weaver_param_update_and_report(esp_weaver_param_t *param, esp_weaver_param_val_t val);

属性标志（esp_weaver_param_property_flags_t，位于 esp_weaver.h）支持位或组合：

多参数批量上报技巧：esp_weaver_param_update()只更新本地值而不上报，因此当多个参数需要一起推送时，可以对前 x-1 个参数调用esp_weaver_param_update()，对最后一个参数调用esp_weaver_param_update_and_report()，SDK 会把此前累积的所有变更一并推送给客户端。头文件注释中给出了示例：update(param1) → update(param2) → update_and_report(param3)会把三个参数的变化一次上报。

4. 写入回调（Bulk Write Callback）

设备通过批量回调统一处理来自客户端的写请求，原型定义在 esp_weaver.h：

typedef esp_err_t (*esp_weaver_device_bulk_write_cb_t)(const esp_weaver_device_t *device, const esp_weaver_param_write_req_t write_req[], uint8_t count, void *priv_data, esp_weaver_write_ctx_t *ctx);

其中esp_weaver_param_write_req_t包含param（参数句柄）与val（待写入的值）两个字段；esp_weaver_write_ctx_t携带请求来源src（ESP_WEAVER_REQ_SRC_INIT表示初始化阶段从 NVS 恢复持久化值，ESP_WEAVER_REQ_SRC_LOCAL表示来自本地控制 HTTP 请求）。

注意：该回调可能在传输层专属任务上下文（如 HTTPD 任务）中执行，而非主任务。官方头文件注释明确要求回调内避免阻塞操作，访问共享状态时需做好同步。

led_light 示例 中的bulk_write_cb是标准写法：遍历write_req数组，通过esp_weaver_param_get_name()识别参数名，将值写入硬件驱动，最后调用esp_weaver_param_update(param, val)回写 SDK 缓存：

static esp_err_t bulk_write_cb(const esp_weaver_device_t *device, const esp_weaver_param_write_req_t write_req[], uint8_t count, void *priv_data, esp_weaver_write_ctx_t *ctx) { for (int i = 0; i < count; i++) { esp_weaver_param_t *param = write_req[i].param; esp_weaver_param_val_t val = write_req[i].val; const char *param_name = esp_weaver_param_get_name(param); if (strcmp(param_name, ESP_WEAVER_DEF_POWER_NAME) == 0) { app_light_set_power(val.val.b); } else if (strcmp(param_name, ESP_WEAVER_DEF_BRIGHTNESS_NAME) == 0) { app_light_set_brightness(val.val.i); } // ... 其余参数同理 esp_weaver_param_update(param, val); } return ESP_OK; }

5. 本地控制服务

// 启动本地控制（HTTP + mDNS，所有设置来自 Kconfig） esp_err_t esp_weaver_local_ctrl_start(void); // 停止本地控制服务 esp_err_t esp_weaver_local_ctrl_stop(void); // 设置自定义 PoP（必须在启动前调用） esp_err_t esp_weaver_local_ctrl_set_pop(const char *pop); // 获取当前 PoP const char *esp_weaver_local_ctrl_get_pop(void); // 设置自定义 mDNS TXT 记录（需在启动后调用） esp_err_t esp_weaver_local_ctrl_set_txt(const char *key, const char *value); // 将参数变化推送给已连接客户端 esp_err_t esp_weaver_local_ctrl_send_params(void);

其中esp_weaver_local_ctrl_send_params()用于配合esp_weaver_param_update()使用：先批量update，再统一调用send_params()推送。

五、标准类型与值辅助宏

设备类型

参数类型

完整列表见 esp_weaver_standard_types.h（含 toss/flip/shake/rotation/push/circle/clap 等全套手势事件类型与三轴方向参数）。对应地，esp_weaver_standard_params.h 提供了建议的默认参数名称（如"Power"、"Brightness"、"Hue"）。这些名称并非强制——开发者完全可以使用 Core API 自定义参数名。

UI 类型

值类型与辅助宏

esp_weaver_param_val_t是一个「类型 + 联合体」结构（见 esp_weaver.h），type字段决定val联合体中哪个成员有效。支持六种值类型：布尔、整数（32 位有符号）、浮点、字符串、JSON 对象字符串、JSON 数组字符串。使用辅助宏可以快速构造：

esp_weaver_bool(x) // 创建布尔值 esp_weaver_int(x) // 创建整数值 esp_weaver_float(x) // 创建浮点值 esp_weaver_str(x) // 创建字符串值 esp_weaver_obj(x) // 创建 JSON 对象值，如 {"name":"value"} esp_weaver_array(x) // 创建 JSON 数组值，如 [1,2,3]

注意：STRING 类型的val.s指向动态分配的内存，SDK 会在参数/设备销毁时自动释放。

六、安全机制：PoP 与 SEC0/SEC1

ESP Weaver 支持两种安全模式（可通过idf.py menuconfig → ESP Weaver配置）：

• SEC0：无安全性，通信明文传输，可被网络中的攻击者窃听或篡改。仅用于开发调试，严禁在生产环境使用；
• SEC1（默认，推荐）：基于 Curve25519 密钥交换 + AES-CTR 加密，并配合拥有证明（PoP）完成设备认证，所有生产部署都应使用此模式。

设备首次启动时，SDK 会自动随机生成 PoP 码并持久化到 NVS，串口日志会打印：

I (10592) esp_weaver_local_ctrl: No PoP in NVS. Generating a new one. I (10592) esp_weaver_local_ctrl: PoP for local control: 8f820513

后续重启会从 NVS 读取并复用同一 PoP（日志显示PoP read from NVS），保证设备身份稳定。也可以在启动本地控制前调用esp_weaver_local_ctrl_set_pop()编程设置自定义 PoP。PoP 的解析优先级为：用户自定义 PoP > NVS 中存储的 PoP > 自动生成的新 PoP（见 esp_weaver.h 的文档说明）。

在 Home Assistant 的 ESP-Weaver 集成中添加设备时，需要输入串口日志中显示的 PoP 码完成配对。

七、Kconfig 配置项全解

所有本地控制相关配置均通过idf.py menuconfig的ESP Weaver菜单配置，定义见 components/esp_weaver/Kconfig：

Kconfig 帮助文本明确建议：SEC1 是安全默认值，SEC0 仅限隔离开发环境中调试使用。

八、实战示例一：LED 智能灯（led_light）

examples/weaver/led_light 是最完整的入门示例，演示如何用 ESP Weaver 构建可控 RGB 智能灯。详见其 README_CN.md。

功能：电源开/关控制、亮度调节（0-100%）、HSV 颜色控制（色相 0-360°，饱和度 0-100%）。

硬件要求：支持芯片的开发板 + RGB LED（WS2812 或 3 引脚 RGB 模块）+ WiFi 路由器；LED 类型与 GPIO 可通过idf.py menuconfig → Example Configuration修改；示例使用开发板 BOOT 按钮。

编译与运行：

idf.py set-target <chip_name> # 例如 esp32c6 idf.py menuconfig # 配置 WiFi SSID/密码，可选配置安全版本 idf.py -p PORT flash monitor # 编译烧录并查看串口输出（Ctrl-] 退出监视器）

设备模型：该示例在 app_light.c 中创建了名为Light的灯泡设备，注册了五个参数：

启动流程（app_main.c）：初始化 NVS → 初始化硬件驱动 → 初始化 Weaver 节点（节点名/类型来自CONFIG_EXAMPLE_NODE_NAME/CONFIG_EXAMPLE_NODE_TYPE）→ 创建并挂载灯设备 → 初始化网络并连接 WiFi → 启动本地控制 → 设置自定义 mDNS TXT 记录。启动成功后的串口日志形如：

I (10552) esp_weaver: Weaver initialized: ESP Weaver Device (Lightbulb), node_id: 6055F9F919EC I (10562) app_main: Node ID: 6055F9F919EC I (10572) esp_weaver_local_ctrl: Starting local control with HTTP transport and security version: 1 I (10592) esp_weaver_local_ctrl: PoP for local control: 8f820513 I (10602) esp_weaver_local_ctrl: Local control started on port 8080, node_id: 6055F9F919EC

在 Home Assistant 中操作灯光时，设备串口会打印控制日志：

I (37132) app_light: Light received 1 params in write I (37132) app_light: Light.Power = false I (40532) app_light: Light received 1 params in write I (40532) app_light: Light.Brightness = 63 I (42272) app_light: Light received 1 params in write I (42272) app_light: Light.Hue = 141

九、实战示例二：IMU 手势检测（imu_gesture）

examples/weaver/imu_gesture 展示了 Weaver 模型在「事件上报型」设备上的用法——设备本身不可被写，而是通过传感器检测手势并向 Home Assistant 推送状态。详见其 README_CN.md。

支持的硬件：支持芯片的开发板 + BMI270 传感器。支持的手势包括：toss（抛起）、flip（翻转）、shake（摇晃）、rotation（旋转）、push（推动）、circle（画圆）、clap_single/clap_double/clap_triple（单/双/三次拍手）。

该示例在 esp_weaver_standard_types.h 中对应了完整的手势参数类型（esp.param.gesture-toss、esp.param.gesture-flip等）以及三轴方向参数（esp.param.orientation-x/y/z）。设备检测到手势后，通过esp_weaver_param_update_and_report()将事件值实时推送给 Home Assistant——这正是 Weaver 参数「实时推送」能力的典型应用，也说明同一种模型既能承载「下行控制」也能承载「上行事件」。

十、接入 Home Assistant

设备侧完成启动后，接入 Home Assistant 的步骤为：

1. 在 Home Assistant 中安装ESP-Weaver 自定义集成（乐鑫开发的对应 Home Assistant 集成组件，通过 esp_local_ctrl 协议实现对 ESP 设备的本地发现与控制）；
2. 设备连接 WiFi 后会被自动发现（零配置，无需手动录入 IP）；
3. 输入设备的 PoP 码完成配对；
4. 设备实体（电源、亮度、颜色，或手势类型、置信度、方向、角度）将出现在 Home Assistant 中。

故障排查要点（来自 led_light 示例文档）：

• WiFi 连接失败：检查 menuconfig 中的 WiFi 凭据，确保设备在 WiFi 范围内；
• 设备未被发现：确保 Home Assistant 和 ESP 设备在同一局域网，且已安装 ESP-Weaver 集成；
• PoP 码被拒绝：验证输入的 PoP 码与串口日志显示的一致。

十一、测试套件：如何验证你的实现

组件在 components/esp_weaver/test_apps 中包含完整的测试套件（共 18 个用例），可直接验证 SDK 行为，也是学习 API 语义的最佳参考。测试覆盖范围（见 test_apps/README.md）：

运行方式：

cd components/esp_weaver/test_apps idf.py set-target esp32 idf.py build flash monitor

监视器提示时输入*运行全部用例，或输入标签（如[init]）进行过滤。测试用例实现见 test_esp_weaver.c，其中对单例约束、重名参数拒绝、类型不匹配等边界行为的断言，直接反映了 SDK 的语义约束。

十二、总结

ESP Weaver 是 ESP-IoT-Solution 为「Home Assistant 本地化智能家居」场景提供的一站式设备端 SDK：通过 esp_local_ctrl + mDNS 实现零配置发现与毫秒级局域网控制，通过 Curve25519 + AES-CTR + PoP 保证端到端安全，通过简洁的设备/参数模型让开发者以极低的学习成本接入 Home Assistant 生态。无论是控制类设备（如 led_light）还是事件上报类设备（如 imu_gesture），都可以在统一模型下快速实现。

建议下一步：阅读 组件 README 与 头文件 API 文档 获取完整参考，运行 led_light 示例 完成端到端验证，再参考 test_apps 中的用例规范你的设备模型边界。

• 物联网
• 嵌入式
• 驱动开发
• 硬件开发