KKRainbow · Oct 20, 2026 · Oct 19, 2026 · Oct 20, 2026 · Oct 20, 2026
diff --git a/.vitepress/config/cn.ts b/.vitepress/config/cn.ts
@@ -64,6 +64,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
@@ -61,6 +61,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
@@ -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
@@ -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
@@ -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
@@ -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/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/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/guide/embed/capabilities.md 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
+未列出的能力默认视为**未支持**。
+:::
diff --git a/guide/embed/index.md 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) 进行查阅。
+:::