---
title: How Simantic runs and debugs firmware
description: How Simantic executes MCU firmware, models peripherals and board devices, advances virtual time, and records evidence for engineers and AI agents.
---

**Simantic executes firmware built for a supported microcontroller against a software model of that MCU and its connected devices.** The local `sim` CLI runs the image on your computer. Cloud Sim provides hosted runs. An engineer or agent can supply inputs, inspect the output, and repeat the experiment after a change.

The local CLI uses Pyrite, Simantic's firmware simulation engine. Its models execute the target program and provide the hardware interfaces that program expects.

## From firmware ELF to a running system

1. **Build for the real target.** Use your firmware toolchain to produce an ELF containing target machine code and memory-layout information. Keep symbols when you want function-level debugging.
2. **Select the MCU.** `sim models` lists the models in that executable and their status. The model supplies the memory map, CPU, interrupts, clocks, and implemented peripheral behavior.
3. **Describe what surrounds it.** A board file or multi-machine scenario supplies external devices and connections. Python peers can provide inputs and responses at the supported device interface.
4. **Execute and advance virtual time.** Firmware accesses modeled registers and memory while scheduled peripheral and interrupt events drive execution.
5. **Check and investigate.** Inspect UART and recorded events, assert a completion condition, or trace the function or memory location that answers your next question.

For the pinned STM32F401RE sample:

```sh
sim STM32F401RE run --elf build-bug/zephyr/zephyr.elf \
  --timeout 1 --ascii --only-messages --output uart.txt
```

`--timeout 1` means one second of virtual time. Host elapsed time is a different quantity. The [complete STM32 tutorial](/stm32-simulator) includes the source, build instructions, expected failure, and verified fix.

## What does the model include?

The MCU model provides the implemented behavior that firmware sees through its architecture and peripheral interfaces. A sensor peer can supply a sample or inject an error; another simulated MCU can exchange messages through a configured medium.

The exact coverage matters. Selecting an Arm CPU does not provide every STM32 peripheral, and selecting an MCU does not automatically reproduce your PCB, wiring, external ICs, or environment. Model status and warnings are inputs to the investigation. Read [what fidelity means](/simulation-fidelity) before generalizing from a passing example.

## What can an AI agent inspect?

An agent can run the same CLI and read the same output as an engineer. It can inspect a recorded run, choose a targeted trace, change one input or code path, and rerun the completion check.

```sh
sim STM32F401RE run --elf build-fixed/zephyr/zephyr.elf \
  --timeout 1 --ascii --record run \
  --expect 'RESULT: PASS' --expect-absent 'RESULT: FAIL'
```

The evidence directory describes the inputs and includes streams such as UART, faults, interrupts, context switches, and usage. Read `runs.jsonl` and its `not_recorded` field first: an absent event proves nothing if that stream was not watched. A function-entry trace proves arrival at that function, not successful return or correct lock ownership.

The [debugging procedure](/docs/guide#debugging-with-evidence) explains how to turn those observations into a tested explanation. `sim docs show guide`, `sim docs show troubleshooting`, and `sim docs show record` provide documentation matched to the installed binary. Those commands do not require a login; simulation runs do require an account check.

## Local CLI, Cloud Sim, and PR review

| Entry point | Where it fits | Where to start |
| --- | --- | --- |
| Local CLI | Run and investigate a supported firmware build on your machine | [Installation and commands](/docs) |
| Cloud Sim | Submit firmware for hosted execution through the browser or API | [Cloud Sim](/cloud-sim) |
| Simantic Bot | Request a firmware build and simulation-backed investigation of a pull request | [PR reviewer setup and limits](/docs/pr-review) |

These entry points do not imply identical model coverage or engine versions. Check the target and version used by the run you are evaluating. The PR reviewer runs when requested; it does not automatically run on every push.

## What still needs hardware?

Use simulation to investigate behavior within the model's scope. Electrical behavior, analog response, physical signal integrity, oscillator variation, and hardware timing claims need suitable measurements. When firmware and simulation disagree, the firmware, model, peer, or test can be wrong.

**Continue:** [Run the STM32 tutorial](/stm32-simulator), [assess fidelity](/simulation-fidelity), [compare QEMU](/simantic-vs-qemu), or [compare Renode](/simantic-vs-renode).

Workflow reviewed November 8, 2026. The linked reproducible example was captured with sim 0.8.11 on November 5, 2026; use your installed binary's documentation for version-specific options.
