# Wokwi

[English]

## Wokwi 是什么？

Wokwi 是一款在线电子仿真器。它支持仿真多数乐鑫芯片以及一系列外围设备和传感器。

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

## 核心功能

Wokwi 提供一系列面向嵌入式开发的功能：

- Wi-Fi 仿真：无需物理硬件即可测试 IoT 项目。

- 虚拟逻辑分析仪：调试数字信号和时序。

- 高级 GDB 调试：设置断点和查看变量。

- `idf.py` 集成：使用熟悉的 `idf.py` 界面控制 Wokwi（参见 使用 idf-wokwi 设置项目）。

- VS Code 集成：直接在 VS Code 中进行开发和仿真。

- CLion 插件：通过 CLion 插件 实现专业开发流程。

- 屏幕截图捕获：支持 CI/CD 自动化视觉测试。

- 自定义芯片 API：除主 MCU 之外，还可构建自定义虚拟芯片。

备注

仿真结果可能与实际硬件不同。在部署之前，请务必在实际硬件上测试你的项目。

## 安装

Wokwi 提供以下使用方式：

基于浏览器（在线使用）

  访问 wokwi.com 即可直接在浏览器中开始仿真，无需安装任何软件。

通过 `idf.py` 使用 `idf-wokwi` 包

  安装 idf-wokwi 包，可将 Wokwi 控制直接集成到 `idf.py` 中。

VS Code 扩展

  安装 Wokwi for VS Code 扩展，可在开发环境中直接进行仿真。

CLion 插件

  安装 Wokwi Simulator 插件，可在 CLion 中结合专业 IDE 功能进行嵌入式开发。

## 配置说明

使用 wokwi-cli 设置项目

若要进行本地开发或 CI/CD 集成，可使用 `wokwi-cli` 为 ESP-IDF 项目配置 Wokwi 仿真。

安装 `wokwi-cli` 请参阅 Wokwi CLI 官方安装指南。

安装完成后，在 ESP-IDF 项目目录下执行：

    wokwi-cli init

该命令会引导你完成若干设置，并自动在项目目录中生成必要的配置文件。

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

- `wokwi.toml`：配置文件，用于指定固件路径、调试用 ELF 文件及仿真器设置。

- `diagram.json`：电路图文件，用于描述开发板、连接组件及其布线关系。

有关配置文件的详细信息，请参阅 Wokwi 项目配置指南。

建议同时阅读官方 ESP32 仿真指南，了解 Wokwi 支持的具体开发板、编程语言及相关功能。

使用 `idf-wokwi` 设置项目

与 `wokwi-cli` 类似，你可以使用 `idf-wokwi` 进行本地开发和 CI/CD 集成。使用 `idf-wokwi` 的优势在于，工作流完全保留在 `idf.py` 中，且 Wokwi 能够自动从 ESP-IDF 获取信息。这样就无需存在 `wokwi.toml` 和 `diagram.json` 文件 —— Wokwi 会隐式生成这些文件。

如何选择 `wokwi-cli` 和 `idf-wokwi`

Wokwi 集成方案对比
功能 | `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`：

    # 安装软件包
    pip install idf-wokwi

    # 设置 API 令牌
    export WOKWI_CLI_TOKEN=your_token_here

    # 运行仿真
    idf.py wokwi

重要

`idf.py` 的模块扩展仅支持 ESP-IDF 6.0 及更高版本。

小技巧

`idf.py wokwi` 会在仿真前自动构建项目。若固件已存在，可使用 `idf.py wokwi --no-build` 跳过构建。

## 可用 CLI 选项

`idf.py wokwi` 命令选项
选项 | 说明
--- | ---
`--diagram-file` | `diagram.json` 文件路径（默认为项目根目录）
`--timeout` | 仿真超时时间，单位毫秒（超时退出码为 42）
`--expect-text` | 当串口输出中出现此文本时成功退出
`--fail-text` | 当串口输出中出现此文本时错误退出
`--expect-regex` | 当串口输出行匹配此正则表达式时成功退出
`--fail-regex` | 当串口输出行匹配此正则表达式时错误退出

## 示例输出

运行 `idf.py wokwi` 会产生类似以下的输出：

    $ 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 环境中：

  >     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` 是否设置正确：

  >     echo $WOKWI_CLI_TOKEN  # 应显示你的令牌，而非为空

  > 如需要，可在 Wokwi CI Dashboard 获取新令牌。

## CI/CD 集成

在 CI/CD 流水线中，`idf-wokwi` 可与 GitHub Actions 无缝集成：

    - name: Simulate with Wokwi
      run: |
        export WOKWI_CLI_TOKEN=${{ secrets.WOKWI_CLI_TOKEN }}
        idf.py wokwi --timeout 30000 --expect-text "Tests passed"

备注

请将 `WOKWI_CLI_TOKEN` 作为密钥存储在 CI/CD 平台（如 GitHub Secrets）中。切勿将令牌提交到代码仓库。

如需了解自动化测试框架的相关信息，可参阅下文的 使用 pytest-embedded 进行测试 章节。

更多文档请参阅官方 Wokwi ESP-IDF 仿真扩展使用指南。

## IDE 集成

VS Code

在 VS Code 中使用 Wokwi 的步骤：

1. 安装 Wokwi for VS Code 扩展。

2. 在项目中创建 `wokwi.toml` 和 `diagram.json` 文件。

3. 按下 `F1`，选择 `Wokwi: Start Simulator` 即可开始仿真。

CLion

CLion 的 Wokwi Simulator 插件 提供以下功能：

- 与 CLion 嵌入式开发工具集成。

- 专业的调试工作流。

- 支持 ESP-IDF 项目。

- 可从 IDE 内无缝访问仿真器。

Espressif IDE

Espressif IDE 2.9.0 及以上版本已内置 Wokwi 集成：

- 可在 IDE 中构建应用程序。

- 支持直接烧录到 Wokwi 仿真器。

- 可在 IDE 控制台中查看串口监视器输出，并与仿真器进行通信。

## 使用 pytest-embedded 进行测试

Wokwi 通过 pytest-embedded-wokwi 与 ESP-IDF 测试框架集成。支持以下功能：

- 自动化单元测试和集成测试。

- 与 GitHub Actions 的 CI/CD 流水线集成。

- 支持屏幕截图验证的视觉测试。

- 无需物理硬件的回归测试。

基本用法

使用 `wokwi-cli` 从命令行运行 Wokwi 仿真：

    # 运行仿真并期望输出中包含特定文本
    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。

相关资源

- pytest-embedded-wokwi 文档

- ESP-IDF pytest 指南

- pytest-embedded 2.x 文档

## 高级功能

调试

Wokwi 支持内置 GDB 服务器，可用于高级调试：

1. 在 `wokwi.toml` 中添加以下配置：

       [wokwi]
       version = 1
       firmware = 'build/your_app.bin'
       elf = 'build/your_app.elf'
       gdbServerPort = 3333

2. 创建 VS Code 调试配置（`.vscode/launch.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 调试指南。

Wi-Fi 网络

Wokwi 支持 IoT 项目的 Wi-Fi 仿真。相关内容请参阅 ESP32 Wi-Fi 网络指南，包括：

- 连接 Wi-Fi 网络。

- MQTT、HTTP 和 HTTPS 协议。

- WebSocket 通信。

- 无需物理硬件的网络测试。

CI/CD 集成

使用 Wokwi 在 GitHub Actions 中自动化测试：

    - 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：了解仿真在嵌入式开发中的强大功能

文档

- Wokwi 文档：涵盖 Wokwi 全部功能的综合资源

- ESP32 仿真指南：介绍支持的开发板、语言和功能

- ESP32 Wi-Fi 网络：IoT 项目 Wi-Fi 仿真指南

- VS Code 集成：设置和配置指南

- CLion 插件：CLion 集成详细信息

- 开发者门户上的 Wokwi 文章：汇集教程和用例

获取帮助

- Wokwi 社区：加入 Wokwi Discord 服务器，获取社区支持与交流

此文档对您有帮助吗？

- 反馈已收到，谢谢！
- 如果您有其他意见，欢迎填写乐鑫文档反馈表。

- 我们重视您的反馈。
- 您可以填写乐鑫文档反馈表告诉我们如何改进该文档。