Getting started with the Neo6502 under Trinity

At the end of this guide, your Neo6502 board starts under Trinity, on NeoDOS, and runs a program copied to a USB stick.

1. What you need · 2. Flash Trinity · 3. Prepare the stick · 4. A first program, in C · 5. Go back to the official firmware · 6. If something goes wrong

1. What you need

An Olimex Neo6502 board.
A USB-C mains adapter for power: a computer's USB-C port is not always enough (keyboard and hub drop out).
A USB-A to USB-A cable, to flash the firmware from a computer: it goes into the board's USB-A port, not the USB-C one.
A USB stick formatted as FAT32 (an 8 GB USB 2 stick was tried; a 60 GB USB 3 stick was not recognised).
A USB keyboard and a small USB hub: the board has a single USB-A port, for the keyboard and the stick.
An HDMI display (the output is DVI on an HDMI connector).

2. Flash Trinity

Download trinity-0.16.71.uf2 (release 0.16.71, with its SHA-256 checksum). NeoDOS 0.32.1 is included.

Unplug the USB-C power.
Hold the board's BOOT button, connect the USB-A to USB-A cable between the board and the computer, then release the button.
A drive named RPI-RP2 appears on the computer: copy the .uf2 file to it. The drive disappears once the firmware is written.
Unplug the USB-A cable, plug the USB-C power back in, then the hub with the keyboard.

At start-up, after the logos, the screen shows in particular (the middle lines depend on what is plugged in):

Trinity Firmware: v0.16.71
USB Storage
NeoDOS version 0.32.1
(C) 2026 bmarty - Neo6502 disk operating system
A:\>

3. Prepare the stick

NeoDOS is built into Trinity: nothing to copy to get it. Without a stick, the screen shows USB Storage (no key) and NeoDOS starts anyway.

At start-up, NeoDOS runs AUTOEXEC.BAT if it is on the stick.

Optional: a boot/ folder on the stick brings up a start-up menu (its .neo programs and .bin images, a key from 1 to 9 to choose, Enter or 3 seconds for NeoDOS). A boot/auto.txt file holding the name of one of these files starts it after 3 seconds; Escape brings back the menu. This is how NeoBASIC is started, from a boot/neobasic.bin.

4. A first program, in C

This example from the API reference (group 2, function 6) writes “Bonjour” in colour:

#include <neo/api.h>

int main(void) {
    const char *texte = "\x83" "Bonjour" "\x87" "\r";   /* $83 : couleur 3, $87 : couleur 7 */
    while (*texte)
        neo_console_write_char(*texte++);
    return 0;
}

Compile it with llvm-mos (llvm-mos SDK): mos-neo6502-clang -Os -o BONJOUR.NEO bonjour.c. Copy BONJOUR.NEO to the root of the stick, then type BONJOUR.NEO at the A:\> prompt: “Bonjour” appears, then the prompt comes back.

Example checked in the Phosphoneo emulator.

5. Go back to the official firmware

Same procedure, with the firmware_usb.uf2 file of the official firmware v1.0.0 (neo6502.zip archive). The board ships with another firmware, Olimex's Apple II emulator.

6. If something goes wrong

The stick is not read (USB Storage (no key), MSC filesystem mount failed): check the FAT32 format, try a USB 2 stick, another hub, and mains power.
Black screen: some displays and adapters cause trouble (see Olimex's FAQ); in video mode 1, changing mode brings the picture back.
The boot/ menu does not appear: without a boot/ folder on the stick, there is no menu; if you press Escape, the screen shows Boot : pas de boot/ -> NeoDOS.

Otherwise, report the problem on the Trinity repository (version, hardware, what is displayed), or write to us.