Metadata-Version: 2.5
Name: sim-bridge
Version: 0.1.3
Summary: Run AVR (simavr), Renode and ESP32 (Espressif QEMU) firmware with UART, GDB debugging, GPIO control and VCD waveforms
Author: grbl-multi contributors
License: MIT
Keywords: avr,debugging,embedded,esp32,espressif,firmware,gdb,gpio,gtkwave,qemu,renode,simavr,simulation,simulator,stm32,vcd,waveform
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Embedded Systems
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.12
Requires-Dist: pyvcd>=0.5.0
Requires-Dist: typer>=0.15.0
Requires-Dist: vcdvcd>=2.6.0
Description-Content-Type: text/markdown

# 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](https://github.com/buserror/simavr) (AVR) and [Renode](https://renode.io/) (STM32) and the custom patched [Espressif official QEMU](https://github.com/espressif/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.

```sh
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](src/sim_bridge/skills/sim-bridge-firmware/references/espressif-qemu.md) 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:

```sh
# 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:

```sh
nc 127.0.0.1 12345
```

See the [firmware input guide](src/sim_bridge/skills/sim-bridge-firmware/references/esp-host.md)
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](src/sim_bridge/skills/sim-bridge-firmware/references/esp8266-qemu.md#esp8266-sdk-virtual-station-component-integration).
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:

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

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

```sh
nc 127.0.0.1 2323
```

To debug the same network-connected firmware:

```sh
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](src/sim_bridge/skills/sim-bridge-firmware/references/vscode-config.md)
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.

```sh
# 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](src/sim_bridge/skills/sim-bridge-firmware/references/cli.md)
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.

```python
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](src/sim_bridge/skills/sim-bridge-firmware/references/session-api.md)
and [E2E guide](src/sim_bridge/skills/sim-bridge-firmware/references/e2e-testing.md)
for complete examples.

## AI agent integration

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

```sh
sim-bridge-skill list
sim-bridge-skill install
```

Installation detects supported agents. An explicit agent name can also be supplied.
See the [skill](src/sim_bridge/skills/sim-bridge-firmware/SKILL.md) for its scope.

## Source layout

```text
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](src/sim_bridge/skills/sim-bridge-firmware/references/avr-simavr.md)
- [STM32 / Renode](src/sim_bridge/skills/sim-bridge-firmware/references/stm32-renode.md)
- [ESP8266 simulation and Station integration](src/sim_bridge/skills/sim-bridge-firmware/references/esp8266-qemu.md)
- [ESP32 family / QEMU](src/sim_bridge/skills/sim-bridge-firmware/references/espressif-qemu.md)
- [Troubleshooting](src/sim_bridge/skills/sim-bridge-firmware/references/troubleshooting.md)

## License

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