# 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:

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

### 3. Run setup

```bash
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

```bash
sudo reboot
```

The Pi will boot directly into the fullscreen camera grid.

## Reconfiguring

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

```bash
# 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

```bash
# 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