Setup guide
The whole process, start to finish. Budget about 20 minutes, most of it spent waiting on downloads.
Download and open Raspberry Pi Imager — the official, free tool from Raspberry Pi themselves. Insert your SD card, then in Imager:
Choose OS → Raspberry Pi OS (64-bit). Choose Storage → your SD card.
Before clicking "Next," click the gear/settings icon (or you'll be prompted) to pre-configure things — set a hostname, enable SSH, and enter your Wi-Fi details here. Doing this now means the Pi connects to your network automatically on first boot, without needing a keyboard/mouse plugged into it at all.
Click Write, and wait for it to finish (this is the slow part).
Move the SD card to the Pi, connect it to your screen, and power it on. Give it a couple of minutes for its first boot — it's doing some one-time setup in the background.
If you're on the Pi directly, open a Terminal window. If you're connecting from another computer instead, open your own terminal and connect over SSH first (replace with the hostname you set in step 1):
Then run the installer:
This downloads the latest version and sets everything up automatically — Node.js, the app itself, and the wall-display kiosk mode. It'll ask for your password partway through (for a couple of one-time system installs) and reboot automatically when it's done.
After it reboots, the calendar display should appear automatically on the connected screen. From your phone or any browser on the same network, visit the address shown on that screen to finish setup — you'll pick whether this is your main device, and (for the main device) enter an email to activate it. If you use Home Assistant, setup will also ask if you'd like to connect it — optional, and just as easy to do later from Settings if you'd rather skip it for now. No payment required during the free period; it's just how you get update notices and, eventually, pricing info.
From there: themes, calendar sources, and everyone in your family or team.
One shortcut worth knowing: Ctrl+Alt+K toggles the kiosk display on or off, if you ever need to get to a terminal on the Pi itself.
Depends which part. If ~/piazzahq doesn't exist yet, the one-line install command is safe to run again from scratch. If it already exists (even from a partial/failed attempt), don't re-run the one-liner — it'll refuse on purpose, to avoid wiping anything. Instead run bash ~/piazzahq/install.sh directly; that part is genuinely safe to re-run as many times as needed, and won't repeat steps that already succeeded. If it keeps failing at the same point, note the exact error and reach out.
Give it another minute — the kiosk display can take a moment to start after boot. If it's still blank, check the HDMI cable is in the port labeled HDMI0 on a Pi 4/5, not the second port.
It's shown directly on the wall display itself once it's running. If you set a custom hostname in step 1, try http://<that-hostname>.local from a phone on the same Wi-Fi network.
Home Assistant is a separate, free project — it doesn't come with Piazza HQ, and setup here only handles connecting to one you already have running. If you're starting from scratch, the easiest hands-off option is Home Assistant Green — a small box that arrives with it already installed, just add power and network.
If you'd rather run it yourself on hardware you already have (a spare Pi, or the same machine as your Piazza HQ central server), this is the official Docker install command — works on a Raspberry Pi or any Linux box with Docker Engine already installed (swap in your own timezone and a folder for its config first):
Once it's running, visit http://<that machine's address>:8123 to finish its own setup — then come back here (Settings → Home Assistant, or the setup wizard on a fresh install) to connect it.
This Docker path doesn't include Home Assistant's optional "apps" (Zigbee2MQTT, an MQTT broker, etc.) — fine for connecting sensors and switches to Piazza HQ, but if you think you'll want those, flashing the full Home Assistant OS instead gets you those too. Home Assistant's own install process can change over time — their official installation docs are the source of truth if anything here looks out of date.
Setup asks if you want to during first-run — just paste your Home Assistant URL (e.g. http://homeassistant.local:8123) and a Long-Lived Access Token (in Home Assistant: your profile → Security tab → Long-Lived Access Tokens → Create Token). Skipped it, or setting up a second display? Do it anytime from Settings → Home Assistant instead. Either way, the URL and token stay on your own server — they're never sent to the display or anyone's phone. Once connected, add an Entity Status widget from Layout to show any sensor or device's current state, toggle lights and switches, adjust a thermostat, or run a scene.
Setting up remote access, switching to X11 manually, checking logs — see the troubleshooting page for copy-paste commands.
Ready to explore what's actually in the app? The user guide covers every tab.