From a3c26b95484fbb5671601900938628f6c298b37d Mon Sep 17 00:00:00 2001
From: Myqfeng <viagrahuang@outlook.com>
Date: Mon, 19 Oct 2026 19:33:08 +0800
Subject: [PATCH 1/3] =?UTF-8?q?feat:=20=E6=96=B0=E5=A2=9E=20ESP=20?=
 =?UTF-8?q?=E6=8F=92=E4=BB=B6=E8=AF=B4=E6=98=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .vitepress/config/cn.ts        |  10 +++
 .vitepress/config/en.ts        |  10 +++
 en/guide/embed/capabilities.md |  35 ++++++++
 en/guide/embed/index.md        |  22 +++++
 en/guide/embed/quick-start.md  | 148 +++++++++++++++++++++++++++++++++
 en/guide/embed/requirements.md |  47 +++++++++++
 en/guide/installation_esp.md   |  37 +++++++++
 guide/embed/capabilities.md    |  35 ++++++++
 guide/embed/index.md           |  22 +++++
 guide/embed/quick-start.md     | 148 +++++++++++++++++++++++++++++++++
 guide/embed/requirements.md    |  47 +++++++++++
 guide/installation_esp.md      |  41 +++++++++
 12 files changed, 602 insertions(+)
 create mode 100644 en/guide/embed/capabilities.md
 create mode 100644 en/guide/embed/index.md
 create mode 100644 en/guide/embed/quick-start.md
 create mode 100644 en/guide/embed/requirements.md
 create mode 100644 en/guide/installation_esp.md
 create mode 100644 guide/embed/capabilities.md
 create mode 100644 guide/embed/index.md
 create mode 100644 guide/embed/quick-start.md
 create mode 100644 guide/embed/requirements.md
 create mode 100644 guide/installation_esp.md

diff --git a/.vitepress/config/cn.ts b/.vitepress/config/cn.ts
index 723a8cf..92e9412 100644
--- a/.vitepress/config/cn.ts
+++ b/.vitepress/config/cn.ts
@@ -14,6 +14,7 @@ export const cn = defineConfig({
           { text: '下载', link: '/guide/download' },
           { text: '安装 CLI', link: '/guide/installation' },
           { text: '安装 GUI', link: '/guide/installation_gui' },
+          { text: '安装 Espressif 组件', link: '/guide/installation_esp' },
           { text: '常见问题', link: '/guide/faq' },
         ],
       },
@@ -64,6 +65,15 @@ export const cn = defineConfig({
           { text: 'MCTier 多功能快速组网', link: '/guide/gui/mctier' },
         ],
       },
+      {
+        text: '嵌入式设备组网',
+        link: '/guide/embed/index',
+        items: [
+          { text: '快速上手', link: '/guide/embed/quick-start' },
+          { text: '使用环境要求', link: '/guide/embed/requirements' },
+          { text: '支持能力说明', link: '/guide/embed/capabilities' },
+        ],
+      },
       {
         items: [
           { text: '关于 P2P', link: '/guide/aboutp2p' },
diff --git a/.vitepress/config/en.ts b/.vitepress/config/en.ts
index 30fa997..7598714 100644
--- a/.vitepress/config/en.ts
+++ b/.vitepress/config/en.ts
@@ -14,6 +14,7 @@ export const en = defineConfig({
           { text: 'Download', link: '/en/guide/download' },
           { text: 'Installation CLI', link: '/en/guide/installation' },
           { text: 'Installation GUI', link: '/en/guide/installation_gui' },
+          { text: 'Install Espressif Component', link: '/en/guide/installation_esp' },
           { text: 'FAQ', link: '/en/guide/faq' },
         ],
       },
@@ -61,6 +62,15 @@ export const en = defineConfig({
           { text: 'QtEasyTier', link: '/en/guide/gui/qteasytier' },
         ],
       },
+      {
+        text: 'Embedded Device Networking',
+        link: '/en/guide/embed/index',
+        items: [
+          { text: 'Quick Start', link: '/en/guide/embed/quick-start' },
+          { text: 'Requirements', link: '/en/guide/embed/requirements' },
+          { text: 'Supported Capabilities', link: '/en/guide/embed/capabilities' },
+        ],
+      },
       {
         items: [
           { text: 'Performance Testing', link: '/en/guide/perf' },
diff --git a/en/guide/embed/capabilities.md b/en/guide/embed/capabilities.md
new file mode 100644
index 0000000..ae29ac1
--- /dev/null
+++ b/en/guide/embed/capabilities.md
@@ -0,0 +1,35 @@
+# Supported Capabilities
+
+EasyTier-ESP does not implement the complete EasyTier protocol. The following describes the capabilities supported by this project.
+
+| Capability | Status | Description |
+| --- | --- | --- |
+| TCP client entry | ✅ Supported | `[[peer]].uri = "tcp://host:port"`; supports IPv4 and DNS hostnames |
+| Multiple entries | ✅ Supported | No limit on the number of entries; concurrent connections are limited by Kconfig (default 6, range 1..8) |
+| Non-secure mode handshake | ✅ Supported | Network name + secret digest verification; not Noise |
+| Automatic keepalive | ✅ Supported | Automatically detects disconnections and reconnects |
+| Control-plane RPC | ✅ Supported | Used for control-plane requests/responses such as route synchronization |
+| Route synchronization | ✅ Supported | Automatically learns the virtual network topology and next hops |
+| Data forwarding (relay) | ✅ Supported | Can act as a relay to forward data for other nodes |
+| AES-128-GCM | ✅ Supported | Data-plane encryption |
+| Disable encryption | ✅ Supported | Can be disabled via `flags.enable_encryption = false` |
+| Static virtual IPv4 | ✅ Supported | `ipv4 = "10.144.144.10/24"` |
+| DHCP auto-assignment | ✅ Supported | `dhcp = true` or CIDR; falls back to `10.126.126.0/24` |
+| lwIP virtual network interface | ✅ Supported | Standard virtual interface; does not take over the default route |
+| Multiple instances | ✅ Supported | Each `et::Inst` exclusively owns its resources |
+| Event callbacks | ✅ Supported | State change notifications; `PeerDown` is currently reserved |
+| Inbound listening | ❌ Not supported | The component does not listen on ports and cannot be actively connected to by other nodes |
+| UDP / KCP / QUIC / WebSocket | ❌ Not supported | Only TCP client transport is implemented |
+| Noise secure mode | ❌ Not supported | Only non-secure mode handshake |
+| Subnet proxy / `proxy_network` | ❌ Not supported | Configuration fields are ignored |
+| Static routes / `routes` | ❌ Not supported | Configuration fields are ignored |
+| Broadcast / multicast | ❌ Not supported | Outbound broadcast/multicast is dropped and counted |
+| IPv6 entries | ❌ Not supported | `peer.uri` only accepts TCP + IPv4/DNS |
+| Zstd compression | ❌ Not supported | Receiving Zstd-compressed RPCs causes an error and revokes Ready |
+| Graphical interface / Web panel | ❌ Not provided | Only the C++ component and example are provided |
+| TLS | ❌ Not supported | TCP transport itself is not encrypted; the data plane is protected by AES-GCM |
+
+
+:::tip
+Capabilities not listed are considered **unsupported** by default.
+:::
diff --git a/en/guide/embed/index.md b/en/guide/embed/index.md
new file mode 100644
index 0000000..5e5466b
--- /dev/null
+++ b/en/guide/embed/index.md
@@ -0,0 +1,22 @@
+# Embedded Device Networking
+
+:::warning
+EasyTier-ESP is currently in preview. Only basic features are implemented, its APIs may change in the future, and unknown issues may exist. Use it with caution in production environments.
+:::
+
+EasyTier-ESP is a lightweight C++ implementation of the EasyTier networking protocol on ESP-IDF.
+It can be used for cross-site networking of ESP32 embedded devices, making it easy for IoT devices to join an EasyTier virtual network.
+This component is not designed to implement all EasyTier features; instead, it implements a subset that matches the performance of ESP32 microcontrollers and the requirements of IoT devices.
+
+**Component information**:
+- ESP Component Registry: myqfeng/easytier-esp
+- Currently compatible with: ESP-IDF >=6.1
+- Verified target: ESP32-S3-N16R8
+
+**Source repositories**:
+- [Github.com/EasyTier/easytier-esp](https://github.com/EasyTier/easytier-esp)
+- [Cnb.cool/myqfeng/qteasytier/easytier-esp](https://cnb.cool/myqfeng/qteasytier/easytier-esp)
+
+:::tip
+For more detailed reference documentation, visit the [EasyTier-ESP documentation site](https://esp.qtet.cn).
+:::
diff --git a/en/guide/embed/quick-start.md b/en/guide/embed/quick-start.md
new file mode 100644
index 0000000..e3e2a11
--- /dev/null
+++ b/en/guide/embed/quick-start.md
@@ -0,0 +1,148 @@
+# Quick Start
+
+### Prerequisites
+
+- Install **ESP-IDF 6.1** (other versions have not been verified, and consistent behavior is not guaranteed);
+- An **ESP32-S3** development board (N16R8 recommended, with **PSRAM enabled**; otherwise the default configuration may easily fail during allocation);
+- An accessible EasyTier entry point (optional; the example can still be built and run without one, but networking will not succeed).
+## Example Project
+
+### Clone the Source Code
+
+```bash
+# GitHub
+git clone https://github.com/EasyTier/easytier-esp.git
+# Or CNB in China
+# git clone https://cnb.cool/myqfeng/qteasytier/easytier-esp.git
+cd easytier-esp
+```
+
+The `main/` directory is a complete example project, including Wi-Fi connection, networking, status printing, and an HTTP control service. The component source and the example are built within the same project, so **no additional component installation is required**.
+
+### Create `main/easytier.toml`
+
+This file may contain sensitive information and is ignored by `.gitignore`, so you need to create it manually:
+
+```toml
+instance_name = "esp32-example"
+hostname = "esp32-example"
+dhcp = true
+
+[network_identity]
+network_name = "esp-demo"
+network_secret = "<YOUR_NETWORK_SECRET>"
+
+[[peer]]
+uri = "tcp://192.0.2.10:11010"
+
+[flags]
+mtu = 1380
+enable_encryption = true
+```
+
+Key points:
+- Replace `192.0.2.10:11010` with your entry address and `<YOUR_NETWORK_SECRET>` with your network secret;
+- To use a static virtual address, remove `dhcp = true` and use `ipv4 = "10.144.144.10/24"` instead (if both are present, the static address takes precedence);
+- The example can still be built and run without this file, but it will only connect to Wi-Fi and will not start EasyTier.
+
+### Configure Wi-Fi
+
+```bash
+idf.py menuconfig
+```
+
+Go to the **EasyTier-ESP Example** menu and fill in:
+- `EXAMPLE_WIFI_SSID` / `EXAMPLE_WIFI_PASSWORD`;
+- `EXAMPLE_EASYTIER_TOML_ENABLED` (enabled by default; loads the embedded TOML at startup and starts networking).
+
+The example's `sdkconfig.defaults` already sets `LWIP_MAX_SOCKETS=24` and `MAIN_TASK_STACK_SIZE=8192`. **Do not reduce these values**, otherwise entry connections or TOML parsing may fail.
+
+### Build and Flash
+
+```bash
+idf.py set-target esp32s3
+idf.py build
+idf.py -p /dev/ttyUSB0 flash monitor   # Use COMx on Windows
+```
+
+### Observe After Power-On
+
+After startup, first check whether Wi-Fi has obtained an IP:
+
+```text
+I (...) et_example: got ip: 192.168.1.50
+```
+
+When networking succeeds, you will see:
+
+```text
+I (...) ET.PROTO: handshake ok, peer=...
+I (...) ET.PROTO: network ready: 1 reachable peer(s)
+I (...) et_example: status: state=ready ... vip=10.144.144.10/24 direct=1 ...
+```
+
+The status is printed every 10 seconds. Watch for changes in `state`, `vip`, `direct`, and `routes`.
+
+The example also runs an HTTP service on port 80: visiting `http://<device-ip>/` or `/toggle` toggles the **GPIO38** level. The device IP can be its physical Wi-Fi address, or, after networking succeeds, the virtual IP from any EasyTier node.
+
+## Basic Component Usage (When Integrating It Yourself)
+### Install the Component
+
+Install the EasyTier-ESP component through the ESP-IDF package manager:
+
+```bash
+idf.py add-dependency qtet/easytier-esp
+```
+
+Or add the dependency to your application's main/idf_component.yml:
+
+```yaml
+dependencies:
+  myqfeng/easytier-esp: "^0.0.2"
+```
+
+ESP-IDF will then automatically download and install the component when building your application.
+
+### TOML Configuration
+
+EasyTier-ESP uses the same TOML configuration text as upstream. Unsupported settings are not parsed (i.e., silently ignored).
+
+### Core Usage
+
+The component exposes only one core class: `et::Inst` (RAII, namespace `et`). Its lifecycle consists of five steps:
+
+```cpp
+et::RuntimeOptions options{};
+options.on_event = &on_event;              // Event callback
+
+et::Inst inst(toml_text, options);         // Construct: parse TOML, validate, prepare resources
+if (!inst.valid()) { /* Check last_error() and logs */ }
+
+ESP_ERROR_CHECK(inst.start());             // Start: create connections, network interface, tasks
+// After Wi-Fi/Ethernet obtains an IP:
+ESP_ERROR_CHECK(inst.connect());           // Connect: start connecting to entry points
+// (To disconnect: inst.disconnect();)
+inst.stop(5000);                           // Stop; destructor releases resources automatically
+```
+
+A few key points:
+
+| Item | Description |
+| --- | --- |
+| `start()` success ≠ networking available | Wait for the `NetworkReady` event or `Status.state == Ready` |
+| After Wi-Fi reconnects | Must call `connect()` again after GOT_IP |
+| Task stack | Construction runs on the caller's stack; task stack ≥ 8 KiB |
+| Changing configuration | Cannot be changed at runtime; destroy the instance and create a new one with the new TOML |
+| Configuration failure behavior | Unsupported fields are silently ignored; invalid values for supported fields cause construction to fail |
+| Memory | A single instance uses about 92 KiB resident; each peer connection uses about 12 KiB; PSRAM is recommended |
+
+## Troubleshooting Common Symptoms
+
+| Symptom | Check first |
+| --- | --- |
+| No `got ip` on serial | Wi-Fi SSID/password, signal |
+| `got ip` but no `network ready` | Entry address/port, network name and secret |
+| `network ready` but ping fails | Peer routes, firewall, virtual subnet conflicts |
+| `easytier.toml` not found | Create `main/easytier.toml` and rebuild |
+
+**For more detailed documentation, visit the [EasyTier-ESP documentation site](https://esp.qtet.cn)**
diff --git a/en/guide/embed/requirements.md b/en/guide/embed/requirements.md
new file mode 100644
index 0000000..59fff64
--- /dev/null
+++ b/en/guide/embed/requirements.md
@@ -0,0 +1,47 @@
+# Environment Requirements
+
+## Software Environment
+
+| Item | Requirement |
+| --- | --- |
+| ESP-IDF | **6.1.x** (verified); the component declares `>=6.1`; behavior consistency is not guaranteed for unverified versions |
+| C++ standard | C++20 |
+| Target chip | **ESP32-S3** (currently verified only on the N16R8 module) |
+| Flash | The example uses a 16 MB module; actual firmware usage depends on the build |
+| PSRAM | **Strongly recommended** |
+
+The component source disables exceptions and RTTI; the component implementation depends on `esp_netif`, `lwip`, `freertos`, and `mbedtls` (PSA Crypto).
+
+## Memory Requirements
+
+| Item | Approximate size | Description |
+| --- | --- | --- |
+| Single instance resident | About **100 KiB** | Component runtime context |
+| Per peer connection | About 12 KiB | 6 by default at most |
+| Task stack | About 24 KiB | Total for component tasks; adjustable via Kconfig |
+| Queues/buffers | Tens of KiB | Depends on the queue depth configuration |
+
+The figures above are approximate, not hard guarantees; actual usage depends on build logs and runtime measurements. **PSRAM is recommended**, otherwise the default configuration may easily fail during allocation.
+
+## Sockets and Main Task Stack
+
+The example writes the following two settings to `sdkconfig.defaults`:
+
+```ini
+CONFIG_LWIP_MAX_SOCKETS=24
+CONFIG_ESP_MAIN_TASK_STACK_SIZE=8192
+```
+
+- `LWIP_MAX_SOCKETS`: The default of 10 may not be enough for peer entry connections + application sockets + lwIP internal usage;
+- `MAIN_TASK_STACK_SIZE`: TOML parsing and `Inst` construction run on the caller's task stack; at least 8 KiB is recommended.
+
+If you construct `et::Inst` in another task, make sure that task's stack is large enough as well, and use `uxTaskGetStackHighWaterMark()` to check the remaining margin.
+
+
+## Verified Combinations
+
+- ESP32-S3-N16R8 module
+- ESP-IDF 6.1
+- EasyTier 2.6.4 ~ 2.7.0
+
+Other versions are not "explicitly unsupported"; they are simply **unverified**. Before using in production, complete your own build, real-device integration testing, and stability testing.
diff --git a/en/guide/installation_esp.md b/en/guide/installation_esp.md
new file mode 100644
index 0000000..6087e20
--- /dev/null
+++ b/en/guide/installation_esp.md
@@ -0,0 +1,37 @@
+# Installation (Espressif Component)
+
+**EasyTier-ESP** is a lightweight C++ implementation based on the EasyTier networking protocol and can be imported as a component in ESP-IDF.
+
+## Import via the ESP-IDF Component Registry
+
+Add the dependency to your application's `main/idf_component.yml`:
+
+```yaml
+dependencies:
+  myqfeng/easytier-esp: "^0.0.1"
+  idf: ">=6.1"
+```
+
+Or use the command:
+
+```bash
+idf.py add-dependency "myqfeng/easytier-esp^0.0.1"
+idf.py build
+```
+
+The component will be downloaded to the project's `managed_components/` directory during the build.
+
+### Import from Local Source
+
+- Copy or symlink `components/easytier-esp` to your application's `components/` directory; or
+- Add this repository's `components` directory to `EXTRA_COMPONENT_DIRS` in the project's top-level `CMakeLists.txt`.
+
+Then declare the dependency in your application component's `CMakeLists.txt`:
+
+```cmake
+idf_component_register(
+    SRCS "main.cpp"
+    INCLUDE_DIRS "."
+    REQUIRES easytier-esp
+)
+```
diff --git a/guide/embed/capabilities.md b/guide/embed/capabilities.md
new file mode 100644
index 0000000..5e161ad
--- /dev/null
+++ b/guide/embed/capabilities.md
@@ -0,0 +1,35 @@
+# 支持能力说明
+
+EasyTier-ESP 没有实现 EasyTier 的完整协议，以下是本项目支持的能力说明。
+
+| 能力 | 状态 | 说明 |
+| --- | --- | --- |
+| TCP 客户端入口 | ✅ 支持 | `[[peer]].uri = "tcp://host:port"`，支持 IPv4 与 DNS 主机名 |
+| 多入口 | ✅ 支持 | 条目数量无上限；同时连接数由 Kconfig 限制（默认 6，范围 1..8） |
+| 非安全模式握手 | ✅ 支持 | 网络名 + 密钥摘要校验；不是 Noise |
+| 自动保活 | ✅ 支持 | 自动探测断线并重连 |
+| 控制面 RPC | ✅ 支持 | 用于路由同步等控制面请求/响应 |
+| 路由同步 | ✅ 支持 | 自动学习虚拟网络拓扑与下一跳 |
+| 数据转发（中继） | ✅ 支持 | 可作为中继转发其他节点的数据 |
+| AES-128-GCM | ✅ 支持 | 数据面加密 |
+| 关闭加密 | ✅ 支持 | 可通过 `flags.enable_encryption = false` 关闭 |
+| 静态虚拟 IPv4 | ✅ 支持 | `ipv4 = "10.144.144.10/24"` |
+| DHCP 自分配 | ✅ 支持 | `dhcp = true` 或 CIDR；回落 `10.126.126.0/24` |
+| lwIP 虚拟网卡 | ✅ 支持 | 标准虚拟网卡，不抢占默认路由 |
+| 多实例 | ✅ 支持 | 每个 `et::Inst` 独占资源 |
+| 事件回调 | ✅ 支持 | 状态变化通知；`PeerDown` 当前预留 |
+| 入站监听 | ❌ 不支持 | 组件不监听端口，不能被其他节点主动连入 |
+| UDP / KCP / QUIC / WebSocket | ❌ 不支持 | 只实现 TCP 客户端传输 |
+| Noise 安全模式 | ❌ 不支持 | 仅非安全模式握手 |
+| 子网代理 / `proxy_network` | ❌ 不支持 | 配置字段会被忽略 |
+| 静态路由 / `routes` | ❌ 不支持 | 配置字段会被忽略 |
+| 广播 / 组播 | ❌ 不支持 | 出站广播/组播直接丢弃并计数 |
+| IPv6 入口 | ❌ 不支持 | `peer.uri` 只接受 TCP + IPv4/DNS |
+| Zstd 压缩 | ❌ 不支持 | 收到 Zstd 压缩的 RPC 会报错并撤销 Ready |
+| 图形界面 / Web 面板 | ❌ 不提供 | 只有 C++ 组件与示例 |
+| TLS | ❌ 不支持 | TCP 传输本身不加密；数据面由 AES-GCM 保护 |
+
+
+:::tip
+未列出的能力默认视为**未支持**。
+:::
\ No newline at end of file
diff --git a/guide/embed/index.md b/guide/embed/index.md
new file mode 100644
index 0000000..de064c9
--- /dev/null
+++ b/guide/embed/index.md
@@ -0,0 +1,22 @@
+# 嵌入式设备组网
+
+:::warning
+EasyTier-ESP 现在为预览版本，仅实现了部分基础功能，接口在今后可能出现变更，且可能存在未知问题，请慎用于生产环境。
+:::
+
+EasyTier-ESP 是 EasyTier 组网协议在 ESP-IDF 上的 C++ 轻量级实现组件，
+可用于 ESP32 嵌入式设备的异地组网，让物联网设备轻松接入 EasyTier 虚拟网络。
+本组件的设计目标并非 EasyTier 的所有功能，而是实现了与 ESP32 单片机的性能以及物联网设备需求相匹配的功能子集。
+
+**组件信息如下**：
+- ESP组件注册表：myqfeng/easytier-esp
+- 当前适配：ESP-IDF >=6.1
+- 已验证目标：ESP32-S3-N16R8
+
+**开源仓库**：
+- [Github.com/EasyTier/easytier-esp](https://github.com/EasyTier/easytier-esp)
+- [Cnb.cool/myqfeng/qteasytier/easytier-esp](https://cnb.cool/myqfeng/qteasytier/easytier-esp)
+
+:::tip
+更详细的参考文档请前往 [EasyTier-ESP 文档网站](https://esp.qtet.cn) 进行查阅。
+:::
\ No newline at end of file
diff --git a/guide/embed/quick-start.md b/guide/embed/quick-start.md
new file mode 100644
index 0000000..f01f295
--- /dev/null
+++ b/guide/embed/quick-start.md
@@ -0,0 +1,148 @@
+# 快速上手
+
+### 前置准备
+
+- 安装 **ESP-IDF 6.1**
+- 一块 **ESP32-S3** 开发板（推荐 N16R8，**开启 PSRAM**，否则默认配置容易在分配阶段失败）
+- 一个可访问的 EasyTier 入口（可选，没有也能编译运行，只是组网不会成功）。
+## 示例工程
+
+### 克隆源码
+
+```bash
+# GitHub 
+git clone https://github.com/EasyTier/easytier-esp.git
+# 或国内 CNB
+# git clone https://cnb.cool/myqfeng/qteasytier/easytier-esp.git
+cd easytier-esp
+```
+
+`main/` 目录就是一个完整的示例工程，包含 Wi-Fi 连接、组网、状态打印和 HTTP 控制服务，组件源码与示例在同一工程内构建，**无需额外安装组件**。
+
+### 创建 `main/easytier.toml`
+
+该文件可能包含敏感信息，已被 `.gitignore` 忽略，需要手动新建：
+
+```toml
+instance_name = "esp32-example"
+hostname = "esp32-example"
+dhcp = true
+
+[network_identity]
+network_name = "esp-demo"
+network_secret = "<YOUR_NETWORK_SECRET>"
+
+[[peer]]
+uri = "tcp://192.0.2.10:11010"
+
+[flags]
+mtu = 1380
+enable_encryption = true
+```
+
+要点：
+- 把 `192.0.2.10:11010` 换成你的入口地址，`<YOUR_NETWORK_SECRET>` 换成你的网络密钥；
+- 想用静态虚拟地址时，删掉 `dhcp = true`，改为 `ipv4 = "10.144.144.10/24"`（两者同时出现时静态地址优先）；
+- 没有此文件也能编译运行，但只连 Wi-Fi，不启动 EasyTier。
+
+### 配置 Wi-Fi
+
+```bash
+idf.py menuconfig
+```
+
+进入 **EasyTier-ESP 示例** 菜单，填写：
+- `EXAMPLE_WIFI_SSID` / `EXAMPLE_WIFI_PASSWORD`；
+- `EXAMPLE_EASYTIER_TOML_ENABLED`（默认开启，启动时加载嵌入的 TOML 并组网）。
+
+示例的 `sdkconfig.defaults` 已设置 `LWIP_MAX_SOCKETS=24` 和 `MAIN_TASK_STACK_SIZE=8192`，**不要改小**，否则入口连接或 TOML 解析可能失败。
+
+### 编译与烧录
+
+```bash
+idf.py set-target esp32s3
+idf.py build
+idf.py -p /dev/ttyUSB0 flash monitor   # Windows 换成 COMx
+```
+
+### 上电观察
+
+启动后先看 Wi-Fi 拿 IP：
+
+```text
+I (...) et_example: got ip: 192.168.1.50
+```
+
+组网成功会出现：
+
+```text
+I (...) ET.PROTO: handshake ok, peer=...
+I (...) ET.PROTO: network ready: 1 reachable peer(s)
+I (...) et_example: status: state=ready ... vip=10.144.144.10/24 direct=1 ...
+```
+
+状态每 10 秒打印一次，关注 `state`、`vip`、`direct`、`routes` 的变化。
+
+示例还会在 80 端口跑一个 HTTP 服务：访问 `http://<设备IP>/` 或 `/toggle` 会翻转 **GPIO38** 电平。设备 IP 可以是 Wi-Fi 物理地址，组网成功后也可以用虚拟 IP 从任意 EasyTier 节点访问。
+
+## 组件的基本用法（自己集成时）
+### 安装组件
+
+通过 ESP-IDF 的包管理器安装 EasyTier-ESP 组件：
+
+```bash
+idf.py add-dependency qtet/easytier-esp
+```
+
+或者在应用的 main/idf_component.yml 中加入依赖：
+
+```yaml
+dependencies:
+  myqfeng/easytier-esp: "^0.0.2"
+```
+
+这样在构建应用 ESP-IDF 时会自动下载并安装组件。
+
+### TOML 配置说明
+
+EasyTier-ESP 与上游使用同一套 toml 配置文本，对于没有支持的设置项不做解析（即静默忽略）
+
+### 核心用法
+
+组件对外的核心只有一个类：`et::Inst`（RAII，命名空间 `et`），生命周期分五步：
+
+```cpp
+et::RuntimeOptions options{};
+options.on_event = &on_event;              // 事件回调
+
+et::Inst inst(toml_text, options);         // 构造：解析 TOML、校验、准备资源
+if (!inst.valid()) { /* 看 last_error() 和日志 */ }
+
+ESP_ERROR_CHECK(inst.start());             // 启动：创建连接、网卡、任务
+// Wi-Fi/以太网拿到 IP 后：
+ESP_ERROR_CHECK(inst.connect());           // 连接：开始连入口
+// (需要断开时：inst.disconnect();)
+inst.stop(5000);                           // 停止；析构自动释放
+```
+
+几个关键注意点：
+
+| 事项 | 说明 |
+| --- | --- |
+| `start()` 成功 ≠ 组网可用 | 要等 `NetworkReady` 事件或 `Status.state == Ready` |
+| Wi-Fi 重连后 | 必须在 GOT_IP 后再次 `connect()` |
+| 任务栈 | 构造在调用者栈上执行，任务栈 ≥ 8 KiB |
+| 修改配置 | 运行期不可改，需析构后用新 TOML 重建实例 |
+| 配置失败行为 | 不支持的字段静默忽略；支持的字段写错则构造失败 |
+| 内存 | 单实例常驻约 92 KiB，每条 Peer 连接约 12 KiB，建议开 PSRAM |
+
+## 常见现象排查
+
+| 现象 | 先看 |
+| --- | --- |
+| 串口没有 `got ip` | Wi-Fi SSID/密码、信号 |
+| 有 `got ip`，没有 `network ready` | 入口地址/端口、网络名与密钥 |
+| 有 `network ready`，ping 不通 | 对端路由、防火墙、虚拟网段冲突 |
+| 提示找不到 `easytier.toml` | 创建 `main/easytier.toml` 并重新构建 |
+
+**更详细的文档请前往 [EasyTier-ESP 文档网站](https://esp.qtet.cn)**
\ No newline at end of file
diff --git a/guide/embed/requirements.md b/guide/embed/requirements.md
new file mode 100644
index 0000000..ab75bc3
--- /dev/null
+++ b/guide/embed/requirements.md
@@ -0,0 +1,47 @@
+# 使用环境要求
+
+## 软件环境
+
+| 项目 | 要求 |
+| --- | --- |
+| ESP-IDF | **6.1.x**（已验证）；组件声明 `>=6.1`，未验证版本不承诺行为一致 |
+| C++ 标准 | C++20 |
+| 目标芯片 | **ESP32-S3**（当前只在 N16R8 模组验证） |
+| Flash | 示例使用 16 MB 模组；具体固件占用以实际构建为准 |
+| PSRAM | **强烈建议开启** |
+
+组件源码关闭异常与 RTTI；组件实现依赖 `esp_netif`、`lwip`、`freertos`、`mbedtls`（PSA Crypto）。
+
+## 内存要求
+
+| 项目 | 量级 | 说明 |
+| --- | --- | --- |
+| 单实例常驻 | 约 **100 KiB** | 组件运行上下文 |
+| 每条Peer连接 | 约 12 KiB | 默认最多 6 条 |
+| 任务栈 | 约 24 KiB | 组件任务合计，可通过 Kconfig 调整 |
+| 队列/缓冲 | 数十 KiB | 与队列深度配置相关 |
+
+以上是量级，不是硬性承诺；实际占用以构建日志和运行时测量为准。**建议开启 PSRAM**，否则默认配置很容易在分配阶段失败。
+
+## Socket 与主任务栈
+
+示例把以下两项写入 `sdkconfig.defaults`：
+
+```ini
+CONFIG_LWIP_MAX_SOCKETS=24
+CONFIG_ESP_MAIN_TASK_STACK_SIZE=8192
+```
+
+- `LWIP_MAX_SOCKETS`：默认 10 不一定足够 Peer 的入口连接 + 应用 socket + lwIP 内部占用；
+- `MAIN_TASK_STACK_SIZE`：TOML 解析与 `Inst` 构造在调用者任务栈上执行，建议至少 8 KiB。
+
+如果你在其他任务里构造 `et::Inst`，也要保证该任务栈足够，并用 `uxTaskGetStackHighWaterMark()` 核对余量。
+
+
+## 已经验证的组合
+
+- ESP32-S3-N16R8 模组
+- ESP-IDF 6.1
+- EasyTier 2.6.4 ~ 2.7.0
+
+其余版本并非“明确不支持”，而是**没有验证**。用于生产前请自行完成构建、真机联调与稳定性测试。
\ No newline at end of file
diff --git a/guide/installation_esp.md b/guide/installation_esp.md
new file mode 100644
index 0000000..e190339
--- /dev/null
+++ b/guide/installation_esp.md
@@ -0,0 +1,41 @@
+# 安装 Espressif 组件
+
+**EasyTier-ESP** 是一个基于 EasyTier 组网协议的 C++ 轻量级实现，可在 ESP-IDF 中作为组件导入。
+
+:::warning
+EasyTier-ESP 现在为预览版本，仅实现了部分基础功能，接口在今后可能出现变更，且可能存在未知问题，请慎用于生产环境。
+:::
+
+## 通过 ESP-IDF 组件注册表导入
+
+在应用的 `main/idf_component.yml` 中加入依赖：
+
+```yaml
+dependencies:
+  myqfeng/easytier-esp: "^0.0.1"
+  idf: ">=6.1"
+```
+
+或者用命令：
+
+```bash
+idf.py add-dependency "myqfeng/easytier-esp^0.0.1"
+idf.py build
+```
+
+构建时组件会被下载到工程的 `managed_components/` 下。
+
+## 本地源码导入
+
+- 把 `components/easytier-esp` 拷贝或软链到应用的 `components/` 目录；或
+- 在工程顶层 `CMakeLists.txt` 把本仓库的 `components` 目录加入 `EXTRA_COMPONENT_DIRS`。
+
+然后在应用组件的 `CMakeLists.txt` 里声明依赖：
+
+```cmake
+idf_component_register(
+    SRCS "main.cpp"
+    INCLUDE_DIRS "."
+    REQUIRES easytier-esp
+)
+```
\ No newline at end of file

From 0610b96ed60d92930cee1b1d14f4fe7ac066efe9 Mon Sep 17 00:00:00 2001
From: Myqfeng <viagrahuang@outlook.com>
Date: Wed, 21 Oct 2026 00:28:17 +0800
Subject: [PATCH 2/3] =?UTF-8?q?docs:=20=E4=BC=98=E5=8C=96=20ESP=20?=
 =?UTF-8?q?=E7=BB=84=E4=BB=B6=E4=BB=8B=E7=BB=8D=E6=96=87=E6=A1=A3=E7=9A=84?=
 =?UTF-8?q?=E7=BB=93=E6=9E=84?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .vitepress/config/cn.ts      |  1 -
 .vitepress/config/en.ts      |  1 -
 en/guide/installation_esp.md | 37 --------------------------------
 en/guide/introduction.md     | 25 ++++++++++++++++++++++
 guide/installation_esp.md    | 41 ------------------------------------
 guide/introduction.md        | 29 +++++++++++++++++++++++++
 6 files changed, 54 insertions(+), 80 deletions(-)
 delete mode 100644 en/guide/installation_esp.md
 delete mode 100644 guide/installation_esp.md

diff --git a/.vitepress/config/cn.ts b/.vitepress/config/cn.ts
index 92e9412..644dced 100644
--- a/.vitepress/config/cn.ts
+++ b/.vitepress/config/cn.ts
@@ -14,7 +14,6 @@ export const cn = defineConfig({
           { text: '下载', link: '/guide/download' },
           { text: '安装 CLI', link: '/guide/installation' },
           { text: '安装 GUI', link: '/guide/installation_gui' },
-          { text: '安装 Espressif 组件', link: '/guide/installation_esp' },
           { text: '常见问题', link: '/guide/faq' },
         ],
       },
diff --git a/.vitepress/config/en.ts b/.vitepress/config/en.ts
index 7598714..dc048a9 100644
--- a/.vitepress/config/en.ts
+++ b/.vitepress/config/en.ts
@@ -14,7 +14,6 @@ export const en = defineConfig({
           { text: 'Download', link: '/en/guide/download' },
           { text: 'Installation CLI', link: '/en/guide/installation' },
           { text: 'Installation GUI', link: '/en/guide/installation_gui' },
-          { text: 'Install Espressif Component', link: '/en/guide/installation_esp' },
           { text: 'FAQ', link: '/en/guide/faq' },
         ],
       },
diff --git a/en/guide/installation_esp.md b/en/guide/installation_esp.md
deleted file mode 100644
index 6087e20..0000000
--- a/en/guide/installation_esp.md
+++ /dev/null
@@ -1,37 +0,0 @@
-# Installation (Espressif Component)
-
-**EasyTier-ESP** is a lightweight C++ implementation based on the EasyTier networking protocol and can be imported as a component in ESP-IDF.
-
-## Import via the ESP-IDF Component Registry
-
-Add the dependency to your application's `main/idf_component.yml`:
-
-```yaml
-dependencies:
-  myqfeng/easytier-esp: "^0.0.1"
-  idf: ">=6.1"
-```
-
-Or use the command:
-
-```bash
-idf.py add-dependency "myqfeng/easytier-esp^0.0.1"
-idf.py build
-```
-
-The component will be downloaded to the project's `managed_components/` directory during the build.
-
-### Import from Local Source
-
-- Copy or symlink `components/easytier-esp` to your application's `components/` directory; or
-- Add this repository's `components` directory to `EXTRA_COMPONENT_DIRS` in the project's top-level `CMakeLists.txt`.
-
-Then declare the dependency in your application component's `CMakeLists.txt`:
-
-```cmake
-idf_component_register(
-    SRCS "main.cpp"
-    INCLUDE_DIRS "."
-    REQUIRES easytier-esp
-)
-```
diff --git a/en/guide/introduction.md b/en/guide/introduction.md
index 4d0ca92..c07dc9a 100644
--- a/en/guide/introduction.md
+++ b/en/guide/introduction.md
@@ -6,6 +6,7 @@ The software can be used via command line or graphical interface. It is ready to
 
 - [🛠️ CLI Installation Page](./installation) provides methods for installing the command-line tool.
 - [🖥️ GUI Installation Page](./installation_gui) provides methods for installing the graphical interface tool.
+- [🔌 Embedded Usage Page](./embed/index) provides methods for using the ESP32 component.
 - [⬇️ Download Page](./download) provides the latest EasyTier download links.
 
 ## Applicable Scenarios
@@ -36,3 +37,27 @@ The software can be used via command line or graphical interface. It is ready to
 EasyTier provides a simple and user-friendly graphical interface, suitable for beginners to get started quickly.
 
 <img src="/assets/gui-screenshot.png" alt="EasyTier GUI Screenshot" width="400">
+
+
+## [Espressif Component](./embed/index)
+
+**EasyTier-ESP** is a lightweight C++ implementation based on the EasyTier networking protocol and can be imported as a component in ESP-IDF.
+
+#### Import via the ESP-IDF Component Registry
+
+Add the dependency to your application's `main/idf_component.yml`:
+
+```yaml
+dependencies:
+  myqfeng/easytier-esp: "^0.0.1"
+  idf: ">=6.1"
+```
+
+Or use the command:
+
+```bash
+idf.py add-dependency "myqfeng/easytier-esp^0.0.1"
+idf.py build
+```
+
+The component will be downloaded to the project's `managed_components/` directory during the build.
diff --git a/guide/installation_esp.md b/guide/installation_esp.md
deleted file mode 100644
index e190339..0000000
--- a/guide/installation_esp.md
+++ /dev/null
@@ -1,41 +0,0 @@
-# 安装 Espressif 组件
-
-**EasyTier-ESP** 是一个基于 EasyTier 组网协议的 C++ 轻量级实现，可在 ESP-IDF 中作为组件导入。
-
-:::warning
-EasyTier-ESP 现在为预览版本，仅实现了部分基础功能，接口在今后可能出现变更，且可能存在未知问题，请慎用于生产环境。
-:::
-
-## 通过 ESP-IDF 组件注册表导入
-
-在应用的 `main/idf_component.yml` 中加入依赖：
-
-```yaml
-dependencies:
-  myqfeng/easytier-esp: "^0.0.1"
-  idf: ">=6.1"
-```
-
-或者用命令：
-
-```bash
-idf.py add-dependency "myqfeng/easytier-esp^0.0.1"
-idf.py build
-```
-
-构建时组件会被下载到工程的 `managed_components/` 下。
-
-## 本地源码导入
-
-- 把 `components/easytier-esp` 拷贝或软链到应用的 `components/` 目录；或
-- 在工程顶层 `CMakeLists.txt` 把本仓库的 `components` 目录加入 `EXTRA_COMPONENT_DIRS`。
-
-然后在应用组件的 `CMakeLists.txt` 里声明依赖：
-
-```cmake
-idf_component_register(
-    SRCS "main.cpp"
-    INCLUDE_DIRS "."
-    REQUIRES easytier-esp
-)
-```
\ No newline at end of file
diff --git a/guide/introduction.md b/guide/introduction.md
index eba8d61..be5ac77 100644
--- a/guide/introduction.md
+++ b/guide/introduction.md
@@ -6,6 +6,7 @@ EasyTier 是一款简单、安全、去中心化的内网穿透和异地组网
 
 - [🛠️安装 CLI 页面](./installation) 可查看安装命令行工具的方法。
 - [🖥️安装 GUI 页面](./installation_gui) 可查看安装图形界面工具的方法。
+- [🔌嵌入式使用页面](./embed/index) 可以查看 ESP32 组件的使用方法
 - [⬇️下载页面](./download) 可获取最新版本 EasyTier 的下载链接。
 
 
@@ -38,3 +39,31 @@ EasyTier 是一款简单、安全、去中心化的内网穿透和异地组网
 EasyTier 提供简单易用的图形界面，适合新手快速上手。
 
 <img src="/assets/gui-screenshot.png" alt="EasyTier GUI Screenshot" width="400">
+
+
+## [Espressif 组件](./embed/index)
+
+**EasyTier-ESP** 是一个基于 EasyTier 组网协议的 C++ 轻量级实现，可在 ESP-IDF 中作为组件导入。
+
+:::warning
+EasyTier-ESP 现在为预览版本，仅实现了部分基础功能，接口在今后可能出现变更，且可能存在未知问题，请慎用于生产环境。
+:::
+
+#### 通过 ESP-IDF 组件注册表导入
+
+在应用的 `main/idf_component.yml` 中加入依赖：
+
+```yaml
+dependencies:
+  myqfeng/easytier-esp: "^0.0.1"
+  idf: ">=6.1"
+```
+
+或者用命令：
+
+```bash
+idf.py add-dependency "myqfeng/easytier-esp^0.0.1"
+idf.py build
+```
+
+构建时组件会被下载到工程的 `managed_components/` 下。

From 77415c61ae19a4a0dc8340ef476841b5dbebae73 Mon Sep 17 00:00:00 2001
From: KKRainbow <5665404+KKRainbow@users.noreply.github.com>
Date: Wed, 21 Oct 2026 00:36:42 +0800
Subject: [PATCH 3/3] docs: mention ESP support in homepage platform cards

Add a separate embedded device support line to the Chinese and English
Cross-Platform cards using their existing HTML line breaks.
---
 en/index.md | 2 +-
 index.md    | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/en/index.md b/en/index.md
index c229beb..9fd1156 100644
--- a/en/index.md
+++ b/en/index.md
@@ -28,7 +28,7 @@ features:
   - title: Easy to Use
     details: Web, client, command line multiple operation methods<br>Supports one-click networking
   - title: Cross-Platform
-    details: Supports Win / MacOS / Linux / FreeBSD / Android<br>Compatible with X86 / ARM / MIPS architectures
+    details: Supports Win / MacOS / Linux / FreeBSD / Android<br>Compatible with X86 / ARM / MIPS architectures<br>Embedded device support (ESP)
     link: /en/guide/download
   - title: Secure
     details: Multiple encryption algorithms including AES-GCM or WireGuard encryption<br>Prevents man-in-the-middle attacks
diff --git a/index.md b/index.md
index 1696ba9..5dcc14a 100644
--- a/index.md
+++ b/index.md
@@ -31,7 +31,7 @@ features:
   - title: 易用
     details: 网页、客户端、命令行多方式操作
   - title: 跨平台
-    details: 支持 Win / MacOS / Linux / FreeBSD / Android<br>兼容 X86 / ARM / MIPS 架构
+    details: 支持 Win / MacOS / Linux / FreeBSD / Android<br>兼容 X86 / ARM / MIPS 架构<br>嵌入式设备支持（ESP）
     link: /guide/download
   - title: 安全
     details: 支持 AES-GCM 等多种加密算法 或 WireGuard 加密<br>防止中间人攻击