Configurator Technical Reference

Configurator Technical Reference

This page documents the internal technical details of the PICO9918 Configurator system. For user-level documentation, see Configurator.

Native Configurator Internals

ROM Banking

Full-featured configurators use ROM banking to store the firmware image within the ROM:

Platform	Banking	Assembler	Notes
TI-99/4A	8KB banks (up to 32)	XAS99 + linkticart	.bin cartridge
ColecoVision	16KB banks	GASM80	Standard ColecoVision ROM
MSX (ASCII16)	16KB (ASCII16 mapper)	GASM80	Most compatible mapper
MSX (Konami)	16KB (Konami mapper)	GASM80	Alternative mapper

The UF2 firmware data is converted to CVBasic DATA statements and organized into banks using uf2cvb.py. Each bank holds approximately 30 blocks (8KB banks) or 61 blocks (16KB banks) of firmware data after accounting for overhead.

Lite Configurator Platforms

Platform	Assembler	Notes
SG-1000/SC-3000	GASM80	.sg ROM
NABU	GASM80	.nabu ROM
CreatiVision	GASM80 (via CVBasic 6502 target)	6502 CPU - uses cvbasic_6502_prologue.asm

VDP Detection Sequence

1. Writes the F18A unlock sequence to register 57
2. Triggers a GPU operation at address >3F00
3. Reads status register 1 to check for F18A mode bit
4. Reports whether a standard TMS9918A, F18A, PICO9918, or V9938 is detected

Firmware Update Protocol

When performing a firmware update via the native configurator:

1. The configurator reads UF2 blocks from its banked ROM data
2. Each 256-byte block is validated (magic bytes, sequence, size, address alignment)
3. Blocks are written to the PICO9918 flash via TMS9918A register interface
4. Flash status is monitored via TMS status register 2
5. The process supports both RP2040 and RP2350 firmware from a single combined ROM

Flash status register 2 provides real-time feedback:

Bits	Field	Values
7	Running	Operation in progress
6-5	Retry count	0-3
4-2	Error code	0=OK, 1=Header, 2=Sequence, 3=Full, 4=Size, 5=Verify
1-0	Status	0=Idle, 1=Validating, 2=Erasing, 3=Writing

Web Configurator Technical Details

The web configurator generates a UF2 file containing the 256-byte configuration structure:

Property	Value
File size	1024 bytes (2 UF2 blocks - one per device family)
Target flash address	0x101FF000 (top 4KB of 2MB flash)
RP2040 family ID	0xE48BFF56
RP2350 family ID	0xE48BFF59
Browser support	Chrome, Firefox, Safari, Edge

The firmware auto-detects which block to use based on the running hardware. The web tool produces byte-identical output to the Python command-line tool (configtool/tools/config_uf2.py).

Color Format

Palette colors use 12-bit RGB with a 4-bit alpha channel:

Component	Bits	Range
Alpha	15-12	Always 0xF (opaque) for colors 1-15
Red	11-8	0x0 - 0xF
Green	7-4	0x0 - 0xF
Blue	3-0	0x0 - 0xF

Color 0 (transparent) is always black. Each color is stored as 2 bytes (big-endian) at config bytes 128-159.

Configuration Byte Map

The configuration structure matches the firmware's flash layout. See Firmware Architecture#configuration-structure-256-bytes for the complete byte map.