Core concepts
The handful of terms used everywhere else in these docs.
Twins
A twin is a model of one part: a microcontroller, a sensor, a memory, a display controller. It exposes the registers, memory map, pins, interrupts and bus behavior the vendor documents, so the firmware that drives the real part drives the twin with no changes.
Twins are generated from vendor documents: datasheets, reference manuals, CMSIS-SVD files, CMSIS packs, errata and vendor headers. Whatever the documents do not describe is left out and reported, never filled in with guesses. The catalog holds the twins already generated; ct twin generate reuses a catalog entry when the part is already there.
What a twin models
- Registers, memory, pins and interrupts, as the firmware reads and writes them
- Peripherals, DMA, timers and buses at the level the firmware observes: bytes, frames and flags
- Sensor and IC twins that answer on the bus the way their datasheet says
What it does not claim
- Cycle accuracy. Time is functional by default; the opt-in
--timing cycle-approximatelayer is provisional, measured on some configurations only, and never cycle-accurate - RF, analog line levels, noise, power and ESD
- Thermal and mechanical behavior of the board itself
Put together: a twin behaves the same as the hardware for everything the firmware can observe, where the part is modeled. Where it is not, the run says so.
Evidence labels
Every capability, and so every result, carries one of three labels. The app, the CLI and the reports never blur them:
| Label | Meaning |
|---|---|
verified | Checked against an independent, reproducible reference: the silicon, or a second implementation of the same instruction set or peripheral. |
provisional | Modeled from the vendor documents and exercised by runs, but not yet independently checked. |
unsupported | Not modeled. A peripheral without a model is a plain register file and is reported; a run that depended on one ends inconclusive (exit code 4), not pass. |
A run that compiled, loaded or looked plausible is never called verified for that reason alone. Verified today: Arm Cortex-M (v6-M to v8-M mainline), Arm Cortex-R5 and R52 (user level), the Xtensa base instruction set, and AVR on the ATmega328P and ATmega2560. Provisional today: Cortex-M23, RISC-V RV32, MSP430, TI C2000, MIPS32, Renesas RX, RL78 and RH850, Infineon TriCore, Power e200, PIC18/16 and 8051.
Projects, systems and worlds
The app uses a few nouns everywhere:
| Word | Meaning |
|---|---|
| Project | Holds your systems, one world, your firmware and your runs. |
| System | Parts wired together: microcontrollers, sensors, memories, transceivers. It can hold other systems. A system with one microcontroller is what you would call a board. |
| Board | A development board such as nucleo-f767zi, stm32f4-discovery or nucleo-f103rb. In the Proving Ground, a board is a circuit board with firmware mounted on a part. |
| Link | A wire, bus or link between the parts of a system: UART, SPI, I2C, CAN, RS-485. |
| World | A project’s 3D space: parts placed in a room, your systems on them, and the room’s temperature, light and gravity. See Proving Ground. |
| Part | A thing in the world: a box, cylinder, sphere or an imported 3D model. |
| Class | What a part is, such as a battery, power supply, regulator, switch, fuse or load, with its properties. |
To start from a PCB design, use Import a PCB in a project, or ct board import.
Runs
A run executes your firmware on a system until a stop target (a console line, a symbol or an address), a virtual time budget, or a fault. Its result holds the console output, the checks, the issues the twins found, and a verdict: pass, fail, inconclusive or error.
Determinism
Runs use virtual time. The same firmware, board, twins and inputs give the same report every time, on your machine, on the hosted service and in CI. Memory the vendor documents as undefined at power-up reads as zero unless you ask for a seeded fill (--uninitialized-memory seeded:<seed>), which is reproducible too.
Scenarios
A scenario (ct.scenario/1) scripts the inputs around a board: motion, temperature, light, magnetic fields and fluids for the sensor twins, and analog circuits whose node voltages an analog circuit solver feeds to the MCU’s converters. List the bundled ones with ct scenario list.
Scenes
A scene (ct.scene/1) runs several microcontrollers, each with its own firmware, in lock-step virtual time, joined by UART, SPI and I2C links, CAN and CAN FD buses, RS-485 buses and Ethernet. A system compiles to a scene. See Systems and scenes.
Test suites
A suite (ct.test-suite/1) is a matrix of firmware, boards, twin configurations, scenarios and assertions. ct test run runs it locally and ct cloud suite run on the hosted service; both write JUnit and JSON reports. ct test run can also compare against a baseline. See Test in CI.
Generation credits
Building a new twin from documents uses one generation credit: uploading a datasheet, importing a microcontroller, or a twin a PCB import needs. A part already in the catalog is reused for free. Credits reset every Monday at 00:00 UTC: 5 a week on Free, 50 on Plus, 250 on Pro and 2,000 shared on Team. Simulation is unlimited on every plan: runs, scenes, suites, debug sessions and Proving Ground sessions never use credits. See Pricing.