# Pi 5 Kiosk Setup — Extrudex (Go + React)

## Prerequisites

- Raspberry Pi 5 (4 GB or 8 GB)
- MicroSD card (32 GB minimum, Class 10+)
- HDMI touchscreen display
- USB barcode scanner (HID keyboard mode)
- Power supply (27W USB-C recommended)

## One-Line Setup

```bash
# 1. Install Raspberry Pi OS (64-bit, Desktop)
# 2. Enable SSH and VNC
# 3. Run the automated bootstrap
curl -sSL https://raw.githubusercontent.com/CubeCraft-Creations/Extrudex/dev/scripts/pi-bootstrap.sh | bash
```

Or follow the manual steps below.

## Manual Setup

### 1. Install Docker

```bash
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker pi
```

Log out and back in for group changes to take effect.

### 2. Clone and deploy

```bash
cd /home/pi
git clone https://code.cubecraftcreations.com/CubeCraft-Creations/Extrudex.git
cd Extrudex
git checkout dev

# Run the deploy script
chmod +x deploy.sh
./deploy.sh
```

### 3. Verify services

```bash
docker compose -f docker-compose.dev.yml ps
# All three services should be "Up"
```

Check the health endpoint:
```bash
curl http://localhost:5080/health
# Expected: {"status":"ok","db_connected":true,"timestamp":"..."}
```

### 4. Configure kiosk auto-start

```bash
# Enable the Docker stack service (starts on boot)
sudo cp systemd/extrudex.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable extrudex.service

# Enable the kiosk service (starts Chromium after Docker stack)
sudo cp systemd/extrudex-kiosk.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable extrudex-kiosk.service
```

### 5. Configure display server

For Pi 5, Raspberry Pi OS uses Wayland by default. If you encounter
X11-specific issues, switch to X11 in raspi-config (Advanced Options →
Resolution → X11).

The kiosk service supports both Wayland and X11 display servers.

### 6. Touchscreen calibration (if needed)

```bash
# Install calibration tools
sudo apt install -y xinput-calibrator

# Run calibration, note the device ID and parameters
xinput_calibrator
```

Add the calibration to `~/.config/labwc/labwc.conf` or `/etc/X11/xorg.conf.d/`
as appropriate for your display server.

## USB Barcode Scanner

The USB barcode scanner works as a HID keyboard device — it types scanned
codes followed by an Enter keypress. No driver configuration is needed.

On the React frontend, the search input auto-focuses on page load and
will capture barcode input immediately. After a touch on another element,
tap the search field again to re-focus.

## Auto-Refresh on Wake

The React app polls the SSE endpoint every 30 seconds for real-time
updates. When the Pi wakes from sleep, the next poll will immediately
sync the UI.

The kiosk service has `Restart=always` and `RestartSec=10`, so Chromium
will restart within 10 seconds of any crash or power cycle.

## Touch Gestures

Chromium is launched with `--touch-events=enabled` and `--enable-pinch`
for native touch gesture support:
- **Tap** — click/submit
- **Two-finger scroll** — page scrolling
- **Pinch** — zoom (disabled in kiosk mode by default; enable if needed)

## Troubleshooting

### Services not starting
```bash
sudo systemctl status extrudex
sudo systemctl status extrudex-kiosk
docker compose -f docker-compose.dev.yml logs
```

### Kiosk shows blank page
- Ensure Docker stack is running: `docker compose ps`
- Check nginx is serving the React build: `curl http://localhost:5081`
- Check Chromium logs: `journalctl -u extrudex-kiosk -n 50`

### Barcode not working
- Verify scanner is in HID keyboard mode (most USB scanners default to this)
- Open a text field and scan — you should see digits appear
- Check with `dmesg | grep -i usb` for device enumeration

### PostgreSQL connection refused
```bash
docker compose -f docker-compose.dev.yml restart extrudex-db
# Wait 15 seconds, then check health
curl http://localhost:5080/health
```

## Architecture

```
┌──────────────────────────────────────────────┐
│  Pi 5 (Raspberry Pi OS 64-bit)               │
│                                              │
│  ┌─────────────┐  ┌──────────┐  ┌─────────┐ │
│  │ Chromium    │  │  Nginx   │  │  Go     │ │
│  │ Kiosk       │→│  (React) │→│  API    │ │
│  │ :5081       │  │  :5080   │  │  :8080  │ │
│  └─────────────┘  └──────────┘  └────┬────┘ │
│                                       │      │
│                              ┌────────▼────┐ │
│                              │  PostgreSQL │ │
│                              │  :5432      │ │
│                              └─────────────┘ │
│                                              │
│  ┌──────────┐                                │
│  │  USB     │                                │
│  │ Scanner  │ → HID keyboard → Browser       │
│  └──────────┘                                │
└──────────────────────────────────────────────┘
```