diff --git a/docs/en/third-party-tools/wokwi.rst b/docs/en/third-party-tools/wokwi.rst index 3ea2a9b59e2..630e3ff33a4 100644 --- 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 `__ is an online electronics simulator. You can use it to simulate most of the Espressif chips and supported parts and sensors. +`Wokwi `__ 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 `). - **VS Code Integration**: Develop and simulate directly from VS Code. - **CLion Plugin**: Professional development workflow with `CLion `__. - **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 `__ to start simulating immediately in your browser. No installation required. +**Via** ``idf.py`` **using the** ``idf-wokwi`` **package** + Install the `idf-wokwi `__ package to integrate Wokwi controls directly into ``idf.py``. + **VS Code Extension** Install the `Wokwi for VS Code extension `__ 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 `__. You are encouraged to read the official `ESP32 Simulation guide `__ 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 `__) + +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 `__ 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 `__ page. + IDE Integration ~~~~~~~~~~~~~~~ @@ -97,6 +246,8 @@ Version 2.9.0 and later of `Espressif IDE `__ 是一款在线电子仿真器。它支持仿真多数乐鑫芯片以及一系列外围设备和传感器。 -通过基于浏览器的操作界面和 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 设置项目 `）。 - **VS Code 集成**：直接在 VS Code 中进行开发和仿真。 - **CLion 插件**：通过 `CLion 插件 `__ 实现专业开发流程。 - **屏幕截图捕获**：支持 CI/CD 自动化视觉测试。 -- **自定义芯片 API**：可在主 MCU 外构建自定义虚拟芯片。 +- **自定义芯片 API**：除主 MCU 之外，还可构建自定义虚拟芯片。 .. note:: @@ -32,11 +33,14 @@ Wokwi 提供一系列面向嵌入式开发的功能： 安装 ~~~~ -Wokwi 提供三种使用方式： +Wokwi 提供以下使用方式： **基于浏览器（在线使用）** 访问 `wokwi.com `__ 即可直接在浏览器中开始仿真，无需安装任何软件。 +**通过** ``idf.py`` **使用** ``idf-wokwi`` **包** + 安装 `idf-wokwi `__ 包，可将 Wokwi 控制直接集成到 ``idf.py`` 中。 + **VS Code 扩展** 安装 `Wokwi for VS Code 扩展 `__，可在开发环境中直接进行仿真。 @@ -62,13 +66,158 @@ Wokwi 提供三种使用方式： Wokwi 项目主要通过两个文件进行配置： -- **wokwi.toml**：配置文件，用于指定固件路径、调试用 ELF 文件及仿真器设置。 -- **diagram.json**：电路图文件，用于描述开发板、连接组件及其布线关系。 +- ``wokwi.toml``：配置文件，用于指定固件路径、调试用 ELF 文件及仿真器设置。 +- ``diagram.json``：电路图文件，用于描述开发板、连接组件及其布线关系。 有关配置文件的详细信息，请参阅 `Wokwi 项目配置指南 `__。 建议同时阅读官方 `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 `__ 创建） + +快速开始 +~~~~~~~~ + +安装并配置 ``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 `__ 获取新令牌。 + +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 仿真扩展使用指南 `__。 + IDE 集成 ~~~~~~~~~~~~~~~ @@ -97,10 +246,12 @@ IDE 集成 - 支持直接烧录到 Wokwi 仿真器。 - 可在 IDE 控制台中查看串口监视器输出，并与仿真器进行通信。 +.. _wokwi-pytest-embedded: + 使用 pytest-embedded 进行测试 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Wokwi 通过 `pytest-embedded-wokwi `__ 与 ESP-IDF 测试框架集成。实现以下功能： +Wokwi 通过 `pytest-embedded-wokwi `__ 与 ESP-IDF 测试框架集成。支持以下功能： - 自动化单元测试和集成测试。 - 与 GitHub Actions 的 CI/CD 流水线集成。