vigilar/kiosk/README.md

Vigilar Kiosk — Raspberry Pi TV Display

Turn a Raspberry Pi into a dedicated security-camera display showing the Vigilar 2x2 camera grid on any HDMI-connected TV.

Hardware

• Raspberry Pi Zero 2W, 3, 4, or 5
• Micro-HDMI (Zero 2W) or HDMI cable to TV
• Power supply (5V, 2.5A+)
• MicroSD card (8 GB+)

Quick Start

1. Flash Raspberry Pi OS

1. Download Raspberry Pi OS Lite (64-bit) (no desktop) from https://www.raspberrypi.com/software/.
2. Flash to MicroSD with Raspberry Pi Imager.
3. In Imager's settings (gear icon), enable SSH and set a password for the pi user. Optionally configure Wi-Fi.
4. Boot the Pi.

2. Copy kiosk files to the Pi

From the machine running Vigilar:

scp -r kiosk/ pi@<pi-ip>:~/kiosk/

3. Run setup

ssh pi@<pi-ip>
cd ~/kiosk
sudo bash setup_kiosk.sh

The script will:

• Install X11, Chromium, and unclutter
• Create a vigilar user
• Ask for the Vigilar server URL (default: https://vigilar.local:49735/kiosk/)
• Configure auto-login and kiosk auto-start via systemd
• Set GPU memory, screen blanking, hostname, and SSH

4. Reboot

sudo reboot

The Pi will boot directly into the fullscreen camera grid.

Reconfiguring

Change URL, rotation, or resolution without re-running full setup:

# Interactive
sudo ./update_kiosk.sh

# Non-interactive
sudo ./update_kiosk.sh --url https://192.168.1.50:49735/kiosk/ --restart

# Change rotation (requires reboot)
sudo ./update_kiosk.sh --rotation 90
sudo reboot

Files

File	Purpose
setup_kiosk.sh	Full initial setup script
update_kiosk.sh	Reconfigure URL/rotation/resolution
kiosk.service	systemd unit (installed by setup)
kiosk_config.txt	Template config (copied to Pi)

On the Pi after setup:

File	Purpose
/home/vigilar/kiosk_config.txt	Active configuration
/home/vigilar/.xinitrc	X session startup
/home/vigilar/.bash_profile	Fallback auto-start
/etc/systemd/system/vigilar-kiosk.service	systemd service

Management

# Check status
sudo systemctl status vigilar-kiosk

# View logs
sudo journalctl -u vigilar-kiosk -f

# Restart kiosk
sudo systemctl restart vigilar-kiosk

# Stop kiosk
sudo systemctl stop vigilar-kiosk

# Switch from systemd to .bash_profile method
sudo systemctl disable vigilar-kiosk
# Then uncomment 'exec startx' in /home/vigilar/.bash_profile

Troubleshooting

Black screen after boot

• Check that the Vigilar server is reachable: curl -k https://vigilar.local:49735/kiosk/
• Check service logs: sudo journalctl -u vigilar-kiosk --no-pager -n 50
• Verify X can start: sudo -u vigilar startx -- -nocursor

"Cannot open display" errors

• Ensure the Pi is booting to tty1 and the service has TTY access
• Check: sudo systemctl status vigilar-kiosk

Certificate errors in Chromium

• The .xinitrc includes --ignore-certificate-errors for self-signed certs
• For production, use a proper certificate on the Vigilar server

Screen stays on when it should sleep

• Screen blanking is deliberately disabled for a security kiosk
• To re-enable: remove consoleblank=0 from cmdline.txt, remove xset lines from .xinitrc

Resolution or rotation not applied

• Rotation and resolution set in config.txt require a reboot
• Check current settings: cat /boot/firmware/config.txt (Bookworm) or cat /boot/config.txt

Low memory on Pi Zero 2W

• Chromium with --incognito and --disk-cache-dir=/dev/null minimises memory use
• The setup sets gpu_mem=128 which is a good balance
• If OOM occurs, try gpu_mem=64 in config.txt