piboard

A wall dashboard for a Raspberry Pi — weather and Google Calendar, drawn straight to the framebuffer (/dev/fb0). Data is fetched on background threads, refreshed on a schedule, and the whole thing runs as a systemd service that starts on boot and restarts itself if it crashes.

Generated with python3 piboard.py --demo — canned weather and events, no network or screen needed.

Who it's for

Anyone with a spare Pi and a spare screen. Everything that's specific to you — your location, your calendars, their colours — is configured through environment variables, so a single checkout runs unchanged on anybody's Pi. No code edits needed to make it yours.

What it is

• A configurable single-Pi framebuffer dashboard: clock, weather, and any number of Google Calendars.
• Self-contained: one Python script (piboard.py) plus a systemd unit.
• Secrets-safe: calendar iCal URLs live only in piboard.env (git-ignored, mode 600) and are injected by systemd — never hard-coded, never committed.

What it isn't

No web UI. No multi-device sync. No general-purpose "home hub". It stays a single-Pi framebuffer dashboard on purpose — that boundary is the point. "Configurable" means env-driven, not feature-sprawling.

What it runs on

The reference install is a Raspberry Pi Zero W — one 1 GHz ARMv6 core and 512 MB of RAM — driving a 1920×1080 screen at 16-bit colour, on Raspberry Pi OS 12 (bookworm) with the stock Python 3.11. That's deliberately the floor: no X server, no browser, no GPU path, just Pillow drawing a frame into /dev/fb0, which is why the slowest Pi still keeps up. Parsing the iCal feeds is the only real cost, and it happens on a background thread. Anything newer has headroom to spare.

Configuring it

All configuration is environment variables (set them in piboard.env):

Variable	Default	Purpose
PIBOARD_LAT / PIBOARD_LON	Cape Town	Weather location (find yours at openstreetmap.org)
PIBOARD_LOCATION	Home	Header label
PIBOARD_UNITS	metric	metric (°C, km/h) or imperial (°F, mph)
PIBOARD_CALENDARS	(none)	Comma-separated calendar labels, e.g. Brett,Mandy
PIBOARD_ICAL_<LABEL>	—	Secret iCal URL for each label (uppercased)
PIBOARD_COLOR_<LABEL>	palette	Optional R,G,B colour override per calendar

Tunables (PIBOARD_GRID_DAYS, PIBOARD_MAX_PER_DAY, PIBOARD_DAYS_AHEAD, the refresh cadences, PIBOARD_FB_DEVICE, PIBOARD_PREVIEW_PATH) also read the environment but rarely need changing — PIBOARD_GRID_DAYS sets how many day columns the week grid shows (default 7) and PIBOARD_MAX_PER_DAY caps the event cards per day before a "+N more". See the CONFIG block in piboard.py for the full list.

Running it

See instructions.md for the full setup-and-run guide: copying the script to the Pi, installing dependencies, the systemd service, and the deploy.sh helper for pushing changes.