ESP Weaver

[English]

支持的芯片

ESP32

ESP32-C2

ESP32-C3

ESP32-C5

ESP32-C6

ESP32-C61

ESP32-S3

ESP Weaver 是一个用于构建智能家居设备的设备端 SDK，支持 Home Assistant 本地发现和控制。基于 ESP-IDF 的 esp_local_ctrl 组件和 mDNS 服务发现，实现毫秒级的局域网内通信，无需依赖云服务。

该 SDK 提供了简单的设备/参数模型，支持设备创建、参数管理、写入回调和参数实时推送。支持 Security1 协议（Curve25519 + AES-CTR）并结合拥有证明 (PoP) 实现安全通信。

功能特性

基于 mDNS + esp_local_ctrl 的低延迟本地控制
离线可用，无需互联网连接
基于拥有证明 (PoP) 的端到端加密
零配置设备发现
简洁的设备/参数模型，用于智能家居集成
兼容 ESP-Weaver Home Assistant 自定义集成

架构

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

ESP 设备启动后连接 WiFi 并通过 mDNS 广播服务
Home Assistant 中的 ESP-Weaver 集成发现设备
用户输入设备的 PoP 码完成配对
通过 Local Control 协议进行双向通信

示例

LED 灯示例: weaver/led_light。RGB LED 灯控制，支持电源、亮度、HSV 颜色和色温。

API 参考

Header File

components/esp_weaver/include/esp_weaver.h

Functions

esp_weaver_param_val_t esp_weaver_bool(bool bval)

Create a Weaver value with a boolean.

参数: bval – [in] Boolean value to store
返回: Weaver param value structure with type WEAVER_VAL_TYPE_BOOLEAN

esp_weaver_param_val_t esp_weaver_int(int ival)

Create a Weaver value with an integer.

参数: ival – [in] Integer value to store (signed 32-bit)
返回: Weaver param value structure with type WEAVER_VAL_TYPE_INTEGER

esp_weaver_param_val_t esp_weaver_float(float fval)

Create a Weaver value with a float.

参数: fval – [in] Floating-point value to store (32-bit)
返回: Weaver param value structure with type WEAVER_VAL_TYPE_FLOAT

esp_weaver_param_val_t esp_weaver_str(const char *sval)

Create a Weaver value with a string.

参数: sval – [in] Pointer to a null-terminated string
返回: Weaver param value structure with type WEAVER_VAL_TYPE_STRING

esp_weaver_param_val_t esp_weaver_obj(const char *val)

Create a Weaver value with a JSON object string.

参数: val – [in] Pointer to a null-terminated JSON object string (e.g. “{"name”:”value”}”)
返回: Weaver param value structure with type WEAVER_VAL_TYPE_OBJECT

esp_weaver_param_val_t esp_weaver_array(const char *val)

Create a Weaver value with a JSON array string.

参数: val – [in] Pointer to a null-terminated JSON array string (e.g. “[1,2,3]”)
返回: Weaver param value structure with type WEAVER_VAL_TYPE_ARRAY

esp_weaver_node_t *esp_weaver_node_init(const esp_weaver_config_t *config, const char *name, const char *type)

Initialize the Weaver node (singleton)

Only one node may exist at a time. Calling this again without esp_weaver_node_deinit() will return NULL.

参数

config – [in] Pointer to configuration structure (must not be NULL, use ESP_WEAVER_CONFIG_DEFAULT())
name – [in] Node name (must not be NULL)
type – [in] Node type (must not be NULL)

返回

Node handle on success, or NULL on failure

esp_err_t esp_weaver_node_deinit(const esp_weaver_node_t *node)

Deinitialize the Weaver node and free all resources.

This function frees all devices, parameters, and node resources. After calling this, esp_weaver_node_init() can be called again.

参数

node – [in] Node handle returned by esp_weaver_node_init() (must not be NULL)

返回

ESP_OK: Node deinitialized successfully
ESP_ERR_INVALID_STATE: Node not initialized
ESP_ERR_INVALID_ARG: Invalid parameter

const char *esp_weaver_get_node_id(void)

Get Node ID.

Returns pointer to the NULL terminated Node ID string.

返回: Pointer to a NULL terminated Node ID string, or NULL if not initialized

esp_err_t esp_weaver_node_add_device(const esp_weaver_node_t *node, esp_weaver_device_t *device)

Add a device to a node.

参数

node – [in] Node handle (must not be NULL)
device – [in] Device handle (must not be NULL)

返回

ESP_OK: Device added successfully
ESP_ERR_INVALID_ARG: Invalid parameter or duplicate device name

esp_err_t esp_weaver_node_remove_device(const esp_weaver_node_t *node, esp_weaver_device_t *device)

Remove a device from a node.

备注

The device should be removed before deleting it with esp_weaver_device_delete().

参数

node – [in] Node handle (must not be NULL)
device – [in] Device handle (must not be NULL)

返回

ESP_OK: Device removed successfully
ESP_ERR_INVALID_ARG: Invalid parameter
ESP_ERR_NOT_FOUND: Device not found in node

esp_weaver_device_t *esp_weaver_device_create(const char *dev_name, const char *type, void *priv_data)

Create a Device.

备注

The device created needs to be added to a node using esp_weaver_node_add_device().

参数

dev_name – [in] The unique device name (must not be NULL)
type – [in] Device type (must not be NULL, e.g., “esp.device.lightbulb”)
priv_data – [in] Private data associated with the device (can be NULL). This will be passed to callbacks

返回

Pointer to the created device, or NULL on failure

esp_err_t esp_weaver_device_delete(esp_weaver_device_t *device)

Delete a Device.

This API will delete a device created using esp_weaver_device_create(). All parameters associated with the device are also freed.

备注

The device should first be removed from the node using esp_weaver_node_remove_device() before deleting.

参数

device – [in] Device handle (must not be NULL)

返回

ESP_OK: Device deleted successfully
ESP_ERR_INVALID_ARG: Invalid parameter

esp_err_t esp_weaver_device_add_param(esp_weaver_device_t *device, esp_weaver_param_t *param)

Add a parameter to a device.

备注

A device supports up to 255 parameters.

参数

device – [in] Device handle (must not be NULL)
param – [in] Parameter handle (must not be NULL)

返回

ESP_OK: Parameter added successfully
ESP_ERR_INVALID_ARG: Invalid parameter or duplicate parameter name
ESP_ERR_NO_MEM: Maximum number of parameters reached

esp_err_t esp_weaver_device_add_bulk_cb(esp_weaver_device_t *device, esp_weaver_device_bulk_write_cb_t write_cb)

Add bulk write callback for a device.

参数

device – [in] Device handle (must not be NULL)
write_cb – [in] Bulk write callback function (must not be NULL)

返回

ESP_OK: Callback set successfully
ESP_ERR_INVALID_ARG: Invalid parameter

esp_err_t esp_weaver_device_assign_primary_param(esp_weaver_device_t *device, esp_weaver_param_t *param)

Assign a primary parameter.

Assign a parameter (already added using esp_weaver_device_add_param()) as a primary parameter, which can be used by clients to give prominence to it.

参数

device – [in] Device handle (must not be NULL)
param – [in] Parameter handle (must not be NULL)

返回

ESP_OK: Primary parameter assigned successfully
ESP_ERR_INVALID_ARG: Invalid parameter
ESP_ERR_NOT_FOUND: Parameter not found in device

const char *esp_weaver_device_get_name(const esp_weaver_device_t *device)

Get device name from handle.

参数: device – [in] Device handle (must not be NULL)
返回: NULL terminated device name string, or NULL on failure

void *esp_weaver_device_get_priv_data(const esp_weaver_device_t *device)

Get device private data from handle.

参数: device – [in] Device handle (must not be NULL)
返回: Pointer to the private data, or NULL if no private data found

esp_weaver_param_t *esp_weaver_device_get_param_by_name(const esp_weaver_device_t *device, const char *param_name)

Get parameter by name.

Get handle for a parameter based on the name.

参数

device – [in] Device handle (must not be NULL)
param_name – [in] Parameter name to search (must not be NULL)

返回

Parameter handle on success, or NULL on failure

esp_weaver_param_t *esp_weaver_device_get_param_by_type(const esp_weaver_device_t *device, const char *param_type)

Get parameter by type.

Get handle for a parameter based on the type.

参数

device – [in] Device handle (must not be NULL)
param_type – [in] Parameter type to search (must not be NULL, e.g., “esp.param.power”)

返回

Parameter handle on success, or NULL on failure

esp_weaver_param_t *esp_weaver_param_create(const char *param_name, const char *type, esp_weaver_param_val_t val, uint8_t properties)

Create a Parameter.

备注

The parameter created needs to be added to a device using esp_weaver_device_add_param(). Parameter name should be unique in a given device.

参数

param_name – [in] Name of the parameter (must not be NULL)
type – [in] Parameter type (must not be NULL, e.g., “esp.param.power”)
val – [in] Value of the parameter. This also specifies the type that will be assigned to this parameter. You can use esp_weaver_bool(), esp_weaver_int(), esp_weaver_float() or esp_weaver_str() functions as the argument here. Eg, esp_weaver_bool(true)
properties – [in] Properties of the parameter, which will be a logical OR of flags in esp_weaver_param_property_flags_t

返回

Pointer to the created parameter, or NULL on failure

esp_err_t esp_weaver_param_delete(esp_weaver_param_t *param)

Delete a Parameter.

Use this to clean up a parameter that was created with esp_weaver_param_create() but not added to a device (e.g., if esp_weaver_device_add_param() failed).

备注

Parameters that have been added to a device are automatically freed when the device is deleted with esp_weaver_device_delete().

参数

param – [in] Parameter handle (must not be NULL)

返回

ESP_OK: Parameter deleted successfully
ESP_ERR_INVALID_ARG: Invalid parameter

esp_err_t esp_weaver_param_add_ui_type(esp_weaver_param_t *param, const char *ui_type)

Add a UI Type to a parameter.

参数

param – [in] Parameter handle (must not be NULL)
ui_type – [in] String describing the UI Type (must not be NULL, e.g., “esp.ui.toggle”)

返回

ESP_OK: UI type added successfully
ESP_ERR_INVALID_ARG: Invalid parameter
ESP_ERR_NO_MEM: Memory allocation failed

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)

Add bounds for an integer/float parameter.

Eg. esp_weaver_param_add_bounds(brightness_param, esp_weaver_int(0), esp_weaver_int(100), esp_weaver_int(5));

参数

param – [in] Parameter handle (must not be NULL)
min – [in] Minimum allowed value
max – [in] Maximum allowed value (must be >= min)
step – [in] Minimum stepping (set to 0 if no specific value is desired)

返回

ESP_OK: Bounds added successfully
ESP_ERR_INVALID_ARG: Invalid parameter
ESP_ERR_NO_MEM: Memory allocation failed

const char *esp_weaver_param_get_name(const esp_weaver_param_t *param)

Get parameter name from handle.

参数: param – [in] Parameter handle (must not be NULL)
返回: NULL terminated parameter name string, or NULL on failure

const esp_weaver_param_val_t *esp_weaver_param_get_val(const esp_weaver_param_t *param)

Get parameter value.

备注

This does not call any explicit functions to read value from hardware/driver.

参数: param – [in] Parameter handle (must not be NULL)
返回: Pointer to parameter value, or NULL on failure

esp_err_t esp_weaver_param_update(esp_weaver_param_t *param, esp_weaver_param_val_t val)

Update a parameter.

This will just update the value of a parameter without actually reporting it. This can be used when multiple parameters need to be reported together. Eg. If x parameters are to be reported, this API can be used for the first x - 1 parameters and the last one can be updated using esp_weaver_param_update_and_report(). This will report all parameters which were updated prior to this call.

Sample:

esp_weaver_param_update(param1, esp_weaver_int(180)); esp_weaver_param_update(param2, esp_weaver_int(80)); esp_weaver_param_update_and_report(param3, esp_weaver_int(50));

参数

param – [in] Parameter handle (must not be NULL)
val – [in] New value of the parameter

返回

ESP_OK: Parameter updated successfully
ESP_ERR_INVALID_ARG: Invalid parameter or type mismatch
ESP_ERR_NO_MEM: Memory allocation failed (for string/object/array types)

esp_err_t esp_weaver_param_update_and_report(esp_weaver_param_t *param, esp_weaver_param_val_t val)

Update and report a parameter.

Calling this API will update the parameter and report it to connected clients. This should be used whenever there is any local change.

参数

param – [in] Parameter handle (must not be NULL)
val – [in] New value of the parameter

返回

ESP_OK: Parameter updated and reported successfully
ESP_ERR_INVALID_ARG: Invalid parameter or type mismatch
ESP_ERR_NO_MEM: Memory allocation failed (for string/object/array types)

esp_err_t esp_weaver_local_ctrl_set_pop(const char *pop)

Set Proof of Possession (PoP) for local control security.

备注

This must be called before esp_weaver_local_ctrl_start() for it to take effect. If not called, a random PoP will be generated and stored in NVS.

参数

pop – [in] NULL terminated PoP string. Pass NULL to clear any previously set custom PoP.

返回

ESP_OK: PoP set successfully
ESP_ERR_INVALID_ARG: Empty PoP string
ESP_ERR_NO_MEM: Memory allocation failed

const char *esp_weaver_local_ctrl_get_pop(void)

Get the Proof of Possession (PoP) for local control.

Returns the current PoP string. The PoP is resolved in this order:

User-set PoP (via esp_weaver_local_ctrl_set_pop())
PoP stored in NVS (from a previous boot)
Auto-generated random PoP (saved to NVS for persistence)

备注

This should be called after esp_weaver_local_ctrl_start() to ensure the PoP has been resolved.

返回: PoP string on success, or NULL on failure

esp_err_t esp_weaver_local_ctrl_start(void)

Start local control service (HTTP + mDNS)

All configuration (HTTP port, security version, etc.) is read from Kconfig.

返回

ESP_OK: Local control started successfully
ESP_ERR_INVALID_STATE: Weaver not initialized or already started
ESP_ERR_NO_MEM: Memory allocation failed

esp_err_t esp_weaver_local_ctrl_set_txt(const char *key, const char *value)

Set a custom mDNS TXT record for the local control service.

Must be called after esp_weaver_local_ctrl_start().

参数

key – [in] TXT record key (must not be NULL)
value – [in] TXT record value (must not be NULL)

返回

ESP_OK: TXT record set successfully
ESP_ERR_INVALID_STATE: Local control not started
ESP_ERR_INVALID_ARG: Invalid parameter

esp_err_t esp_weaver_local_ctrl_stop(void)

Stop local control service.

返回

ESP_OK: Local control stopped successfully
ESP_ERR_INVALID_STATE: Local control not started

esp_err_t esp_weaver_local_ctrl_send_params(void)

Push current parameter values to local control clients.

Call this after updating parameters with esp_weaver_param_update() to push the changes to connected clients. Not needed after esp_weaver_param_update_and_report() which sends automatically.

返回

ESP_OK: Parameters sent successfully
ESP_ERR_INVALID_STATE: Local control not started
ESP_FAIL: Failed to generate or send parameters

Unions

union esp_weaver_val_t

#include <esp_weaver.h>

ESP Weaver Value data union.

Union containing the actual data for Weaver values. The active member is determined by the type field in the parent esp_weaver_param_val_t structure.

备注

Only access the member corresponding to the value type.

Public Members

bool b: Boolean data value

int i: Integer data value (signed 32-bit)

float f: Floating-point data value (32-bit)

char *s: String data value (pointer to null-terminated string)

Structures

struct esp_weaver_param_val_t

ESP Weaver Parameter Value.

Complete Weaver value with its type and associated data. Provides a unified way to handle different data types in the Weaver protocol.

备注

The type field determines which member of the val union is valid.

备注

For STRING type, val.s points to dynamically allocated memory.

Public Members

esp_weaver_val_type_t type: Type of the value (boolean, integer, float, or string)

esp_weaver_val_t val: Union containing the actual value data

struct esp_weaver_write_ctx_t

Write request Context.

Public Members

esp_weaver_req_src_t src: Source of the write request

struct esp_weaver_param_write_req_t

Parameter write request payload.

Public Members

esp_weaver_param_t *param: Parameter handle

esp_weaver_param_val_t val: Value to write

struct esp_weaver_config_t

ESP Weaver Configuration.

Public Members

const char *node_id: Custom node ID (max 32 chars). NULL to auto-generate from MAC address

Macros

ESP_WEAVER_CONFIG_DEFAULT(): Default Weaver configuration (auto-generated node ID)

Type Definitions

typedef struct esp_weaver_node esp_weaver_node_t

ESP Weaver Node handle.

Opaque structure representing a Weaver node instance.

typedef struct esp_weaver_device esp_weaver_device_t

ESP Weaver Device handle.

Opaque structure representing a device attached to a Weaver node.

typedef struct esp_weaver_param esp_weaver_param_t

ESP Weaver Parameter handle.

Opaque structure representing a single parameter within a device.

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)

Callback for bulk parameter value write requests.

This callback is invoked when multiple parameters are received in a single request.

备注

This callback may execute in a transport-specific task context (e.g., HTTPD task), not the main task. Avoid blocking operations and ensure any shared state access is properly synchronized.

Param device

[in] Device handle (must not be NULL)

Param write_req

[in] Array of write requests (must not be NULL)

Param count

[in] Number of write requests in the array

Param priv_data

[in] Pointer to the private data passed while creating the device

Param ctx

[in] Context associated with the request

Return

ESP_OK: Success
ESP_ERR_INVALID_ARG: Invalid parameter
ESP_FAIL: Error

Enumerations

enum esp_weaver_val_type_t

ESP Weaver Value type.

Supported data types for Weaver parameter values.

Values:

enumerator WEAVER_VAL_TYPE_INVALID: Invalid

enumerator WEAVER_VAL_TYPE_BOOLEAN: Boolean

enumerator WEAVER_VAL_TYPE_INTEGER: Integer. Mapped to a 32 bit signed integer

enumerator WEAVER_VAL_TYPE_FLOAT: Floating point number

enumerator WEAVER_VAL_TYPE_STRING: NULL terminated string

enumerator WEAVER_VAL_TYPE_OBJECT: NULL terminated JSON Object string Eg. {“name”:”value”}

enumerator WEAVER_VAL_TYPE_ARRAY: NULL terminated JSON Array string Eg. [1,2,3]

enum esp_weaver_param_property_flags_t

Param property flags.

Values:

enumerator PROP_FLAG_WRITE: Parameter is writable

enumerator PROP_FLAG_READ: Parameter is readable

enumerator PROP_FLAG_PERSIST: Parameter value is persisted in NVS

enum esp_weaver_req_src_t

Parameter read/write request source.

Values:

enumerator ESP_WEAVER_REQ_SRC_INIT: Request triggered in the init sequence i.e. when a value is found in persistent memory for parameters with PROP_FLAG_PERSIST

enumerator ESP_WEAVER_REQ_SRC_LOCAL: Request from local control (HTTP)

enumerator ESP_WEAVER_REQ_SRC_MAX: This will always be the last value. Any value equal to or greater than this should be considered invalid

提供有关此文档的反馈