Raspberry Pi Kiosk Mode

Transform a Raspberry Pi into a dedicated digital signage display running Liveposter in full-screen kiosk mode. Setting up is easier than you think! With the buildpi command, you get everything bundled and ready to deploy in just a few steps.

Quick Start (Recommended Method)

This is the easiest way to get Liveposter running on a Raspberry Pi. The buildpi command creates a complete, ready-to-deploy package with automated setup.

What You’ll Need

Hardware (~$95 total):

• Raspberry Pi 5 (4GB) - $60 (recommended for 4K@60Hz)
• Power Supply (27W USB-C) - $12
• microSD Card (32GB+) - $15
• HDMI Cable (micro HDMI to HDMI) - $8

Or Budget Option (~$70):

• Raspberry Pi 4 (2GB) - $35
• Same other components

Step 1: Build Your Package

On your development computer, create your kiosk package:

# Build your Liveposter content for Raspberry Pi
npx liveposter buildpi my-posters.json

This creates a dist-pi/ folder containing:

• ✓ Your Liveposter content (built and optimized)
• ✓ kiosk-setup.sh - Automated setup script
• ✓ SETUP-GUIDE.md - Comprehensive manual
• ✓ test-kiosk.html - Performance test page
• ✓ README.txt - Quick start instructions

Everything you need, bundled together! 🎉

Step 2: Prepare Your Raspberry Pi

1. Download Raspberry Pi Imager

2. Flash Raspberry Pi OS (64-bit) to your microSD card

   • Click the gear icon (⚙️) for settings
   • Set hostname (e.g., liveposter-kiosk)
   • Enable SSH (optional, for remote access)
   • Set username and password
   • Configure WiFi
   • Click Write

3. Boot your Raspberry Pi

   • Insert the SD card
   • Connect HDMI to your display
   • Connect power
   • Wait for first boot (1-2 minutes)

Step 3: Transfer Your Package

Choose your preferred method:

Option A: Using SCP (if SSH enabled)

scp -r dist-pi/* pi@raspberrypi.local:/home/pi/kiosk/

Option B: Using a USB Drive

1. Copy the entire dist-pi/ folder to a USB drive
2. Plug the USB into your Raspberry Pi
3. On the Pi, copy files from USB to /home/pi/kiosk/

Option C: Download Directly (if files are online)

# On the Raspberry Pi
wget https://your-site.com/dist-pi.zip
unzip dist-pi.zip -d /home/pi/kiosk/

Step 4: Run the Setup Script

On your Raspberry Pi:

cd /home/pi/kiosk
chmod +x kiosk-setup.sh
./kiosk-setup.sh

The script will:

• ✓ Install Chromium browser with GPU acceleration
• ✓ Configure 4K@60Hz HDMI output
• ✓ Setup auto-boot to fullscreen mode
• ✓ Configure Chromium to display your built content
• ✓ Hide cursor and disable screen blanking

Step 5: Reboot

sudo reboot

That’s it! Your Raspberry Pi will boot directly into fullscreen kiosk mode displaying your Liveposter content. 🥧✨

What The Setup Does

When you run kiosk-setup.sh, here’s what happens behind the scenes:

1. Updates System - Ensures all packages are up to date
2. Installs Chromium - Browser optimized for kiosk displays
3. Configures HDMI - Sets up 4K@60Hz output
4. Creates Autostart Script - Pi boots directly to your built content
5. Verifies Content - Checks that your index.html is in place
6. Hides Cursor - No mouse pointer visible on screen
7. Disables Screen Blanking - Display never sleeps
8. Optimizes Performance - GPU acceleration enabled

All fully automated! No manual configuration needed.

Updating Your Content

Need to change your content? It’s easy:

Method 1: Rebuild and Replace

# On your development computer, rebuild
npx liveposter buildpi updated-posters.json

# Transfer just the new content
scp dist-pi/index.html pi@raspberrypi.local:/home/pi/kiosk/
scp -r dist-pi/lib/* pi@raspberrypi.local:/home/pi/kiosk/lib/

# Refresh the browser (if you have SSH access)
ssh pi@raspberrypi.local "DISPLAY=:0 xdotool key F5"

Method 2: Full Replacement

# Transfer entire new package
scp -r dist-pi/* pi@raspberrypi.local:/home/pi/kiosk/

# Reboot the Pi
ssh pi@raspberrypi.local "sudo reboot"

That’s all there is to it!

Troubleshooting

Black Screen After Boot

Try this first:

# Check if the setup script completed successfully
ssh pi@raspberrypi.local
cat ~/.config/lxsession/LXDE-pi/autostart

If the file is empty:

• Re-run the setup script: cd /home/pi/kiosk && ./kiosk-setup.sh

Wrong Resolution

The setup script configures 4K@60Hz by default. For different resolutions:

# Edit the config
sudo nano /boot/firmware/config.txt

# For 1080p@60Hz, use:
hdmi_mode=82

# Save and reboot
sudo reboot

Cursor Still Visible

# Verify unclutter is installed
which unclutter

# Reinstall if needed
sudo apt-get install --reinstall unclutter
sudo reboot

Screen Blanking After a Few Minutes

# Check autostart configuration
cat ~/.config/lxsession/LXDE-pi/autostart | grep xset

# Should see:
# @xset s off
# @xset s noblank
# @xset -dpms

# If missing, re-run the setup script

Poor Performance / Choppy Animations

Check temperature:

vcgencmd measure_temp

If over 70°C, add active cooling (fan). Otherwise:

# Increase GPU memory
sudo nano /boot/firmware/config.txt
# Change to: gpu_mem=512
sudo reboot

Can’t Connect via SSH

# On the Pi (with keyboard/monitor), enable SSH:
sudo systemctl enable ssh
sudo systemctl start ssh

# Find your Pi's IP address
hostname -I

Creating Your Poster List

The buildpi command works with the same poster list format as the regular build command. Here’s an example optimized for kiosk displays:

{
  "buildConfig": {
    "template": "sequential",
    "title": "My Kiosk Display",
    "displayMode": "contain",
    "aspectRatio": "16/9"
  },
  "posters": [
    {
      "configPath": "specs/welcome.json",
      "name": "Welcome Screen"
    },
    {
      "configPath": "specs/announcements.json",
      "name": "Daily Announcements"
    },
    {
      "configPath": "specs/gallery.json",
      "name": "Photo Gallery"
    }
  ]
}

Tips for Kiosk Content:

• ✓ Use "template": "sequential" for better performance
• ✓ Set "displayMode": "contain" to avoid cropping
• ✓ Match "aspectRatio" to your display (usually “16/9”)
• ✓ Optimize images for your display resolution
• ✓ Keep total package size under 500MB for faster loading
• ✓ Test loop behavior to ensure seamless playback

Use Cases & Ideas

Running Liveposter on a Raspberry Pi is perfect for:

🏪 Retail & Business

• Store front displays
• Menu boards (restaurants, cafes)
• Price displays
• Promotional content rotation

🏢 Corporate

• Office dashboards
• Meeting room schedules
• Company announcements
• Reception area displays

🎨 Creative

• Art gallery exhibitions
• Photography portfolios
• Museum information displays
• Interactive installations

🏠 Home

• Family photo displays
• Smart home dashboards
• Calendar and weather displays
• Ambient art displays

📚 Education

• Classroom schedules
• Event calendars
• Student work showcases
• Library displays

Hardware Recommendations

Display Performance by Model

Model	Resolution	Animation Complexity	Expected FPS
Pi 5 (4GB+)	4K (3840×2160)	High (overlays, effects)	60 FPS
Pi 5 (4GB+)	1080p	High	60 FPS
Pi 4 (4GB)	4K	Medium	30-45 FPS
Pi 4 (4GB)	1080p	High	60 FPS
Pi 4 (2GB)	1080p	Medium	60 FPS

Recommended Accessories

For 24/7 Operation:

• Active cooling fan ($5-10)
• Quality case with ventilation ($10-15)
• High-endurance microSD card ($15-25)
• UPS/battery backup ($50-100) - prevents SD corruption from power loss

For Installation:

• VESA mount bracket ($5-15) - mount Pi behind display
• Cable management clips ($5)
• Power timer/smart plug ($15-30) - schedule on/off times

For Management:

• Wireless keyboard/mouse ($20-30) - for initial setup
• USB hub ($10) - if you need multiple USB devices

Best Practices

For Reliable 24/7 Operation

1. Use Quality Power Supply - Official Raspberry Pi PSU prevents undervoltage issues
2. Add Active Cooling - Keeps temperatures under 70°C
3. Monitor Temperature - Check regularly with vcgencmd measure_temp
4. Use Ethernet When Possible - More reliable than WiFi
5. Enable Watchdog - Auto-restart if system freezes (see Advanced section)
6. Regular Backups - Backup your SD card periodically
7. Update Regularly - Keep Raspberry Pi OS updated

For Best Performance

1. Optimize Images - Use correct resolution, compress without quality loss
2. Use Sequential Template - Better for many posters or large files
3. Increase GPU Memory - 512MB for Pi with 4GB+ RAM
4. Enable Hardware Acceleration - Automatically configured by setup script
5. Limit Complexity - On lower-end Pis, use simpler transitions
6. Test Before Deployment - Always test with the actual hardware first

For Easy Management

1. Use Static IP - Easier to find and SSH into your Pi
2. Enable SSH - Update content remotely without physical access
3. Document Your Setup - Keep notes on configuration for future reference
4. Label Your Devices - Helpful if managing multiple kiosks
5. Plan Content Updates - Schedule regular content refresh times

Advanced: Server-Based Approach

The buildpi method creates static files (recommended for most users). If you need dynamic content or server-side features, you can run the Liveposter server directly on the Pi.

When to Use Server Mode

• You need to update content without rebuilding
• You’re serving dynamic content
• You want to access the web interface remotely
• You need server-side image processing

Quick Server Setup

1. Install Node.js on your Raspberry Pi:

# Install Node.js 20 LTS
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verify
node --version  # Should show v20.x.x

2. Install Liveposter:

sudo npm install -g @liveposter/demo-server

3. Create your poster content:

mkdir -p ~/liveposter-content
cd ~/liveposter-content

# Add your poster.json and images here

4. Create systemd service:

sudo nano /etc/systemd/system/liveposter.service

Add:

[Unit]
Description=Liveposter Server
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=pi
WorkingDirectory=/home/pi/liveposter-content
Environment="PORT=3000"
ExecStart=/usr/bin/liveposter poster.json
Restart=on-failure

[Install]
WantedBy=multi-user.target

5. Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable liveposter.service
sudo systemctl start liveposter.service

6. Update autostart to point to server:

Edit ~/.config/lxsession/LXDE-pi/autostart and change the Chromium URL from:

file:///home/pi/kiosk/index.html

To:

http://localhost:3000

Pros of server mode:

• Live content updates without rebuilding
• Access web interface remotely
• Dynamic server-side features

Cons:

• More complex setup
• Requires Node.js on Pi
• Additional process overhead
• More troubleshooting if issues arise

For most users, the static buildpi approach is simpler and more reliable!

Network Configuration

Setting Up WiFi

During Initial Setup:

• Use Raspberry Pi Imager advanced settings (gear icon)
• Enter WiFi credentials before flashing

After Setup:

sudo raspi-config
# System Options → Wireless LAN

Using Static IP

Recommended for easier remote access:

sudo nano /etc/dhcpcd.conf

Add at the end:

interface wlan0
static ip_address=192.168.1.100/24
static routers=192.168.1.1
static domain_name_servers=192.168.1.1 8.8.8.8

Restart networking:

sudo systemctl restart dhcpcd

Now you can always access your Pi at 192.168.1.100!

Remote Access

SSH (for updates and troubleshooting):

ssh pi@192.168.1.100

File Transfer:

# Copy new content
scp new-content.html pi@192.168.1.100:/home/pi/kiosk/

# Sync entire directory
rsync -avz ./updated-content/ pi@192.168.1.100:/home/pi/kiosk/

FAQs

Q: Can I use my old Raspberry Pi 3? A: It will work, but performance may not be great. We recommend Pi 4 or 5 for smooth animations.

Q: What happens if power is lost? A: The Pi will automatically restart and boot back into kiosk mode. Use a UPS for critical displays to prevent SD card corruption.

Q: Can I schedule the display to turn off at night? A: Yes! Use a smart plug or power timer. The Pi will auto-start when power returns.

Q: How do I exit kiosk mode to access the Pi? A: Plug in a keyboard and press Alt+F4, or SSH into the Pi and stop the display service.

Q: Can I run multiple displays from one Pi? A: Pi 5 has dual HDMI outputs and can drive two displays, but they’ll show the same content.

Q: Do I need a keyboard/mouse permanently attached? A: No! Only needed for initial setup (or you can use SSH instead). Once configured, the Pi runs headlessly.

Q: How much power does it use? A: Raspberry Pi 5 uses 5-15W depending on load. Running 24/7 costs approximately $1-2/month in electricity.

Q: Can I use a USB drive instead of microSD? A: Yes! Pi 4 and 5 support USB boot. USB SSDs are faster and more durable than SD cards.

Next Steps

🎉 Congratulations! You now have a working Liveposter kiosk!

What to do next:

1. Customize your content - Create your own poster specifications
2. Optimize performance - Adjust settings for your specific display
3. Set up remote access - Enable SSH for easy updates
4. Plan content rotation - Schedule different content for different times
5. Add monitoring - Set up health checks if running 24/7

Explore more:

• Poster Spec Format - Learn all configuration options
• Animation Modes - Discover different animation styles
• Poster List Format - Create multi-poster displays

Get Help

Need assistance?

• 📖 Check the SETUP-GUIDE.md in your dist-pi/ folder for detailed troubleshooting
• 💬 Open an issue on GitHub
• 🌐 Visit the Raspberry Pi Forums

Share your setup!

We’d love to see what you create! Share your Liveposter kiosk displays in our showcase.

---

Built something awesome? Let us know!