Pimoroni Galactic Unicorn (53x11 LED matrix) on a Raspberry Pi Pico W running MicroPython. A weather clock that rotates four screens on the matrix:
- clock — local time, RTC synced via NTP (EU DST computed in pure integer
math in
src/tz.py— MicroPython has no tzdata), blinking colon; shown only when the RTC is trustworthy (NTP-synced, or already reading >= 2026 after a soft reset) — otherwise the slot showsno ntp - weather — animated 10x11 icon + current temperature from open-meteo (no API key); icons are hand-drawn pixel art per WMO code with day/night variants (twinkling sun/moon, drifting fog bands, falling rain/snow, flashing storm bolt)
- hi/lo — today's high/low with up/down arrows
- CO2 — ppm from an optional SCD41 sensor on the STEMMA QT connector, color-coded green/amber/red by indoor air quality
Buttons: A toggles the matrix rain mode — one anti-aliased drop per
column (subpixel motion, gradual brightness between rows) with a fading trail.
Five speed/brightness tiers (very dim crawl → full-brightness sprint) are
hashed across the columns, gaps between passes span 4–11 rows, and ~1 pass in
10 rests entirely, so the rain's density and tempo visibly breathe; each drop's
head cycles through a few subtle green variations as it falls and settles on
its hue
for the second half of the pass, and every pass mixes its hue and trail length
from a deterministic LCG (no randomness — sim and board render identically).
One press plays it full-screen for two minutes (a second press stops it early),
then the regular rotation resumes. With a trusted RTC the clock shows through
the rain (sim/sim.py --screen rainclock): the clock phases in over ~0.3 s
on entry; when the mode ends it dissolves right away — the dim box lifts,
the field pours across the still-bright digits, and the clock's ink converts
to falling drops pixel by pixel (staggered, organic); at full strength
the field dims to 35 % alpha inside
the clock's text box while bright white digits draw on top, so
the rain visibly
pours across the time; without a trusted RTC the rain runs alone (same rule as
the rotation's clock-hiding). The rain keeps a persistent frame tick
across runs, so it always continues where it left off.
The regular rotation (clock → animated weather → hi/lo → CO2), rendered by the
host sim from the real main.py — regenerate with
python3 sim/run_main.py --seconds 24 --delay 0.12 --preseed-co2 53 --gif docs/demo-rotation.gif
(the preseed fills the CO2 history with ~2.6 h of canned readings so the
GIF's strip isn't empty; micropython-check verifies the tracked GIF
against this exact command; needs Pillow; these GIFs are tracked, all other
recordings stay uncommitted).
The rain-clock mode as one press plays it: the bare field pours, the clock
phases in over ~0.3 s, holds steady with drops crossing the bright digits,
then the exit dissolves the ink into falling drops frame by frame.
python3 sim/sim.py play --screen rainclock --delay 0.12 --gif docs/demo-rainclock.gif renders the whole episode (lengths ride the
render constants, so --frames doesn't apply); sim/check_demo_gif.py (CI)
enforces that both GIFs match the code.
- Pimoroni Galactic Unicorn (Pico W); optional SCD41 CO2 sensor (STEMMA QT, SDA=4/SCL=5)
- Windows 11 host + WSL2 (Ubuntu-24.04) — GitHub:
abalawender/galactic-clock - Board shared with the WSL side over USB via usbipd:
usbipd.exe;mpremote(apt install micropython-mpremote) - Pillow — only needed for
--gifoutput in the sim (everything else is stdlib) - Firmware: MicroPython v1.29.0 board build
pico_w_galactic-v1.29.0-micropython.uf2from https://github.com/pimoroni/unicorn/releases/tag/v1.29.0 (local copy infirmware/, gitignored — flashing notes indocs/flashing.md)
# find the board's bus id (env-specific; changes with the port):
usbipd list # e.g. 2-4 Pico W (pico_w_galactic)
# once, as admin on Windows (bus id from the list):
usbipd bind --busid <busid>
# from WSL:
usbipd.exe attach --wsl --busid <busid> # -> /dev/ttyACM0
mpremote exec "import os; print(os.uname().version)"
The board reads /secrets.py at boot. It is gitignored and lives only on the
board flash — never commit it, never print it, never copy it back off the
board. To create it, copy the committed template secrets.example.py — each
variable is documented inline there (WiFi, location, TZ, optional
SCD41_ALTITUDE_M) — and fill in real values:
cp secrets.example.py secrets.py # fill in real values
mpremote cp secrets.py :secrets.py # host -> board only
rm secrets.py # board holds the only copy
from galactic import GalacticUnicorn
from picographics import PicoGraphics, DISPLAY_GALACTIC_UNICORN
gu = GalacticUnicorn() # 53x11
d = PicoGraphics(display=DISPLAY_GALACTIC_UNICORN)
d.set_pen(d.create_pen(255, 60, 0))
d.pixel(26, 5)
gu.update(d)See exactly what the 53x11 matrix will show — without touching the board.
sim/sim.py runs the same src/render.py as the board, with a faithful
re-implementation of the PicoGraphics bitmap6 font (sim/font6_data.py), so
layouts match the device pixel-for-pixel. The sim never reads secrets.py;
weather values are CLI args (--code/--temp/--hi/--lo/--night).
python3 sim/sim.py print --screen weather --code 61 --temp 21 --frames 8
# plain ASCII frames on stdout (for agent analysis)
python3 sim/sim.py play --screen weather --code 61 --temp 21 # animate in terminal
python3 sim/sim.py play --screen weather --code 0 --night # moon + stars
python3 sim/sim.py play --screen icons --frames 8 # contact sheet: all icons
python3 sim/sim.py play --screen hilo --hi 25 --lo 18
python3 sim/sim.py play --screen matrix --frames 60 # code rain
See it in motion — render any screen, or the whole display loop of the real
main.py (fully mocked: WiFi/NTP/open-meteo/SCD41), to an animated GIF
(needs Pillow; GIFs are gitignored and generated on demand for PRs — the only
tracked one is the README demo above):
python3 sim/run_main.py --seconds 24 --gif /tmp/rotation.gif # clock -> weather -> hi/lo -> CO2
python3 sim/sim.py play --screen matrix --frames 60 --gif /tmp/matrix.gif
python3 sim/sim.py play --screen icons --frames 8 --gif /tmp/icons.gif
python3 sim/sim.py play --screen weather --code 61 --temp 21 --frames 12 --gif /tmp/rain.gif
HITL review on the physical board (see all icons before approving a PR):
python3 skills/unicorn/display.py --icons cycles every weather icon on the
matrix, 3 s each, WMO code labelled (n = night); then --stop and
mpremote reset return to the clock.
The weather icon (10x11, left of the temperature) is animated per WMO code: twinkling sun/moon, partly-cloudy sun+moon peeking behind a drifting cloud, fog bands, falling rain streaks (drizzle/snow fall slower, showers pulse, heavy variants denser), and a flashing bolt for storms. The icons are hand-drawn 10x11 pixel art, tuned frame by frame in the sim.
Recordings are generated on demand and never committed (gitignored). For PR reviews, before/after GIFs of every screen (base ref vs PR head) are rendered automatically:
python3 sim/before_after.py --ref origin/micropython --out /tmp/pr
# writes /tmp/pr_<screen>_{before,after,compare}.gif per screen
# (weather/icons/clock/hilo/co2) plus pr_rotation_* — a full mocked
# run of the real main.py (sim/run_main.py), robust to screen changes.
# "icons" is a contact sheet of every animated weather icon
# (WMO code x day/night) in one GIF. --ref takes the PR base SHA
# (CI passes github.event.pull_request.base.sha); locally use
# origin/micropython. Screens pixel-identical to the base
# produce no GIFs at all, so the CI upload/PR comment skips
# them — the review only shows what changed. Attach the GIFs
# to the PR; CI does this automatically.
- Tests (host-only, no board):
python3 -m unittest discover -s tests -v— rendered-bitmap property checks, golden ASCII dumps, EU DST rules, and a fully mocked run of the realmain.py - Preview every display change in
sim/before deploying (above) - Deploy:
scripts/deploy.sh— attaches the board first if/dev/ttyACM0is missing (see Connect above), uploads the modules on its manifest (main.py+ thesrc/services), then resets the board - PRs to
micropythonthat touchmain.py/src//sim//tests/run the tests and post before/after GIFs inline on the PR — see.github/workflows/pr-sim.yml micropython-check(.github/workflows/micropython-check.yml) runs on PRs tomicropythonand on pushes to it: tests + a check that the tracked demo GIF above matches the code (sim/check_demo_gif.py). It is a required status check under themicropythonruleset (rebase-only merges, one approving review, resolved threads). If you change rendering, regeneratedocs/demo-rotation.gifin the same PR (command above the GIF)
AGENTS.md— ramp-up essentials: golden rules, workflow, layoutmain.py— board entry point: WiFi/NTP/open-meteo/SCD41 + screen loop (thin)src/render.py— all drawing; pure functions, no board imports (also runs in the sim)src/tz.py— EU DST offset in pure integer math (MicroPython has no tzdata)sim/— host simulator:sim.py(play/print/GIF),font6_data.py(real bitmap6 font metrics),run_main.py(mocked full run ofmain.py),before_after.py(PR review GIFs),gif.py(Pillow writer)tests/— unittest suite (bitmaps, golden ASCII, tz rules, mocked main loop)scripts/— attach.sh, deploy.sh (uploads the board sources, resets board)skills/— agent skills: board access via mpremote (attach/recovery, REPL rules, flash files) inmpremote; the Galactic Unicorn board itself (LED matrix display snippets, frozengalacticsynth API) inunicorndocs/— flashing notes, hardware resource inventory (hardware.md) + the tracked README demo GIF;firmware/— local uf2 copy (gitignored)
MIT — see LICENSE. Contributions (mostly AI agents) follow
AGENTS.md: branch off micropython with small atomic commits,
and CI will run the tests and post before/after GIF previews inline on the PR.

