C64 Meatloaf Debug

C64 / Meatloaf Unattended Debug Cycle

This skill guides the full iterative loop for debugging C64 BASIC programs that use Meatloaf's Full-Mode HTTP Client:

┌──────────────────┐    IEC serial   ┌──────────────┐   HTTP   ┌─────────────┐
│  Ultimate 64     │ ◄──────────────►│  Meatloaf    │◄────────►│  API /      │
│  (BASIC program) │                 │  (ESP32)     │          │  Test Svr   │
└──────────────────┘                 └──────┬───────┘          └─────────────┘
                                            │ USB serial (monitor_speed)
                                            ▼
                                     ┌──────────────┐
                                     │  Serial      │
                                     │  capture     │
                                     │  (this PC)   │
                                     └──────────────┘

Two codebases are debugged in the same loop:

• BASIC — runs on the C64, talks to Meatloaf via IEC bus
• Meatloaf C++ — the ESP32 firmware in this repo (the directory holding platformio.ini; MEATLOAF_DIR overrides it)

Which one to fix? Claude decides based on evidence from the screen and serial log. The skill provides tools to gather evidence and deploy fixes to either side.

Architecture

Ultimate 64 REST API

The Ultimate 64 exposes a REST API on port 80. Key endpoints:

Memory locations used:

• $0277 — Keyboard buffer (10-byte FIFO). Key codes go here.
• $00C6 — Keyboard buffer count. Set after writing to $0277.
• $0400 — Screen memory. 40×25 = 1000 bytes. READ that.
• $0801 — BASIC program start. POST tokenized BASIC here. C PRGs use this address too by default (cc65 EXEHDR at $0801).
• $002D-002E — Variable pointer. BASIC-only — set to end of BASIC program after injection. Do NOT touch for C PRGs (clobbers the zero-page globals cc65 set up).
• $D7FF — U64 debug register. Single free byte in the cartridge expansion area. Useful as a runtime checkpoint signal from C code (see "cc65 Debug Options" below).
• $DD00-$DD03 — CIA#2. $DD00 is the IEC serial bus (ATN/CLK/DATA), $DD01/$DD03 the user port data and direction used by parallel speeders (DolphinDOS, SpeedDOS), $DD02 the Port A direction. Decoded by the bus command — see "F. IEC bus and user port signals".
• $DC0D — CIA#1 interrupt control/status. Bit 4 is the /FLAG pin, where the IEC SRQ line arrives (shared with the datasette input). Reading it is destructive on a 6526 — it clears latched interrupt flags.

Full register reference: https://csdb.idolpx.com/tools/mem64

Meatloaf Source Structure

Build Configuration

All build settings are read from the project's platformio.ini — never hardcode them, and never assume the values below. The board, serial port and baud rate change per machine and per user; platformio.ini is where the project documents them, so it is the single source of truth.

Ask for the resolved settings before doing anything that touches the device:

python3 scripts/meatloaf_debug.py config

{
  "project_root": "/Users/you/src/meatloaf",
  "ini_path": "/Users/you/src/meatloaf/platformio.ini",
  "environment": "fujiloaf-rev0",
  "board": "esp32-wrover-16m",
  "mcu": "esp32",
  "flash_size": "16m",
  "u64_ip_address": "192.168.1.176",
  "upload_port": "/dev/cu.usbserial-14520",
  "serial_port": "/dev/cu.usbserial-14520",
  "monitor_speed": "2000000",
  "verbose_flags": [],
  "defines": ["BUILD_IEC", "ENABLE_CONSOLE", "SD_CARD", "..."],
  "overrides": {}
}

scripts/pio_config.py does the parsing (${section.key} interpolation and ; comments included) and is imported by both meatloaf_debug.py and serial_capture.py. The project root is found by walking up from the script, so the skill works from any working directory.

Checking verbose_flags matters. If the serial log is missing the HTTP diagnostics this skill's tables refer to, VERBOSE_HTTP is probably not enabled — it ships commented out. Uncomment it in platformio.ini under [env] build_flags and reflash, rather than concluding the code path was never reached.

To target a different board or port for one run without editing platformio.ini, set the MEATLOAF_* env vars (see "Environment Variables").

Skill Components

commodore64debugging/
├── SKILL.md                            ← This file: workflow + reference
├── scripts/
│   ├── meatloaf_debug.py               ← Python automation + CLI
│   ├── pio_config.py                   ← Reads build settings from platformio.ini
│   └── serial_capture.py               ← Robust serial capture daemon
└── evals/
    └── evals.json                      ← Test cases

### BASIC Compilation

**Only bc64 is supported** for BASIC compilation. The built-in BASIC V2
tokenizer has been removed — all `.bas` files go through the `bc64` CLI:

```bash
bc64 -a -o /tmp/output.prg source.bas

The 2-byte PRG load address header (01 08) is stripped automatically by inject_basic(), which POSTs the raw tokenized body directly to $0801.

bc64 features used across all test programs:

• @alias variables for unlimited-length names (via -a flag)
• Labels for control flow (Start:, ShowMenu:, HttpFetch)
• Auto-numbering (no manual line numbers needed)
• Case-insensitive keywords

C Compilation (cc65)

C programs use the cc65 toolchain (cl65, ca65, ld65). Deploying a .prg requires: reset → upload body-only to $0801 → type RUN. The full protocol is in the "C-PRG / cc65 Programs" section below.

Recommended build flags:

cl65 -t c64 -O -I. --mapfile foo.map -o foo.prg foo.c
# Debug build: add --listing foo.lst and -g (skip -O)

The --mapfile is essential — see "cc65 Debug Options" below.

Python Modules

scripts/meatloaf_debug.py — The main automation module. Use it for every operation. Run commands via CLI or import as a Python module.

scripts/serial_capture.py — A self-contained daemon for reading Meatloaf's UART debug output. Does not require meatloaf_debug.py to run — it's a standalone script.

Python dependencies

Both scripts need requests (U64 REST API) and pyserial (capture daemon).

A modern system Python is usually PEP 668 "externally managed", so pip install --user requests pyserial fails outright. Use a venv and call its interpreter explicitly rather than python3:

python3 -m venv /tmp/c64dbg && /tmp/c64dbg/bin/pip install requests pyserial
/tmp/c64dbg/bin/python scripts/meatloaf_debug.py config

Symptom if you skip this: Error: 'requests' library required. pip install requests from meatloaf_debug.py, or ModuleNotFoundError: No module named 'serial' from the capture daemon.

Robust Serial Capture

The serial capture is the most important diagnostic tool. It reads the ESP32's Debug_printv() output over USB UART, on the port and baud rate resolved from platformio.ini (monitor_port / monitor_speed — run meatloaf_debug.py config to see them).

Why It's Robust

What survives

• ESP32 crash/reboot — the capture detects the port error, enters backoff mode, and reconnects automatically when the port reappears.
• USB cable disconnect — reconnects with backoff when cable goes back in.

What does not survive:

• Flashing firmware — stop the capture first. esptool needs the port to itself on every platform, not just Windows (see "When to stop it").

When to start it

Start capture before running any tests:

python3 scripts/meatloaf_debug.py capture start

After flashing firmware, wait for the ESP32 to boot and start logging:

python3 scripts/meatloaf_debug.py capture wait --timeout 20

This polls until new data appears in the serial log (up to 20s timeout).

When to stop it

Stop the capture when the debug session ends — it holds the serial port open, and on Windows that port is exclusive, so nothing else can attach until it lets go:

python3 scripts/meatloaf_debug.py capture stop

Leaving it running blocks the two things a person reaches for next: their own serial monitor (pio device monitor, PuTTY, the IDE terminal), and the next flash.

Flashing fails while the capture holds the port — on every platform. The error differs but the cause is the same:

The macOS/Linux message is misleading — it reads like a cable or driver fault, and esptool's own note points you at the hardware. It is neither. The port is shared there, so the capture keeps reading bytes out from under esptool's Connecting.... handshake and the sync never completes. Verified on macOS 2026-08-19: build --flash failed this way with the capture running, and the identical pio run -t upload succeeded seconds later once it was stopped.

So the flash sequence is always: stop capture, flash, start capture. And the last thing any session does is stop it.

Health check

# Quick check (exit code 0 = running)
python3 scripts/meatloaf_debug.py capture status
# Or independently:
python3 scripts/serial_capture.py --check /tmp/serial_capture.pid

Reading the log

# Last 50 lines
python3 scripts/meatloaf_debug.py capture tail

# Grep for specific patterns
python3 scripts/meatloaf_debug.py capture grep --pattern "perform OK"

# Read raw log
cat /tmp/meatloaf_serial.log

Keystroke Injection (Keyboard Buffer)

Sending keys to the C64 uses the keyboard buffer at $0277, a 10-byte hardware FIFO. This is the only way to inject keystrokes on the U64.

Why not CIA registers? The U64 API docs explicitly state "Writing to the I/O registers of the 6510 is not possible", which blocks direct CIA #1 ($DC00/$DC01) keyboard matrix manipulation. The keyboard buffer at $0277 is the sole injection path.

How it works

1. Flush stale keys from the buffer by zeroing $00C6 first
2. Write ≤8 PETSCII key codes to $0277 (leaving margin in the 10-byte FIFO)
3. Set the count at $00C6 — this triggers the KERNAL IRQ to read the buffer
4. Poll $00C6 until it returns to 0 (C64 has consumed the keystrokes)
5. Write the next chunk
6. If drain times out: flush stale keys, retry in 1-byte chunks

Robustness features

Known limitations

• Blocking I/O blocks the IRQ — if the C64 is stuck in KERNAL IEC transfer (LOAD/SAVE/OPEN), the keyboard IRQ won't fire and the buffer won't drain. press_stop() sends STOP repeatedly because the KERNAL checks for RUN/STOP at specific I/O polling points.
• No feedback — there's no way to confirm a specific key was processed beyond polling $00C6 (you can't tell which key was consumed).
• 10-byte FIFO is small — long text strings require multiple chunks with drain waits between.
• NMI/RESTORE not accessible — the RESTORE key (CPU /NMI pin) could theoretically unstick even KERNAL-blocked I/O, but the U64 API has no mechanism to trigger it (no CIA or NMI endpoints).

C-PRG / cc65 Programs

A .prg file (cc65, KickAss, raw binary with a 2-byte LE header) is uploaded very differently from a BASIC program. The existing inject_basic() is BASIC-only — it always writes to $0801 and pokes the BASIC variable pointer at $002D. Both assumptions are wrong for C.

Why BASIC and C differ

The cc65 PRG layout (default cl65 -t c64)

$0801  EXEHDR (8 bytes: jump to STARTUP at $080D)
$080D  STARTUP (zero page init, runtime init, call main)
$0840  CODE (cc65 runtime + your functions)
       ...
       RODATA (string literals, lookup tables, sin/cos)
       DATA (initialised globals)
       INIT (run once, then freed for BSS)
$5415  BSS (zeroed globals; ONCE constructors run, then this region)
$5A00  <-- your memory is free above here for sprites, bitmap, etc.

cc65's --start-addr (or -S) default for -t c64 is $0801, so the PRG header shows 01 08 (little-endian). That's why the first bytes of c64u_radar.prg are 01 08 0B 08 ... — load at $0801, EXEHDR contains 0B 08 = $080B = jump to STARTUP at $080D (the +2 accounts for the JSR instruction's own size).

Injecting a cc65 C PRG

The inject-prg command does not exist in this version of meatloaf_debug.py. Use the raw POST to writemem instead.

The correct deploy sequence — always:

# 1. Reset the U64 (clears RAM)
python3 scripts/meatloaf_debug.py reset
sleep 4                      # wait for boot + READY prompt

# 2. Upload PRG body (strip the 2-byte load-address header)
U64_IP="${U64_IP_ADDRESS:-192.168.1.176}"
python3 -c "
import requests
with open('/path/to/your.prg', 'rb') as f:
    body = f.read()[2:]                    # strip LE load-address header
r = requests.post(f'http://${U64_IP}/v1/machine:writemem?address=0x0801',
                  data=body, timeout=10)
print(f'Upload {len(body)} B -> {r.status_code}')
"

# 3. RUN (type keystrokes via keyboard buffer)
python3 scripts/meatloaf_debug.py type "RUN"
sleep 3
python3 scripts/meatloaf_debug.py screen   # verify output

Why reset first? The POST writemem appends to existing RAM content, it doesn't clear it. Stale BASIC program bytes from earlier runs corrupt the linker's EXEHDR. A hardware reset gives a clean $0801-$7FFF space.

Why strip the header? The .prg file starts with a 2-byte little-endian load address (01 08 = $0801). The POST writemem writes bytes directly into RAM starting at the given address — if you POST the header bytes too, they end up as program data at $0801-$0802, corrupting the BASIC stub.

How the upload works

1. Read the .prg file in binary mode.
2. Skip the first 2 bytes (LE load address).
3. POST the remaining bytes to writemem?address=0x0801.
4. The PRG's EXEHDR (BASIC SYS stub) at $0801-$080C handles RUN → SYS2061.
5. cc65's STARTUP runs at $080D, calls main().

Do NOT touch the BASIC variable pointer at $002D. C programs use the zero page for their own globals; clobbering it corrupts state.

Auxiliary data uploads (sprites, tables, char sets)

Many C programs reference pre-built data at known addresses (sprite patterns at $5A00, lookup tables generated by Python at $7000, etc.). The PRG doesn't include them; you upload them separately:

# Upload sprite patterns to the standard sprite area
python3 scripts/meatloaf_debug.py write-mem 5A00 sprites.bin

# Upload a sin/cos table generated by a Python tool
python3 scripts/meatloaf_debug.py write-mem 7000 sincos.bin

# Read back what you wrote (to verify)
python3 scripts/meatloaf_debug.py read-mem 5A00 512 > /tmp/sprites_readback.bin
diff <(xxd -p sprites.bin) <(xxd -p /tmp/sprites_readback.bin)

write-mem and read-mem are arbitrary-address, arbitrary-length wrappers around the same writemem/readmem REST endpoints used by the BASIC path.

Common pitfalls

cc65 Debug Options

The cc65 toolchain ships with several outputs that are pure gold for debugging — far more useful than just the .prg.

The map file in practice

$ grep -E "(__MAIN|__BSS|__STACK|HIMEM|EXEHDR|STARTUP)" foo.map
Exehdr                000801  00080C  00000C
Startup               00080D  00083F  000033
__MAIN_START__        00080D RLA    __MAIN_SIZE__     00C7F3 REA
__BSS_RUN__           005415 RLA    __BSS_SIZE__      000031 REA
__STACKSIZE__         000800 REA    __HIMEM__         00D000 REA

The columns: Name, Start, End, Size, Align. The suffixes mean:

• RLA = relocatable address (resolved at link time) — absolute C64 address after linking
• REA = relocatable expression (might be a constant, not an addr)
• RLZ = relocatable address in zero page
• LL = linker-generated local

Debugging without VICE: the U64 debug register

The U64 exposes a machine:debugreg endpoint that reads/writes a single byte at $D7FF. This is the cartridge expansion ROM/RAM area; cc65 doesn't use it, so it's a free scratch byte for runtime assertion logging:

// In your C code:
#define DBG_REG (*(volatile unsigned char *)0xD7FF)

// At a checkpoint:
DBG_REG = 0x42;   // marks "I reached the JSON parser"

// On error:
DBG_REG = 0xEE;   // marks "fatal: out of memory"

Read it from the host:

python3 scripts/meatloaf_debug.py read-mem D7FF 1
# → 42 if the program reached your checkpoint

Combine with the U64 REST debugreg endpoint for an even faster poll without going through readmem:

curl http://192.168.1.176/v1/machine:debugreg

Building for debug vs release

For the c64u-radar build (/home/qus/dev/_c64/c64u-radar/c64u_radar/Makefile):

# Debug:
cl65 -t c64 -g --mapfile foo.map --listing foo.lst -o foo.prg foo.c

# Release:
cl65 -t c64 -Oir -Os --mapfile foo.map -o foo.prg foo.c

Quick Reference: All Commands

C64 Control

# Read screen (40×25 PETSCII screen codes decoded to ASCII)
python3 scripts/meatloaf_debug.py screen

# Inject BASIC from file (- = stdin)
python3 scripts/meatloaf_debug.py inject test/http/my_test.bas

# Type a BASIC command and read screen
python3 scripts/meatloaf_debug.py run "RUN"
python3 scripts/meatloaf_debug.py run "LIST 100-200"
python3 scripts/meatloaf_debug.py run "PRINT PEEK(53280)" --wait 1

# Type text (no screen read, for interactive programs)
python3 scripts/meatloaf_debug.py type "hello"

# Decode IEC serial bus + user port ($DD00-$DD03)
python3 scripts/meatloaf_debug.py bus
python3 scripts/meatloaf_debug.py bus --samples 60 --interval 0.1  # is it moving?
python3 scripts/meatloaf_debug.py bus --srq      # also $DC0D.4 — DESTRUCTIVE

# STOP (interrupt running BASIC)
python3 scripts/meatloaf_debug.py stop

# Hardware reset
python3 scripts/meatloaf_debug.py reset

# Inject a compiled .prg (cc65, KickAss) — full cycle:
python3 scripts/meatloaf_debug.py reset
sleep 4
python3 -c "import requests
with open('path/to/foo.prg','rb') as f: body=f.read()[2:]
requests.post('http://192.168.1.176/v1/machine:writemem?address=0x0801', data=body, timeout=10)"
python3 scripts/meatloaf_debug.py type "RUN"
sleep 3
python3 scripts/meatloaf_debug.py screen

# Upload auxiliary data (sprite patterns, lookup tables, char sets)
python3 scripts/meatloaf_debug.py write-mem 5A00 sprites.bin
python3 scripts/meatloaf_debug.py write-mem 7000 sincos.bin

# Read back to verify
python3 scripts/meatloaf_debug.py read-mem 5A00 512
python3 scripts/meatloaf_debug.py read-mem 0801 19514 --raw > /tmp/prg_readback.bin

# Inject + RUN in one step
python3 scripts/meatloaf_debug.py test my_test.bas
python3 scripts/meatloaf_debug.py test --wait 5 < my_test.bas

Serial Capture

# Start (auto-kills stale, auto-reconnects on port drops)
python3 scripts/meatloaf_debug.py capture start

# Stop
python3 scripts/meatloaf_debug.py capture stop

# Status + log size
python3 scripts/meatloaf_debug.py capture status

# Tail last N lines
python3 scripts/meatloaf_debug.py capture tail --lines 50

# Grep for diagnostics
python3 scripts/meatloaf_debug.py capture grep --pattern "Request URL"
python3 scripts/meatloaf_debug.py capture grep --pattern "perform OK"
python3 scripts/meatloaf_debug.py capture grep --pattern "sendRequest"

# Wait for data to appear (after flash)
python3 scripts/meatloaf_debug.py capture wait --timeout 20

Meatloaf Console (via serial FIFO)

The serial capture daemon holds the serial port open and provides a command FIFO at /tmp/serial_capture_cmd. Write a Meatloaf console command to the FIFO, and the daemon relays it over serial and captures the response in the log.

# Send a command and read the response
python3 scripts/meatloaf_debug.py send "sysinfo"
python3 scripts/meatloaf_debug.py send "ifconfig" --wait 1.5
python3 scripts/meatloaf_debug.py send "meminfo"

Useful Meatloaf console commands:

Using wget for isolated HTTP tests: This is a powerful debugging technique. Instead of running the full C64→Meatloaf cycle, test HTTP directly from the Meatloaf console:

# Download a URL to Meatloaf's temp filesystem
python3 scripts/meatloaf_debug.py send "wget -o /tmp/test.txt http://192.168.1.131:8080/echo" --wait 3

# Read the downloaded content
python3 scripts/meatloaf_debug.py send "cat /tmp/test.txt" --wait 2

Diagnostic logic: If wget works but C64 BASIC fails → the issue is in the BASIC code or IEC data path. If wget also fails → the issue is in Meatloaf's HTTP client or network layer.

Build & Flash

# Show build settings resolved from platformio.ini (no hardware needed)
python3 scripts/meatloaf_debug.py config

# Build only
python3 scripts/meatloaf_debug.py build

# Build + flash — STOP THE CAPTURE FIRST or the upload fails (see above).
# A full rebuild after a framework/build-flag change takes several minutes;
# a source-only change is much quicker.
python3 scripts/meatloaf_debug.py capture stop
python3 scripts/meatloaf_debug.py build --flash
python3 scripts/meatloaf_debug.py capture start

Echo Test Server

# Start on port 8080
python3 scripts/meatloaf_debug.py echo start

# Stop
python3 scripts/meatloaf_debug.py echo stop

Full Unattended Cycle

# One cycle: ensure capture → inject → RUN → read screen
python3 scripts/meatloaf_debug.py cycle --basic my_test.bas

# With firmware flash first
python3 scripts/meatloaf_debug.py cycle --basic my_test.bas --firmware

Diagnostics

python3 scripts/meatloaf_debug.py diag

Example output:

{
  "u64": "reachable",
  "screen_preview": "READY. | ... |",
  "u64_info": {
    "product": "Ultimate 64",
    "firmware": "3.12",
    "hostname": "ultimate-123456"
  },
  "serial_capture": {
    "running": true,
    "log_path": "/tmp/meatloaf_serial.log",
    "log_size": 18347
  },
  "echo_server": {
    "pid_file": false
  }
}

The Unattended Debug Cycle (Full Protocol)

Phase 1: Setup

Run once at the start of a session:

0. config — confirm the environment, port and baud resolved from platformio.ini match the hardware actually plugged in
1. diag — check U64 is reachable, serial capture status (its output includes config under build_config)
2. capture start — ensure serial capture is running
3. Start echo server if you'll do body verification: echo start
4. reset or stop + clear — ensure the C64 is at READY

Phase 2: Identify what changed

Phase 3: Run and observe

For self-contained BASIC test programs:

screen = cycle.inject_and_run(basic_code, wait=wait_time)

For cc65 C programs (the correct deploy sequence):

# 1. Reset (clears RAM, ensures clean memory)
python3 scripts/meatloaf_debug.py reset
sleep 4

# 2. Upload PRG body (strip the 2-byte LE load-address header)
U64_IP="${U64_IP_ADDRESS:-192.168.1.176}"
python3 -c "
import requests
with open('/path/to/foo.prg', 'rb') as f:
    body = f.read()[2:]
r = requests.post(f'http://${U64_IP}/v1/machine:writemem?address=0x0801',
                  data=body, timeout=10)
print(f'Upload {len(body)} B -> {r.status_code}')
"

# 3. Launch via RUN (the BASIC EXEHDR stub at $0801 handles SYS2061)
python3 scripts/meatloaf_debug.py type "RUN"
sleep 3
python3 scripts/meatloaf_debug.py screen

For interactive programs (menus, chat clients):

cycle.u64.type_text("What is the weather?")
time.sleep(5)  # Wait for HTTP round-trip
screen = cycle.u64.read_screen()