diff --git a/docs/en/resources.rst b/docs/en/resources.rst
index e150c6d0f5..f4a2c46f48 100644
--- a/docs/en/resources.rst
+++ b/docs/en/resources.rst
@@ -10,6 +10,7 @@ Resources
 
     third-party-tools/platformio
     third-party-tools/clion
+    third-party-tools/wokwi
     third-party-tools/visualgdb
 
 For inquiries related to these third-party tools, we recommend seeking assistance from the respective tool's support channels or user communities.
diff --git a/docs/en/third-party-tools/wokwi.rst b/docs/en/third-party-tools/wokwi.rst
new file mode 100644
index 0000000000..3ea2a9b59e
--- /dev/null
+++ b/docs/en/third-party-tools/wokwi.rst
@@ -0,0 +1,225 @@
+.. _wokwi:
+
+Wokwi
+#####
+
+:link_to_translation:`zh_CN:[中文]`
+
+What Is Wokwi?
+~~~~~~~~~~~~~~
+
+`Wokwi <https://wokwi.com/esp32>`__ is an online electronics simulator. You can use it to simulate most of the Espressif chips and supported parts and sensors.
+
+Wokwi provides a browser-based interface and IDE integrations that offer a simple and intuitive way to start coding your next IoT project within seconds. It supports ESP-IDF projects and provides Wi-Fi simulation, virtual logic analyzers, advanced debugging with GDB and screenshot capture for automated testing.
+
+Key Features
+~~~~~~~~~~~~
+
+Wokwi provides many features for embedded development:
+
+- **Wi-Fi Simulation**: Test IoT projects without physical hardware.
+- **Virtual Logic Analyzers**: Debug digital signals and timing.
+- **Advanced GDB Debugging**: Set breakpoints and inspect variables.
+- **VS Code Integration**: Develop and simulate directly from VS Code.
+- **CLion Plugin**: Professional development workflow with `CLion <https://plugins.jetbrains.com/plugin/23826-wokwi-simulator>`__.
+- **Screenshot Capture**: Automated visual testing for CI/CD.
+- **Custom Chips API**: Build your own virtual chips in addition to main MCU.
+
+.. note::
+
+   Simulation results may differ from real hardware. Always test your project on actual hardware before deployment.
+
+Installation
+~~~~~~~~~~~~
+
+Wokwi can be used in three ways:
+
+**Browser-based (Online)**
+   Visit `wokwi.com <https://wokwi.com/esp32>`__ to start simulating immediately in your browser. No installation required.
+
+**VS Code Extension**
+   Install the `Wokwi for VS Code extension <https://docs.wokwi.com/vscode/getting-started>`__ to integrate simulation directly into your development environment.
+
+**CLion Plugin**
+   Install the `Wokwi Simulator plugin <https://plugins.jetbrains.com/plugin/23826-wokwi-simulator>`__ for CLion to use Wokwi with professional IDE features and embedded development tools.
+
+Configuration
+~~~~~~~~~~~~~
+
+**Setting Up a Project with wokwi-cli**
+
+For local development and CI/CD integration, you can use ``wokwi-cli`` to configure your ESP-IDF project for Wokwi simulation.
+
+To install ``wokwi-cli``, please refer to the `official Wokwi CLI installation guide <https://docs.wokwi.com/wokwi-ci/cli-installation>`__.
+
+Once installed, run the following command in your ESP-IDF project directory:
+
+.. code-block:: bash
+
+   wokwi-cli init
+
+The ``wokwi-cli init`` command will prompt you with a few questions and automatically create the necessary configuration files in your project directory.
+
+Wokwi projects are configured using two main files:
+
+- **wokwi.toml**: A configuration file that specifies firmware paths, ELF files for debugging, and simulator settings.
+- **diagram.json**: A circuit diagram file that describes the board, connected components, and their wiring.
+
+For detailed information about configuration files, see the `Wokwi project configuration guide <https://docs.wokwi.com/vscode/project-config>`__.
+
+You are encouraged to read the official `ESP32 Simulation guide <https://docs.wokwi.com/guides/esp32>`__ to understand which boards, languages, and features are supported by Wokwi.
+
+IDE Integration
+~~~~~~~~~~~~~~~
+
+**VS Code**
+
+To use Wokwi with VS Code:
+
+1. Install the `Wokwi for VS Code extension <https://marketplace.visualstudio.com/items?itemName=wokwi.wokwi-vscode>`__.
+2. Create ``wokwi.toml`` and ``diagram.json`` files in your project.
+3. Press ``F1`` and select ``Wokwi: Start Simulator`` to begin simulation.
+
+**CLion**
+
+The `Wokwi Simulator plugin for CLion <https://plugins.jetbrains.com/plugin/23826-wokwi-simulator>`__ provides:
+
+- Integration with CLion's embedded development tools.
+- Professional debugging workflow.
+- Support for ESP-IDF projects.
+- Seamless simulator access from the IDE.
+
+**Espressif IDE**
+
+Version 2.9.0 and later of `Espressif IDE <https://developer.espressif.com/blog/how-to-use-wokwi-simulator-with-espressif-ide/>`__ includes Wokwi integration:
+
+- Build applications in the IDE.
+- Flash directly to the Wokwi simulator.
+- View serial monitor output in the IDE console while communicating with the simulator.
+
+Testing with pytest-embedded
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Wokwi integrates with ESP-IDF's testing framework through `pytest-embedded-wokwi <https://pypi.org/project/pytest-embedded-wokwi/>`__. This enables:
+
+- Automated unit and integration testing.
+- CI/CD pipeline integration with GitHub Actions.
+- Screenshot validation for visual testing.
+- Regression testing without physical hardware.
+
+**Basic Usage**
+
+Run Wokwi simulations from the command line with ``wokwi-cli``:
+
+.. code-block:: bash
+
+   # Run simulation and expect specific text in output
+   wokwi-cli --timeout 5000 --expect-text "Hello World"
+
+   # Take a screenshot after 4.5 seconds
+   wokwi-cli --screenshot-part esp --screenshot-time 4500 --screenshot-file screenshot.png
+
+   # Save serial output to a file
+   wokwi-cli --serial-log-file output.log --timeout 10000
+
+For a complete project template with CI/CD configured, see the `ESP-IDF Project Template with CI and Wokwi <https://github.com/wokwi/wokwi-esp-test-template>`__.
+
+**Related Resources**
+
+- `pytest-embedded-wokwi Documentation <https://pypi.org/project/pytest-embedded-wokwi/>`__
+- `ESP-IDF Tests with Pytest Guide <https://docs.espressif.com/projects/esp-idf/en/stable/esp32/contribute/esp-idf-tests-with-pytest.html>`__
+- `pytest-embedded 2.x Documentation <https://docs.espressif.com/projects/pytest-embedded>`__
+
+Advanced Features
+~~~~~~~~~~~~~~~~~
+
+**Debugging**
+
+Wokwi provides built-in GDB server support for advanced debugging:
+
+1. Add to ``wokwi.toml``:
+
+   .. code-block:: toml
+
+      [wokwi]
+      version = 1
+      firmware = 'build/your_app.bin'
+      elf = 'build/your_app.elf'
+      gdbServerPort = 3333
+
+2. Create a VS Code launch configuration (``.vscode/launch.json``):
+
+   .. code-block:: json
+
+      {
+        "version": "0.2.0",
+        "configurations": [
+          {
+            "name": "Wokwi GDB",
+            "type": "cppdbg",
+            "request": "launch",
+            "program": "${workspaceFolder}/build/your_app.elf",
+            "cwd": "${workspaceFolder}",
+            "MIMode": "gdb",
+            "miDebuggerPath": "xtensa-esp32-elf-gdb",
+            "miDebuggerServerAddress": "localhost:3333"
+          }
+        ]
+      }
+
+3. Start simulator with ``F1`` → ``Wokwi: Start Simulator and Wait for Debugger``.
+4. Press ``F5`` in VS Code to attach the debugger.
+
+For more details, see the `Wokwi debugging guide <https://docs.wokwi.com/guides/debugger>`__.
+
+**Wi-Fi Networking**
+
+Wokwi supports Wi-Fi simulation for IoT projects. See the `ESP32 Wi-Fi networking guide <https://docs.wokwi.com/guides/esp32-wifi>`__ for information on:
+
+- Connecting to Wi-Fi networks.
+- MQTT, HTTP, and HTTPS protocols.
+- WebSocket communication.
+- Network testing without physical hardware.
+
+**CI/CD Integration**
+
+Automate testing in GitHub Actions using Wokwi:
+
+.. code-block:: yaml
+
+   - name: Simulate & take screenshot
+     run: |
+       wokwi-cli \
+         --screenshot-part "esp" \
+         --screenshot-time 5000 \
+         --screenshot-file "screenshot-${{ matrix.board }}.png" \
+         "boards/${{ matrix.board }}"
+
+   - name: Upload screenshot
+     uses: actions/upload-artifact@v4
+     with:
+       name: screenshot-${{ matrix.board }}
+       path: screenshot-${{ matrix.board }}.png
+
+This enables automated visual regression testing and ensures consistent behavior across commits.
+
+Resources
+~~~~~~~~~
+
+**Videos**
+
+- `DevCon24 - Flash Less, Do More: The Magic of Virtual Hardware <https://youtu.be/8PTYnNFK1pw>`__: Learn about the power of simulation for embedded development
+
+**Documentation**
+
+- `Wokwi Documentation <https://docs.wokwi.com>`__: Comprehensive resource for all Wokwi features
+- `ESP32 Simulation Guide <https://docs.wokwi.com/guides/esp32>`__: Supported boards, languages, and features
+- `ESP32 Wi-Fi Networking <https://docs.wokwi.com/guides/esp32-wifi>`__: Wi-Fi simulation for IoT projects
+- `VS Code Integration <https://docs.wokwi.com/vscode/getting-started>`__: Setup and configuration guide
+- `CLion Plugin <https://plugins.jetbrains.com/plugin/23826-wokwi-simulator>`__: CLion integration details
+- `Wokwi Articles on Developer Portal <https://developer.espressif.com/tags/wokwi/>`__: Collection of tutorials and use cases
+
+**Getting Help**
+
+- `Wokwi Community <https://discord.gg/wokwi>`__: Join the Wokwi Discord server to get help from the community
+
diff --git a/docs/zh_CN/resources.rst b/docs/zh_CN/resources.rst
index a951d0b32f..4b56e41df1 100644
--- a/docs/zh_CN/resources.rst
+++ b/docs/zh_CN/resources.rst
@@ -10,6 +10,7 @@
 
     third-party-tools/platformio
     third-party-tools/clion
+    third-party-tools/wokwi
     third-party-tools/visualgdb
 
 有关这些第三方工具的问题，请寻求该工具的支持渠道或用户社区的帮助。
diff --git a/docs/zh_CN/third-party-tools/wokwi.rst b/docs/zh_CN/third-party-tools/wokwi.rst
new file mode 100644
index 0000000000..eaadd070f5
--- /dev/null
+++ b/docs/zh_CN/third-party-tools/wokwi.rst
@@ -0,0 +1,225 @@
+.. _wokwi:
+
+Wokwi
+#####
+
+:link_to_translation:`en:[English]`
+
+Wokwi 是什么？
+~~~~~~~~~~~~~~~~~~~
+
+`Wokwi <https://wokwi.com/esp32>`__ 是一款在线电子仿真器。它支持仿真多数乐鑫芯片以及一系列外围设备和传感器。
+
+通过基于浏览器的操作界面和 IDE 集成，Wokwi 能够帮助你快速开启 IoT 项目编程，支持 Wi-Fi 仿真、虚拟逻辑分析仪、高级 GDB 调试以及自动化测试用的屏幕截图捕捉等功能。
+
+核心功能
+~~~~~~~~~~~~
+
+Wokwi 提供一系列面向嵌入式开发的功能：
+
+- **Wi-Fi 仿真**：无需物理硬件即可测试 IoT 项目。
+- **虚拟逻辑分析仪**：调试数字信号和时序。
+- **高级 GDB 调试**：设置断点和查看变量。
+- **VS Code 集成**：直接在 VS Code 中进行开发和仿真。
+- **CLion 插件**：通过 `CLion 插件 <https://plugins.jetbrains.com/plugin/23826-wokwi-simulator>`__ 实现专业开发流程。
+- **屏幕截图捕获**：支持 CI/CD 自动化视觉测试。
+- **自定义芯片 API**：可在主 MCU 外构建自定义虚拟芯片。
+
+.. note::
+
+   仿真结果可能与实际硬件不同。在部署之前，请务必在实际硬件上测试你的项目。
+
+安装
+~~~~
+
+Wokwi 提供三种使用方式：
+
+**基于浏览器（在线使用）**
+   访问 `wokwi.com <https://wokwi.com/esp32>`__ 即可直接在浏览器中开始仿真，无需安装任何软件。
+
+**VS Code 扩展**
+   安装 `Wokwi for VS Code 扩展 <https://docs.wokwi.com/vscode/getting-started>`__，可在开发环境中直接进行仿真。
+
+**CLion 插件**
+   安装 `Wokwi Simulator 插件 <https://plugins.jetbrains.com/plugin/23826-wokwi-simulator>`__，可在 CLion 中结合专业 IDE 功能进行嵌入式开发。
+
+配置说明
+~~~~~~~~
+
+**使用 wokwi-cli 设置项目**
+
+若要进行本地开发或 CI/CD 集成，可使用 ``wokwi-cli`` 为 ESP-IDF 项目配置 Wokwi 仿真。
+
+安装 ``wokwi-cli`` 请参阅 `Wokwi CLI 官方安装指南 <https://docs.wokwi.com/wokwi-ci/cli-installation>`__。
+
+安装完成后，在 ESP-IDF 项目目录下执行：
+
+.. code-block:: bash
+
+   wokwi-cli init
+
+该命令会引导你完成若干设置，并自动在项目目录中生成必要的配置文件。
+
+Wokwi 项目主要通过两个文件进行配置：
+
+- **wokwi.toml**：配置文件，用于指定固件路径、调试用 ELF 文件及仿真器设置。
+- **diagram.json**：电路图文件，用于描述开发板、连接组件及其布线关系。
+
+有关配置文件的详细信息，请参阅 `Wokwi 项目配置指南 <https://docs.wokwi.com/vscode/project-config>`__。
+
+建议同时阅读官方 `ESP32 仿真指南 <https://docs.wokwi.com/guides/esp32>`__，了解 Wokwi 支持的具体开发板、编程语言及相关功能。
+
+IDE 集成
+~~~~~~~~~~~~~~~
+
+**VS Code**
+
+在 VS Code 中使用 Wokwi 的步骤：
+
+1. 安装 `Wokwi for VS Code 扩展 <https://marketplace.visualstudio.com/items?itemName=wokwi.wokwi-vscode>`__。
+2. 在项目中创建 ``wokwi.toml`` 和 ``diagram.json`` 文件。
+3. 按下 ``F1``，选择 ``Wokwi: Start Simulator`` 即可开始仿真。
+
+**CLion**
+
+`CLion 的 Wokwi Simulator 插件 <https://plugins.jetbrains.com/plugin/23826-wokwi-simulator>`__ 提供以下功能：
+
+- 与 CLion 嵌入式开发工具集成。
+- 专业的调试工作流。
+- 支持 ESP-IDF 项目。
+- 可从 IDE 内无缝访问仿真器。
+
+**Espressif IDE**
+
+`Espressif IDE <https://developer.espressif.com/blog/how-to-use-wokwi-simulator-with-espressif-ide/>`__ 2.9.0 及以上版本已内置 Wokwi 集成：
+
+- 可在 IDE 中构建应用程序。
+- 支持直接烧录到 Wokwi 仿真器。
+- 可在 IDE 控制台中查看串口监视器输出，并与仿真器进行通信。
+
+使用 pytest-embedded 进行测试
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Wokwi 通过 `pytest-embedded-wokwi <https://pypi.org/project/pytest-embedded-wokwi/>`__ 与 ESP-IDF 测试框架集成。实现以下功能：
+
+- 自动化单元测试和集成测试。
+- 与 GitHub Actions 的 CI/CD 流水线集成。
+- 支持屏幕截图验证的视觉测试。
+- 无需物理硬件的回归测试。
+
+**基本用法**
+
+使用 ``wokwi-cli`` 从命令行运行 Wokwi 仿真：
+
+.. code-block:: bash
+
+   # 运行仿真并期望输出中包含特定文本
+   wokwi-cli --timeout 5000 --expect-text "Hello World"
+
+   # 在 4.5 秒后截取屏幕截图
+   wokwi-cli --screenshot-part esp --screenshot-time 4500 --screenshot-file screenshot.png
+
+   # 将串口输出保存到文件
+   wokwi-cli --serial-log-file output.log --timeout 10000
+
+有关包含 CI/CD 配置的完整项目模板，请参阅 `ESP-IDF Project Template with CI and Wokwi <https://github.com/wokwi/wokwi-esp-test-template>`__。
+
+**相关资源**
+
+- `pytest-embedded-wokwi 文档 <https://pypi.org/project/pytest-embedded-wokwi/>`__
+- `ESP-IDF pytest 指南 <https://docs.espressif.com/projects/esp-idf/zh_CN/v5.5.2/esp32/contribute/esp-idf-tests-with-pytest.html>`__
+- `pytest-embedded 2.x 文档 <https://docs.espressif.com/projects/pytest-embedded>`__
+
+高级功能
+~~~~~~~~~~~~~~~~~
+
+**调试**
+
+Wokwi 支持内置 GDB 服务器，可用于高级调试：
+
+1. 在 ``wokwi.toml`` 中添加以下配置：
+
+   .. code-block:: toml
+
+      [wokwi]
+      version = 1
+      firmware = 'build/your_app.bin'
+      elf = 'build/your_app.elf'
+      gdbServerPort = 3333
+
+2. 创建 VS Code 调试配置（``.vscode/launch.json``）：
+
+   .. code-block:: json
+
+      {
+        "version": "0.2.0",
+        "configurations": [
+          {
+            "name": "Wokwi GDB",
+            "type": "cppdbg",
+            "request": "launch",
+            "program": "${workspaceFolder}/build/your_app.elf",
+            "cwd": "${workspaceFolder}",
+            "MIMode": "gdb",
+            "miDebuggerPath": "xtensa-esp32-elf-gdb",
+            "miDebuggerServerAddress": "localhost:3333"
+          }
+        ]
+      }
+
+3. 使用 ``F1`` → ``Wokwi: Start Simulator and Wait for Debugger`` 启动仿真器。
+4. 在 VS Code 中按 ``F5`` 附加调试器。
+
+更多详细信息请参阅 `Wokwi 调试指南 <https://docs.wokwi.com/guides/debugger>`__。
+
+**Wi-Fi 网络**
+
+Wokwi 支持 IoT 项目的 Wi-Fi 仿真。相关内容请参阅 `ESP32 Wi-Fi 网络指南 <https://docs.wokwi.com/guides/esp32-wifi>`__，包括：
+
+- 连接 Wi-Fi 网络。
+- MQTT、HTTP 和 HTTPS 协议。
+- WebSocket 通信。
+- 无需物理硬件的网络测试。
+
+**CI/CD 集成**
+
+使用 Wokwi 在 GitHub Actions 中自动化测试：
+
+.. code-block:: yaml
+
+   - name: Simulate & take screenshot
+     run: |
+       wokwi-cli \
+         --screenshot-part "esp" \
+         --screenshot-time 5000 \
+         --screenshot-file "screenshot-${{ matrix.board }}.png" \
+         "boards/${{ matrix.board }}"
+
+   - name: Upload screenshot
+     uses: actions/upload-artifact@v4
+     with:
+       name: screenshot-${{ matrix.board }}
+       path: screenshot-${{ matrix.board }}.png
+
+以上配置可实现自动化视觉回归测试，确保项目在不同提交之间表现一致。
+
+更多资源
+~~~~~~~~
+
+**视频教程**
+
+- `DevCon24 - Flash Less, Do More: The Magic of Virtual Hardware <https://youtu.be/8PTYnNFK1pw>`__：了解仿真在嵌入式开发中的强大功能
+
+**文档**
+
+- `Wokwi 文档 <https://docs.wokwi.com>`__：涵盖 Wokwi 全部功能的综合资源
+- `ESP32 仿真指南 <https://docs.wokwi.com/guides/esp32>`__：介绍支持的开发板、语言和功能
+- `ESP32 Wi-Fi 网络 <https://docs.wokwi.com/guides/esp32-wifi>`__：IoT 项目 Wi-Fi 仿真指南
+- `VS Code 集成 <https://docs.wokwi.com/vscode/getting-started>`__：设置和配置指南
+- `CLion 插件 <https://plugins.jetbrains.com/plugin/23826-wokwi-simulator>`__：CLion 集成详细信息
+- `开发者门户上的 Wokwi 文章 <https://developer.espressif.com/tags/wokwi/>`__：汇集教程和用例
+
+**获取帮助**
+
+- `Wokwi 社区 <https://discord.gg/wokwi>`__：加入 Wokwi Discord 服务器，获取社区支持与交流
+