Install RF Ranger on a Raspberry Pi

What you need

• A Raspberry Pi 4 or 5 with 2 GB of memory or more, and its official power supply. A phone charger often can't power a Pi properly, and an underpowered Pi misbehaves in odd ways.
• A microSD card, 16 GB or larger, from a known brand.
• An Ethernet cable to the network your receivers are on. Wi-Fi often drops the messages receivers use to announce themselves.
• To drive a TV: a micro-HDMI to HDMI cable (the Pi 4 and 5 have micro-HDMI ports).
• A Mac or Windows computer with an SD card slot or reader, to set up the card.

1. Set up the SD card

Raspberry Pi Imager puts the Pi's operating system on the card, and lets you name the Pi and turn on remote access as it goes.

1. Download and open Raspberry Pi Imager (free), and put the SD card in your computer.
2. Device: choose your Pi model.
3. Operating system: choose Raspberry Pi OS (64-bit). That's the version with a desktop, which the TV display needs. If the Pi will never drive a screen, Raspberry Pi OS Lite (64-bit) (under "Raspberry Pi OS (other)") is smaller. Either way it must be 64-bit.
4. Storage: choose the SD card. Check it's the card and not another drive: everything on it is erased.
5. Customisation: when Imager offers to customise the OS, say yes and fill in:
   • Hostname: rf-ranger. The Pi's address becomes rf-ranger.local.
   • Username and password: choose them and write them down. You'll need them in the next step.
   • Time zone: yours. Planning Center auto-sync runs on the Pi's clock.
   • Wi-Fi: leave it out if you're using a cable.
   • SSH (under Services or Remote access): turn it on, with password authentication.
6. Write the card. When Imager says it's done, eject the card.

2. Start the Pi and connect to it

1. Put the card in the Pi. Plug in the Ethernet cable, and the TV if you're using one. Then plug in the power.
2. Give it a few minutes: the first start sets itself up and restarts once.
3. On your computer, open Terminal (Mac) or PowerShell (Windows) and connect, using the username you chose:

   ssh yourname@rf-ranger.local

   Copy
   The first time, type yes to trust the Pi. Then type your password; nothing shows while you type, which is normal.

"Could not resolve hostname"? Some networks don't pass .local names. Find the Pi's IP address in your router's list of devices and use that instead: ssh yourname@192.168.1.50. If the Pi is on a TV with a keyboard and mouse, you can also skip ssh and open Terminal on the Pi's own desktop.

3. Install RF Ranger

Paste this into the same window and press Enter:

curl -fsSL https://raw.githubusercontent.com/jdnelson19/RF-Ranger/main/packaging/linux/install.sh | bash

It downloads the latest RF Ranger, sets it to start every time the Pi does, and asks two things:

• An admin password, typed twice. See below for what it's for. You can skip it and set one later.
• Whether to show RF Ranger on the Pi's own screen (only with the desktop version). Say yes for a Pi behind a TV.

It may ask for your password again when it needs to install something. When it finishes it prints the addresses to open. If you chose the screen, restart the Pi to start it:

sudo reboot

4. Open it from anywhere on the network

• Engineer view on a laptop or iPad: http://rf-ranger.local:8058
• Pickup screen for another TV: http://rf-ranger.local:8058/#/pickup
• The Pi's own screen shows the pickup screen. Choose what it shows from the engineer view (Pickup display) or with a show preset.

Tip: some Android tablets and older Windows PCs can't open .local addresses. Use the Pi's IP address instead, and ask whoever runs your network to give the Pi a fixed IP address (a DHCP reservation) so bookmarks keep working.

The admin password

Connecting Planning Center, adding or forgetting a device and the Device Inspector change how RF Ranger works, so other screens on the network can't use them. On a Mac or Windows laptop you'd use them on that laptop. A Pi has nobody sitting at it, so with an admin password set, those pages show a password box on any screen instead.

• Set or change it on the Pi: rf-ranger --set-password (changing it signs every screen out).
• On a shared iPad, sign out again from ⚙ → Sign out of admin.
• Keep RF Ranger on your production network, not the open internet.

Updating

When the engineer view says a new version is out, connect to the Pi as in step 2 and run the install command again. Your settings, presets, Planning Center link and display setup are kept.

To remove RF Ranger: the same command, with bash -s -- --uninstall in place of bash at the end.

Troubleshooting

• No receivers show up. The Pi needs to be wired to the same network as the receivers. If they're on another network, sign in as admin and add each one by IP address on the Devices page.
• "This is 32-bit Raspberry Pi OS". Set up the card again (step 1) and choose the 64-bit version.
• The TV shows the desktop, not RF Ranger. Run the install command again with bash -s -- --display in place of bash, then restart the Pi.
• The TV goes black after a while. Check the TV's own power-saving or auto-off settings.
• Something else. Is RF Ranger running? sudo systemctl status rf-ranger. Its log is in ~/.rf-ranger/logs/rf-ranger.log. Tell us what happened and we'll help.