sim-bridge

Simulate embedded firmware, debug it with GDB, communicate over UART or virtual WiFi, and record digital waveforms without a physical board.

sim-bridge provides command-line tools and Python sessions for AVR, STM32 and Espressif firmware. It starts the simulator, connects its control and communication interfaces, and gives tests a repeatable way to drive inputs and inspect outputs.

it's backend is simavr (AVR) and Renode (STM32) and the custom patched Espressif official QEMU (ESP32/S3/C3)

Features

• Firmware debugging: attach GDB or an editor debugger, set breakpoints and step through your code.
• ESP8266 WiFi communication: exercise firmware TCP services through a virtual Station connection, including while debugging with GDB.
• UART communication: use a terminal or Python client to interact with the firmware console.
• GPIO and waveform inspection: set simulated inputs, discover available signals and record VCD files for GTKWave.
• Automated E2E tests: start a simulator from Python, send application commands and check firmware responses or output signals.
• Automatic simulator preparation: ESP QEMU is prepared and cached on first use; users do not need to select a QEMU executable or download an ESP8266 ROM manually.

Simulation covers the peripherals implemented by each backend. Virtual WiFi tests the ESP8266 SDK network stack and application communication; it does not simulate radio propagation or connection to a physical access point. Digital waveforms show the simulator's behavior, and do not replace electrical or timing checks on hardware.

Supported platforms

Firmware	Simulator	Main capabilities
AVR	simavr	UART, GDB, GPIO control, memory inspection and VCD
STM32	Renode	UART, GDB, GPIO control and VCD on supported platform descriptions
ESP8266	sim-bridge managed QEMU	UART, GDB, virtual Station TCP, GPIO, FRC1 and I2S signal inspection
ESP32 / ESP32-S3 / ESP32-C3	sim-bridge managed QEMU	UART, GDB, GPIO control and VCD

Available peripherals and signals depend on the selected chip and simulator model. The virtual Station adapter is currently specific to ESP8266.

Installation

Python 3.12 or newer is required. Linux, including WSL, is the recommended environment.

pip install sim-bridge

# Or install from this source checkout:
pip install -e .

Install the dependencies for the backend you use:

Backend	Setup
AVR on Debian/Ubuntu	sudo apt install build-essential libsimavr-dev rapidjson-dev
Renode	uv tool install git+https://github.com/antmicro/renode-run.git
ESP QEMU	Prepared automatically on first use; see the ESP setup guide for native build dependencies

The first ESP launch needs network access and can take time to build the simulator. Subsequent launches reuse the compatible cached build. Compile your application with its normal firmware toolchain before launching sim-bridge.

Run firmware

Supply the firmware path explicitly:

# AVR ELF
simavr-host build/firmware.elf

# STM32 ELF and a Renode platform script
renode-host build/firmware.elf --resc board.resc

# ESP8266 SDK application ELF
esp-host build/app.elf --target esp8266

# ESP32 complete merged Flash image
esp-host build/flash.bin --target esp32

For SDK firmware, keep the application ELF in its build directory alongside the SDK-generated files. sim-bridge uses those files to prepare the boot images. An application-only BIN is not a complete Flash image.

The host prints the UART endpoint and any enabled services. Use a serial terminal for the AVR PTY, or a TCP client for the Renode/QEMU UART endpoint:

nc 127.0.0.1 12345

See the firmware input guide for supported ELF/BIN inputs and chip choices.

ESP8266 virtual WiFi and debugging

Build simulation firmware with the packaged sim_bridge_station SDK component, following the Station integration guide. The component is for simulation builds; exclude it from firmware flashed to hardware.

Start the firmware and forward its TCP service on port 23 to the host:

esp-host build/app.elf --target esp8266 --tcp-port 2323

In another terminal, communicate using your application's protocol:

nc 127.0.0.1 2323

To debug the same network-connected firmware:

esp-host build/app.elf --target esp8266 --tcp-port 2323 --gdb-port 3335 --paused

Attach your firmware GDB to 127.0.0.1:3335, then continue execution. --paused keeps the CPU stopped before it executes firmware; it does not resume automatically when a debugger connects or inputs are set. Without a debugger, use esp-ctl resume. The TCP service becomes available after the firmware starts and opens its listener.

GDB and virtual networking are independent: omit --gdb-port for simulation only, or omit --tcp-port when networking is unnecessary. UART command handling is decided by the firmware, even when the simulator exposes a UART endpoint.

See editor debugging for launch configuration examples.

Inputs and waveforms

Run control and recording commands from the same project directory as the host. Choose pins and initial levels to match your board.

# One input, or several inputs in one command
esp-ctl pin set GPIO4 1
esp-ctl pin set --pins GPIO4=1 GPIO5=1

# Discover and record signals
esp-vcd list
esp-vcd start --signals i2s.tx_word --file i2s.vcd
esp-vcd status
esp-vcd stop

Open the resulting VCD file in GTKWave. Use simavr-vcd or renode-vcd for the other backends. Renode takes the output file at stop, because it exports buffered recordings then; simavr and QEMU take it at start.

The CLI guide describes signal selection, input control and backend-specific commands. Each command also provides --help.

Python and E2E tests

Use the session for your backend directly: AvrSession, RenodeSession or QemuSession. Context managers stop the simulator when the test finishes.

from sim_bridge import Console
from sim_bridge import QemuSession

with QemuSession("build/app.elf", target="esp8266") as sim:
    sim.boot(start=False)
    # Initialize inputs required by your board before starting the CPU.
    sim.control.drive_gpio("GPIO", 4, True)
    sim.start_cpu()
    # This build includes sim_bridge_station and a firmware TCP service.
    with Console(sim.tcp_transport).open(timeout=10) as connection:
        connection.send(b"your application command\n")

Firmware readiness, protocol commands and expected responses belong to your test. See the session API and E2E guide for complete examples.

AI agent integration

The packaged firmware skill helps coding agents configure simulation, debugging and tests for a project:

sim-bridge-skill list
sim-bridge-skill install

Installation detects supported agents. An explicit agent name can also be supplied. See the skill for its scope.

Source layout

src/sim_bridge/
  common/         Shared console, session utilities and control options
  avr/            simavr sessions, CLI tools and native bridge source
  renode/         Renode sessions, control client and CLI tools
  esp/            ESP sessions, CLI tools, firmware and debugger preparation
    patches/      QEMU peripheral models and patches
    esp8266/      ROM assets and virtual Station SDK component
  skills/         Firmware integration guides and agent skill

Public session classes are imported from sim_bridge. Backend implementation modules live in their respective directories; CLI tools call them directly.

Further reading

• AVR / simavr
• STM32 / Renode
• ESP8266 simulation and Station integration
• ESP32 family / QEMU
• Troubleshooting

License

The sim-bridge Python package is MIT licensed. Simulator code and third-party components retain their respective licenses.