Setting up a TV Display involves preparing a Raspberry Pi to run in "Kiosk Mode"—automatically booting into our full-screen TV application.
We use Tailscale to ensure you can securely manage these devices from anywhere without needing complex network configuration.
Quick facts
Start here
- Use Raspberry Pi Imager to pre-configure Wi-Fi and SSH before you even plug in the Pi.
- Tailscale provides a secure "mesh VPN" so you can SSH into your TVs even from a different network.
- The setup script handles all the heavy lifting for Chromium kiosk mode and auto-refresh.
Step 1: Flash Raspberry Pi OS
Download and install the Raspberry Pi Imager on your computer.
1. Select Device: Choose your Raspberry Pi model (e.g., Raspberry Pi 4 or 5).
2. Select OS: Choose Raspberry Pi OS (64-bit) (the Desktop version is recommended for the best browser performance).
3. Select Storage: Plug in your microSD card and select it.
Step 2: OS Customization (Crucial)
After clicking "Next", a "Use OS customisation?" dialog will appear. Click Edit Settings.
Under the General tab:
- Set hostname: Give it a unique name (e.g., tv-menu-left).
- Set username and password: Create a manager account (e.g., admin).
- Configure wireless LAN: Enter your Wi-Fi SSID and password so the Pi connects immediately.
- Set locale settings: Ensure the time zone matches your location.
Under the Services tab:
- Enable SSH: Select Allow public-key authentication only for maximum security (or password if you haven't set up keys yet).
Step 3: Install Tailscale for Remote Access
Once the Pi boots and you have SSH access (or a keyboard/monitor), install Tailscale by running this command in the terminal:
`bash
curl -fsSL https://tailscale.com/install.sh | sh
`
After installation, authenticate the device:
`bash
sudo tailscale up
`
Follow the link provided to log in. Once authenticated, the Pi will appear in your Tailscale dashboard with its own stable private IP.
Step 4: Run the TV Display Setup Script
Now, run the kiosk installation script. You can find your specific command on the TV Displays page by clicking "Copy Pi Script" next to a setup code.
The command looks like this:
`bash
curl -sSL https://raw.githubusercontent.com/sgerner/tv-kiosk/main/install-pi-display.sh | bash -s -- --code YOUR_CODE --location YOUR_ID
`
This script will:
- Install Chromium and necessary dependencies.
- Configure the system to boot directly into the TV app.
- Disable screen sleeping and mouse cursors.
Step 5: Verify and Manage
Reboot the Pi. It should now automatically open to the TV setup screen or the live menu.
In the Manager UI, you will see the device appear under "Registered Displays".
You can now use Remote Actions to Refresh, Clear Cache, or Identify the device from your browser.