From f3d78be94bfbf5bf10299a42bde5dfb84aa951d0 Mon Sep 17 00:00:00 2001 From: w1ne <14119286+w1ne@users.noreply.github.com> Date: Wed, 10 Jun 2026 12:58:16 +0200 Subject: [PATCH] docs: add LabWired to unit-testing simulators --- _static/images/debug_probes/labwired.png | Bin 0 -> 4425 bytes advanced/unit-testing/simulators/index.rst | 1 + advanced/unit-testing/simulators/labwired.rst | 95 ++++++++++++++++++ 3 files changed, 96 insertions(+) create mode 100644 _static/images/debug_probes/labwired.png create mode 100644 advanced/unit-testing/simulators/labwired.rst diff --git a/_static/images/debug_probes/labwired.png b/_static/images/debug_probes/labwired.png new file mode 100644 index 0000000000000000000000000000000000000000..6227cf1fac605cbb5cbfc4e35cb640a840a049f2 GIT binary patch literal 4425 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 literal 0 HcmV?d00001 diff --git a/advanced/unit-testing/simulators/index.rst b/advanced/unit-testing/simulators/index.rst index 186a16e5ad..6fee80b8e0 100644 --- a/advanced/unit-testing/simulators/index.rst +++ b/advanced/unit-testing/simulators/index.rst @@ -37,6 +37,7 @@ frameworks: .. toctree:: :maxdepth: 1 + labwired qemu renode simavr diff --git a/advanced/unit-testing/simulators/labwired.rst b/advanced/unit-testing/simulators/labwired.rst new file mode 100644 index 0000000000..51254266e0 --- /dev/null +++ b/advanced/unit-testing/simulators/labwired.rst @@ -0,0 +1,95 @@ +.. Copyright (c) 2014-present PlatformIO + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + +.. _unit_testing_simulators_labwired: + +LabWired +-------- + +.. image:: ../../../_static/images/debug_probes/labwired.png + :target: https://labwired.com/?utm_source=platformio&utm_medium=docs + +LabWired is an open source (MIT) deterministic firmware simulator with +instruction-level CPU models (ARM Cortex-M, RISC-V, Xtensa) and peripheral +models validated against physical silicon. The same firmware binary that runs +on hardware runs in the simulator, and a run produces identical results every +time, which makes it suitable as a CI gate. For more information, see +`LabWired's official website `__. + +Configuration +~~~~~~~~~~~~~ + +Integration of LabWired requires the ``labwired`` CLI on ``PATH`` + +.. code-block:: bash + + curl -fsSL https://labwired.com/install.sh | sh + +and overriding the :ref:`projectconf_test_testing_command` in your +:ref:`projectconf`. PlatformIO builds the test firmware, LabWired boots the +ELF and mirrors the test UART to stdout, and PlatformIO parses the Unity +results as usual. + +See the example of ``platformio.ini`` for the :ref:`board_nordicnrf52_nrf52840_dk` +board from :ref:`platform_nordicnrf52`: + +.. code-block:: ini + + [platformio] + ; required so the ${platformio.*} variables below resolve + + [env:nrf52840_dk] + platform = nordicnrf52 + board = nrf52840_dk + test_framework = unity + + test_testing_command = + labwired + test + --no-key + --script + labwired.test.yaml + --firmware + ${platformio.build_dir}/${this.__env__}/firmware.elf + +The ``labwired.test.yaml`` script selects the board model and the UART that +Unity output is read from. A complete, runnable project (including the test +script, a bare-metal nRF52840 setup, and a GitHub Actions workflow) is +available at +`labwired-core/examples/platformio/nrf52840-unity `__. + +Testing +~~~~~~~ + +LabWired does not require a firmware uploading stage. Please use +the :option:`pio test --without-uploading` command option. + +.. code:: + + > pio test --without-uploading -e nrf52840_dk + + Verbose mode can be enabled via `-v, --verbose` option + Collected 1 tests + + Processing test_smoke in nrf52840_dk environment + ------------------------------------------------ + Building... + Testing... + test/test_smoke/test_main.c:50: test_addition [PASSED] + test/test_smoke/test_main.c:51: test_uart_is_enabled [PASSED] + test/test_smoke/test_main.c:52: test_string_length [PASSED] + -------------- nrf52840_dk:test_smoke [PASSED] Took 2.12 seconds -------------- + + ================================ SUMMARY ================================ + Environment Test Status Duration + ------------- ---------- -------- ------------ + nrf52840_dk test_smoke PASSED 00:00:02.122 + ============== 3 test cases: 3 succeeded in 00:00:02.122 ==============