Atari ST track
Step 8 ยท Atari ST

Build your idea with Claude Code.

An assistant that knows nothing about this hardware will write code that compiles, looks right, and fails on the board for reasons you cannot diagnose. An assistant that has been told the constraints is fast here. This page is about the difference.

What an assistant is good and bad at here

Be deliberate about this, because the failure mode is expensive: confident, plausible code that violates a limit nothing in the source file mentions.

Good at Bad at
Explaining an unfamiliar codebase back to you Anything cycle-sensitive: PIO, bus timing, the emulation path
Ordinary C in the rp/ half: parsing, state machines, file handling 68000 assembly, unless you check it closely
Filling in the shape of a command handler you have described Guessing sizes and budgets it was never told about
Reading a build error and telling you which line matters Knowing that the Atari side cannot use normal RAM

The pattern that works: you decide where code goes and what it may not do, the assistant writes it. The decisions on this page are the ones you keep.

The context block

The things this project knows that a general-purpose assistant cannot infer from the files in front of it live in one file, so there is a single copy to keep correct:

context.md

Give your assistant the URL, or pull it into the repository you are working in so it is there every session:

Terminal 
curl -O https://md-store.sidecartridge.com/build/atari-st/context.md

What is in it, and why each part earns its place:

  • The hardware. Pico W only. An assistant that assumes a Pico 2 W will suggest things that cannot work.
  • The two halves, and that the Atari side executes in place from ROM. Everything awkward follows from that one fact.
  • The shared memory map, with the instruction never to hard-code an address inside it.
  • The hard constraints from step 7: 6 KB of Atari-side code, no Atari RAM, half the microcontroller's RAM spoken for, a main loop that must never block, flash writes off the critical path.
  • The files that are off limits, and what to do instead of editing them.
  • The build and deploy loop, so it can tell you how to test what it wrote.
  • An instruction to say when it is unsure rather than guess a size, an address or a timing figure.
  • The four reference pages, which it can fetch and read.
The template already has instructions of its own. Read those too.

Both templates ship a CLAUDE.md and an AGENTS.md at the repository root, which Claude Code and most other assistants read automatically. They are detailed and current, and they know things context.md does not: the exact error a build prints when the cartridge overruns 8 KB, why a stale target_firmware.h shows garbage on the Atari while commands still work, and which submodule directories must never be edited.

context.md supplements them and says so in its own opening lines. If the two ever disagree, the files in the template win: they sit next to the code and change with it.

Prompts for real tasks

Three shapes that come up constantly. Note what they have in common: they say where the code goes, and they state the limit that applies.

Adding a command handler

Prompt 
Add a command that the Atari side can send to ask for <what you want>.

- Register it through chandler_addCB, following the existing handler in
  rp/src/ as the pattern.
- The handler must return quickly; chandler_loop() has to keep turning.
  If the work is slow, split it across iterations and tell me how.
- On the Atari side, add the send_sync call in userfw.s. Keep it minimal,
  that file has a 6 KB budget.

Show me the C side first. Do not touch the emulation files.

Reading a file from the SD card

Prompt 
In the C half, read <file> from the microSD card and <what to do with it>.

Use the existing FatFs setup (sdcard_initFilesystem, the SDCARD_INIT_OK
check) rather than introducing another filesystem API. Handle the card
being absent or the file missing, because this runs on real hardware where
both happen. Use DPRINTF for diagnostics.

Remember roughly half the 264 KB of RAM is available; do not read a whole
file into memory without checking its size first.

Drawing to the framebuffer

Prompt 
Using the framebuffer template's model, draw <what you want>.

The buffer is 320x200, one byte per pixel. Write pixels, then call
fb_publish() once per frame. There is roughly a 19 ms compute window per
vertical blank at 50 Hz. If the work will not fit, say so and propose
spreading it across frames rather than dropping the frame rate.
Watch for the two things it will get wrong.

First, drift toward the Atari half. Assembly is where the interesting-looking hardware is, and an assistant will happily put logic there that should be in C. Push back every time.

Second, blocking work in the main loop. A sleep, a busy wait, a long parse: anything that stops chandler_loop() stops the Atari being answered, and the symptom is a machine that appears to freeze rather than an error.

Verify it, do not trust it

Generated code that compiles has cleared a very low bar. The loop that actually tells you something is the one from step 6, and it is short:

after every meaningful change 
./build.sh pico_w debug 44444444-4444-4444-8444-444444444444

# with developer mode on, push it over Wi-Fi and launch it:
UF2=dist/44444444-4444-4444-8444-444444444444-$(cat version.txt).uf2
curl --fail --data-binary @"$UF2" \
     -H "Content-Type: application/octet-stream" \
     "http://sidecart.local/dev_upload.cgi"
curl --fail "http://sidecart.local/mngr_launchapp.cgi?uuid=44444444-4444-4444-8444-444444444444"

# or over USB: picotool load dist/*.uf2, then power-cycle the Atari

Run it after small changes rather than large ones. When something breaks after ten accepted suggestions you have ten candidates. After one, you have one.

Two questions worth asking about any non-trivial change before you accept it:

  • Which half did this go in, and is that right?
  • Does anything here block, allocate a lot, or write to flash?

If the answer to the second is yes, ask why. Sometimes it is fine. Sometimes it is the bug you would otherwise spend an evening on.

Read the existing microfirmwares.

Several are open source, and they are the best available answer to "what does a real one look like?". There is a drives emulator, a ROM emulator, an RTC emulator, a web browser, a MIDI bridge. Pointing your assistant at a repository that already solves a similar problem beats describing the problem from scratch. You can find them from the store, each one is written up in the apps catalogue , and the sources live under the sidecartridge organisation . The drives emulator and ROM emulator are the two most instructive to read first.