The Raspberry Pi

Which Pi to choose?

• Raspberry Pi Zero 2 W - the sweet spot for e-ink frames. Four 64-bit cores, tiny, ~1 W of power, around $15-20. This is what most FrameOS frames run on.
• Raspberry Pi 5 / 4 - use these for fast HDMI/LCD output (up to 60 FPS) or when size doesn't matter. The Pi 5 and CM5 have their own SD image.
• Raspberry Pi Zero W (v1), Pi 1, CM1 - a single 32-bit ARMv6 core. Slow to deploy to, but supported all the way down, prebuilt SD image included.

Not a Pi person, or dreaming of a battery-powered frame? FrameOS also runs on the ESP32-S3 microcontroller, on Pico W boards, and with no hardware at all.

Option 1: prebuilt FrameOS SD image (recommended)

FrameOS ships purpose-built SD card images: a minimal Buildroot-based Linux that boots straight into FrameOS. No Raspberry Pi OS, no manual SSH setup, nothing to install afterwards.

There are three, one per board family - each covers every board in its family, so you match a family rather than an exact model:

You can get an image two ways:

• Generate it in the backend: when you add a new frame, choose Download SD card. Pick your board, and the image comes out preconfigured with your WiFi credentials, timezone, display driver and frame settings - flash it, insert, done. Whether root login is enabled, and with which password, is an explicit choice on that screen.
• Download a generic image from the latest release (look for frameos-*-raspberry-pi-64-buildroot.img.gz and its siblings). On first boot the frame starts a WiFi hotspot called FrameOS-Setup (password frame1234). Join it from your phone, enter your WiFi credentials, and the frame connects to your network.

Flash the image with Raspberry Pi Imager ("Use custom image"), balenaEtcher, or plain dd. The partitions expand to fill your SD card on first boot.

SD-image frames can also upgrade themselves in place: the frame downloads a new release, verifies its signature against a key baked into the build, and swaps it in on the next reboot - no re-flashing, no SSH.

Option 2: stock Raspberry Pi OS Lite

If you prefer a standard OS underneath - or you want to run other things on the same Pi:

1. Download the Raspberry Pi Imager and pick the Lite version of Raspberry Pi OS (no desktop needed).

   • 64-bit for Pi 3, 4, 5, Zero 2 W.
   • 32-bit for Pi 1, 2 and the original Zero W.

   

2. When prompted, edit the OS customisation settings: set a hostname, your WiFi credentials, and enable SSH. Use a password, or better, generate an SSH keypair and paste the public key.

   

3. Write the card, insert it into the Pi, connect the display, and power up.

4. Wait for the Pi to appear on your network, then verify you can reach it:

   ping frame.local        # or check your router's client list for the IP
   ssh [email protected]

5. Once connected, bring the OS up to date:

   sudo apt update -y && sudo apt upgrade -y

That's all. Given SSH access, the FrameOS backend does the rest - including installing dependencies and (for most targets) deploying precompiled binaries, so there's no slow on-device compilation.

Option 3: no SSH? install with a script

When the backend can't reach the Pi over SSH - a locked-down machine, a different network, a device you only have a keyboard on - add the frame with Install with a script. The backend hands you a single command to paste on the device. It installs FrameOS, starts FrameOS Remote, and the frame connects back to the backend over an outbound WebSocket. Deploys, logs, metrics and the terminal all work from there without an inbound route.

Next step

Deploy your first scene.