Raspberry Pi TV Displays
The Iron Horse Raspberry Pi TV display system turns shop-floor televisions into centrally managed operational dashboards. Each TV is driven by a Raspberry Pi kiosk client. The Pi registers with the Iron Horse API, checks in with heartbeats, downloads its assigned display queue, and launches Chromium in fullscreen kiosk mode.
The system is designed so operations staff do not need to touch Linux once a Pi is installed. Administrators manage what appears on each TV through Pi Manager / Dashman and the Pi automatically pulls the newest content.
What the system does
- Displays operational URLs, images, or videos on TVs around the facility.
- Lets admins centrally assign display assets to each Raspberry Pi.
- Keeps a device inventory of registered Pis, including online/offline status.
- Rotates through each Pi's queue by display order and duration.
- Supports department-specific dashboard pages such as Dispatch, Operations, Engineering, and General displays.
- Runs unattended after boot using
systemd, Chromium kiosk mode, and scheduled config polling. - Supports remote maintenance through Tailscale when the Pi is joined to the Iron Horse tailnet.
Main URLs
- Pi Manager: https://tools.ihrailsoftware.com/pi-manager
- Dashman: https://tools.ihrailsoftware.com/dashman
- Dispatch TV dashboard: https://dashboard.ihrailsoftware.com/tv/dept-1
- Yard Operations TV dashboard: https://dashboard.ihrailsoftware.com/tv/dept-2
- Engineering / IT TV dashboard: https://dashboard.ihrailsoftware.com/tv/dept-3
- General TV dashboard: https://dashboard.ihrailsoftware.com/tv/dept-4
Standard unit plan
| Unit | Hostname | Department | Typical location | Typical assets |
|---|---|---|---|---|
| Pi 1 | ihr-tv-1 | Dispatch | Dispatch office TV | Dispatch dashboard, yard status |
| Pi 2 | ihr-tv-2 | Operations | Operations / shop-floor TV | Operations dashboard, POD/workload views |
| Pi 3 | ihr-tv-3 | Engineering | Engineering / IT display | Engineering dashboard, system status |
| Pi 4 | ihr-tv-4 | Break Room / General | Break room TV | General announcements, scoreboard, leaderboards |
The department names can be changed in Pi Manager, but keep hostnames predictable. Predictable names make Tailscale SSH, DHCP troubleshooting, and physical labeling easier.
Bill of materials
Per TV display:
| Item | Recommended spec | Notes |
|---|---|---|
| Raspberry Pi | Raspberry Pi 4, 4GB RAM | Pi 4 has enough memory and browser performance for Chromium kiosk mode. |
| SD card | 32GB Class 10 or faster | SanDisk Endurance or equivalent is preferred for reliability. |
| Power supply | Official Raspberry Pi USB-C PSU, 5V/3A | Undervoltage causes random kiosk crashes. Use the official supply where possible. |
| HDMI cable | Micro HDMI to HDMI | Pi 4 uses micro HDMI. Use HDMI0, the port closest to USB-C power. |
| Case | Pi 4 case with fan or heatsinks | Chromium and video playback can run warm. |
| Network | Ethernet preferred, Wi-Fi supported | Ethernet is more stable for always-on displays. |
| TV / monitor | Any HDMI display | Set the TV to the correct HDMI input and disable aggressive sleep mode if possible. |
| Optional label | Printed hostname/location label | Label both Pi case and power supply. |
For the initial deployment, the hardware set was:
- 4 Raspberry Pi 4 units, 4GB RAM
- 4 32GB SD cards
- 4 micro HDMI cables
- 4 cases with power supply and fan
Architecture
Pi boots
↓
systemd starts pi-dashboard.service
↓
register.sh registers device if needed
↓
kiosk-launch.sh starts local renderer and Chromium
↓
renderer/server.js serves localhost:8080
↓
Chromium displays localhost:8080 fullscreen
↓
heartbeat.sh checks in every 60 seconds
↓
config-poll.sh pulls queue/config every 5 minutes
Components on the Pi
| Component | Purpose |
|---|---|
setup.sh | Master install script. Installs packages, copies scripts, installs service/cron entries. |
register.sh | Registers the Pi with the Iron Horse API and stores the device UUID. |
heartbeat.sh | Sends online heartbeat status to the API every 60 seconds. |
config-poll.sh | Downloads the current asset queue/config from the API every 5 minutes. |
kiosk-launch.sh | Starts the local renderer and launches Chromium in kiosk mode. |
renderer/server.js | Local Node.js server used by Chromium. Serves the current config and display UI. |
pi-dashboard.service | systemd service that starts the kiosk on boot. |
Files on the Pi
| Path | Purpose |
|---|---|
/opt/pi-dashboard/ | Installed dashboard scripts and renderer. |
/etc/pi-dashboard/device_id | Device UUID assigned by the API. |
/etc/pi-dashboard/current-config.json | Cached display queue/config. |
/etc/pi-dashboard/reload-trigger | Marker file touched when config changes. |
/var/log/pi-dashboard-heartbeat.log | Heartbeat logs. |
/var/log/pi-dashboard-config.log | Config polling logs. |
/var/log/pi-dashboard-renderer.log | Local renderer logs. |
API endpoints used by the Pi client
| Action | Method | Endpoint |
|---|---|---|
| Register device | POST | /api/pi-devices/register |
| Heartbeat | PUT | /api/pi-devices/:id/heartbeat |
| Get config | GET | /api/pi-devices/:id/config |
The Pi client should only need these endpoints during normal operation. If a Pi stops appearing online, check heartbeat first, then config polling, then renderer/Chromium.
Source locations
Current operational source packages on Hopper:
/home/ubuntu/pi-dashboard-setup/
/home/ubuntu/pi-dashboard-client/
/home/ubuntu/pi-os-setup/
/home/ubuntu/ihr-playwright-tests/tests/tv-dashboards.spec.ts
Important files:
/home/ubuntu/pi-dashboard-setup/SETUP_GUIDE.md
/home/ubuntu/pi-dashboard-setup/flash-config.sh
/home/ubuntu/pi-dashboard-setup/firstrun.sh
/home/ubuntu/pi-dashboard-setup/cloud-init.yaml
/home/ubuntu/pi-dashboard-client/setup.sh
/home/ubuntu/pi-dashboard-client/register.sh
/home/ubuntu/pi-dashboard-client/heartbeat.sh
/home/ubuntu/pi-dashboard-client/config-poll.sh
/home/ubuntu/pi-dashboard-client/kiosk-launch.sh
/home/ubuntu/pi-dashboard-client/renderer/server.js
/home/ubuntu/pi-dashboard-client/systemd/pi-dashboard.service
/home/ubuntu/pi-os-setup/flash-sd.sh
/home/ubuntu/pi-os-setup/firstboot-setup.sh
Setup path A — automated SD card preparation
Use this path when preparing SD cards before sending Pis to the shop floor. This is the preferred setup method because Wi-Fi, SSH, first-boot install, and the Iron Horse setup script can be written before the card ever boots.
1. Flash Raspberry Pi OS
On a Mac or Linux workstation:
- Insert the SD card.
- Open Raspberry Pi Imager.
- Choose Raspberry Pi 4 as the device.
- Choose Raspberry Pi OS Lite (64-bit).
- Choose the SD card as storage.
- Write and verify.
- Eject and reinsert the SD card so the
bootfspartition remounts.
2. Run the flash configuration script
From the setup package:
sudo bash flash-config.sh \
--hostname ihr-tv-1 \
--dept "Dispatch" \
--wifi-ssid "IHT Wifi" \
--wifi-pass "REDACTED_WIFI_PASSWORD" \
--tailscale-key "REDACTED_TAILSCALE_AUTH_KEY"
Repeat for each Pi, changing the hostname and department:
sudo bash flash-config.sh --hostname ihr-tv-1 --dept "Dispatch" --wifi-ssid "IHT Wifi" --wifi-pass "REDACTED" --tailscale-key "REDACTED"
sudo bash flash-config.sh --hostname ihr-tv-2 --dept "Operations" --wifi-ssid "IHT Wifi" --wifi-pass "REDACTED" --tailscale-key "REDACTED"
sudo bash flash-config.sh --hostname ihr-tv-3 --dept "Engineering" --wifi-ssid "IHT Wifi" --wifi-pass "REDACTED" --tailscale-key "REDACTED"
sudo bash flash-config.sh --hostname ihr-tv-4 --dept "Break Room" --wifi-ssid "IHT Wifi" --wifi-pass "REDACTED" --tailscale-key "REDACTED"
Standard access values for the current Iron Horse TV Pis:
- SSH/local Linux user:
pi - Existing display password convention:
Safety2026! - Office Wi-Fi SSID:
IHT Wifi - Remote maintenance: Tailscale + SSH
- Raspberry Pi Connect: not part of the standard setup unless intentionally added later
The setup script creates the pi user for SSH/local maintenance. For existing shop-floor TV Pis, use the current display password convention above when SSH prompts for a password.
Do not commit or paste real Wi-Fi passwords, Tailscale auth keys, API tokens, or private keys into docs or chat. Use the values only at runtime.
3. First boot
- Insert the SD card into the Pi.
- Connect the micro HDMI cable to HDMI0, the port closest to USB-C power.
- Connect Ethernet if available.
- Connect USB-C power last.
- Wait 5-10 minutes for first boot.
- The Pi should update packages, install dependencies, run the Iron Horse setup script, register itself, install the service, and reboot into kiosk mode.
4. Verify the device
From another machine on the same network or Tailscale:
ssh pi@ihr-tv-1.local
# or
ssh pi@ihr-tv-1
# password: Safety2026!
systemctl status pi-dashboard
cat /etc/pi-dashboard/device_id
journalctl -u pi-dashboard -n 50
Open Pi Manager:
https://tools.ihrailsoftware.com/pi-manager
The device should appear within about 60 seconds of the first heartbeat.
Setup path B — manual install on an already-booted Pi
Use this path when a Pi is already booted and reachable over SSH.
SSH in first:
ssh pi@ihr-tv-1.local
# password: Safety2026!
1. Prepare the Pi
sudo apt-get update
sudo apt-get upgrade -y
sudo apt-get install -y nodejs npm chromium-browser unclutter x11-xserver-utils curl
Install Tailscale if remote access is required:
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up --authkey="REDACTED_TAILSCALE_AUTH_KEY" --accept-routes
2. Run the Iron Horse setup script
This is the full manual install path for an already-booted Pi. It installs/registers the TV dashboard software; run the Tailscale install/auth step above first if the Pi is not already on the tailnet.
curl -fsSL https://api.ihrailsoftware.com/pi-setup | sudo bash -s -- \
--name "Dispatch TV" \
--dept "Dispatch" \
--tailscale-key "REDACTED_TAILSCALE_AUTH_KEY"
Then reboot:
sudo reboot
3. Verify after reboot
systemctl status pi-dashboard
curl http://localhost:8080/health
cat /etc/pi-dashboard/device_id
journalctl -u pi-dashboard -f
Setup path C — hardware guide flash script
The hardware guide package also includes an OS flashing script:
/home/ubuntu/pi-os-setup/flash-sd.sh
Typical Mac flow:
diskutil list
sudo ./flash-sd.sh /dev/rdisk4
Replace /dev/rdisk4 with the actual SD card device. Never use the Mac internal disk. The script prompts for Iron Horse Wi-Fi details and writes the first-boot setup to the SD card.
With Tailscale:
sudo AUTH_KEY="REDACTED_TAILSCALE_AUTH_KEY" ./flash-sd.sh /dev/rdisk4
How the display dashboard works
The dashboard system separates device management from display content.
Device management
Pi Manager tracks the physical device:
- device UUID
- display name
- department
- online/offline status
- last heartbeat time
- assigned asset queue
A Pi is considered online when its heartbeat is recent. If heartbeat stops, the display may still be showing cached content, but Pi Manager should mark it offline after the configured window.
To correct a misspelled display name or department after setup, use the Pi Manager edit function rather than reflashing the SD card:
- Open https://tools.ihrailsoftware.com/pi-manager.
- Select the device.
- Click edit.
- Correct the display name or department.
- Save.
- Wait for the next config poll, or SSH into the Pi and force a refresh:
sudo /opt/pi-dashboard/config-poll.sh
sudo systemctl restart pi-dashboard
The display name in Pi Manager is separate from the Linux hostname. Only change the hostname if DNS/Tailscale/SSH naming is wrong.
Display content
Each Pi receives a queue of display assets. Assets can be:
- URL — a web page such as a dashboard route.
- Image — a JPG or PNG, shown fullscreen.
- Video — an MP4 or remote video URL, played fullscreen.
Each asset should include:
- type
- URL or uploaded media reference
- display order
- duration in seconds
- enabled/disabled state, if supported by the UI
The Pi stores the latest config in:
/etc/pi-dashboard/current-config.json
The local renderer reads that config and cycles through assets. If there is no config, the renderer shows an offline or unassigned splash so the TV does not appear broken.
Adding a new item to a TV display
Use Pi Manager unless you are debugging the backend directly.
- Open https://tools.ihrailsoftware.com/pi-manager.
- Select the target device in the Devices panel.
- Confirm the device is online or was recently online.
- Add an asset:
- choose
URL,Image, orVideo. - for a URL, paste the full route, such as
https://dashboard.ihrailsoftware.com/tv/dept-1. - for an image/video, upload or provide the approved hosted URL.
- choose
- Set the display duration.
- Save the asset.
- Queue the asset for the selected device.
- Drag/reorder the queue as needed.
- Wait up to 5 minutes for the Pi to poll config.
- To force immediate refresh, SSH into the Pi and run:
sudo /opt/pi-dashboard/config-poll.sh
sudo systemctl restart pi-dashboard
Use restart only when polling does not update the display. Normal queue changes should not require rebooting the Pi.
Adding a new department TV dashboard page
A department TV dashboard is just a public kiosk-safe page that can be assigned as a URL asset.
Recommended route pattern:
https://dashboard.ihrailsoftware.com/tv/dept-N
Checklist for a new TV dashboard page:
- Make it public/no-auth if it must run unattended on a TV.
- Do not expose secrets, private tokens, write actions, or admin controls.
- Use large typography readable from across the room.
- Use dark/high-contrast styling for TVs.
- Include Iron Horse branding and the department name.
- Include a clock or last-updated indicator.
- Auto-refresh or poll data on a safe interval.
- Fail gracefully if an API call errors.
- Avoid requiring keyboard, mouse, login, or popups.
- Test at 1920×1080 resolution.
- Add the URL as a Pi Manager asset and verify it in the actual kiosk path.
Existing Playwright coverage for the four department dashboards lives at:
/home/ubuntu/ihr-playwright-tests/tests/tv-dashboards.spec.ts
Those tests verify:
/tv/dept-1through/tv/dept-4load without login redirects.- A clock is visible.
- Iron Horse branding is visible.
- The department title is visible.
- Auto-refresh metadata is present.
- Each page has expected stat widgets.
- Dispatch calls
/api/dispatch/stats.
Remote access with Tailscale
Recommended Tailscale tag:
tag:ihr-tv
Example ACL shape:
{
"tagOwners": {
"tag:ihr-tv": ["autogroup:admin"]
},
"acls": [
{
"action": "accept",
"src": ["autogroup:admin"],
"dst": ["tag:ihr-tv:22"]
}
]
}
SSH examples:
ssh pi@ihr-tv-1
ssh pi@ihr-tv-2
ssh pi@ihr-tv-3
ssh pi@ihr-tv-4
Useful maintenance commands:
# Check kiosk service
systemctl status pi-dashboard
# Follow service logs
journalctl -u pi-dashboard -f
# Check recent service logs
journalctl -u pi-dashboard -n 50
# Check local renderer
curl http://localhost:8080/health
# Force config fetch
sudo /opt/pi-dashboard/config-poll.sh
# Restart kiosk
sudo systemctl restart pi-dashboard
# Heartbeat/config logs
tail -f /var/log/pi-dashboard-heartbeat.log
tail -f /var/log/pi-dashboard-config.log
tail -f /var/log/pi-dashboard-renderer.log
# Confirm registered device ID
cat /etc/pi-dashboard/device_id
Troubleshooting
Pi does not appear in Pi Manager
- Confirm the Pi has network access.
- Confirm the API is reachable:
curl https://api.ihrailsoftware.com/api/pi-devices
- Check the device ID:
cat /etc/pi-dashboard/device_id
- Check registration/setup logs:
cat /var/log/pi-dashboard-setup.log
journalctl -u pi-dashboard -n 100
- Re-run registration if needed:
sudo /opt/pi-dashboard/register.sh
TV shows a black screen
- Confirm the HDMI cable is plugged into HDMI0, the micro HDMI port closest to USB-C power.
- Confirm the TV input is correct.
- Confirm the Pi is powered and not undervoltage-throttled.
- SSH in and run:
systemctl status pi-dashboard
journalctl -u pi-dashboard -n 100
Kiosk browser does not launch
systemctl status lightdm
systemctl status pi-dashboard
cat /var/log/pi-dashboard-firstrun.log
sudo systemctl restart pi-dashboard
Config changes are not showing
sudo /opt/pi-dashboard/config-poll.sh
cat /etc/pi-dashboard/current-config.json
sudo systemctl restart pi-dashboard
Also confirm the Pi Manager queue is assigned to the correct device. A common operational mistake is adding an asset globally but not queueing it to the selected Pi.
Chromium crashes or freezes
sudo systemctl restart pi-dashboard
journalctl -u pi-dashboard -n 100
Check for heavy pages, oversized videos, unsupported codecs, or TVs sleeping/renegotiating HDMI.
SSH is refused
sudo systemctl enable ssh
sudo systemctl start ssh
If using Tailscale, confirm the Pi is on the tailnet and tagged as expected:
tailscale status
tailscale ip -4
Operational rules
- Treat each Pi as a display appliance. Do not use it for unrelated workloads.
- Prefer URL dashboards over uploading static screenshots, unless the content is intentionally static.
- Keep display pages read-only and safe for public shop-floor viewing.
- Keep secrets out of docs, Pi configs, display URLs, and screenshots.
- Use Tailscale or local LAN SSH for maintenance; do not expose Pi SSH to the public internet.
- Label physical Pis and power supplies with hostname and location.
- When replacing SD cards, delete stale devices from Pi Manager or clearly mark them retired.
- Verify changes on the actual TV path, not just in a desktop browser.
Quick start checklist
- Flash Pi OS Lite 64-bit to SD card.
- Run
flash-config.shwith hostname, department, Wi-Fi, and optional Tailscale key. - Boot the Pi with HDMI0 connected.
- Wait for automatic setup and reboot.
- Confirm
pi-dashboard.serviceis running. - Confirm device appears in Pi Manager.
- Assign at least one URL/image/video asset.
- Wait for config polling or run
sudo /opt/pi-dashboard/config-poll.sh. - Confirm the TV displays the assigned content.
- Label the Pi and document its location.