Raspberry Pi Setup

Download the pre-built DisplayCache image for Raspberry Pi. This is a complete operating system image with everything pre-configured — no terminal commands, no manual setup.

File size is approximately 1.5 GB. The download is a compressed .img.gz file. You do not need to extract it — Raspberry Pi Imager handles that automatically.

Use Raspberry Pi Imager to write the image to your SD card. It is free, cross-platform, and handles decompression automatically.

1. Download and install Raspberry Pi Imager from raspberrypi.com/software. Available for Windows, macOS, and Linux.
2. Insert your SD card into your computer using a built-in card reader or USB adapter.
3. Open Raspberry Pi Imager and click Choose OS.
4. Scroll to the bottom and select Use custom. Browse to the .img.gz file you downloaded.
5. Click Choose Storage and select your SD card. Double-check you have selected the correct drive — this will erase everything on it.
6. Click Write. The process takes 5–10 minutes depending on your SD card speed.
7. When it finishes, safely eject the SD card from your computer.

Note: You do not need to configure any OS customization settings (hostname, WiFi, SSH) in the Imager. The DisplayCache image handles all of that automatically.

1. Insert the SD card into your Raspberry Pi.
2. Connect an HDMI cable from the Pi to your TV or display. Use the HDMI 0 port (closest to the USB-C power port) for best compatibility.
3. Connect ethernet if available. A wired connection is strongly recommended — especially on Pi 3 B+ (see Tested Hardware below).
4. Plug in the power supply. The Pi boots automatically: branded DisplayCache splash, then the kiosk takes over. First boot takes 1–2 minutes; subsequent boots about 30 seconds.

No ethernet? Use the WiFi setup hotspot.

If no ethernet is connected within 60 seconds of boot, the Pi automatically broadcasts a temporary setup network called DisplayCache-XXXX (random 4-digit suffix). To configure WiFi from your phone:

1. On your phone, connect to the DisplayCache-XXXX network. Password: displaycache.
2. A setup page opens automatically. If it doesn't, visit http://10.42.0.1.
3. Pick your home or office WiFi from the list, enter the password, tap Connect.
4. The phone will lose the hotspot connection — that's expected. The Pi is now joining your real WiFi.
5. After 30–60 seconds, the pairing code appears on the TV. If the hotspot reappears in your phone's WiFi list, the password was wrong — reconnect and try again.

Once the Pi finishes booting, a 6-character pairing code appears on screen. This code is unique to the device and refreshes every few minutes.

1. Open admin.displaycache.com in your browser and sign in.
2. Go to Devices in the sidebar.
3. Click + Pair Device (or Add Device).
4. Enter the 6-character code shown on the TV and click Pair.
5. Give the device a friendly name (e.g., "Lobby TV Left") and assign it to a location.

The device connects to your organization within seconds. The pairing code disappears and the screen shows a "Connected" confirmation.

Now that the device is paired, tell it what to display.

1. Add the device to a group (optional). Device groups let you target content to multiple screens at once (e.g., "Lobby Screens", "Classrooms").
2. Assign a playlist directly, or create a schedule that switches playlists at different times of day.
3. Save. The Pi downloads the assigned content immediately and begins playback within a minute or two, depending on how much content needs to be cached.

From this point on, any changes you make in the web admin are pushed to the Pi automatically. No need to touch the device again.

HDMI Ghost Display Emulator (~$10)

For Pis whose TV is powered off most of the day (overnight, weekends, summer break), the HDMI signal physically drops when the TV goes to standby. The Pi sees “no display attached,” the Wayland compositor stops drawing, and when the TV comes back on the slideshow may not return until the Pi reboots.

A 1920×1080 HDMI Ghost Display Emulator plugs into the Pi’s second micro-HDMI port (Pi 4/5 both have two) and emulates a connected display 24/7. The Pi always thinks a screen is attached, the compositor never sleeps, and the slideshow resumes the instant the TV powers back on.

• Recommended: Fueran 1920×1080 HDMI Headless Ghost Display Emulator on Amazon. You’ll also need a micro-HDMI to HDMI adapter for the Pi side.
• Required for: Pis with a scheduled TV power-off, plus any Pi running fully headless.
• Setup: Plug into the unused micro-HDMI port. No driver, no config. The agent doesn’t need to know about it.

Pick the right HDMI port

• Use HDMI 1 on the TV. Many TVs only honor CEC on HDMI 1 and ignore commands on other ports.
• Avoid ports labeled “ARC” or “eARC” unless that’s the only CEC port. ARC expects an audio-system handshake the Pi doesn’t fully implement.
• On the Pi side, use HDMI 0 (the port closest to the power connector). HDMI 1 on the Pi exists but CEC behavior on the secondary port varies by firmware revision.

Enable CEC in the TV menu

CEC is called something different on every brand. Find the right name and turn it on:

• LG: SimpLink
• Samsung: Anynet+
• Sony: BRAVIA Sync / Control for HDMI
• Panasonic: Viera Link
• Sharp: Aquos Link
• Hisense: HDMI-CEC / Anyview
• Vizio: Settings → System → CEC → Enabled
• Roku TVs (Westinghouse, TCL, Hisense Roku, etc.): Settings → System → Control other devices (CEC) → 1-touch play: ON and System standby: ON. Both default to off; without 1-touch play, only power-off works.

Disable eco / fast-start tradeoffs

• Quick Start / Fast TV Start / Instant On — enable this. Many TVs disable the CEC chip in standby to save power. Without Quick Start, the TV cannot be woken by CEC because the chip isn’t listening when the TV is off.
• Auto power-off / Sleep timer — disable on the TV side. The DisplayCache schedule should be the only thing powering the TV down.
• Eco mode — turn off if it has its own switch separate from Quick Start.