mirror of
https://github.com/espressif/esp-idf.git
synced 2026-10-02 03:00:34 +03:00
docs: add idf.py wokwi command documentation
This commit is contained in:
Juraj Michalek
@@ -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
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
|
||||
Reference in New Issue
Block a user