Set up a Raspberry Pi

A Raspberry Pi makes a capable, inexpensive signage player. A single setup script configures it to boot straight into STQRY Signage full screen, with no desktop, no cursor and no screen blanking.

What you need

• A Raspberry Pi 4 or 5 with at least 2 GB of RAM.

• A microSD card, 8 GB or larger.
• Raspberry Pi OS Lite (64-bit) — the Lite image, without a desktop.
• An HDMI cable and a screen.
• A network connection.
• SSH access to the Pi, or a keyboard and monitor for the initial setup.

The setup script installs a handful of packages — an X server, Chromium and a few supporting libraries — so allow a few minutes and a reasonable connection.

Step 1: Prepare the Pi

Write Raspberry Pi OS Lite (64-bit) to the microSD card using Raspberry Pi Imager.

In Imager's settings, before writing:

• Set a hostname you'll recognize.

• Enable SSH and set a username and password.
• Configure Wi-Fi if you're not using Ethernet.

Boot the Pi and connect to it over SSH.

Step 2: Run the setup script

Copy the setup script to the Pi and run it:

bash setup.sh

To set it up for a different user than the one you're logged in as:

bash setup.sh stqry

Contact us for the current script if you don't have it.

What the script does

• Installs Chromium and a minimal X environment.

• Configures auto-login on the console so the Pi boots without anyone typing a password.
• Writes a kiosk launch script that starts Chromium full screen, pointed at STQRY Signage.
• Disables screen blanking and the screen saver, and hides the mouse cursor.
• Starts the kiosk from the login profile, gated so that it only runs on the physical console — your SSH sessions are unaffected.
• Waits up to 30 seconds for the network before launching, so a Pi that boots faster than the router doesn't start with no connection.

It auto-detects the screen's resolution and falls back to 1920×1080 if it can't.

Step 3: Reboot

sudo reboot

The Pi boots to the console, logs itself in, starts X, and launches Chromium full screen into STQRY Signage. The provisioning screen appears with a screen code.

Step 4: Adopt the display

In STQRY Builder, go to Displays → Adopt display and type the screen code.

Then set the display's project, timezone, license and content. See Connect a display to your account.

Portrait mounting

Portrait is set on the Pi, not in Signage. On current Raspberry Pi OS the kiosk runs under X, so the rotation is applied with xrandr in the kiosk launch script — contact us for the exact line for your setup.

On older, non-KMS installations, /boot/firmware/config.txt accepts:

display_rotate=1

for 90° clockwise, or:

display_rotate=3

for 90° counter-clockwise.

Reboot after changing it. STQRY Signage follows whatever the Pi reports and locks nothing.

Other config.txt options worth knowing

For video-heavy content, give the GPU more memory:

gpu_mem=256

If the screen still blanks despite the script's settings, some displays respond to the console blanking timeout instead:

consoleblank=0

Reboot after any change to config.txt.

Opening the settings overlay

Attach a USB keyboard and press Esc, or click five times in the bottom-right corner if a mouse is attached. Both land on the PIN prompt. See Open the on-device settings overlay.

Maintenance over SSH

The kiosk only launches on the physical console, so you can SSH into a running signage Pi without disturbing it.

Restart the kiosk without rebooting:

sudo systemctl restart getty@tty1

Check the Pi's temperature — signage Pis in enclosures run hot:

vcgencmd measure_temp

Check free space:

df -h

Updates

The app runs from the network on a Pi, which makes it the only installed platform that picks up new versions without anyone touching it. That's a side effect of how the Pi setup works rather than a promise — if you need a Pi fleet pinned to a specific version, tell us.

Your content updates normally. See How updates reach your displays.

Practical notes

Power supply. Use the official Raspberry Pi supply. Under-voltage causes exactly the kind of intermittent, hard-to-diagnose faults you don't want in a wall-mounted sign — look for the lightning-bolt icon or vcgencmd get_throttled.

Cooling. A Pi 4 or 5 running video continuously in a sealed enclosure will throttle. Use a case with a heatsink, and check the temperature after it's been installed and running for an hour.

SD card quality. Signage writes little, but a cheap card will still fail eventually. Use a decent A2-rated card, and keep a spare written image.

Wired network. If you can run a cable, run a cable.

Troubleshooting

The Pi boots to a console login prompt and stops. Auto-login didn't configure. Re-run the setup script.

Chromium starts but shows an error page. The Pi reached the network but couldn't reach the app. Check DNS and any filtering proxy — see Regions and license keys for the hostnames to allow.

The screen goes black after a few minutes. Add consoleblank=0 to config.txt and reboot.

Content is rotated the wrong way. Set display_rotate in config.txt.

Content won't load. See Troubleshooting a display.

Next steps

• Quick start: from zero to content on screen

• Screen orientation and external HDMI displays
• Troubleshooting a display