Ossuary Pi

The ultimate kiosk system for Raspberry Pi
Built for LumenCanvas with WiFi failover, WebGPU support, and seamless configuration.

Features • Quick Start • Pre-Built Image • Manual Setup • Configuration • Troubleshooting

Features

Automatic WiFi failover — Falls back to AP mode when no known network is available
First-run welcome page — Shows setup instructions on the Pi's display until configured
LumenCanvas first-class support — WebGPU enabled, kiosk optimized, refresh behaviors built-in
Captive portal configuration — Configure WiFi and startup commands from any device
Always-accessible control panel — Web UI available at hostname.local:8081 when connected
Connection-aware behaviors — Auto-refresh on reconnection, scheduled refreshes, connection monitoring
Process management — Keeps your kiosk app running with automatic restart on crash
Chromium kiosk mode — Pre-configured flags for password-store, crash recovery, and error suppression

Requirements

Raspberry Pi 4 or 5 (64-bit recommended)
Raspberry Pi OS Bookworm (2024) or Trixie (2025+)
MicroSD card (16GB+ recommended)
WiFi connectivity
Display connected for kiosk mode

Quick Start

Option A: Pre-Built Image (Recommended)

Download our pre-built image with Ossuary pre-installed — no manual installation required.

Option B: Manual Install

If you already have a Pi with Raspberry Pi OS and SSH access:

git clone https://github.com/lumencanvas/ossuary-pi.git
cd ossuary-pi
sudo ./install.sh

The installer will configure everything and reboot. After reboot, access the control panel at http://your-pi-hostname.local:8081.

Pre-Built Image Setup

The easiest way to get started — a complete Raspberry Pi OS image with Ossuary pre-installed.

Step 1: Download the Image

Download the latest release:

64-bit (Pi 4/5): ossuary-pi-arm64.img.zip
32-bit (Pi 3/Zero 2 W): ossuary-pi-armhf.img.zip
All Releases: GitHub Releases

Step 2: Flash with Raspberry Pi Imager

Download and install Raspberry Pi Imager if you haven't already
Open Raspberry Pi Imager and configure:

Setting Selection

Device Your Raspberry Pi model (Pi 4, Pi 5, etc.)

Operating System Scroll down → Use custom → Select the downloaded .img.zip file

Storage Your SD card
Click "Next" — Pi Imager will ask if you want to customize settings
Click "Edit Settings" to configure:

General tab:
- ✅ Set hostname: ossuary (or your preferred name)
- ✅ Set username and password: pi / your-password
- ✅ Configure wireless LAN: Enter your WiFi name and password
- ✅ Set locale settings: Your timezone and keyboard layout
Services tab:
- ✅ Enable SSH: Use password authentication
Click "Save" then "Yes" to apply settings
Click "Yes" to confirm and write the image

⏱️ Writing takes 5-15 minutes depending on your SD card speed.

Step 3: First Boot

Insert the SD card into your Raspberry Pi
Connect a display (HDMI) and power on
Wait 1-2 minutes for first boot to complete

What you'll see:

The Pi boots and shows a welcome page with setup instructions
If you configured WiFi in Pi Imager, it will connect automatically
The control panel becomes available at http://your-hostname.local:8081

Step 4: Access the Control Panel

Once booted, open a browser on any device connected to the same network:

http://ossuary.local:8081

(Replace ossuary with your chosen hostname)

From the control panel you can:

Select a preset (LumenCanvas, Web Kiosk, Custom)
Configure the startup command
Manage WiFi networks
Set up scheduled refreshes

If WiFi Wasn't Configured

If you didn't set up WiFi in Pi Imager, or need to change networks:

The Pi will broadcast a "Ossuary-Setup" WiFi network
Connect your phone/laptop to this network
A captive portal opens (or visit http://192.168.42.1)
Select your WiFi network and enter the password
The Pi connects and your kiosk starts

Full Setup Guide (Manual Installation)

Step 1: Prepare the SD Card

Download Raspberry Pi Imager from raspberrypi.com/software
Open Raspberry Pi Imager and select:
- Device: Your Raspberry Pi model (Pi 4, Pi 5, etc.)
- OS: Raspberry Pi OS (64-bit) — under "Raspberry Pi OS (other)"
- Storage: Your SD card
Click the gear icon (or "Edit Settings") to configure:
- Hostname: Choose a name (e.g., ossuary-kiosk)
- Username/Password: Set your login credentials
- WiFi: Enter your network name and password
- SSH: Enable SSH with password authentication
- Locale: Set your timezone and keyboard layout
Write the image to the SD card

For detailed instructions, see the official Raspberry Pi documentation.

Step 2: Connect via SSH

Insert the SD card into your Pi and power it on. Wait 1-2 minutes for first boot.

On macOS/Linux — Open Terminal:

ssh pi@your-hostname.local
# or use the IP address
ssh pi@192.168.1.xxx

On Windows — Use PuTTY or Windows Terminal:

ssh pi@your-hostname.local

Can't find your Pi? Check your router's connected devices or use ping your-hostname.local.

Step 3: Update and Configure the System

sudo apt-get update && sudo apt-get upgrade -y

Expand the filesystem (if your SD card shows less space than expected):

sudo raspi-config

Advanced Options > Expand Filesystem — Uses the full SD card
Finish and reboot when prompted

After reboot, configure additional settings:

sudo raspi-config

System Options > Boot / Auto Login — Select "Desktop Autologin"
Display Options > Screen Blanking — Disable screen blanking
Finish and reboot if prompted

Note: Raspberry Pi OS usually auto-expands the filesystem on first boot, but check with df -h if unsure.

Step 4: Install Ossuary

git clone https://github.com/lumencanvas/ossuary-pi.git
cd ossuary-pi
sudo ./install.sh

The installer will:

Install required packages (NetworkManager, Python, Chromium, etc.)
Download and configure Balena WiFi Connect
Set up all systemd services
Configure auto-login for kiosk mode
Reboot automatically when complete

The installation runs in the background if you're connected via SSH, so you won't lose progress if disconnected.

Step 5: Configure Your Kiosk

After reboot, access the control panel:

URL: http://your-hostname.local:8081
Example: http://ossuary-kiosk.local:8081

Select a preset or enter a custom command:

How It Works

First Boot (Fresh Install)

Pi boots and displays the welcome page with setup instructions
Connect your phone/laptop to the "Ossuary-Setup" WiFi network
A captive portal opens automatically (or visit http://192.168.42.1)
Configure your WiFi network and startup command
Pi connects to WiFi and runs your configured command

Normal Operation

On boot, Ossuary tries to connect to saved WiFi networks
If connected: runs your startup command (Chromium kiosk, script, etc.)
If disconnected: broadcasts "Ossuary-Setup" AP for reconfiguration
Control panel always available at http://hostname.local:8081

Connection Events

When configured, Ossuary can:

On connection lost: Show overlay, pause, or continue
On connection regained: Refresh the page automatically
On schedule: Refresh at configured intervals

Configuration

Web Control Panel

Access at http://your-pi-hostname.local:8081 when connected to the same network.

Features:

View system status and network info
Configure startup command
Set up connection behaviors
Schedule automatic refreshes
Change WiFi networks
Reboot the system

Scheduling

Set up automatic refresh schedules:

Startup Command Examples

LumenCanvas Display:

chromium --kiosk https://lumencanvas.studio/canvas/YOUR_CANVAS_ID

Custom Web Kiosk:

chromium --kiosk https://your-website.com

Python Script:

python3 /home/pi/my_display_script.py

Node.js App:

node /home/pi/app/server.js

Note: Chromium commands are automatically enhanced with kiosk flags (--password-store=basic, --noerrdialogs, --disable-infobars, WebGPU flags, etc.)

Configuration File

Stored at /etc/ossuary/config.json:

{
  "startup_command": "chromium --kiosk https://lumencanvas.studio/canvas/abc123",
  "saved_networks": [
    {"ssid": "MyNetwork", "password": "..."}
  ],
  "behaviors": {
    "on_connection_lost": {"action": "show_overlay"},
    "on_connection_regained": {"action": "refresh_page"},
    "scheduled_refresh": {"enabled": true, "interval_minutes": 60}
  }
}

Services

Ossuary runs several systemd services:

Service	Description	Port
`wifi-connect`	Balena WiFi Connect (AP mode)	8080 (in AP)
`wifi-connect-manager`	Manages WiFi/AP switching	—
`ossuary-web`	Web configuration server	8081
`ossuary-startup`	Process manager for user command	—
`ossuary-connection-monitor`	Monitors connectivity & triggers behaviors	—
`captive-portal-proxy`	Handles captive portal detection	80

Check Status

./check-status.sh
# or
sudo systemctl status ossuary-startup ossuary-web wifi-connect-manager

View Logs

# All services
journalctl -u ossuary-startup -u ossuary-web -u wifi-connect -f

# Just the startup command
cat /var/log/ossuary-process.log

Troubleshooting

Welcome page stuck / AP doesn't appear

# Check WiFi Connect manager
sudo systemctl status wifi-connect-manager
sudo journalctl -u wifi-connect-manager -n 50

# Force AP mode
sudo systemctl restart wifi-connect-manager

Startup command not running

# Check process manager
sudo systemctl status ossuary-startup
cat /var/log/ossuary-process.log

# Restart it
sudo systemctl restart ossuary-startup

Web UI not accessible

# Check config server
sudo systemctl status ossuary-web
sudo journalctl -u ossuary-web -n 50

# Restart it
sudo systemctl restart ossuary-web

Chromium crashes or shows prompts

The process manager automatically:

Clears crash state before launch
Adds --password-store=basic to prevent keyring prompts
Adds --disable-session-crashed-bubble to prevent restore prompts

If issues persist, check: /home/pi/.config/chromium/Default/Preferences

Uninstall

sudo /opt/ossuary/uninstall.sh

This removes all Ossuary services, scripts, and configuration while preserving NetworkManager settings.

File Locations

Path	Description
`/opt/ossuary/`	Installation directory
`/opt/ossuary/custom-ui/`	Web UI files
`/etc/ossuary/config.json`	Configuration
`/var/log/ossuary-process.log`	Process manager log
`/run/ossuary/`	Runtime PID files

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    OSSUARY PI SYSTEM                        │
├─────────────────────────────────────────────────────────────┤
│  WiFi Connect Manager                                       │
│  └── Decides when to enable AP mode vs normal WiFi          │
├─────────────────────────────────────────────────────────────┤
│  Process Manager                                            │
│  ├── Shows welcome page on first run                        │
│  ├── Runs configured startup command                        │
│  ├── Auto-restarts on crash                                 │
│  └── Enhances Chromium with kiosk flags                     │
├─────────────────────────────────────────────────────────────┤
│  Connection Monitor                                         │
│  ├── Monitors network connectivity                          │
│  ├── Triggers refresh on reconnection                       │
│  └── Handles scheduled refreshes                            │
├─────────────────────────────────────────────────────────────┤
│  Config Server (port 8081)                                  │
│  ├── Web UI for configuration                               │
│  ├── REST API for settings                                  │
│  └── WiFi network management                                │
└─────────────────────────────────────────────────────────────┘

Documentation

User Guide — Detailed usage instructions
Technical Reference — API endpoints, file formats
Troubleshooting — Common issues and solutions
WiFi Connect Flags — Chromium flag reference

Contributing

Contributions welcome! Please keep the codebase minimal and focused.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 40 Commits
.github/workflows		.github/workflows
custom-ui		custom-ui
docs		docs
screenshots		screenshots
scripts		scripts
stage-ossuary		stage-ossuary
.gitignore		.gitignore
HANDOFF.md		HANDOFF.md
MULTI_PROCESS_PLAN.md		MULTI_PROCESS_PLAN.md
PI_GEN_BUILD_ISSUE.md		PI_GEN_BUILD_ISSUE.md
README.md		README.md
TROUBLESHOOTING.md		TROUBLESHOOTING.md
check-status.sh		check-status.sh
install.sh		install.sh
uninstall.sh		uninstall.sh

Setting	Selection
Device	Your Raspberry Pi model (Pi 4, Pi 5, etc.)
Operating System	Scroll down → Use custom → Select the downloaded `.img.zip` file
Storage	Your SD card

Folders and files

Latest commit

History

Repository files navigation

Ossuary Pi

Features

Requirements

Quick Start

Pre-Built Image Setup

Step 1: Download the Image

Step 2: Flash with Raspberry Pi Imager

Step 3: First Boot

Step 4: Access the Control Panel

If WiFi Wasn't Configured

Full Setup Guide (Manual Installation)

Step 1: Prepare the SD Card

Step 2: Connect via SSH

Step 3: Update and Configure the System

Step 4: Install Ossuary

Step 5: Configure Your Kiosk

How It Works

First Boot (Fresh Install)

Normal Operation

Connection Events

Configuration

Web Control Panel

Scheduling

Startup Command Examples

Configuration File

Services

Check Status

View Logs

Troubleshooting

Welcome page stuck / AP doesn't appear

Startup command not running

Web UI not accessible

Chromium crashes or shows prompts

Uninstall

File Locations

Architecture

Documentation

Contributing

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages