docs: add idf.py wokwi command documentation

Closes DOC-14900
2026-08-18 06:35:35 +03:00 · 2026-06-22 15:59:25 +08:00
parent bf08ef8b50 0f909d01e9
commit e197da08dd
2 changed files with 314 additions and 12 deletions
--- a/docs/en/third-party-tools/wokwi.rst
+++ b/docs/en/third-party-tools/wokwi.rst
@@ -8,7 +8,7 @@ Wokwi
 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 <https://wokwi.com/esp32>`__ is an online electronics simulator. You can use it to simulate most 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.

@@ -20,10 +20,11 @@ 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.
+- ``idf.py`` **Integration**: Use the familiar ``idf.py`` interface to control Wokwi (see :ref:`Set Up a Project with idf-wokwi <idf-wokwi-setup>`).
 - **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.
+- **Custom Chips API**: Build your own virtual chips in addition to the main MCU.

 .. note::

@@ -32,11 +33,14 @@ Wokwi provides many features for embedded development:
 Installation
 ~~~~~~~~~~~~

-Wokwi can be used in three ways:
+Wokwi can be used in the following ways:

 **Browser-based (Online)**
   Visit `wokwi.com <https://wokwi.com/esp32>`__ to start simulating immediately in your browser. No installation required.

+**Via** ``idf.py`` **using the** ``idf-wokwi`` **package**
+   Install the `idf-wokwi <https://pypi.org/project/idf-wokwi/>`__ package to integrate Wokwi controls directly into ``idf.py``.
+
 **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.

@@ -46,7 +50,7 @@ Wokwi can be used in three ways:
 Configuration
 ~~~~~~~~~~~~~

-**Setting Up a Project with wokwi-cli**
+**Set 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.

@@ -62,13 +66,158 @@ The ``wokwi-cli init`` command will prompt you with a few questions and automati

 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.
+- ``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.

+**Set Up a Project with** ``idf-wokwi``
+
+.. _idf-wokwi-setup:
+
+Similar to ``wokwi-cli``, you can use ``idf-wokwi`` for local development and CI/CD integration. The advantage of using ``idf-wokwi`` is not only that the workflow remains within ``idf.py``, but also that Wokwi will be able to automatically fetch information from ESP-IDF. This avoids the need for ``wokwi.toml`` and ``diagram.json`` to exist — Wokwi will implicitly generate these files.
+
+**Choose Between** ``wokwi-cli`` **and** ``idf-wokwi``
+
+.. list-table:: Comparison of Wokwi integration options
+   :header-rows: 1
+   :widths: 25 38 37
+
+   * - Feature
+     - ``wokwi-cli``
+     - ``idf-wokwi``
+   * - **Config files**
+     - Required (``wokwi.toml`` and ``diagram.json``)
+     - Auto-generated from ESP-IDF
+   * - **Build integration**
+     - Manual (build first, then simulate)
+     - Automatic via ``idf.py``
+   * - **ESP-IDF version**
+     - Any version
+     - 6.0 or greater only
+   * - **Use case**
+     - Non-ESP-IDF projects, custom workflows
+     - ESP-IDF 6.0+ projects, native workflow
+
+Prerequisites
+~~~~~~~~~~~~~
+
+Before using ``idf-wokwi``, ensure that you have:
+
+- ESP-IDF 6.0 or greater (``idf.py`` module extensions require this)
+- Wokwi API token (You can create an API token on the `Wokwi CI Dashboard <https://wokwi.com/dashboard/ci>`__)
+
+Getting Started
+~~~~~~~~~~~~~~~
+
+Install and configure ``idf-wokwi``:
+
+.. code-block:: bash
+
+   # Install the package
+   pip install idf-wokwi
+
+   # Set your API token
+   export WOKWI_CLI_TOKEN=your_token_here
+
+   # Run simulation
+   idf.py wokwi
+
+.. important::
+
+   Module extensions to ``idf.py`` are only supported on ESP-IDF versions 6.0 or greater.
+
+.. tip::
+
+   ``idf.py wokwi`` automatically builds your project before simulation. Skip build with ``idf.py wokwi --no-build`` if firmware already exists.
+
+Available CLI Options
+~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table:: ``idf.py wokwi`` command options
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Option
+     - Description
+   * - ``--diagram-file``
+     - Path to ``diagram.json`` (defaults to project root)
+   * - ``--timeout``
+     - Simulation timeout in milliseconds (exit code 42 on timeout)
+   * - ``--expect-text``
+     - Exit successfully when this text appears in serial output
+   * - ``--fail-text``
+     - Exit with error when this text appears in serial output
+   * - ``--expect-regex``
+     - Exit successfully when this regex matches a serial output line
+   * - ``--fail-regex``
+     - Exit with error when this regex matches a serial output line
+
+Example Output
+~~~~~~~~~~~~~~
+
+Running ``idf.py wokwi`` produces output similar to the following:
+
+.. code-block:: none
+
+   $ idf.py wokwi
+   Running Wokwi simulation...
+   Firmware: build/your_project.bin
+   ELF: build/your_project.elf
+   Simulator ready at: https://wokwi.com/...
+   Press Ctrl+C to stop...
+
+   I (123) main: Hello, World!
+   I (145) main: System initialized
+
+Troubleshooting
+~~~~~~~~~~~~~~~
+
+- ``Module not found`` or ``No module named 'idf_wokwi'``
+
+   Verify that ``idf-wokwi`` is installed in the same Python environment used by ESP-IDF:
+
+   .. code-block:: bash
+
+      pip show idf-wokwi
+      xtensa-esp32-elf-gdb --version  # Verify ESP-IDF environment
+
+- ``idf.py: error: no such option: wokwi``
+
+   Your ESP-IDF version is earlier than 6.0 and does not support module extensions. Upgrade ESP-IDF or use ``wokwi-cli`` instead.
+
+- ``Invalid token`` or ``401 Unauthorized``
+
+   Verify that ``WOKWI_CLI_TOKEN`` is set correctly:
+
+   .. code-block:: bash
+
+      echo $WOKWI_CLI_TOKEN  # Should show your token, not empty
+
+   Get a new token at `Wokwi CI Dashboard <https://wokwi.com/dashboard/ci>`__ if needed.
+
+CI/CD Integration
+~~~~~~~~~~~~~~~~~~
+
+For automated testing in CI/CD pipelines, ``idf-wokwi`` integrates seamlessly with GitHub Actions:
+
+.. code-block:: yaml
+
+   - name: Simulate with Wokwi
+     run: |
+       export WOKWI_CLI_TOKEN=${{ secrets.WOKWI_CLI_TOKEN }}
+       idf.py wokwi --timeout 30000 --expect-text "Tests passed"
+
+.. note::
+
+   Store your ``WOKWI_CLI_TOKEN`` as a secret in your CI/CD platform (e.g., GitHub Secrets). Never commit tokens to the repository.
+
+For automated testing frameworks, also see the :ref:`wokwi-pytest-embedded` section below.
+
+Additional documentation is available on the official `Wokwi ESP-IDF simulation extension usage <https://docs.wokwi.com/wokwi-ci/idf-wokwi-usage>`__ page.
+
 IDE Integration
 ~~~~~~~~~~~~~~~

@@ -97,6 +246,8 @@ Version 2.9.0 and later of `Espressif IDE <https://developer.espressif.com/blog/
 - Flash directly to the Wokwi simulator.
 - View serial monitor output in the IDE console while communicating with the simulator.

+.. _wokwi-pytest-embedded:
+
 Testing with pytest-embedded
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

--- a/docs/zh_CN/third-party-tools/wokwi.rst
+++ b/docs/zh_CN/third-party-tools/wokwi.rst
@@ -10,7 +10,7 @@ Wokwi 是什么？

 `Wokwi <https://wokwi.com/esp32>`__ 是一款在线电子仿真器。它支持仿真多数乐鑫芯片以及一系列外围设备和传感器。

-通过基于浏览器的操作界面和 IDE 集成，Wokwi 能够帮助你快速开启 IoT 项目编程，支持 Wi-Fi 仿真、虚拟逻辑分析仪、高级 GDB 调试以及自动化测试用的屏幕截图捕捉等功能。
+通过基于浏览器的操作界面和 IDE 集成，Wokwi 能够帮助你快速开启 IoT 项目编程，支持 ESP-IDF 项目、Wi-Fi 仿真、虚拟逻辑分析仪、高级 GDB 调试以及自动化测试用的屏幕截图捕获等功能。

 核心功能
 ~~~~~~~~~~~~
@@ -20,10 +20,11 @@ Wokwi 提供一系列面向嵌入式开发的功能：
 - **Wi-Fi 仿真**：无需物理硬件即可测试 IoT 项目。
 - **虚拟逻辑分析仪**：调试数字信号和时序。
 - **高级 GDB 调试**：设置断点和查看变量。
+- ``idf.py`` **集成**：使用熟悉的 ``idf.py`` 界面控制 Wokwi（参见 :ref:`使用 idf-wokwi 设置项目 <idf-wokwi-setup>`）。
 - **VS Code 集成**：直接在 VS Code 中进行开发和仿真。
 - **CLion 插件**：通过 `CLion 插件 <https://plugins.jetbrains.com/plugin/23826-wokwi-simulator>`__ 实现专业开发流程。
 - **屏幕截图捕获**：支持 CI/CD 自动化视觉测试。
- **自定义芯片 API**：可在主 MCU 外构建自定义虚拟芯片。
+- **自定义芯片 API**：除主 MCU 之外，还可构建自定义虚拟芯片。

 .. note::

@@ -32,11 +33,14 @@ Wokwi 提供一系列面向嵌入式开发的功能：
 安装
 ~~~~

-Wokwi 提供三种使用方式：
+Wokwi 提供以下使用方式：

 **基于浏览器（在线使用）**
   访问 `wokwi.com <https://wokwi.com/esp32>`__ 即可直接在浏览器中开始仿真，无需安装任何软件。

+**通过** ``idf.py`` **使用** ``idf-wokwi`` **包**
+   安装 `idf-wokwi <https://pypi.org/project/idf-wokwi/>`__ 包，可将 Wokwi 控制直接集成到 ``idf.py`` 中。
+
 **VS Code 扩展**
   安装 `Wokwi for VS Code 扩展 <https://docs.wokwi.com/vscode/getting-started>`__，可在开发环境中直接进行仿真。

@@ -62,13 +66,158 @@ Wokwi 提供三种使用方式：

 Wokwi 项目主要通过两个文件进行配置：

- **wokwi.toml**：配置文件，用于指定固件路径、调试用 ELF 文件及仿真器设置。
- **diagram.json**：电路图文件，用于描述开发板、连接组件及其布线关系。
+- ``wokwi.toml``：配置文件，用于指定固件路径、调试用 ELF 文件及仿真器设置。
+- ``diagram.json``：电路图文件，用于描述开发板、连接组件及其布线关系。

 有关配置文件的详细信息，请参阅 `Wokwi 项目配置指南 <https://docs.wokwi.com/vscode/project-config>`__。

 建议同时阅读官方 `ESP32 仿真指南 <https://docs.wokwi.com/guides/esp32>`__，了解 Wokwi 支持的具体开发板、编程语言及相关功能。

+**使用** ``idf-wokwi`` **设置项目**
+
+.. _idf-wokwi-setup:
+
+与 ``wokwi-cli`` 类似，你可以使用 ``idf-wokwi`` 进行本地开发和 CI/CD 集成。使用 ``idf-wokwi`` 的优势在于，工作流完全保留在 ``idf.py`` 中，且 Wokwi 能够自动从 ESP-IDF 获取信息。这样就无需存在 ``wokwi.toml`` 和 ``diagram.json`` 文件 —— Wokwi 会隐式生成这些文件。
+
+**如何选择** ``wokwi-cli`` **和** ``idf-wokwi``
+
+.. list-table:: Wokwi 集成方案对比
+   :header-rows: 1
+   :widths: 25 38 37
+
+   * - 功能
+     - ``wokwi-cli``
+     - ``idf-wokwi``
+   * - **配置文件**
+     - 必需（``wokwi.toml`` 和 ``diagram.json``）
+     - 由 ESP-IDF 自动生成
+   * - **构建集成**
+     - 手动（需先构建，再仿真）
+     - 通过 ``idf.py`` 自动完成
+   * - **ESP-IDF 版本**
+     - 任意版本
+     - 仅支持 6.0 及以上
+   * - **适用场景**
+     - 非 ESP-IDF 项目、自定义工作流
+     - ESP-IDF 6.0+ 项目、原生工作流
+
+前置条件
+~~~~~~~~
+
+使用 ``idf-wokwi`` 之前，请确保：
+
+- 使用 ESP-IDF 6.0 或更高版本（``idf.py`` 模块扩展需要此版本）
+- 已有 Wokwi API 令牌（在 `Wokwi CI Dashboard <https://wokwi.com/dashboard/ci>`__ 创建）
+
+快速开始
+~~~~~~~~
+
+安装并配置 ``idf-wokwi``：
+
+.. code-block:: bash
+
+   # 安装软件包
+   pip install idf-wokwi
+
+   # 设置 API 令牌
+   export WOKWI_CLI_TOKEN=your_token_here
+
+   # 运行仿真
+   idf.py wokwi
+
+.. important::
+
+   ``idf.py`` 的模块扩展仅支持 ESP-IDF 6.0 及更高版本。
+
+.. tip::
+
+   ``idf.py wokwi`` 会在仿真前自动构建项目。若固件已存在，可使用 ``idf.py wokwi --no-build`` 跳过构建。
+
+可用 CLI 选项
+~~~~~~~~~~~~~
+
+.. list-table:: ``idf.py wokwi`` 命令选项
+   :header-rows: 1
+   :widths: 30 70
+
+   * - 选项
+     - 说明
+   * - ``--diagram-file``
+     - ``diagram.json`` 文件路径（默认为项目根目录）
+   * - ``--timeout``
+     - 仿真超时时间，单位毫秒（超时退出码为 42）
+   * - ``--expect-text``
+     - 当串口输出中出现此文本时成功退出
+   * - ``--fail-text``
+     - 当串口输出中出现此文本时错误退出
+   * - ``--expect-regex``
+     - 当串口输出行匹配此正则表达式时成功退出
+   * - ``--fail-regex``
+     - 当串口输出行匹配此正则表达式时错误退出
+
+示例输出
+~~~~~~~~
+
+运行 ``idf.py wokwi`` 会产生类似以下的输出：
+
+.. code-block:: none
+
+   $ idf.py wokwi
+   Running Wokwi simulation...
+   Firmware: build/your_project.bin
+   ELF: build/your_project.elf
+   Simulator ready at: https://wokwi.com/...
+   Press Ctrl+C to stop...
+
+   I (123) main: Hello, World!
+   I (145) main: System initialized
+
+故障排除
+~~~~~~~~
+
+- ``Module not found`` 或 ``No module named 'idf_wokwi'``
+
+   检查 ``idf-wokwi`` 是否安装在与 ESP-IDF 相同的 Python 环境中：
+
+   .. code-block:: bash
+
+      pip show idf-wokwi
+      xtensa-esp32-elf-gdb --version  # 验证 ESP-IDF 环境
+
+- ``idf.py: error: no such option: wokwi``
+
+   你的 ESP-IDF 版本低于 6.0，不支持模块扩展功能。请更新 ESP-IDF 或改用 ``wokwi-cli``。
+
+- ``Invalid token`` 或 ``401 Unauthorized``
+
+   检查 ``WOKWI_CLI_TOKEN`` 是否设置正确：
+
+   .. code-block:: bash
+
+      echo $WOKWI_CLI_TOKEN  # 应显示你的令牌，而非为空
+
+   如需要，可在 `Wokwi CI Dashboard <https://wokwi.com/dashboard/ci>`__ 获取新令牌。
+
+CI/CD 集成
+~~~~~~~~~~
+
+在 CI/CD 流水线中，``idf-wokwi`` 可与 GitHub Actions 无缝集成：
+
+.. code-block:: yaml
+
+   - name: Simulate with Wokwi
+     run: |
+       export WOKWI_CLI_TOKEN=${{ secrets.WOKWI_CLI_TOKEN }}
+       idf.py wokwi --timeout 30000 --expect-text "Tests passed"
+
+.. note::
+
+   请将 ``WOKWI_CLI_TOKEN`` 作为密钥存储在 CI/CD 平台（如 GitHub Secrets）中。切勿将令牌提交到代码仓库。
+
+如需了解自动化测试框架的相关信息，可参阅下文的 :ref:`wokwi-pytest-embedded` 章节。
+
+更多文档请参阅官方 `Wokwi ESP-IDF 仿真扩展使用指南 <https://docs.wokwi.com/wokwi-ci/idf-wokwi-usage>`__。
+
 IDE 集成
 ~~~~~~~~~~~~~~~

@@ -97,10 +246,12 @@ IDE 集成
 - 支持直接烧录到 Wokwi 仿真器。
 - 可在 IDE 控制台中查看串口监视器输出，并与仿真器进行通信。

+.. _wokwi-pytest-embedded:
+
 使用 pytest-embedded 进行测试
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

-Wokwi 通过 `pytest-embedded-wokwi <https://pypi.org/project/pytest-embedded-wokwi/>`__ 与 ESP-IDF 测试框架集成。实现以下功能：
+Wokwi 通过 `pytest-embedded-wokwi <https://pypi.org/project/pytest-embedded-wokwi/>`__ 与 ESP-IDF 测试框架集成。支持以下功能：

 - 自动化单元测试和集成测试。
 - 与 GitHub Actions 的 CI/CD 流水线集成。