Troubleshooting
Everything here runs on the Pi itself — either directly, or over SSH from another computer (ssh [email protected], or whatever hostname you set) or a phone using an SSH app like Termius or PiSSH. Tap the icon on any command to copy it.
Reach the control app from anywhere, not just your home network — sets up Tailscale, a private network (nothing exposed publicly). This is interactive: it'll show you a login link to open once in any browser.
Already set up? Check its status:
The installer offers this automatically near the end of setup. If you skipped it, or want to do it manually:
sudo raspi-config → 6 Advanced Options → Wayland → W1 X11 → reboot.Safe to run again as many times as needed — it won't repeat steps that already succeeded, and never touches your actual data (events, photos, chores).
curl | bash install command once ~/piazzahq already exists — it refuses on purpose, specifically so it can't be used to accidentally wipe a real install. The command above is the one that's actually safe to repeat.Destructive. This is a different, much bigger step than the repair command above — use it only if you genuinely want to lose everything and set up as if this were a brand new Pi. The vast majority of "something's wrong" situations are the repair command above, not this.
Destructive. Different from the fresh-install command above — this doesn't reinstall anything afterward. Use this when you actually want Piazza HQ gone from this specific device (retiring it, repurposing the Pi for something else), not when you're troubleshooting.
After power-on the display goes through a few stages before the layout appears, and on a small Pi that takes a while: on a Pi 3B+, expect the screen to sit white, then dark, for up to a minute or so before the layout draws. That's the Pi being busy starting up, not a fault. If yours is still white or blank after two or three minutes, or stays that way until you press F11 or F5, work through these in order.
1. Update to version 1.87.14 or newer. It shortens the white stage on small Pis (calendar feeds no longer all sync during the first minute after start-up), makes the start-up check wait for the desktop, and fixes a browser window that comes up too small. In the control app: Settings → Advanced → Version & License, then update.
2. Try F11. With a keyboard plugged into the Pi, press F11. If the layout appears, the browser window started smaller than the screen. Over SSH instead:
3. Run the checkup. It changes nothing and prints no passwords: it reports your Pi model, desktop type, how the browser is launched at boot, and whether that launch line points at a file that exists.
On a version older than 1.87.14 that file isn't on your Pi yet; this fetches and runs the same checkup:
4. If the checkup says a boot line points at a missing file, the display never starts after a reboot because the launcher it names is gone (this happens on a Pi whose project folder was renamed or moved). Re-running the installer repairs it, and is safe to repeat:
Drop in and out of the fullscreen display without racing an auto-relaunching browser.
kiosk toggle — no SSH needed for routine use. (Older installs may still have the previous Super+K binding, which turned out to conflict with the Raspberry Pi desktop's own "tap Super to open the menu" gesture — re-running install.sh adds Ctrl+Alt+K alongside it without removing the old one.) The commands below stop the underlying process cleanly either way, and are the only option if you're on a device with no keyboard at all. If you're physically at the Pi with no SSH access and need a terminal, Ctrl+Alt+F2 switches to a text console below the whole graphical session — log in there and run kiosk off.Bring it back:
Or just flip between the two:
kiosk restart leaves a black screen, or logs you out of the desktop, the kiosk command on your Pi is an old copy. The installer used to copy it into a system folder once, and updates can't refresh a file there, so fixes to it never reached the command you type (and the Ctrl+Alt+K shortcut). Newer installs link to the up-to-date copy automatically; on an older one, run this once (it asks for your Pi password):Until then, the current copy always works when you run it by its full path:
Watch its logs live (useful if something's actually broken):
Restart it (e.g. after manually changing a setting):
Still stuck? Get in touch — include what you ran and what actually happened, and it's usually a quick fix.