Tramuntana proto r1a

Tramuntana — hardware hacking tool for embedded systems

An open bench tool for analysing and debugging embedded systems, built on the RP2350 (Raspberry Pi Pico 2) and Zephyr OS. One USB cable, three serial ports, one 16-pin header:

• SPI master and sniffer — SPIDriver-style sel/write/read/unsel transactions up to 75 MHz; passive full-duplex (MOSI + MISO) bus tap.
• I2C master and sniffer — I2CDriver-style start/write/read/stop primitives, scan, register access, bus recovery; passive decoder.
• Oscilloscope — 2 × 12-bit channels, 500 kS/s, pre-trigger.
• Waveform generator — sine/tri/saw/square/stairs/DC/arbitrary, 1 Hz–100 kHz.
• Logic analyzer — 8 channels, 150 MS/s, edge triggers in hardware, pattern trigger with pre-trigger, VCD export for PulseView.
• USB-UART bridge — the target's console as /dev/ttyACM2, baud rate follows whatever you open it with; RTS/DTR can drive the target's reset and boot pins, so esptool and friends flash through it.
• Emulated I2C/SPI device — the board answers on the target's bus from a register file the host loads and reads back.
• Sequencer — host-built step lists (GPIO, waits, bus transfers, captures) run on the board with microsecond timing.
• Timeline — the target's UART, sniffed buses, DIO edges and emulator transfers timestamped on one clock (host library, CLI, AI tools).
• Switched, protected 3.3 V rail for the target, switchable I2C pull-ups, RGB status LED and a TFT dashboard.

The passive instruments (sniffers, logic analyzer) only listen, so they can watch a bus while the board's own master, the UART bridge or a target drives it.

Two boards share the design: tramuntana_r1a (RP2350 on the PCB) and tramuntana_lite_r1a (a Pico 2 soldered onto a two-layer carrier — the one handed out at workshops). Firmware and host software are common.

Documentation

The full documentation is in docs/: getting started, a usage guide for every instrument, and complete references for the Python library, the CLI, the shell, the binary protocol, the firmware internals, the webapp and the AI tools.

What's new

Firmware 1.3.0, host package 2.3.0

Fixes found using the Tramuntana as the test bench of an FPGA module library.

Firmware

• SPI emulator: written bytes go into the response table as they arrive, and the CS-rise interrupt rearms the shifters first. From CS rise to ready now takes under 2 µs; before, it took up to 160 µs after a write, and the next transaction was lost or garbled. A window that still starts too early is counted (late) and its event flagged suspect.
• I2C emulator: the START and STOP flags are read in one go. A STOP and the next START landing between two separate reads made the emulator NAK its own address after a write.
• I2C emulator: SDA is held ~330 ns after SCL falls (UM10204); it was 30–140 ns.
• I2C sniffer: SCL must still be high a moment later before an SDA change counts as a START/STOP, so a slave with a short SDA hold no longer produces spurious STARTs or STOPs.
• Emulator events: the queue grows from 16 to 64, dropped events are counted and the next one is flagged (gap), reads log what went out on the bus, and display refreshes are rate-limited.
• Protocol: EMU_STATUS gains dropped and late; EVT_EMU flags bit 4 = suspect, bit 5 = gap.
• Sequencer: PWM (0x16) and PWM_SYNC (0x17) ops.

Host

• MCP server: pwm_set / pwm_phase / pwm_sync / pwm_stop / pwm_status tools, pwm ops in sequence_run, spi_release and spi_transaction(release=), names as {dio: name}, and logic_capture waits up to 1 h (re-arming every 60 s).
• Library and CLI: Spi.release(), tramuntana spi release, Sequence.pwm() / pwm_sync().
• Decoders: sck_hz / scl_hz are the median clock, and the new bit_rate_hz gives the average including pauses.
• EmuTransfer.suspect / gap and Emu.status() dropped / late; the webapp shows them.

Docs: measured SPI emulator speed limits, SPI master timing, releasing pins after use, best-effort emulator events; the AI skill is updated.

Repository

fw/apps/tramuntana_fw/   Zephyr firmware                                -> its README
fw/boards/               devicetree for the board
fw/imgs/                 display images + font, with their generators
fw/build.sh              build / flash wrapper (local paths in fw/.env)
host/python/             Python package: library, `tramuntana` CLI, MCP server
                         and skill for AI agents                         -> its README
host/webapp/             browser front-end (Web Serial, no install)     -> its README
hw/tramuntana_lite_r1a/  KiCad project, hardware notes, 3D-printed case
hw/tramuntana_r1a/       KiCad project of the full board
docs/                    documentation                           -> its README

Quick start

1. Flash zephyr.uf2 from the latest GitHub release (hold BOOTSEL while plugging the Pico 2 in, copy the file to the RP2350 drive), or build it yourself — see below. Three ports appear: shell, API, UART bridge.
2. Talk to it:

picocom /dev/ttyACM0           # the shell: try 'help', 'i2c scan', 'scope 1024'
source host/python/env.sh      # `tramuntana` command for this shell (creates the venv once)
tramuntana info
tramuntana i2c scan
tramuntana scope -n 2048 --trigger rising --level 1.65 --plot
tramuntana logic -n 65536 --rate 25M --vcd capture.vcd
picocom -b 115200 /dev/ttyACM2 # the target's UART, through the bridge

or open host/webapp/index.html in Chrome/Edge and press Connect.

3. Or hand it to an AI agent. The package carries an MCP server and the tramuntana-debug skill; one command registers both:

python3 -m venv ~/.venvs/tramuntana
~/.venvs/tramuntana/bin/pip install "./host/python[mcp]"
~/.venvs/tramuntana/bin/tramuntana ai install claude     # or opencode, copilot, all
# --project PATH registers it for that project only; 'ai uninstall' undoes it

Then ask: "Power the target, scan the I2C bus and tell me what the devices are." See AI tools.

tramuntana command reference

source host/python/env.sh defines the command in the current shell (it runs host/python/.venv/bin/tramuntana, creating the venv the first time). It talks to the board's API port, found automatically by USB id.

Conventions: bytes and I2C addresses are hex (9f 00 ff, 9f00ff, 68); frequencies accept k/M suffixes (400k, 8M, 1e6); volts are decimal (1.65). Exit code 0 on success, 1 if no board is found, 2 if the board rejected the command (NAK, busy, bad argument…), 3 on a link error.

Global options

Board

dio masks accept 0x.., 0b.. or decimal (0x0f, 0b1010, 15).

SPI — DIO2 CS, DIO3 MISO, DIO4 MOSI, DIO5 SCK

tramuntana spi conf 8M 0
tramuntana spi txn 9f --read 3                  # JEDEC id of a SPI flash
tramuntana spi txn 03 00 00 00 --read 256       # first page of the flash
tramuntana spi sel && tramuntana spi write 06 && tramuntana spi unsel   # write enable, step by step

I2C — DIO6 SCL, DIO7 SDA

tramuntana i2c conf 400k
tramuntana i2c scan
tramuntana i2c read 68 75              # WHO_AM_I of an MPU-6050
tramuntana i2c write 68 6b 00          # wake it up
tramuntana i2c regs 50                 # dump an EEPROM's first 256 bytes

The low-level primitives (start, raw write/read, stop) are in the shell, the Python library and the webapp; the CLI covers complete transactions.

Oscilloscope — AIN0 (and AIN1)

tramuntana scope [options] captures, prints per-channel min / max / Vpp / mean / RMS / frequency, and optionally saves or plots.

tramuntana scope -n 4096 --trigger rising --level 1.65 --pre 1024 --plot
tramuntana scope --ch 2 --rate 100k --csv two_channels.csv

Waveform generator — AOUT0

Frequencies go from 1 Hz to 100 kHz; the command prints the frequency actually achieved. Arbitrary waveforms are loaded from the Python library (t.awg.arbitrary(...)) or the webapp.

PWM outputs — any DIO

Logic analyzer — DIO0..DIO7

tramuntana logic [options] captures, prints the number of transitions per channel, and optionally saves or plots.

tramuntana logic -n 131072 --rate 150M --trigger rising --pin 5 --vcd spi.vcd
tramuntana logic -n 100000 --rate 10M --trigger pattern --mask 0x80 --value 0 --pre 2000 --vcd i2c.vcd   # I2C START (SDA low)

UART bridge — DIO1 TX, DIO0 RX

The data itself goes through the third serial port, e.g. picocom -b 115200 /dev/ttyACM2 (the baud rate you open it with is the one used on the target, unless overridden with --baud).

Emulated device, timeline, DIO watch

The sequencer has no CLI front: build a Sequence in Python (API) or use the AI tools' sequence_run.

Building the firmware

A Zephyr workspace (per the getting started guide) and the Zephyr SDK, plus device-tree-compiler on the host. fw/ is not its own west workspace; build.sh builds an app against that install. Tell it where they are in fw/.env (defaults: ~/zephyrproject and ~/zephyr-sdk-1.0.1):

cd fw
cp .env.example .env             # then edit ZEPHYRPROJECT / ZEPHYR_SDK
./build.sh                       # builds tramuntana_fw
./build.sh flash                 # build + flash (reboots the board into the
                                 # UF2 bootloader over USB, no BOOTSEL needed)

Only the first flash — or recovering from a hung firmware — needs BOOTSEL held while plugging the board in.

Header

 1 3V3 (switched)   2 GND       3 AIN0     4 GND      5 AIN1    6 GND
 7 AOUT0            8 VREF      9 DIO0    10 DIO1    11 DIO2   12 DIO3
13 DIO4            14 DIO5     15 DIO6    16 DIO7

DIO0/1 = UART RX/TX    DIO2..5 = SPI CS / MISO / MOSI / SCK    DIO6/7 = I2C SCL/SDA
DIO0..7 = GPIO and logic analyzer channels 0..7   (`tramuntana pinout` draws it)

License

See LICENSE.