hex-bot
a1d47f2536
All checks were successful
Dev Build / build-test (pull_request) Successful in 1m22s
169 lines
5.3 KiB
Markdown
169 lines
5.3 KiB
Markdown
# 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 │
|
|
│ └──────────┘ │
|
|
└──────────────────────────────────────────────┘
|
|
```
|