Download → write the card → phone Wi-Fi setup → claim code → first playlist
For Raspberry Pi 3, 4 and 5 · OS 0.3.2 preview · Keep this guide on your computer while using your phone for setup.
Before you begin
You need a computer, a card reader, a 16 GB or larger microSD card, a Pi with suitable power, an HDMI display and cable, a phone, and the venue Wi-Fi name and password.
Use the official Raspberry Pi Imager. Select the compressed .img.xz file directly in Imager. Extraction is optional.
Pi 3: ads-only, one display; still images recommended on 512 MB A+. Pi 4/5: ads-only or live video with side ads. One image detects the board automatically.
Three different details, used at different times
Detail
Where it comes from
Where to enter it
Pi setup Wi-Fi password
Shown on the Pi’s display
Enter in your phone’s Wi-Fi settings to join ScreenSplice-XXXX.
Venue Wi-Fi password
Your venue or router
Enter on the phone setup page so the Pi can join the venue network.
One-time SS device code
Shown after the Pi joins Wi-Fi and reboots
Enter on the ScreenSplice website under Devices → Add device.
The capture device for live HDMI video
No capture card is needed for ads-only playback, including Pi 3.
Video source HDMI → capture card HDMI input → Pi blue USB 3 port. Pi HDMI output → display. Keep a Fire TV’s own power adapter connected.
Two independent live feeds need two capture cards. HDCP-protected content may not appear. Dual capture is experimental and needs hardware testing.
1Download on your computer
Sign in at https://screensplice.com using the account for your workspace, then open Downloads.
Click Download ScreenSplice OS and let the download finish. Save it to your computer, not to the Pi or microSD card yet.
One image supports Pi 3, Pi 4 and Pi 5. Pi 3 automatically uses full-screen ads only; Pi 4/5 can also use live capture.
What you should see: You have a compressed file ending .xz, about 1 GB for this release. Check that the filename ends .img.xz.
2Keep the image compressed
Raspberry Pi Imager can write the .img.xz download directly. You do not need to extract it.
In Windows File Explorer, turn on View → Show → File name extensions. If storage changed the name to end img.xz without a dot before img, rename the completed download to ScreenSplice.img.xz.
Already extracted it? Rename only the extracted ScreenSplice disk image to ScreenSplice.img if it is missing that extension. Do not rename a compressed .xz archive to .img.
What you should see: You have a completed .img.xz download or an extracted .img file, not a zero-byte file.
An .img is a disk image, not a photograph. Imager handles decompression while writing.
3Write the microSD card with Pi Imager
Insert a 16 GB or larger microSD card into your computer’s card reader and open Raspberry Pi Imager.
Choose your Raspberry Pi model. Under Choose OS, choose Use custom, then select the downloaded .img.xz file (or an already extracted .img).
Under storage, choose the microSD card. Check its name and capacity carefully: writing will erase the selected card.
Skip or decline Imager’s OS customization. Do not add a username, Wi-Fi or SSH settings here; ScreenSplice handles network setup from your phone.
Write the image and let Imager finish its verification. Eject the card safely. If Windows later asks to format a Linux partition on the card, choose Cancel.
What you should see: Pi Imager reports that writing and verification have finished.
4Connect the Pi, display and optional capture card
Put the card into the Pi. Connect the Pi’s HDMI output to the display and select that HDMI input on the display. Pi 3 uses full-size HDMI; Pi 4/5 use micro-HDMI.
For ads-only playback, no capture card or video source is needed.
For live video on Pi 4/5, connect your source’s HDMI output to the Guermok capture card’s HDMI input, then plug the card into a blue USB 3 port on the Pi. The Pi’s own HDMI sockets are outputs.
Power a Fire TV or other source separately if it requires its own power adapter. Then power the Pi with a suitable supply for that model.
What you should see: After the initial boot messages, the display shows Connect this screen to Wi-Fi and its setup network details.
First boot can take a few minutes. Check the display and power connections while it starts.
5Connect your phone to the Pi’s setup Wi-Fi
Read the setup Wi-Fi name and password from the Pi’s display. The name looks like ScreenSplice-AB12.
On your phone, open Wi-Fi settings and join that exact network using the password shown on the display. The password uses uppercase letters and numbers; enter it without spaces.
If the phone says this network has no internet, choose Stay connected or Use without internet. That is expected during setup.
On Android, allow your browser to access local devices if asked. If the page reports ERR_TOO_MANY_RETRIES or cannot be reached, open Settings → Apps → Chrome (or your browser) → Permissions and allow Nearby devices or Local network. Force-stop and reopen the browser, then retry. If it already says Allow, toggle it off and back on.
Tap Sign in to network if your phone offers it. If the setup page does not appear, type http://10.42.0.1:8080/ into the address bar while still connected to ScreenSplice Wi-Fi. Use http, not https. The original http://10.42.0.1 address also works.
What you should see: Your phone shows the local ScreenSplice Wi-Fi setup page. You do not sign in to your website account on this local page.
6Tell the Pi which venue Wi-Fi to join
Tap Scan for networks, choose the venue’s Wi-Fi name, and enter that network’s password. Use Show password to check it before connecting. This is different from the Pi’s setup Wi-Fi password.
Tap Connect Wi-Fi. The setup Wi-Fi disappears as the Pi joins the venue network and reboots. Your phone losing the 10.42.0.1 page at this point is expected.
What you should see: The Pi reboots, connects to the internet and shows a one-time device code.
Use a normal Wi-Fi network with a password. Networks that require a separate browser login or acceptance page are not supported by this setup. A visible 2.4 GHz network is a useful fallback if your Pi cannot see the venue network.
7Add the Pi to your online workspace
Reconnect your phone or computer to normal internet access. Close the local 10.42.0.1 setup page and open https://screensplice.com.
Sign in to the workspace that should own this display. Open Devices → Add device.
Enter the complete code shown on the Pi, such as SS-4KQ2-M9XT. Give the screen a useful name, such as Lobby display, and save it. Older FS codes are accepted too.
Choose full-screen advertisements for ads-only playback, or live feed with side advertisement for a Pi 4/5 that was set up with a capture card.
What you should see: The device appears in your workspace and checks in. The one-time code is no longer needed after pairing.
Joining the Pi’s temporary Wi-Fi only sets up its network. Entering the displayed device code on the website is the separate step that links it to your customer account.
8Put your first advertisement on screen
Open Ad library and add a JPG or PNG image for your first test. Full-screen artwork is 1920 × 1080; side artwork is 480 × 864. For a memory-limited Pi 3, smaller 1280 × 720 still images are recommended.
Open Playlists → New playlist, name it, then choose Create & add ads. Add your test image and save the playlist.
Use Deploy from the playlist or device page, choose your screen, and confirm the deployment.
Keep the Pi online while it downloads the content. Changes usually arrive on the next check-in, about a minute; larger downloads take longer.
What you should see: Your advertisement appears. A Pi 4/5 configured for live capture shows the source beside the ad; an ads-only player fills the screen with the ad.
9Add your branding and keep it running
Under Setup → Your screen branding, save your business name, tagline and logo. A transparent PNG works well for a logo or icon.
Open a device’s display settings to choose its design, playback mode and optional timed full-screen ad breaks. Each device can have its own settings.
Leave the player connected to the venue network for content changes and signed player updates. Let it check in after a restart. During a network drop while already playing, it keeps the last cached playlist.
Use portal changes and automatic player updates for routine changes. Reflashing a card is a fresh installation and removes local setup; do not reflash a working paired card just to change its theme or advertisements.
What you should see: The device reports online and displays the correct playlist and venue branding.
If something does not match
Android says ERR_TOO_MANY_RETRIES or cannot reach the local page
In Android Settings → Apps → your browser → Permissions, allow Nearby devices or Local network, then force-stop and reopen the browser. If already allowed, toggle that permission off and on. Rejoin ScreenSplice Wi-Fi and retry http://10.42.0.1:8080/. Use the phone’s Sign in to network prompt when offered. Alternatively, use another phone, tablet or computer connected to the Pi’s setup Wi-Fi. ScreenSplice cannot enable a browser permission remotely.
The setup Wi-Fi rejects the password
Forget the saved ScreenSplice network and rejoin using the password currently on the display. Use uppercase letters and numbers, with no spaces. Keep IP settings on DHCP/Automatic. The setup password is different from your venue password and website account password.
Imager cannot see the file, or a file is 0 KB
Select the completed .img.xz download directly. If you already extracted it, enable file name extensions and rename the extracted ScreenSplice image to ScreenSplice.img. A compressed archive must keep .xz. Download again if the file is empty.
The phone cannot open 10.42.0.1
Check that the phone is still on the Pi’s ScreenSplice setup Wi-Fi, with IP settings on DHCP/Automatic and Proxy set to None. Keep the no-internet connection and enter http://10.42.0.1:8080/ directly. If needed, temporarily turn off mobile data during local setup.
The venue network is missing or joining fails
Rescan, move the Pi closer, verify the venue password and Wi-Fi country, and try a visible 2.4 GHz network. A normal phone hotspot can help test the connection. Browser-login guest networks are not supported.
The setup page becomes unreachable after Connect Wi-Fi
That is expected when the Pi’s setup Wi-Fi shuts down. Return your phone to normal internet access and watch the Pi’s display for its pairing code.
No code appears after the reboot
Give first boot and internet setup a few minutes. Check power, the display’s selected HDMI input and the network connection. Photograph any error on the Pi’s screen for support.
The device is already linked or the code is not accepted
Use the current full code and the intended workspace. A code is consumed once. If installing a fresh card in a previously paired Pi, remove its old entry from the owning workspace first, or ask that workspace’s administrator for help.
The screen is paired but has no advertisement
Add an image to a playlist and deploy that playlist to the correct device. Keep the Pi online while the files download.
The advertisement shows but HDMI video does not
Pi 3 is ads-only. On Pi 4/5, check USB source and feed mode, the source’s power, the HDMI cable into the capture card, and its blue USB 3 connection. HDCP-protected content may not be capturable.
A download link expires
Sign in, return to Downloads and request the image again. Download links are temporary; do not bookmark the storage link as the permanent download page.