Step 5: Pick a template (Atari ST)

Step 5 · Atari ST

Pick a template.

You do not start from an empty directory. There are two official templates, and choosing between them is the one decision in this track that is expensive to reverse. It is worth two minutes of thought.

The question to ask

Are you drawing the screen, or are you answering commands?

That is the whole decision. The two templates are built around different relationships between the Atari and the microcontroller, and switching later is closer to a restart than a refactor. The upstream programming guide describes the project structure both of them share.

	md-microfirmware-template	md-framebuffer-template
Shape of the app	The Atari sends commands. The microcontroller does work and replies.	The microcontroller renders a full screen. The Atari displays it.
Good for	Emulated peripherals, network services, file and disk tools, anything terminal-driven.	Demos, games, visualisers, anything where you own the display.
You write	C, plus some 68000 in `userfw.s`.	Mostly just C. The template hides the assembly and the bus timing.
Display model	Whatever you build.	320x200, one byte per pixel. Write pixels, call `fb_publish()` once per frame.
Also gives you	The command handler framework and the shared-memory protocol.	YM2149 audio, Atari keyboard input, SD card access through FatFs.

If you are new to this, the framebuffer template is the gentler start.

It gives you a ~19 ms compute window every vertical blank at 50 Hz, and a simple contract: fill a buffer, publish it, repeat. You get something visible on screen sooner, and you can stay in C almost the whole time.

Both are GPL-3.0. Whatever you build on top inherits that, which matters when you get to publishing in step 10. Decide now if that is a problem for you rather than later.

If you want to see where each shape leads, the published apps are documented individually. The drives emulator and the ROM emulator are command-driven, and MIDI-to-IP shows what a network service looks like. The full list is the apps catalogue .

Create your repository from it

Both repositories are marked as GitHub template repositories, so you do not fork them. You generate a fresh repository with its own clean history.

md-microfirmware-template for command-driven apps.
md-framebuffer-template for framebuffer apps.

Open the one you chose and press Use this template, then Create a new repository. Clone your new repository and pull in its submodules:

Terminal

git clone git@github.com:<your-user>/<your-repo>.git
cd <your-repo>
git submodule update --init --recursive

Do not skip the submodule command.

The templates carry pico-sdk, pico-extras and fatfs-sdk as submodules, pinned to versions known to work together. Clone without them and you get empty directories and a build that fails with confusing missing-header errors.

This is also the answer to "where do I download the Pico SDK from?". You do not. It is right there.

Strip it down to something you can read

The templates ship with demo code so that they do something visible on first build. That is useful once, when you run it unmodified in step 6, and then it is in your way.

The framebuffer template includes a script that reduces it to a minimal starting point:

from the repository root

examples/hello_text/apply.sh

Run the unmodified template first, in step 6, confirm it works, and only then strip it. If you strip first and something breaks, you will not know whether it was the template or your environment.

Have your assistant read the template before you change anything.

This is the highest-value thing you can do with an assistant right now, much more useful than asking it to write code. Point it at the freshly cloned repository and ask it to explain the layout back to you:

Prompt

This repository is a template for a SidecarTridge Multi-device microfirmware
for the Atari ST. Read it and tell me:

1. Which files are the C code that runs on the Raspberry Pi Pico W, and which
   are the 68000 code that runs on the Atari.
2. Which files are infrastructure I should not modify, and which are the
   ones I am expected to edit.
3. Where the entry point of my own application code is.

Do not change anything yet.

Step 7 covers the same ground properly. Doing both is not wasted. You will read it once from the assistant with your own repository in front of you, and once here with the reasoning behind it.