Flash the DisplayOps image

Writing the image to a microSD card takes about ten minutes and needs no Linux knowledge. Pick the computer you are using and follow the steps in order.

Before you start

What you need

• A Raspberry Pi 4 (2 GB or more), Raspberry Pi 5, or Pi 400/500. A Pi 3B+ also works for websites, images and messages.
• A microSD card of 16 GB or more. A high-endurance (A2) card lasts far longer in a screen that runs all day. 8 GB is the smallest card the image fits on.
• A card reader. A USB card reader is the most reliable choice, especially on Windows.
• An HDMI cable, a screen, and the official Raspberry Pi power supply.
• Network: an Ethernet cable (nothing to configure), or your Wi-Fi name and password.

Download the image

1. Sign in to the portal and open Displays → Pair a display.
2. Under Get the image, click Download displayops-0.1.0.img.xz. The file is about 700 MB.
3. Leave the file compressed. Every tool on this page reads the .img.xz directly.
4. Recommended: compare the SHA-256 shown next to the download with the checksum of your file. Each section below has the one-line command for your system. If they differ, download again.

Windows

Two good tools. Raspberry Pi Imager can set up Wi-Fi for you. Rufus is a single small download and is the quickest route when the Pi will use Ethernet.

Option A: Raspberry Pi Imager

1. Download Raspberry Pi Imager from raspberrypi.com/software (Download for Windows) and run the installer.
2. Insert the microSD card.
3. Open Raspberry Pi Imager. Click Choose Device and pick your Pi model, or No filtering.
4. Click Choose OS, scroll to the bottom of the list and click Use custom. Select the displayops-0.1.0.img.xz you downloaded.
5. Click Choose Storage and pick your microSD card. Check that the size matches your card so you do not erase the wrong drive.
6. Click Next. Imager asks whether to apply OS customisation settings. Click Edit Settings. (Newer Imager versions show the same settings as a short series of pages instead of one dialog.)
7. Wi-Fi: tick Configure wireless LAN, enter your network name and password, and set Wireless LAN country to your two-letter country code (for example CA or US). Skip this if the Pi will use Ethernet.
8. Leave the hostname as displayops, or set one you will recognise on your router.
9. Only if you want to log in to the Pi for troubleshooting: tick Set username and password, use the username admin, and on the Services tab tick Enable SSH. Most people skip this step.
10. Click Save, then Yes to apply the settings, then Yes to confirm the card will be erased.
11. Wait while Imager writes and verifies (3 to 5 minutes). When it shows Write Successful, click Continue and remove the card.

Continue at First boot and pairing.

Option B: Rufus

Rufus writes the image faithfully but cannot set up Wi-Fi. Use an Ethernet cable, or add Wi-Fi afterwards with the text file described in Wi-Fi without Imager.

1. Download Rufus from rufus.ie. The portable version needs no installation. Run it. If it asks to check for updates online, either answer is fine.
2. Insert the microSD card.
3. Under Device, choose your card and check that the size matches. If the card is not listed, click Show advanced drive properties and tick List USB Hard Drives, or use a USB card reader.
4. Under Boot selection, click SELECT and pick displayops-0.1.0.img.xz. Rufus recognises it as a compressed disk image and greys out the options that do not apply. (If your Rufus refuses the file, extract it first with 7-Zip and select the .img instead.)
5. Click START. Rufus warns that all data on the device will be destroyed. Click OK.
6. Wait for the green bar to finish and the status to read READY (3 to 5 minutes).
7. If Windows asks to format a disk, click Cancel. Close Rufus.
8. Using Ethernet? Remove the card and continue at First boot and pairing. Using Wi-Fi? Leave the card in and follow Wi-Fi without Imager.

Verify the download on Windows

Open your Downloads folder in File Explorer, right-click an empty area and choose Open in Terminal, then run:

certutil -hashfile displayops-0.1.0.img.xz SHA256

The long line of letters and numbers must match the SHA-256 on the pairing page.

macOS

Option A: Raspberry Pi Imager

1. Download Raspberry Pi Imager from raspberrypi.com/software (Download for macOS). Open the .dmg and drag Raspberry Pi Imager into Applications.
2. Insert the microSD card using an adapter or a USB card reader.
3. Open Raspberry Pi Imager. If macOS refuses to open it, right-click the app and choose Open, or allow it under System Settings → Privacy & Security.
4. Click Choose Device and pick your Pi model, or No filtering.
5. Click Choose OS, scroll to the bottom and click Use custom. Select displayops-0.1.0.img.xz from your Downloads folder.
6. Click Choose Storage and pick the card. Check the size.
7. Click Next, then Edit Settings. For Wi-Fi, tick Configure wireless LAN and enter the network name, password and your two-letter country code. Optional: hostname, and username admin plus Enable SSH on the Services tab if you want to log in later. Click Save.
8. Click Yes to apply the settings and Yes to erase the card. Enter your Mac password when asked; Imager needs it to write to the card.
9. Wait for Write Successful (3 to 5 minutes), click Continue, and remove the card.

Continue at First boot and pairing.

Option B: Terminal

This needs the xz tool, which macOS does not include. Install it with Homebrew (brew install xz). If you do not use Homebrew, use Raspberry Pi Imager instead.

1. Insert the card and open Terminal (Applications → Utilities).
2. Find the card. Look for the entry whose size matches your card and is marked external, physical, for example /dev/disk4. Note the number; the next steps use it. Getting it wrong erases the wrong disk.

   diskutil list

3. Unmount the card (keep your own disk number):

   diskutil unmountDisk /dev/disk4

4. Write the image. rdisk instead of disk is several times faster. Enter your password when asked. Press Ctrl+T to see progress; the prompt returns when it is done (3 to 10 minutes).

   xz -dc ~/Downloads/displayops-0.1.0.img.xz | sudo dd of=/dev/rdisk4 bs=4m

5. For Wi-Fi, the small bootfs volume now appears in Finder: follow Wi-Fi without Imager. Otherwise eject and remove the card:

   diskutil eject /dev/disk4

Verify the download on macOS

shasum -a 256 ~/Downloads/displayops-0.1.0.img.xz

Linux

Option A: Raspberry Pi Imager

1. Install Raspberry Pi Imager. On Ubuntu, Debian or Raspberry Pi OS: sudo apt install rpi-imager. On other distributions download it from raspberrypi.com/software or install org.raspberrypi.rpi-imager from Flathub.
2. Insert the microSD card and open Raspberry Pi Imager.
3. Click Choose Device and pick your Pi model, or No filtering.
4. Click Choose OS, scroll to the bottom and click Use custom. Select displayops-0.1.0.img.xz.
5. Click Choose Storage and pick the card. Check the size.
6. Click Next, then Edit Settings. For Wi-Fi, tick Configure wireless LAN and enter the network name, password and country code. Optional: hostname, username admin and Enable SSH for troubleshooting. Click Save.
7. Click Yes to apply and Yes to erase. Enter your password when asked.
8. Wait for Write Successful, click Continue, and remove the card.

Continue at First boot and pairing.

Option B: Terminal

1. Insert the card. List disks and find the card by size, for example sdb for a USB reader or mmcblk0 for a built-in slot. Use the whole device, never a partition (sdb, not sdb1).

   lsblk -d -o NAME,SIZE,MODEL,TRAN

2. Unmount anything your desktop mounted automatically (keep your own device name):

   sudo umount /dev/sdb* 2>/dev/null

3. Write the image and wait for the prompt to return (3 to 10 minutes):

   xz -dc ~/Downloads/displayops-0.1.0.img.xz | sudo dd of=/dev/sdb bs=4M status=progress conv=fsync

4. Run sync, then remove the card. For Wi-Fi, reinsert it so the bootfs partition mounts and follow Wi-Fi without Imager.

Verify the download on Linux

sha256sum ~/Downloads/displayops-0.1.0.img.xz

Wi-Fi and SSH without Imager

Use this when you flashed with Rufus or the terminal and the Pi will use Wi-Fi, or when you want to be able to log in to the Pi. The device reads one small text file from the card on its first boot.

1. Put the card into your computer, or leave it in after flashing. A small drive named bootfs appears: a new drive letter on Windows, /Volumes/bootfs on macOS, usually under /media on Linux. Ignore any message about a second, unreadable partition.
2. On that drive, create a new plain-text file named exactly custom.toml. In Windows Notepad choose File → Save as, set Save as type to All files, and type the name custom.toml so Windows does not add .txt. In macOS TextEdit choose Format → Make Plain Text first.
3. Paste the following and replace the three values. Keep the double quotes. The country is your two-letter code (CA, US, GB, DE, AU, …); it sets the allowed Wi-Fi channels and 5 GHz may not connect without it.

   config_version = 1
   
   [wlan]
   ssid = "Your Wi-Fi name"
   password = "your Wi-Fi password"
   password_encrypted = false
   hidden = false
   country = "CA"

4. Optional, for troubleshooting only. Add this to the same file to set a login password and turn on SSH. Afterwards you can connect with ssh admin@displayops.local. Leave it out for a screen that just needs to work.

   [user]
   name = "admin"
   password = "choose-a-long-password"
   password_encrypted = false
   
   [ssh]
   enabled = true
   password_authentication = true

5. Save the file, eject the card safely, and continue at First boot and pairing. The Pi applies the settings on its first boot and then deletes the file from the card; the settings stay.

First boot and pairing

1. With the Pi unplugged, insert the card. Connect the HDMI cable (on a Pi 4 or Pi 5 use the port next to the USB-C power connector), the Ethernet cable if you use one, and finally the power.
2. The first boot takes one to two minutes and the Pi restarts once on its own: it expands the card, creates its own keys and applies your Wi-Fi settings. The screen may stay black or show scrolling text meanwhile. Wait.
3. The pairing screen appears: a six-character code and a QR code.
4. Scan the QR code with your phone, or on any computer sign in to the portal, click Pair a display and type the code. Give the screen a name, optionally choose what to show, and click Pair display.
5. The screen switches to your content within a few seconds. Every later boot takes about 40 seconds and needs no attention.

Troubleshooting

Still stuck? Email support@simplecontrolops.com with your Pi model, the tool you used, and a photo of the screen.