| description | LabWired uses YAML configuration to define the simulated hardware, so the same firmware binary runs against different hardware configurations. |
|---|
LabWired uses a YAML-based configuration system to define the simulated hardware environment. This separation allows the same firmware binary to be tested against different hardware configurations (e.g., changing memory sizes or remapping peripherals) without recompilation.
A complete simulation requires two descriptor files:
- Chip Descriptor (
chips/<name>.yaml): Defines the internal architecture of the SoC (Flash/RAM size, internal peripheral addresses). - System Manifest (
systems/<name>.yaml): Instantiates a chip and defines board-level wiring (external sensors, UART loopbacks).
A chip descriptor loaded from a path may include: other chip YAMLs (§2), and
a manifest's external_devices: entries resolve either to a model built into
the engine or to a declarative device descriptor — configs/devices/*.yaml —
whose behavior: primitives are the third, data-only configuration surface
(§3, External devices).
Defines the invariant properties of the silicon.
name: "STM32F103"
arch: "arm"
core: "cortex-m3" # Exact CPU core; gates core-specific behavior
# (e.g. bit-band aliasing exists only on M3/M4)
flash:
base: 0x08000000
size: "64KB" # Supports KB/MB suffixes
ram:
base: 0x20000000
size: "20KB"
peripherals:
# Internal Peripheral Definition
- id: "usart1"
type: "uart"
base_address: 0x40013800
irq: 37
config:
profile: "stm32f1" # Loads architecture-specific register map
- id: "gpioa"
type: "gpio"
base_address: 0x40010800
config:
profile: "stm32f1"
# Declarative Peripheral (Custom)
- id: "my_custom_timer"
type: "declarative"
base_address: 0x40004000
config:
path: "../peripherals/custom_timer.yaml"This is the complete ChipDescriptor surface (crates/config/src/chip.rs); the
sample above is its common shape. name, arch, flash, ram, and
peripherals are required (peripherals: [] is a valid chip with no MMIO);
everything else is optional and has a default.
| Key | Meaning | Minimal example |
|---|---|---|
schema_version |
Free-form descriptor version; defaults to "1.0". |
schema_version: "1.0" |
name |
Part label; also how a manifest's bare-word chip: finds a built-in. |
name: "STM32F103" |
arch |
Instruction-set family: arm, riscv, xtensa, avr, unknown (family aliases like cortex-m3 are accepted). |
arch: "arm" |
core |
Exact core (cortex-m3, cortex-m33, cortex-m0+); gates per-core bus behavior — bit-band aliasing exists only on M3/M4. |
core: "cortex-m3" |
cpu_hz |
The clock the simulator runs the core at, in Hz. Declared, not derived — see Clock, schema and includes. 0 = undeclared. |
cpu_hz: 72_000_000 |
flash |
Primary flash window: base, size, optional cpu_writes policy (see below). |
flash: {base: 0x08000000, size: "64KB"} |
ram |
Primary RAM window: base, size, optional cpu_writes. |
ram: {base: 0x20000000, size: "20KB"} |
reset_vector_offset |
Bytes from the flash base to the application vector table when a stage-2 bootloader precedes it (0 = vectors at the flash base). |
reset_vector_offset: 0x100 |
flash_boot_alias |
true (default): address 0x0 mirrors flash (the STM32 boot alias). false for a part whose low addresses are real memory (i.MX RT ITCM at 0x0). |
flash_boot_alias: false |
atomic_register_aliases |
Register-alias flavour: false (default), true (= rp2040), rp2040, efr32s2. |
atomic_register_aliases: "efr32s2" |
ns_alias_offset |
TrustZone non-secure alias offset; applied only to otherwise-unmapped addresses, so it cannot shadow a declared peripheral. | ns_alias_offset: 0x10000000 |
memory_regions |
Extra CPU-visible windows beyond flash/ram — see Memory-map keys. |
see below |
peripherals |
MMIO peripheral list; see Peripheral entries. | peripherals: [] |
pins |
Authoritative pad→GPIO map; once declared, an unlisted pad no longer resolves (no silent label-letter fallback). | pins: {PA5: {gpio: gpio_a, bit: 5}} |
analog_pins |
Pad→ADC map (peripheral, channel); kept apart from pins so naming only the ADC inputs does not force a full GPIO transcription. |
analog_pins: {PA0: {peripheral: "adc1", channel: 0}} |
io_voltage_v |
The supply the chip's GPIO pads run from, in volts; reference for gpio_input_thresholds. Absent = "not transcribed" (nothing defaults it). |
io_voltage_v: 3.3 |
gpio_input_thresholds |
Digital input thresholds as ratios of io_voltage_v; must satisfy 0 < vil < vih < 1. |
gpio_input_thresholds: {vil: 0.35, vih: 0.65} |
supply_monitor |
POR/PDR/BOR supply thresholds — see Supply supervisor. | see below |
include |
Chip YAML include(s), expanded only when the descriptor is loaded from a path. | include: nrf52-common.yaml |
flash: and ram: are memory regions: base, size, and the optional
cpu_writes policy. The policy says what the bus does with a CPU-initiated
store into that region; it is independent per region and defaults to allow
(the only behaviour that existed before the key):
# configs/chips/ci-fixture-stm32l476-readonly.yaml
flash:
base: 0x08000000
size: "1024KB"
cpu_writes: fault # allow (default) | warn | fault
ram:
base: 0x20000000
size: "96KB" # omitted cpu_writes ⇒ allow| Mode | A CPU store into the region… | Recorded when the store is flagged or refused |
|---|---|---|
allow (default) |
commits silently, exactly as before | this region records nothing |
warn |
commits; one deduplicated WARN per region |
violation count + first {addr, cycle, pc} |
fault |
does not commit; raises SimulationError::MemoryViolation(addr) |
violation count + first {addr, cycle, pc} |
The semantics, precisely (crates/config/src/chip.rs CpuWritePolicy,
crates/core/src/bus/memory_policy.rs, crates/core/src/bus/accessors.rs):
- CPU stores only. The gate sits at the top of the CPU store path for every
access width (
write_u8/16/32/64) before anything commits. Host/loader writes never pass through it: loading an image whose segments land insideflash:/ram:writes the backing memory directly (Machine::load_firmware→LinearMemory::load_from_segment), and a snapshot restore is the same. The generic DMA request path runs with the gate explicitly bypassed; peripheral-internal DMA models that write through&mut dyn Busare a recorded deferral, not part of this rule yet. - The boot alias counts as flash. A store through the boot alias (address
0x0on a flash-at-0x08000000part) is gated as a flash store. fault→ precise BusFault. The store raisesSimulationError::MemoryViolation(addr). On an ARMv7-M core with BusFault enabled that is a precise data BusFault withBFARvalid, and the CLI's verdict names the region when the fault address matches the first recorded violation in afault-mode region (crates/cli/src/fault_report.rs):data access at 0x0800_1000 (BFAR valid; store to read-only flash).warncommits and records. The store lands exactly as withallow; one WARN is logged for the first violation in the region and no more — the count and the first violation are still recorded in full.result.json.memory_policyis skip-on-default.labwired testwrites the block only when at least one of the two regions is non-allow; an all-default config produces byte-identical artifacts to before the key existed. Each region carriesmode,violations, andfirst(addr,cycle,pc; omitted when there were none).
Runnable receipt: examples/readonly-flash/
runs a firmware store into cpu_writes: fault flash end to end, and
Add a board shows the flip to warn.
Known caveat — images linked at the boot alias. A segment whose address is
not inside the flash/RAM backing (an ELF linked at 0x0 on a part whose flash
sits at 0x0800_0000) is loaded byte-by-byte through the bus
(Machine::load_firmware falls back to one bus store per byte), and those load
stores are subject to cpu_writes like any other. With cpu_writes: fault on
flash, such an image cannot load: the first store is refused and the segment
fails — the Cortex-M loader logs
Failed to load segment at 0x0 - outside of memory map and continues with a
blank flash. Link firmware at the flash base, as real parts' images are; the
read-only-flash example is linked at
0x0800_0000, so its own load is direct and recorded as zero violations.
-
reset_vector_offset— where the real reset vector hides when a stage-2 bootloader precedes the application. The simulator does not execute the stage-2 blob (flash is directly mapped); it uses this offset to find the vector table when the flash-base vectors are not valid. RP2040 sets0x100(the boot2 blob).reset_vector_offset: 0x100 # configs/chips/rp2040.yaml
-
flash_boot_alias(defaulttrue) — whether address0x0mirrors the flash image. Setfalsefor a part whose low addresses are memory of their own; on the i.MX RT the ITCM sits at0x0, and with the alias on a store there would be written into flash.flash_boot_alias: false # no in-tree chip needs it today
-
atomic_register_aliases— the 0x1000-strided aliases of every peripheral register that a family's HAL uses for read-modify-write. Two families use the SAME stride with DIFFERENT ops, so the value names the flavour:rp2040:+0x1000XOR,+0x2000SET,+0x3000CLR (also RP2350);efr32s2:+0x1000SET,+0x2000CLR,+0x3000TGL (EFR32/EFM32 Series 2).
The historical boolean spelling still loads:
true==rp2040;false(or omitting the key) means an alias address is ordinary unmapped MMIO.atomic_register_aliases: true # configs/chips/rp2040.yaml atomic_register_aliases: "efr32s2" # configs/chips/efr32mg26.yaml
-
ns_alias_offset— the TrustZone non-secure alias window. An MMIO access that maps to no peripheral but whose address plus this offset DOES map to one is served by that peripheral; the offset applies only as a fallback, so it can never shadow a declared peripheral. The nRF54L family exposes every peripheral at0x5000_0000+(secure) and exactly0x1000_0000below it.ns_alias_offset: 0x10000000 # configs/chips/nrf54l15.yaml
-
memory_regions— additional CPU-visible windows beyondflash/ram(ESP32-C3 IRAM0x4037C000and flash-DROM view0x3C000000, the RP2040 bootrom). Each entry hasname,base,size, and optionally:image_env— an environment variable naming a raw binary loaded into the region atbase(a mask-ROM dump, say). The region stays zero-filled when the variable is unset or the file is missing.erased— fill the region with0xFFinstead of0x00. An erased flash byte reads ones, so a blank settings page must readffffffff …in the twin too.
# configs/chips/efr32mg26.yaml (excerpt) memory_regions: - name: "userdata" base: 0x0FE00000 size: "1KB" erased: true
Each peripherals: entry is a PeripheralConfig (crates/config/src/chip.rs):
| Key | Meaning | Minimal example |
|---|---|---|
id |
Instance name; clock:, board_io: and external_devices[].connection cite it. |
id: "usart1" |
type |
Model selector; an unrecognised type fails the load (see below). | type: "uart" |
base_address |
MMIO window base; accepts 0x… or an underscored integer. |
base_address: 0x40013800 |
size |
Optional window length. | size: "1KB" |
irq |
Vector line: irq: 37, or irq: nvic@37 to name the controller in one token. |
irq: 37 |
irq_controller |
Controller id when not given by the controller@line sugar. |
irq_controller: "nvic" |
clock |
RCC gate(s) that must ALL be set for the block to answer: one {reg, bit} or a list. reg is a symbolic enable-register name resolved at build time; a name the family does not expose is a hard build error. Absent ⇒ never gated. |
clock: {reg: "apb2enr", bit: 14} |
config |
Instance knobs. Unknown top-level keys flatten in here (easyDMA: true ≡ config: {easyDMA: true}); nested config: wins on a colliding key. |
config: {profile: "stm32f1"} |
The clock: mechanism (one gate or several ANDed) is documented in the
Peripheral modeling guide; declarative register blocks in
Declarative Register Definitions.
uart,usart: Universal Asynchronous Receiver Transmittergpio: General Purpose I/Orcc: Reset and Clock Controltimer: Basic Timeri2c: Inter-Integrated Circuitspi: Serial Peripheral Interfaceexti: External Interrupt Controllerafio: Alternate Function I/Odma: Direct Memory Access Controllersystick: System Tick Timerdeclarative: Loads a generic peripheral from a YAML register description.strict_ir: Loads a register map from Strict IR JSON.stub: A zero-filled window — only for types on the explicit known-stub allowlist (crates/core/src/bus/known_stubs.rs, shrink-only, each entry with a written reason).
Family factories add family-specific types (nrf52_uart, esp32c3_i2c,
imxrt_lpi2c, …). An unrecognised type is a load error, never a silent
zero-filled stub: the message tells you to model it, describe it with
type: declarative plus a descriptor path, or — if answering zeros really is
right — declare type: stub (or add the type to the allowlist with a reason).
| Key | Meaning | Minimal example |
|---|---|---|
pins |
Authoritative pad label → {gpio, bit} map. When a chip declares any pins, resolution goes through the map, so a pad whose label implies the wrong port still resolves correctly — and an undeclared pin fails to resolve instead of silently letter-parsing onto a port. Extra fields (e.g. functions:) are ignored by the simulator. |
pins: {PA5: {gpio: gpio_a, bit: 5}} (configs/chips/atsamd21g18a.yaml) |
analog_pins |
Pad label → the ADC that samples it (peripheral, channel), transcribed from the datasheet pinout. A pad absent here means "no analog pad is modelled", not "channel 0": the co-simulation board.analog.<pad>_volts path refuses such a pad rather than guessing. |
analog_pins: {PA0: {peripheral: "adc1", channel: 0}} (configs/chips/stm32f103.yaml) |
io_voltage_v |
The supply the GPIO pads run from, in volts. Absent means "not transcribed", and nothing defaults it — a board at another supply would get thresholds for the wrong rail. | io_voltage_v: 3.3 |
gpio_input_thresholds |
Datasheet digital input thresholds as ratios of io_voltage_v: a pad reads low at or below vil and high at or above vih. |
gpio_input_thresholds: {vil: 0.35, vih: 0.65} (configs/chips/stm32f103.yaml) |
supply_monitor: transcribes the part's reset and power-control thresholds: the
MCU is held in reset until VDD rises to por_rising_v (and, with a brown-out
level active, to that level's rising_v); it resets again when VDD falls below
pdr_falling_v or the active level's falling_v. It is only consulted when a
board routes its VDD net into the engine (board.power.vdd_volts); absent means
the chip cannot be held in reset by its supply, and such a route is refused
rather than guessed.
# configs/chips/stm32f401.yaml (excerpt)
supply_monitor:
por_rising_v: 1.72
pdr_falling_v: 1.68
bor_levels:
bor1: { falling_v: 2.19, rising_v: 2.29 }
bor2: { falling_v: 2.50, rising_v: 2.59 }
bor3: { falling_v: 2.83, rising_v: 2.92 }
# bor_level: bor1 # optional: the level in effect (absent = BOR disabled)cpu_hz— declared, not derived. Nothing walks RCC/PLL registers to compute a clock. This number is the single source of truth for every "how many cycles is a microsecond" question, and self-timed device models (DHT22, WS2812, the rotary encoder) scale their datasheet windows by it, so it must agree with the clock the firmware was built against or the firmware decodes noise.0means undeclared; every in-tree chip declares it (every_chip_descriptor_declares_a_cpu_hzfails the build if a new one does not). A board that runs the part slower overrides it with the manifest'scpu_hz:— the NUCLEO-L476RG never leaves the 4 MHz MSI reset clock and says so in its manifest.cpu_hz: 80_000_000
schema_version— descriptor version string, defaults to"1.0". No engine behaviour keys off it; it is provenance.schema_version: "1.0"
include— chip YAML include(s), expanded only when the descriptor is loaded from a path (ChipDescriptor::from_file); built-in chips cannot include because there is no filesystem. Paths are relative to the including file, includes load first, and local keys win.peripheralsmerge byid,memory_regionsbyname,pins/analog_pinsas maps.include: nrf52-common.yaml # or: include: [a.yaml, b.yaml]
Defines the board-level environment.
name: "BluePill Board"
chip: "../chips/stm32f103.yaml" # Path relative to this file
# Accepted but ignored today: the engine has no `connectors:` field (see the
# note under "Every manifest key"). Console routing is `debug_uart:`; external
# buses are `external_devices:`. Nine in-tree system manifests still carry this
# block, so it is documented rather than deleted.
connectors:
- type: "uart"
peripheral: "usart1"
endpoint: "host_console" # Pipes UART output to simulator stdoutThis is the complete SystemManifest surface (crates/config/src/manifest.rs).
name and chip are required; everything else is optional.
| Key | Meaning | Minimal example |
|---|---|---|
schema_version |
Defaults to "1.0"; environment manifests must declare "1.0" exactly. |
schema_version: "1.0" |
name |
Board label; used in logs and to name a private lab air. | name: "BluePill Board" |
chip |
A bare word (stm32f103) is a built-in/plugin chip name; anything containing /, \, or ending .yaml/.yml/.json is a path resolved relative to THIS manifest, so a manifest is relocatable with the files it names. |
chip: "stm32f103" |
cpu_hz |
Board-level override of the chip's declared clock, in Hz. Absent ⇒ the chip's default. | cpu_hz: 4_000_000 (configs/systems/nucleo-l476rg.yaml) |
memory_overrides |
Parsed but not consulted by the engine today — region sizes come from the chip descriptor. The field exists so manifests may carry it; do not rely on it. | memory_overrides: {flash: "512KB"} |
peripherals |
Chip-peripheral patches/additions. An entry whose id matches a chip peripheral merges its config keys and overrides base_address (when nonzero; 0 keeps the chip's), irq and size; an unmatched id adds a new peripheral. id, type and base_address are required on every entry. |
peripherals: [{id: "usart1", type: "uart", base_address: 0, config: {profile: "stm32f1"}}] |
external_devices |
The parts on the board's buses — see External devices. | see below |
parts |
Manifest-carried part packs (private/vendor catalogs). The labwired.part/v1 contract lives in Part packs; - path: is a CLI convenience that SystemManifest::from_file inlines, so a manifest handed straight to the browser/engine must carry the pack inline. |
parts: [{path: "./acme.yaml"}] |
cosim_models |
Scalar signal-level co-simulation plants — see Co-simulation and motor models. | see below |
motor_models |
Typed motor plants (kind: dc or kind: bldc) with SI-unit fields. |
see below |
board_io |
Board-level pin bindings — see Board I/O. | see below |
debug_uart |
Which console the board's USB socket is wired to; see its section below. | debug_uart: "uart0" |
wifi_ap |
Opt-in per-lab virtual WiFi AP — see WiFi AP. Absent ⇒ no AP. | see below |
walk_deleted |
Per-cycle peripheral-walk deletion: absent = auto-derive, true = force deleted, false = pin on. Only consulted in event-scheduler builds; a legacy build always walks. |
walk_deleted: true (examples/nokia5110-invaders-lab/system.yaml) |
connectors: — nine in-tree system manifests (arduino-uno-r4-minima,
calliope-mini-v1, metro-m4, microbit-v1, microbit-v2, nano-33-iot, pybadge,
stm32f7-discovery, teensy-41) still carry a connectors: block that the engine
ignores; their consoles work through the defaults meanwhile. One day core may
parse it; today it is not a configuration surface.
walk_deleted in full (crates/config/src/manifest.rs): absent means the core
auto-derives walk-deletability at build time — the walk is deleted iff EVERY
peripheral on the bus is provably walk-independent for all firmware states
(conservative). true is a hand opt-in for a config verified byte-identical
walk-free; false pins the walk on.
Each external_devices: entry:
| Key | Meaning |
|---|---|
id |
Instance name. board_io and stimulus channels address the device by it, and mux children name it as their connection. |
type |
The device model — see the catalog below. An unknown type is a hard load error; nothing is silently skipped. |
connection |
What the device hangs off: normally a controller peripheral id ("i2c1", "spi1", "uart2"), or a GPIO peripheral id for pin-timing parts. It may also name ANOTHER external device's id — that is how a slave is placed behind a TCA9548A bus switch. |
channel |
Downstream channel on a bus switch (0..=7; absent behind a switch means 0). Meaningless and ignored when connection names a controller. |
route |
Optional signal→pad route: sda/scl, mosi/miso/sck, tx/rx. Required by controllers whose pads are runtime-routed — an ESP32-C3 I²C rejects a missing route because its GPIO matrix makes the wiring runtime-configurable. |
config |
Per-device knobs (i2c_address, pin labels, seeds, …); the model's metadata lists the keys it reads. |
Resolution order — one implementation in crates/core/src/bus/external_devices.rs:
- the manifest's own
parts:packs (most specific wins); - the built-in kit registry (the catalog below);
- the declarative
configs/devices/*.yamldescriptors.
Anything still unclaimed fails the build with the manifest id and type named.
The catalog is generated from the kit registry into
crates/core/tests/fixtures/peripherals/manifest.json (regenerate with
cargo run -p labwired-cli --bin gen-peripherals-manifest). One line per
canonical type:; the table below is rendered from that file by
python3 scripts/ci/device_catalog_doc.py --write and checked in CI:
type |
Bus | Model |
|---|---|---|
bg770a-cellular |
UART | LTE-M / NB-IoT cellular modem with the full Quectel AT command surface |
bt201 |
UART | Dual-mode Bluetooth 5.0 audio + BLE module with a UART AT interface and BLE transparent data |
esp32c3_esp_at |
UART | Bounded AT peer with explicit mock connection state |
hc-05 |
UART | Bluetooth SPP module with AT command shell over UART |
iolink-master |
UART | IO-Link master state machine over UART |
max485 |
UART | Half-duplex RS-485 transceiver between a UART and a shared A/B pair |
neo6m-gps |
UART | GPS module streaming NMEA sentences over UART RX |
sim800l |
UART | SIM800L UART AT command shell (no cellular RF) |
tiol112 |
UART | TI IO-Link digital transceiver: EN, inverted CQ, WAKE and NFAULT |
xy-md02 |
UART | SHT20 RS-485 temperature and humidity transmitter speaking Modbus RTU |
ydlidar-scanner |
UART | Spinning lidar streaming YDLIDAR scan frames over UART RX at 230400 baud |
ads1015 |
I²C | 4-channel 12-bit I²C ADC (TI ADS1015), sibling of the ADS1115 |
ads1115 |
I²C | 4-channel 16-bit I²C ADC (TI ADS1115) |
adxl345 |
I²C | 3-axis ±2/4/8/16 g digital accelerometer over I2C |
aht20 |
I²C | Aosong AHT20 I²C temperature and humidity sensor |
as5600 |
I²C | 12-bit contactless magnetic rotary position sensor over I²C |
at24c256 |
I²C | I²C serial EEPROM with a 16-bit address pointer and 64-byte pages |
atecc608a |
I²C | I²C secure element: P-256 sign/verify, RNG, key slots (HSM/TPM role) |
bh1750 |
I²C | Ambient-light sensor over I²C (single-byte opcodes) |
bme280 |
I²C | Bosch BME280 temp + humidity + pressure sensor over I2C |
bme680 |
I²C | Bosch BME680 temperature / pressure / humidity sensor over I²C (gas channel not modelled) |
bmi160 |
I²C | Bosch BMI160 6-axis IMU (accel + gyro + temperature) over I²C |
bmi270 |
I²C | Bosch BMI270 low-power IMU with hardware step counter over I2C |
bmm150 |
I²C | Bosch BMM150 3-axis geomagnetic sensor over I²C (chip ID 0x32, trim block) |
bmp280 |
I²C | Bosch BMP280 I²C pressure + temperature sensor (no humidity) |
bno055 |
I²C | 9-DoF absolute orientation sensor (Bosch BNO055) over I²C |
cap1188 |
I²C | Microchip CAP1188 8-channel capacitive touch controller over I2C |
dht20 |
I²C | Aosong DHT20 I²C temperature and humidity module (AHT20-based) |
drv2605 |
I²C | TI DRV2605 haptic motor driver over I2C |
ds3231 |
I²C | I²C real-time clock with temperature-compensated crystal |
ens160 |
I²C | ScioSense ENS160 MOx multi-gas sensor (TVOC, eCO2, AQI-UBA) over I²C |
fxos8700 |
I²C | NXP FXOS8700 6-axis accelerometer + magnetometer over I2C |
ht16k33 |
I²C | 16×8 LED matrix / 7-segment I²C controller (display RAM, setup commands) |
icm20948 |
I²C | TDK InvenSense ICM-20948 motion sensor (accel + gyro + temperature; magnetometer not modelled) over I²C |
icm42688 |
I²C | TDK InvenSense ICM-42688-P 6-axis IMU (accel + gyro + temperature) over I²C |
ina219 |
I²C | High-side current and bus voltage sensor over I²C |
ina226 |
I²C | TI INA226 bidirectional current / power monitor over I²C (36 V, 16-bit) |
ina260 |
I²C | TI INA260 current / voltage / power monitor with an integrated 2 mΩ shunt over I²C (36 V, 15 A) |
ina3221 |
I²C | TI INA3221 three-channel shunt and bus voltage monitor over I²C (26 V) |
lcd1602 |
I²C | 16×2 HD44780 character LCD behind a PCF8574 I2C backpack |
lsm303agr_accel |
I²C | ST LSM303AGR accelerometer half over I2C (address 0x19) |
lsm303agr_mag |
I²C | ST LSM303AGR magnetometer half over I2C (address 0x1E) |
max30102 |
I²C | Maxim MAX30102 pulse-oximetry / heart-rate front-end over I2C |
mcp9808 |
I²C | ±0.25 °C I²C temperature sensor with seeded noise + thermal lag |
mcp23017 |
I²C | Microchip MCP23017 16-bit I²C GPIO expander (IODIR / GPIO / OLAT register map) |
mlx90614 |
I²C | Single-point IR (non-contact) thermometer over SMBus/I2C |
mlx90640 |
I²C | Melexis MLX90640 32×24 far-IR thermal array over I2C |
mma8451q |
I²C | 3-axis 14-bit accelerometer over I2C with standby/active gating |
mpu6050 |
I²C | 6-axis gyro + accelerometer over I2C |
mpu9250 |
I²C | TDK InvenSense MPU-9250 motion sensor (accel + gyro + temperature; AK8963 magnetometer not modelled) over I²C |
nau88l21 |
I²C | Nuvoton NAU88L21 stereo audio codec: I2C control port and register file |
oled-sh1107 |
I²C | 128×128 monochrome OLED display over I2C with a paged framebuffer |
oled-ssd1306 |
I²C | 128×64 monochrome OLED display over I2C with a paged framebuffer |
oled-ssd1306-128x32 |
I²C | 0.91″ 128×32 monochrome OLED display over I2C with a paged framebuffer |
oled-ssd1309 |
I²C | 2.42in 128×64 monochrome OLED on a Solomon Systech SSD1309, I2C, paged framebuffer |
ov3660 |
I²C | OmniVision 3 MP camera: SCCB control at 0x3C plus 8-bit DVP frames into the ESP32-S3 LCD_CAM |
pca9685 |
I²C | 16-channel 12-bit I²C PWM / servo controller |
pcf8574 |
I²C | NXP PCF8574 8-bit I²C quasi-bidirectional port expander |
pcf8575 |
I²C | 16-bit I²C quasi-bidirectional port expander (PCF8575) |
pmsa003i |
I²C | Plantower PMSA003I particulate-matter sensor (PM1.0 / PM2.5 / PM10) over I²C |
pn532 |
I²C | NXP PN532 I²C NFC controller probe shell (no RF) |
scd41 |
I²C | Photoacoustic CO₂ + temperature + humidity sensor over I2C |
sgp40 |
I²C | MOx VOC sensor returning the raw SRAW_VOC signal over I²C |
sgp41 |
I²C | MOx gas sensor returning raw VOC/NOx signals over I2C |
sht30 |
I²C | Sensirion SHT30 I²C temperature and humidity sensor |
sht31 |
I²C | Temperature + humidity sensor over I²C (Sensirion CRC-8) |
sht40 |
I²C | Sensirion SHT40 I²C temperature and humidity sensor (single-byte commands, CRC-8) |
sps30 |
I²C | Laser particulate-matter sensor (PM1/2.5/4/10) over I2C |
tmp102 |
I²C | 12-bit I²C temperature sensor (self-drifting demo) |
tmp117 |
I²C | TI TMP117 high-accuracy digital temperature sensor over I2C |
tsl2591 |
I²C | ams TSL2591 high-dynamic-range light sensor (full-spectrum + IR channels) over I²C |
vcnl4010 |
I²C | Proximity + ambient-light sensor over I2C (fixed address 0x13) |
veml6075 |
I²C | UVA / UVB light sensor over I²C (16-bit counts, ID 0x0026) |
veml7700 |
I²C | Ambient-light sensor (lux) over I2C |
vl53l0x |
I²C | Laser time-of-flight distance sensor over I²C (ST VL53L0X) |
vl53l1x |
I²C | Laser time-of-flight distance sensor over I2C |
74hc595 |
SPI | 8-bit serial-in / parallel-out shift register over SPI |
ads1256 |
SPI | 8-channel 24-bit delta-sigma SPI ADC (RREG/WREG/RDATA, PGA, DRDY) |
adxl345_spi |
SPI | 3-axis ±16 g accelerometer over SPI (full-resolution, 256 LSB/g) |
amoled-rm67162 |
SPI | 240x536 RGB565 AMOLED, 4-wire SPI (DBI Type-C) |
apa102 |
SPI | SPI-clocked addressable RGB LED strip (write-only sink) |
bmi270_spi |
SPI | Native four-wire BMI270 with real CS/dummy-byte framing, verified configuration upload and nominal motion sampling |
gc9a01 |
SPI | 1.28in round 240x240 RGB565 IPS TFT on a GalaxyCore GC9A01A, 4-wire SPI |
hc595-7seg |
SPI | 4-digit 7-segment LED display driven by two chained 74HC595 shift registers over SPI |
ili9341 |
SPI | 240×320 RGB565 SPI TFT display |
ili9488 |
SPI | 320×480 SPI TFT controller with modelled 18-bit COLMOD |
inmp441 |
SPI | Omnidirectional MEMS microphone, 24-bit I2S digital output |
led-matrix |
SPI | 8×8 LED matrix driven by a MAX7219 serial display driver over SPI |
lora-sx1278 |
SPI | Semtech SX1278 SPI LoRa register shell (no RF) |
max31855 |
SPI | K-type thermocouple-to-digital converter over SPI (read-only 32-bit frame) |
mcp2515 |
SPI | Functional SPI classical CAN controller for standard 11-bit data frames |
mcp3008 |
SPI | 8-channel 10-bit SPI ADC (single-ended / differential, Figure 6-1 framing) |
microsd |
SPI | SPI-mode SDHC card backed by a disk image or an in-memory block store (init, CSD/CID, single and multi-block read/write) |
nrf24l01 |
SPI | 2.4 GHz SPI transceiver register shell (no air link) |
pcd8544 |
SPI | Nokia 5110 (PCD8544) monochrome 84×48 LCD over SPI |
rc522 |
SPI | MFRC522 SPI RFID reader with ISO/IEC 14443-A cascade-level-1 air interface |
rfm95 |
SPI | HopeRF RFM95W (Semtech SX1276) SPI LoRa register shell (no RF) |
sn74hc165 |
SPI | 8-bit parallel-in / serial-out shift register over SPI |
ssd1680_tricolor_290 |
SPI | 2.9" tri-color (black/white/red) e-paper over SPI. Driver class GxEPD2_290_C90c -- the WeAct / Waveshare 2.9" B/W/R module. Not interchangeable with the UC8151D part |
st7735 |
SPI | 1.8in 128x160 RGB565 TFT on a Sitronix ST7735R, 4-wire SPI |
st7789-170x320 |
SPI | 1.9in 170x320 IPS TFT on a Sitronix ST7789V, 4-wire SPI |
sx1262 |
SPI | Semtech SX1262 LoRa transceiver, SPI command interface (status, standby/RX/TX, registers, IRQ) — no RF air link |
sx1276 |
SPI | Semtech SX1276 LoRa transceiver, SPI register model of the LoRa page (no RF air link) |
uc8151d_tricolor_290 |
SPI | 2.9" tri-color (black/white/red) e-paper over SPI. Driver class GxEPD2_290_Z13c. Different command set from the SSD1680 part -- pick by the driver class your firmware instantiates, not by how the panel looks |
74cbtlv3257 |
GPIO | Four 1-of-2 bus switches; S picks the A or B side, OE opens all four |
74hc00 |
GPIO | Four independent 2-input NAND gates, 9 ns propagation delay |
74hc04 |
GPIO | Six independent inverting buffers, 7 ns propagation delay |
74hc08 |
GPIO | Four independent 2-input AND gates, 8 ns propagation delay |
74hc32 |
GPIO | Four independent 2-input OR gates, 9 ns propagation delay |
74hc125 |
GPIO | Four non-inverting buffers, each with its own active-low output enable |
74hc245 |
GPIO | Eight bidirectional bits; DIR picks the direction, OE isolates both buses |
74hc4051 |
GPIO | Routes one of eight analog inputs (Y0..Y7) to an ADC channel, selected by three GPIO pins |
74lvc1t45 |
GPIO | Single-bit bidirectional translator; DIR picks the direction, OE isolates |
a4988 |
GPIO | A4988/DRV8825/TMC2209-class STEP/DIR twin (step count + angle) |
bldc-motor |
GPIO | Configurable deterministic three-phase BLDC motor plant |
bldc_hall_driver |
GPIO | PWM/DIR/ENABLE in; 6-step Hall pattern out. Duty→RPM not modelled |
dc-motor |
GPIO | Configurable deterministic brushed DC motor plant |
dfplayer_mini |
GPIO | MP3 player module: serial commands in, BUSY low while playing |
dht11 |
GPIO | One-wire temperature + humidity sensor |
dht22 |
GPIO | One-wire temperature + humidity sensor |
hc-sr04 |
GPIO | Ultrasonic distance sensor (trigger / echo) |
hx711 |
GPIO | 24-bit load-cell amplifier (DT/SCK bit-bang) |
ili9341-16bit |
GPIO | 240×320 RGB565 TFT over Intel 8080 16-bit GPIO bit-bang |
keypad |
GPIO | 4×4 membrane keypad (row-drive / column-read) |
l298n |
GPIO | L298N/TB6612/L293D-class dual H-bridge twin (direction + enable effort) |
led-matrix-mux |
GPIO | Row/column LED matrix (micro:bit 5x5, bare 8x8) multiplexed by GPIO row and column lines, with per-pixel brightness |
limit-switch |
GPIO | Mechanical end-stop with common, normally-open and normally-closed contacts |
lm393-moisture |
GPIO | Resistive soil/moisture module with LM393 comparator DOUT (LOW=wet, HIGH=dry) |
logic_level_shifter_4ch |
GPIO | BSS138-class 4-channel bidirectional shifter; DIR is a sim strap (not on the PCB) |
neopixel |
GPIO | Addressable RGB LED strip on one data pin (edge-timed bit stream) |
pybadge_buttons |
GPIO | Eight active-low buttons through the board's SN74HC165 |
rotary_encoder |
GPIO | Incremental quadrature knob (EC11) |
segment-display-mux |
GPIO | N-digit 7/14/16-segment LED display, multiplexed by GPIO segment and digit-select lines |
servo |
GPIO | RC hobby servo driven by a single PWM control pin (GPIO edges and/or LEDC duty) |
seven-segment |
GPIO | Bare single-digit 7-segment LED display driven straight from nine GPIO pins |
sk6812 |
GPIO | Addressable RGBW LED strip on one data pin (32-bit edge-timed frames) |
tm1637-7seg |
GPIO | 4-digit 7-segment LED display with the TM1637 2-wire (CLK/DIO) driver |
tm1638 |
GPIO | 8-digit 7-segment + 8 LED display with the TM1638 3-wire (STB/CLK/DIO) driver |
uln2003 |
GPIO | Four-phase unipolar stepper twin (IN1..IN4) |
uln2803 |
GPIO | Eight inverting open-collector Darlington sink channels (500 mA each), 200 ns delay |
acs712 |
Analog | Ratiometric Hall current sensor, 185 mV/A and VCC/2 at zero current |
gp2y0a21 |
Analog | Sharp GP2Y0A21YK0F analogue infrared distance sensor, 10–80 cm (Vo on ADC) |
joystick |
Analog | Two ratiometric potentiometer axes and a push contact |
ldr |
Analog | CdS photoresistor + voltage divider on an ADC channel |
lipo_charger |
Analog | Single-cell LiPo pack + TP4056-class analog charger on an ADC channel |
mq-6 |
Analog | Hanwei MQ-6 LPG/propane semiconductor gas sensor module (AOUT on ADC) |
ntc-thermistor |
Analog | 10 kΩ NTC + voltage divider on an ADC channel |
potentiometer |
Analog | 3-pin linear potentiometer on an ADC channel (rotary or slide) |
rain-sensor |
Analog | Rain drop plate + LM393 module (AO on ADC; wetter → lower voltage) |
soil-moisture |
Analog | Capacitive soil moisture probe module (AOUT on ADC; wetter → lower voltage) |
sound-sensor |
Analog | Analog microphone sound-level module (A0 on ADC) |
tmp36 |
Analog | Analog temperature sensor, 10 mV/°C with 500 mV at 0 °C |
xl4015 |
Analog | Adjustable XL4015 buck; Vout setpoint observed through a ÷11 ADC divider |
can-bridge |
CAN | Boundary between a CAN controller and traffic from outside the simulation |
can-diagnostic-tester |
CAN | One-shot single-frame UDS-style request injector on bxCAN/FDCAN |
can-player |
CAN | Replays candump-format traffic into a bxCAN/FDCAN controller |
uds-tester |
CAN | Stateful multi-frame UDS tester (SecurityAccess-class handshakes) |
Legacy and alternate spellings resolve to the same canonical models:
sn74cbtlv3257 = 74cbtlv3257; 74ls00/74hct00 = 74hc00;
74ls04/74hct04 = 74hc04; 74ls08/74hct08 = 74hc08;
74ls125/74lvth125/sn74lvth125 = 74hc125;
74ls245/74lvc245/sn74lvc245a = 74hc245; 74ls32/74hct32 = 74hc32;
cd4051/cd74hc4051 = 74hc4051; hc595 = 74hc595;
sn74lvc1t45 = 74lvc1t45; drv8825/tmc2209 = a4988; dc_motor =
dc-motor; bldc_motor = bldc-motor; bldc-hall-driver =
bldc_hall_driver; uds-diagnostic-tester = can-diagnostic-tester; am2302
= dht22; drv2605l = drv2605; hc05 = hc-05; hcsr04 = hc-sr04;
hc595_7seg = hc595-7seg; ili9341_16bit = ili9341-16bit;
bts7960/ibt-2/ibt2/l293d/tb6612 = l298n; max7219 = led-matrix;
led_matrix_mux = led-matrix-mux; logic-level-shifter-4ch =
logic_level_shifter_4ch; ws2812 = neopixel; slide-potentiometer =
potentiometer; rotary-encoder = rotary_encoder; segment_display_mux =
segment-display-mux; sg90/mg996r = servo; seven_segment =
seven-segment; epd-2in9-tricolor/gxepd2_290_c90c =
ssd1680_tricolor_290; tm1637_7seg = tm1637-7seg; epd-2in9-uc8151d =
uc8151d_tricolor_290; stepper-28byj48 = uln2003.
Two I²C types are attached by the I²C factory rather than the kit registry and
so are absent from the generated catalog: tca9548a (aliases pca9548a,
tca9548) — the 8-channel bus switch whose channel: places children behind
it; and shm_i2c — a shared-memory I²C bridge for host-injected traffic.
Beyond the catalog and those two, any type: is valid if the manifest's own
parts: defines it — see Part packs for the
labwired.part/v1 contract and the behavior: primitive reference.
Every model in the catalog is a device descriptor: the in-tree ones live in
configs/devices/*.yaml, and a manifest can carry its own in parts:. The
top-level keys (crates/config/src/peripherals.rs DeviceDescriptor):
| Key | Meaning |
|---|---|
type |
The type: string the manifest uses — a descriptor's identity. |
behavior |
Which runtime primitive backs the part and how its pins/registers are declared. |
emit |
How the canvas compiler emits this device into a manifest (used by the browser compiler; optional). |
metadata |
Display labels, accepted config: keys, and the stimulus channels the part serves — load-bearing: the same channel definitions back the device's SimInput impl. |
schema |
Contract version — required of a manifest-carried pack (labwired.part/v1). |
source |
Provenance (which catalog/vendor shipped the pack), so errors can name where a model came from. |
overrides |
The built-in type this pack deliberately replaces; shadowing a built-in is otherwise a hard error. |
catalog |
App-layer catalog record (opaque to the simulator). |
behavior.primitive selects the interpreter (one line each):
| Primitive | What the engine interprets |
|---|---|
i2c_device |
Register-pointer I²C part (the i2c: block). |
spi_device |
SPI register/frame part (the spi: block). |
display |
Framebuffer panel: geometry, pixel format, RAM layout, command/data framing. |
led_strip |
Addressable LED strip: wire protocol plus the artifact it publishes. |
analog_source |
ADC-channel plant: the datasheet's output curve. |
uart_device |
Byte-stream part: frame shape, command table, unsolicited output. |
uart_transceiver |
A part that gates a UART (driver/receiver enable pads). |
gpio_device |
Pin-timing part driven by rules and finite edge schedules. |
logic_gate |
74-series truth table, enables, direction/select, propagation delay. |
segment_display |
Multiplexed 7/14/16-segment display. |
led_matrix |
Row/column multiplexed LED matrix. |
analog_mux |
Analog multiplexer: select pins, channel count, enable. |
dc_motor / bldc_motor |
Motor plants — converted to the typed plants at the loader boundary. |
The wire-level detail (register encoding keys, schedules, artifacts, rules)
lives in Part packs; declarative register blocks for chip
peripherals live in Declarative Register Definitions.
Worked examples: configs/devices/adxl345.yaml (I²C), configs/devices/dht22.yaml
(one-wire GPIO), and the howtos under Extend LabWired.
cosim_models: declares scalar signal-level plants stepped in lockstep with the
machine: id, adapter (external_process, fmi, mock, analog),
model (required for external_process and fmi), step_ns (default
1000), inputs/outputs (signal name → board.* route) and free-form
config. The analog adapter needs config.netlist (a path) or
config.netlist_text (inline) plus config.probes. Deep reference:
External-process co-simulation.
# examples/cosim-spice-rc/system.yaml (excerpt)
cosim_models:
- id: "rc_lowpass"
adapter: "external_process"
model: "./models/rc_lowpass.py"
step_ns: 100000 # 100 us; RC tau is 1 ms
inputs:
gpio: "board.gpio.pa5"
outputs:
v_out: "board.analog.pa0_volts"
config:
protocol: "jsonl"
engine: "ngspice"
netlist: "./rc.cir"motor_models: declares typed deterministic motor plants —
kind: dc (brushed) or kind: bldc — with SI-unit fields (resistance,
inductance, torque/back-EMF constants, inertia, friction, supply, encoder CPR)
and pad bindings; see
examples/nucleo-l476rg-bldc/system.yaml
for the full BLDC form. A motor can equivalently be declared as an
external_devices entry with type: dc-motor or bldc-motor: the loader
converts it to the same typed plant (MotorModelConfig::from_external_device),
so the two spellings cannot drift.
For a physical three-lead winding driven by a solved inverter circuit, use
armature: circuit and the circuit BLDC contract.
The timer-driven BLDC plant reads channels 1–3 and their complementary outputs from the
configured timer's output-stage snapshot. The loader resolves the six phase
pin names, but live GPIO MODER/AFR selection does not gate the plant. The
STM32L476 mapping uses PA8–PA10 and PB13–PB15 as AF1; native pad capture must
check that mapping separately. Arbitrary runtime phase-pin remapping is
outside this plant contract.
Native numeric instruments can read live_numeric_capture(cursor, maxPoints)
from a machine. This additive stream has its own string epoch, stable
name/unit channel descriptors, and finite f64 observations at native
timeNs. Each point has a sequence seq and a zero-based numeric channel
index. The fixed 20,000-point ring keeps the newest observations, including
quiet accepted motor samples. Historical analog_series remains a separate
65,536-point-per-channel prefix with its existing deadbands and dropped
count; neither cursor nor retention policy is shared with the co-simulation
analog ring.
Pass back nextCursor as the next unread sequence. oldestCursor is the
oldest retained sequence, evicted counts normal cumulative ring evictions,
readerMissed counts requested points already overwritten, and omitted
counts available points excluded only by this read's newest-point limit.
Reads do not consume data. On an epoch change or resetRequired, discard the
old cursor/history and reread at zero. Replacement or a true timeline rewind
changes the epoch; a physical CPU reset on a continuing timeline does not.
Each channel reports valid, knownFromNs, knownUntilNs, and
invalidReason. A failed plant cannot extend its horizon using a healthy
peer's time. A resumed channel starts a new known interval, and a channel
without a retained native anchor has null knownFromNs. The export is null
when the machine has no live numeric producer.
# examples/f401-hbridge-dc-motor/system.yaml (excerpt)
external_devices:
- id: motor
type: dc-motor
connection: gpio
config:
resistance_ohm: 1.2
inductance_h: 0.002
torque_constant_nm_per_a: 0.08
back_emf_constant_v_per_rad_s: 0.08
rotor_inertia_kg_m2: 0.00004
viscous_friction_nm_per_rad_s: 0.00001
coulomb_friction_nm: 0.006
supply_voltage_v: 12.0
load_torque_nm: 0.0
encoder_cpr: 1024
simulation_clock_hz: 84000000
in1_pin: PA0
in2_pin: PA1
both_inputs_low: brake
pwm_pin: PA6
timer_name: tim3
timer_channel: 1A kind: dc motor can instead put its winding in an analog netlist with
armature: circuit. The netlist carries the winding as series R + L + a
back-EMF voltage source under whatever switch, flyback diode and rail drive it
(a low-side transistor, a bridge, a relay — any MCU); it routes the solved
winding current in on board.motor.<id>.current_a and reads the motor's
back-EMF on board.motor.<id>.back_emf_v (see
cosimulation_plugins.md). The plant then only turns
that current into torque and integrates the shaft, so the supply is the
netlist's wired rail: supply_voltage_v, pwm_pin and the direction / brake /
enable / timer keys are refused. Every motor also publishes
motor.<id>.speed_rpm and motor.<id>.current_a change-point series in
analog_series (with armature: circuit, current is absent until routed).
The netlist may also route the rail feeding the winding in on
board.motor.<id>.supply_v; the motor reports it as its bus_voltage_v
(0 while unrouted).
Both motor kinds take an optional coulomb_friction_nm (default 0): dry
bearing and brush friction, a constant torque opposing rotation that also
holds a resting shaft until the drive exceeds it. Viscous drag alone never
stops a shaft — the catalog motor's 10 µN·m·s/rad over a 40 g·cm² rotor is a
4 s time constant — so the catalog dc-motor part defaults it to 6 mN·m,
which stops a coasting fan in well under a second.
motor_models:
- kind: dc
id: fan
armature: circuit # default: bridge
resistance_ohm: 1.2
inductance_h: 0.002
torque_constant_nm_per_a: 0.08
back_emf_constant_v_per_rad_s: 0.08
rotor_inertia_kg_m2: 0.00004
viscous_friction_nm_per_rad_s: 0.00001
coulomb_friction_nm: 0.006
load_torque_nm: 0.0
encoder_cpr: 12
simulation_clock_hz: 16000000board_io: is the board-level pin vocabulary: an LED soldered to a pad, a
button a user can press, an ADC input. Entries are BoardIoBinding:
| Key | Meaning |
|---|---|
id |
Binding name; also the stimulus channel for a drivable contact. |
kind |
led, button, adc_input, pwm_output, i2c_device, spi_device, uart_device. |
peripheral |
The peripheral id (from the chip or a manifest patch) that owns the pin. |
pin |
Bit within that peripheral's port / ADC channel number. |
signal |
output (default) or input. A kind: button binding with signal: input is additionally materialised as a drivable button stimulus; an output-kind button is not a contact the firmware samples. |
active_high |
Polarity, default true. |
i2c_address |
For kind: i2c_device bindings. |
device_type |
The external-device type this binding surfaces, for the browser. |
channel |
Stimulus channel this contact exposes when it is not a plain pressed button (obstacle, field, vibration, …); absent means pressed. |
# configs/systems/nucleo-l476rg.yaml (excerpt)
board_io:
- id: "led_ld2"
kind: "led"
peripheral: "gpioa"
pin: 5
signal: "output"
active_high: true
- id: "button_b1"
kind: "button"
peripheral: "gpioc"
pin: 13
signal: "input"
active_high: falsewifi_ap: is the opt-in virtual access point, emitted when a lab diagram
contains a wifi-ap component. Absent ⇒ no AP, and WiFi MACs stay
unassociated (the honest "no AP present"). No in-tree system manifest uses the
key yet.
wifi_ap:
ssid: "labwired-ap" # defaults shown
ip: "192.168.4.1" # its /24 is the DHCP pool
serves: "labwired-stats" # or "none"
password: "" # empty/absent = open AP; a WPA handshake is not modelled yetFor st7789-170x320 external devices, the optional config keys col_offset,
row_offset, cols, and rows describe the glass in physical 240×320
frame-memory coordinates. Supply all four together. For a module exposing
columns 35–204 and all 320 rows, use col_offset: 35, row_offset: 0,
cols: 170, and rows: 320; the offsets are module integration values.
The configured framebuffer and artifact dimensions remain 170×320 regardless of MADCTL rotation or mirroring. MADCTL controls how firmware writes map into physical memory, while the glass stays fixed. Without a configured window, the framebuffer uses firmware coordinates and reports 240×320 or 320×240 according to MADCTL's row/column exchange bit.
debug_uart: "usb_serial_jtag" # ESP32-C3 SuperMini, ESP32-S3 Zero
debug_uart: "uart0" # CP210x/CH34x bridge boards
debug_uart: "uart1" # a board that routes its console elsewhereAn ESP32-C3 or -S3 has two consoles in silicon: UART0 and the chip's own
USB-Serial-JTAG block. Which one carries Serial to the developer's cable is
neither a chip fact nor a firmware fact — it is a BOARD fact, decided by what
the USB socket is soldered to:
| board's USB socket | console | Serial build flag |
|---|---|---|
| native USB | USB-Serial-JTAG | ARDUINO_USB_CDC_ON_BOOT=1 |
| USB-UART bridge IC | UART0 | ARDUINO_USB_CDC_ON_BOOT=0 |
The build flags and this key must come from the SAME board fact. If they
disagree, firmware built for one console runs against a twin listening on the
other and the Serial pane stays empty — which is exactly what a real board does
when the flags are wrong, and exactly what shipped: a hosted build flashed to a
real ESP32-C3 SuperMini printed the ROM and bootloader banners and then nothing,
because Serial was on UART0 and a SuperMini's USB-C is not.
The engine taps ONE console, the declared one, because a real board gives you
one cable. It records the other and reports what the firmware said there
(WasmSimulator::console_mismatch) so a silent pane has a reason. A declared
console the bus does not have is refused at construction rather than silently
substituted — see crates/core/src/console.rs.
Omit the key to keep each path's historical default (UART0 on the ESP32-C3 merged-flash paths; every console-capable UART elsewhere).
For an inputs.env CI world, each nodes[].system value points to this
same System Manifest format used by the Playground. The environment manifest
adds node IDs, firmware paths, and explicit interconnects; it does not create a
second board-configuration dialect. v0.19 world manifests reject
nodes[].config_overrides: the field must be omitted, including {} and null.
Each resolved node chip must resolve to arch: arm and declare
core: cortex-m*; its firmware must be an EM_ARM ELF with a valid Cortex-M
Thumb reset vector at flash.base + reset_vector_offset (SP in RAM and
Thumb-bit reset handler in flash). See the CI Test Runner
for the closed world-interconnect schema.
A node may set profile: arduino-esp32, the same boot profile a test script
names in inputs.profile: a classic-ESP32 (Xtensa LX6) node running an
Arduino-ESP32 sketch ELF then takes the Arduino fast boot
(install_arduino_esp32_profile). Any other value, or the profile on any other
chip, is refused, and a world admits one such node (the profile's boot thunks
keep per-thread state). ESP32-S3 and ESP32-C3 nodes need no profile; their mask
ROMs are provisioned like the single-chip engine's (in the browser, passed as
the node's blobs).
World completion stays in the inputs.env test script, not the manifest. Set
limits.stop_when_assertions_pass: true to opt into a durable early completion:
all node-qualified assertions must pass at or after the optional
stop_when_assertions_pass_min_steps floor and remain true for the optional
stop_when_assertions_pass_settle_steps window (default 100000). The default
is false; a same-round runtime failure or wall_time_ms, max_cycles, or
max_uart_bytes limit takes precedence over assertions_passed. max_steps
remains the outer execution bound, so an all-pass final world round reports
assertions_passed.
To run a simulation, provide both the firmware and the system manifest:
labwired --firmware firmware.elf --system configs/systems/bluepill.yamlThe simulator loads the system manifest, resolves the chip descriptor, initializes the memory map, and begins execution at the Reset Vector.