Skip to main content

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​

Standard unit plan​

UnitHostnameDepartmentTypical locationTypical assets
Pi 1ihr-tv-1DispatchDispatch office TVDispatch dashboard, yard status
Pi 2ihr-tv-2OperationsOperations / shop-floor TVOperations dashboard, POD/workload views
Pi 3ihr-tv-3EngineeringEngineering / IT displayEngineering dashboard, system status
Pi 4ihr-tv-4Break Room / GeneralBreak room TVGeneral 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:

ItemRecommended specNotes
Raspberry PiRaspberry Pi 4, 4GB RAMPi 4 has enough memory and browser performance for Chromium kiosk mode.
SD card32GB Class 10 or fasterSanDisk Endurance or equivalent is preferred for reliability.
Power supplyOfficial Raspberry Pi USB-C PSU, 5V/3AUndervoltage causes random kiosk crashes. Use the official supply where possible.
HDMI cableMicro HDMI to HDMIPi 4 uses micro HDMI. Use HDMI0, the port closest to USB-C power.
CasePi 4 case with fan or heatsinksChromium and video playback can run warm.
NetworkEthernet preferred, Wi-Fi supportedEthernet is more stable for always-on displays.
TV / monitorAny HDMI displaySet the TV to the correct HDMI input and disable aggressive sleep mode if possible.
Optional labelPrinted hostname/location labelLabel 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​

ComponentPurpose
setup.shMaster install script. Installs packages, copies scripts, installs service/cron entries.
register.shRegisters the Pi with the Iron Horse API and stores the device UUID.
heartbeat.shSends online heartbeat status to the API every 60 seconds.
config-poll.shDownloads the current asset queue/config from the API every 5 minutes.
kiosk-launch.shStarts the local renderer and launches Chromium in kiosk mode.
renderer/server.jsLocal Node.js server used by Chromium. Serves the current config and display UI.
pi-dashboard.servicesystemd service that starts the kiosk on boot.

Files on the Pi​

PathPurpose
/opt/pi-dashboard/Installed dashboard scripts and renderer.
/etc/pi-dashboard/device_idDevice UUID assigned by the API.
/etc/pi-dashboard/current-config.jsonCached display queue/config.
/etc/pi-dashboard/reload-triggerMarker file touched when config changes.
/var/log/pi-dashboard-heartbeat.logHeartbeat logs.
/var/log/pi-dashboard-config.logConfig polling logs.
/var/log/pi-dashboard-renderer.logLocal renderer logs.

API endpoints used by the Pi client​

ActionMethodEndpoint
Register devicePOST/api/pi-devices/register
HeartbeatPUT/api/pi-devices/:id/heartbeat
Get configGET/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:

  1. Insert the SD card.
  2. Open Raspberry Pi Imager.
  3. Choose Raspberry Pi 4 as the device.
  4. Choose Raspberry Pi OS Lite (64-bit).
  5. Choose the SD card as storage.
  6. Write and verify.
  7. Eject and reinsert the SD card so the bootfs partition 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​

  1. Insert the SD card into the Pi.
  2. Connect the micro HDMI cable to HDMI0, the port closest to USB-C power.
  3. Connect Ethernet if available.
  4. Connect USB-C power last.
  5. Wait 5-10 minutes for first boot.
  6. 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:

  1. Open https://tools.ihrailsoftware.com/pi-manager.
  2. Select the device.
  3. Click edit.
  4. Correct the display name or department.
  5. Save.
  6. 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.

  1. Open https://tools.ihrailsoftware.com/pi-manager.
  2. Select the target device in the Devices panel.
  3. Confirm the device is online or was recently online.
  4. Add an asset:
    • choose URL, Image, or Video.
    • 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.
  5. Set the display duration.
  6. Save the asset.
  7. Queue the asset for the selected device.
  8. Drag/reorder the queue as needed.
  9. Wait up to 5 minutes for the Pi to poll config.
  10. 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:

  1. Make it public/no-auth if it must run unattended on a TV.
  2. Do not expose secrets, private tokens, write actions, or admin controls.
  3. Use large typography readable from across the room.
  4. Use dark/high-contrast styling for TVs.
  5. Include Iron Horse branding and the department name.
  6. Include a clock or last-updated indicator.
  7. Auto-refresh or poll data on a safe interval.
  8. Fail gracefully if an API call errors.
  9. Avoid requiring keyboard, mouse, login, or popups.
  10. Test at 1920×1080 resolution.
  11. 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-1 through /tv/dept-4 load 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​

  1. Confirm the Pi has network access.
  2. Confirm the API is reachable:
curl https://api.ihrailsoftware.com/api/pi-devices
  1. Check the device ID:
cat /etc/pi-dashboard/device_id
  1. Check registration/setup logs:
cat /var/log/pi-dashboard-setup.log
journalctl -u pi-dashboard -n 100
  1. 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​

  1. Flash Pi OS Lite 64-bit to SD card.
  2. Run flash-config.sh with hostname, department, Wi-Fi, and optional Tailscale key.
  3. Boot the Pi with HDMI0 connected.
  4. Wait for automatic setup and reboot.
  5. Confirm pi-dashboard.service is running.
  6. Confirm device appears in Pi Manager.
  7. Assign at least one URL/image/video asset.
  8. Wait for config polling or run sudo /opt/pi-dashboard/config-poll.sh.
  9. Confirm the TV displays the assigned content.
  10. Label the Pi and document its location.