Flashing and the loader¶

Most of the time you only copy .blit games onto a console. This page covers the lower-level jobs: setting up a new console, updating ChiliChip OS, and building it yourself.

BOOTSEL mode¶

The RP2350 has a built-in bootloader that shows up as a USB drive and accepts .uf2 files. To enter it:

Connect the console to your computer.
Switch it off, then hold the top X button and switch it on.
A drive named RP2350 appears (on Linux usually at /media/$USER/RP2350).

Copy a .uf2 onto that drive and the console writes it to flash and restarts.

Setting up a console¶

vgc-os-factory.uf2 holds the loader with the home screen already installed, so one copy sets up a new or wiped console:

cp vgc-os-factory.uf2 /media/$USER/RP2350/

The console restarts into the home screen, ready for games to be copied onto its drive.

The image writes the loader to flash 0–256 KB and the home screen at 256 KB, and leaves the rest of flash alone: other installed games and the USB drive (saves and settings) are kept. A game that was installed at 256 KB is overwritten and needs installing again.

Updating the OS¶

The home screen is a .blit: copy a new vgc-os.blit onto the console's drive like a game.
The loader is a .uf2: copy a new blit-loader.uf2 in BOOTSEL mode. This keeps installed games, saves and settings. Do this when a game reports "Needs a system update".

Building the OS¶

Build the loader, the home screen and the factory image from the SDK itself:

cd 32blit-sdk
mkdir build.vgc-blit
cd build.vgc-blit
cmake .. \
  -DPICO_SDK_PATH=../../pico-sdk \
  -DPICO_BOARD=chilichip_vgc \
  -DPICO_PLATFORM=rp2350-arm-s \
  -DCMAKE_TOOLCHAIN_FILE=../pico2.toolchain \
  -DBLIT_EXECUTABLE_PICO_BLIT=1
make

Output	What it is
`32blit-pico/loader/blit-loader.uf2`	the loader (system firmware)
`vgc-os/vgc-os.blit`	the home screen
`vgc-os/vgc-os-factory.uf2`	the loader with the home screen pre-installed
`launcher/launcher.blit`	the stock 32blit launcher, as an alternative home screen

The CI's "VGC-blit" build produces the same files.

tools/factory-uf2.py makes the factory image by adding .blit files at fixed flash offsets (in KB) to the loader's .uf2, numbered as one image:

python3 tools/factory-uf2.py blit-loader.uf2 vgc-os.blit@256 -o vgc-os-factory.uf2

The same tool can preload games, for example for a batch of consoles: add a game.blit@<offset> argument per game. Offsets must be multiples of 64 and must not overlap: each game starts after the end of the previous file, rounded up to the next 64 KB.

Installing over USB serial¶

With the console running the loader and connected over USB, the 32blit tool installs .blit files without going through the drive:

32blit install vgc-os.blit
32blit install game.blit

Build options¶

These are set for the console in 32blit-pico/board/chilichip_vgc/config.h and config.cmake. You only need them when changing the OS itself.

Setting	Effect
`SYSTEM_MENU`	a short HOME press opens the system menu (loader only)
`AUTO_INSTALL`	`.blit` files on the drive install after eject; the drive is read-only while a game runs (loader only)
`STORAGE_VOLUME_LABEL`	the drive label, `CHILICHIP`; applied at boot, so older drives are relabelled
`USB_VENDOR_STR`, `USB_PRODUCT_STR`	the USB device name, "ChiliChip Console"
`BATTERY_ADC_PIN`, `BATTERY_DIVIDER`	battery sensing on GPIO 29 through a ÷3 divider
`LCD_MAX_CLOCK`	the display's SPI clock cap, 20 MHz
`BLIT_ENABLE_CORE1`	mix audio on the second core
`BLIT_LOADER_RAM_KB`	RAM reserved for the loader, 64 KB

The install logic is install_blit_file() in 32blit-pico/blit_launch.cpp, the drive watcher is 32blit-pico/installer.cpp, and the system menu is 32blit-pico/system_menu.cpp.