Firmware simulation

Simulate your firmware before the board exists.

Nihil runs your real control code against a model of the board, in two places: a chip model inside a circuit simulator that solves the copper, and a physics twin of the product. Nineteen microcontrollers are modelled today. Seventeen run at register level, generated from their vendors' register files: the ATmega328P, ATmega2560, ATmega32U4 and ATtiny85 behind the Arduino Uno, Nano, Mega and Leonardo; the ESP32, ESP32-S3, ESP32-S2, ESP32-C6, ESP32-C5 and ESP32-C3; the RP2040 and RP2350 of the Raspberry Pi Pico and Pico 2; the STM32F411 and STM32F401 of the Black Pill; the SAMD21 and SAMD51; and the i.MX RT1062 of the Teensy 4. The ESP32-P4 and the STM32G030F6 run from hand-made tables. Their register-level firmware runs in the loop; Arduino sketches and vendor SDK programs do not yet. The NVIDIA Jetson Orin Nano is a Linux computer: its program runs as it is, with real CUDA, against simulated devices; the Orin NX, the AGX Orin and the Raspberry Pi 5, 4 and Zero 2 W have board profiles on the same path. This page says exactly what that catches, what it cannot, and shows a recorded run.

4chip models: ESP32-P4, STM32G030F6, RP2040, ESP32-C3

1 msfixed twin step; the circuit solver steps adaptively

2412host-test checks passed of 2412, on the demo firmware

1 hashsame inputs and seed give the same trace hash, same toolchain

Two ways your firmware runs

One session may use only one of them for a given microcontroller, so the firmware never runs twice at once.

1. In the digital twin

The twin links your real control code and replaces the hardware with models: physics, sensors with the noise and bias from their datasheets, motors with their constants. The firmware sees them through a hosted hardware layer. Scenarios drive it the way a bench station would, and stochastic ones run over many seeds, so the answer is a distribution, never the best seed.

2. On a chip model inside the circuit simulator

Your app's hardware calls land on a model of the chip whose pins are nodes in the board's circuit. A GPIO is a driver with an output resistance, an ADC is a sample-and-hold charging through its switch, and an I2C or SPI transfer is either bytes handed to a device model or edges driven against the pull-ups. Brown-outs, a hot-plugged supply, a stalled motor and a warm start are scenarios the firmware has to survive, and the simulator counts every tick that ran late.

What you can simulate today
ChipTarget buildToolchain
ESP32-P4esp32p4_rangefinderESP-IDF
STM32G030F6stm32g0_butter, stm32g0_pwmgenArm GNU toolchain and make

What “real firmware” means here

The control core is portable C11 with no vendor headers and no heap: estimators, controllers, state machines and codecs. It is built twice from the same source, once for the microcontroller and once for your PC, behind a small hardware table. The PC build is what the twin and the circuit simulator run. That is your code, not a vendor binary in an emulator.

The hardware table returns raw counts, codes and bytes, and the core converts them with constants it owns. A wrong divider ratio or LSB in firmware therefore shows up in the simulation instead of on the bench.

What this catches, and what it does not

Catches: control logic, state machines, timing against a modelled plant, ADC scaling, bus transactions and their electrical edges, brown-out and fault handling, and ticks that run late.

Does not catch: startup code, vector tables, linker and compiler behaviour, an RTOS, or peripheral register quirks on the real silicon. Those belong to the target build and the bench. Instruction-set emulation of the chip, the level that would, is documented in the method and not built. Any simulator is a model; Espressif says the same about Wokwi in its ESP-IDF docs.

Nihil's Sandbox in its Circuit view on the car_ctrl board of the demo RC car: the board in 3-D with copper coloured by net voltage, the sim supply and each connector’s load listed on the left, sliders for the duty knob and the supply on the right, and the car_ctrl gate reading nihil obstat.
The car_ctrl board in the Circuit view. Copper colour is the net's voltage, 4497 track pieces and 2487 current segments solved, and the probes on the right are live.

A recorded run

The demo project is an RC car: an ESP32-P4 controller board, an opto-isolated PWM amplifier board, a 6S battery pack, a gearmotor and four time-of-flight sensors. This is the circuit gate's own scenario, short_drive, on the car_ctrl board (73 nets and 150 parts across the car's two boards, 793 tracks and 53 vias on car_ctrl):

hil_circuit_run rc_car_netlist.json short_drive.cscn --seed 1
[circuit] short_drive seed 1: PASS fw.state=3 ...
[circuit] short_drive seed 1 trace fnv1a64=455fbf73fa890068 steps=213815

In it, the firmware sits ARMED until 1.161 s, then goes to DRIVE at duty 0.80 and the motor spins up, with every net, current segment and temperature recorded. Run it again with seed 1 and you get the same hash. The home page plays the recording, and the demo opens the whole project in a tab.

A scenario ends in acceptance lines, and the engine that owns the metric judges them:

accept max(U1.VIN) <= 6.0
accept pp(+3V3) <= 0.10 in 0 0.010
accept tick_overruns == 0

Fast enough to leave running

You choose how much of each board is solved. full solves the circuit with real copper. io keeps the chips, sensors, inputs and outputs and replaces each rail with an ideal source, so the firmware runs against modelled sensors at speed. On the demo car, the twin at io fidelity runs a 14.2-hour battery-to-flat scenario (14,095 passes, 40.1 Wh) in about 35 seconds. A rangefinder session at io ran 7.5x to 12.7x faster than the same session at full, with its worst deviation a 12 % difference in display bytes and every verdict held. A check on something a fidelity level removed does not pass quietly: it fails and says why.

From the simulation to the board

The firmware's host tests print one summary line, for example [hil] controller: 120/120 checks passed, 0 failed, and a suite that exits without it counts as red. The demo firmware's suites report 2412 of 2412. The rule that ties the simulation to the bench is that a scenario which passes in the twin must run on hardware unchanged, and every constant only a bench can settle is a BENCH row the twin result names.

New to the idea? Hardware-in-the-loop, software-in-the-loop and digital twins sorts out the terms.

See it run on a real board.

The demo project is an RC car, its two boards, its twin and every gate’s record, in the real app, read-only, in a tab. The desktop app is in invite-only alpha for Windows, macOS and Linux.