Raspberry Pi Setup

Overview

On Raspberry Pi, DisplayGrid uses Chromium in kiosk mode rather than the standalone Electron app. This gives excellent performance on ARM hardware with no extra installation — Chromium ships with Raspberry Pi OS by default.

The architecture is simple:

• Server machine (any PC, Mac, or Linux box): runs the DisplayGrid Server App, which hosts the dashboard and WebSocket server.
• Raspberry Pi: boots straight into Chromium pointing at your server, displaying your signage content fullscreen.

Requirements

• Raspberry Pi 4B (2 GB RAM minimum) or Raspberry Pi 5
• Raspberry Pi OS (64-bit) — Bookworm or later recommended
• MicroSD card (16 GB or larger, Class 10 / A1)
• HDMI display and power supply
• Network connection (Ethernet recommended for reliability)

OS setup

Flash Raspberry Pi OS Lite (64-bit) or the full desktop image using Raspberry Pi Imager. The Lite image uses fewer resources and is recommended for dedicated kiosks.

During imaging, click the settings gear and configure:

• Hostname (e.g. displaygrid-kiosk)
• Wi-Fi credentials (or use Ethernet)
• Enable SSH for remote management
• Set username/password

After first boot, update the system:

sudo apt update && sudo apt upgrade -y

Install Chromium and any missing dependencies:

sudo apt install -y chromium-browser unclutter

Auto-login to desktop

The Pi needs to log in automatically so the kiosk can start without a keyboard.

Using raspi-config (easiest)

sudo raspi-config

Navigate to System Options → Boot / Auto Login → Desktop Autologin and confirm.

Using the Lite image (console autologin + X server)

Install a minimal X server:

sudo apt install -y --no-install-recommends xserver-xorg x11-xserver-utils openbox

Enable console autologin:

sudo raspi-config nonint do_boot_behaviour B2

Kiosk autostart

Replace 192.168.1.10:3000 with your server's actual IP and port throughout.

Raspberry Pi OS Desktop (LXDE / Wayland)

Edit the LXDE autostart file:

mkdir -p ~/.config/lxsession/LXDE-pi
nano ~/.config/lxsession/LXDE-pi/autostart

Add these lines:

@xset s off
@xset -dpms
@xset s noblank
@chromium-browser \
  --kiosk \
  --noerrdialogs \
  --disable-infobars \
  --disable-session-crashed-bubble \
  --autoplay-policy=no-user-gesture-required \
  --disable-features=TranslateUI \
  http://192.168.1.10:3000

Minimal / headless (Openbox + systemd)

Create an Openbox autostart:

mkdir -p ~/.config/openbox
nano ~/.config/openbox/autostart

xset s off
xset -dpms
xset s noblank
chromium-browser \
  --kiosk \
  --noerrdialogs \
  --disable-infobars \
  --disable-session-crashed-bubble \
  --autoplay-policy=no-user-gesture-required \
  http://192.168.1.10:3000 &

Create a systemd service to start X on boot at ~/.config/systemd/user/kiosk.service:

[Unit]
Description=DisplayGrid Kiosk
After=network-online.target
Wants=network-online.target

[Service]
Environment=DISPLAY=:0
ExecStartPre=/bin/sleep 3
ExecStart=startx /usr/bin/openbox-session
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target

systemctl --user enable kiosk
systemctl --user start kiosk

Hide the mouse cursor

Add unclutter to your autostart so the cursor disappears after 1 second of inactivity:

# In your autostart file, add:
@unclutter -idle 1 -root

Or if using Openbox:

unclutter -idle 1 -root &

Disable screensaver & blanking

The xset commands in the autostart above handle this. If you're still getting a blank screen, also edit /etc/lightdm/lightdm.conf (if using LightDM) and add:

[Seat:*]
xserver-command=X -s 0 -dpms

For Raspberry Pi OS Bookworm with Wayland (labwc), disable the compositor screensaver:

sudo nano /etc/xdg/labwc/rc.xml

Set <screenSaverTimeout>0</screenSaverTimeout> inside the <core> block.

Auto-restart on crash

Add a Chromium crash watchdog by wrapping the browser in a loop inside your autostart:

# chromium-watchdog.sh
#!/bin/bash
while true; do
  chromium-browser \
    --kiosk \
    --noerrdialogs \
    --disable-infobars \
    --autoplay-policy=no-user-gesture-required \
    http://192.168.1.10:3000
  sleep 2
done

chmod +x ~/chromium-watchdog.sh

Then in your autostart, call the script instead of Chromium directly:

@bash /home/pi/chromium-watchdog.sh

Tips & troubleshooting

Pi shows "Connection refused" on boot

The Pi is booting faster than the server. Add a short delay before Chromium launches:

# At the top of your autostart:
@sleep 10

Or use the Wants=network-online.target in your systemd unit to wait for the network.

Screen is rotated

Add to /boot/config.txt (or /boot/firmware/config.txt on Bookworm):

# 0 = normal, 1 = 90°, 2 = 180°, 3 = 270°
display_rotate=1

4K display runs slowly

In /boot/firmware/config.txt, limit the framebuffer and enable hardware acceleration:

dtoverlay=vc4-kms-v3d
max_framebuffers=2

On Pi 4, also try forcing 1080p output if the display supports it — full 4K decoding is CPU-heavy.

Chromium shows "Restore pages?" dialog

Add --disable-session-crashed-bubble and --restore-last-session flags, or delete the Chromium profile before launch:

rm -f ~/.config/chromium/Default/Preferences
rm -f ~/.config/chromium/SingletonLock

Use the screen token for zero-touch setup

Append the screen token as a URL parameter so the Pi boots straight into the player without showing the token entry screen:

http://192.168.1.10:3000/display?token=YOUR_SCREEN_TOKEN

Get the token from the dashboard: Screens → your screen → key icon → Copy token.