EoSim Developer Documentation v0.1.0

Multi-architecture embedded simulation platform. Supports native Python simulation, binary emulation, and hardware-in-the-loop (HIL) testing across ARM, RISC-V, Xtensa, and x86 targets. Python CLI (eosim) with optional Tkinter GUI.

💻 Architecture

EoSim CLI / GUI
  |
  +-- Platform Registry (52 platforms from YAML files)
  |       |              |              |
  |  Native Engine   Binary Engine  HIL Bridge
  |  (Python sim)    (ARM/RV/x86)   (OpenOCD/Serial)
  |  GPIO,UART,SPI   Full binary    Real hardware
  |  I2C,Timer,ADC   execution      via debug probe
  |
  +-- 3D Renderers (drone, robot, vehicle, aircraft, medical, satellite)
  +-- GUI Dashboard (GPIO panel, UART terminal, CPU state, memory view)

📄 eosim list

eosim list [options]

List all simulation platforms from the registry. Supports filtering and grouping. Output: table (default), JSON, or CSV.

Options

`--arch <name>`	`string`	Filter: arm, arm64, riscv64, xtensa, x86_64.
`--vendor <name>`	`string`	Filter: ST, NXP, Nordic, Espressif, Renesas, TI, Microchip, NVIDIA.
`--class <name>`	`string`	Filter: mcu, sbc, soc, edge-server.
`--engine <name>`	`string`	Filter: native, qemu, hil.
`--domain <name>`	`string`	Filter: automotive, industrial, medical, iot, robotics, aerospace.
`--group-by <f>`	`string`	Group by: arch, vendor, class, engine, domain.
`--format <fmt>`	`string`	Output: table, json, csv.

Example

$ eosim list --arch arm --class mcu

Available platforms (8):
  NAME                ARCH    ENGINE   VENDOR     CLASS  DESCRIPTION
  -------------------------------------------------------------------
  stm32f4             arm     native   ST         mcu    STM32F407 Cortex-M4F
  stm32h7             arm     native   ST         mcu    STM32H743 Cortex-M7
  nrf52               arm     native   Nordic     mcu    nRF52840 Cortex-M4F
  nrf5340             arm     native   Nordic     mcu    nRF5340 Cortex-M33
  k64f                arm     native   NXP        mcu    Kinetis K64 Cortex-M4F
  samc21              arm     native   Microchip  mcu    SAMC21 Cortex-M0+
  psoc6               arm     native   Infineon   mcu    PSoC 6 Cortex-M4F
  s32k344             arm     qemu     NXP        mcu    S32K344 Cortex-M7

🔍 eosim search

eosim search <query>

Fuzzy search platforms by name, vendor, SoC, or architecture.

Parameters

query string Search term.

Example

$ eosim search nordic
Search results for 'nordic' (3 matches):
  nrf52     arm   native  Nordic  nRF52840
  nrf5340   arm   native  Nordic  nRF5340
  nrf9160   arm   qemu    Nordic  nRF9160

▶ eosim run

eosim run <platform> [options]

Start simulation for a platform. Loads YAML config, initializes engine (native/binary emulation), optionally loads firmware.

Options

`--firmware <path>`	`string`	ELF or BIN firmware to load.
`--engine <type>`	`string`	Override: native, qemu.
`--gdb-port <N>`	`int`	GDB server port (default: 3333).
`--uart-port <N>`	`int`	UART TCP bridge port (default: 4444).
`--gui`	`flag`	Open GUI dashboard.
`--headless`	`flag`	No GUI or terminal.
`--timeout <sec>`	`int`	Auto-stop after N seconds.

Example

$ eosim run stm32f4 --firmware build/my-robot.elf --gui

[eosim] Platform: stm32f4 (STM32F407VG)
[eosim] Engine: native (Python peripheral simulation)
[eosim] Peripherals: GPIO(144), UART(6), SPI(6), I2C(3), TIM(14), ADC(3)
[eosim] GDB server: localhost:3333
[eosim] UART bridge: localhost:4444
[eosim] GUI dashboard opened
[eosim] Simulation running... (Ctrl+C to stop)

📊 eosim stats

eosim stats

Show platform registry statistics: total count, breakdown by architecture, vendor, engine, class, and domain.

Example

$ eosim stats
Platform Registry Statistics:
  Total platforms: 52
  By Architecture:  arm: 22, arm64: 10, riscv64: 3, riscv32: 2, xtensa: 3, x86_64: 2, mipsel: 2, powerpc: 1, microblaze: 1, arc: 1, tricore: 1, rh850: 1
  By Engine:        native: 32, qemu: 16, hil: 4
  By Class:         mcu: 20, sbc: 10, soc: 5, devboard: 5, virtual: 4, automotive: 3, safety: 3, fpga: 1, industrial: 1
  By Vendor:        ST: 5, Broadcom: 5, Nordic: 3, NXP: 3, Espressif: 3, TI: 3, ARM: 3, NVIDIA: 2, ...

🎨 eosim gui

eosim gui [platform]

Open the EoSim GUI dashboard (Tkinter). Includes: GPIO pin visualizer, UART terminal, CPU state panel, memory viewer, peripheral register inspector, and optional 3D product renderers (drone, robot, vehicle, aircraft, medical, satellite).

Options

platform string Optional platform to auto-start simulation.

Example

$ eosim gui stm32f4
# Opens Tkinter window with:
# - GPIO panel: 144 pins, click to toggle, color by state
# - UART terminal: real-time serial output
# - CPU panel: registers, PC, SP, flags, clock
# - Memory view: hex dump of RAM/Flash regions
# - Peripheral registers: TIM, ADC, SPI, I2C config

📜 Platform YAML Format

# platforms/stm32f4/platform.yml
name: stm32f4
display_name: "STM32F407VG Discovery"
arch: arm
vendor: ST
soc: STM32F407VG
platform_class: mcu
engine: native
domain: iot

cpu:
  core: cortex-m4f
  fpu: true
  mpu: true
  clock_hz: 168000000
  icache: false
  dcache: false

memory:
  flash_kb: 1024
  ram_kb: 192
  ccm_kb: 64       # Core-coupled memory

peripherals:
  gpio: { ports: [A,B,C,D,E,F,G,H,I], pins_per_port: 16 }
  uart: { count: 6, max_baud: 10500000 }
  spi:  { count: 6, max_clock_hz: 42000000 }
  i2c:  { count: 3, max_clock_hz: 400000 }
  timer: { count: 14, bits: [16, 32] }
  adc:  { count: 3, channels: 16, resolution: 12 }
  dac:  { count: 2, channels: 2, resolution: 12 }
  dma:  { count: 2, streams: 16 }
  usb:  { otg_fs: true, otg_hs: true }
  can:  { count: 2 }
  sdio: { count: 1 }
  ethernet: { count: 1 }

debug:
  interface: SWD
  gdb_port: 3333
  uart_bridge_port: 4444

qemu:
  machine: netduinoplus2
  cpu: cortex-m4

⚙ Simulation Engines

Engine	Type	Speed	Fidelity	Use Case
`native`	Python simulation	Fast	Medium	Rapid prototyping, CI testing, peripheral logic verification. Simulates GPIO, UART, SPI, I2C, Timer, ADC registers in Python.
`qemu`	Binary emulation	Medium	High	Full firmware execution on emulated CPU. Uses EoSim binary emulation with GDB and QMP interfaces. Supports ARM, RISC-V, Xtensa, x86.
`hil`	Hardware-in-loop	Real-time	Exact	Real hardware via debug probe (OpenOCD/J-Link). Bridges serial and GDB. Highest fidelity for production validation.

🔌 Native Engine Peripheral Registers

The native engine simulates peripheral register maps in Python. Each peripheral provides read/write access to memory-mapped registers.

GPIO Register Map (per port)

Offset	Register	Description
`0x00`	MODER	Mode register: 2 bits per pin (00=input, 01=output, 10=AF, 11=analog).
`0x04`	OTYPER	Output type: 0=push-pull, 1=open-drain.
`0x08`	OSPEEDR	Speed: 00=low, 01=med, 10=high, 11=vhigh.
`0x0C`	PUPDR	Pull-up/down: 00=none, 01=up, 10=down.
`0x10`	IDR	Input data (read-only, 16 bits).
`0x14`	ODR	Output data (read/write, 16 bits).
`0x18`	BSRR	Bit set/reset (write-only, atomic).
`0x1C`	LCKR	Lock register.
`0x20`	AFRL	Alternate function low (pins 0-7).
`0x24`	AFRH	Alternate function high (pins 8-15).

UART Register Map

Offset	Register	Description
`0x00`	SR	Status: TXE, RXNE, TC, IDLE, ORE, NE, FE, PE flags.
`0x04`	DR	Data register (read=RX, write=TX).
`0x08`	BRR	Baud rate register (mantissa + fraction).
`0x0C`	CR1	Control: UE, TE, RE, RXNEIE, TCIE, TXEIE, M, OVER8.
`0x10`	CR2	Control: STOP bits, CLKEN, LINEN.
`0x14`	CR3	Control: DMAT, DMAR, CTSE, RTSE.

Timer Register Map

Offset	Register	Description
`0x00`	CR1	Control: CEN, UDIS, URS, OPM, DIR, ARPE.
`0x0C`	DIER	DMA/interrupt enable: UIE, CC1IE, CC2IE, TIE.
`0x10`	SR	Status: UIF, CC1IF, CC2IF, TIF.
`0x24`	CNT	Counter value.
`0x28`	PSC	Prescaler.
`0x2C`	ARR	Auto-reload value.
`0x34`	CCR1	Capture/compare channel 1.

EoSim requires Python 3.10+. Binary emulation engine requires qemu-system binaries installed. HIL engine requires OpenOCD and a compatible debug probe. Install: pip install eosim.