Quick Start

This chapter takes a fresh Raspberry Pi from a blank SD card to broadcasting PSN over your network in about 30 minutes. It assumes you’ve read Core Concepts and have the hardware listed in Hardware ready.

Before you start

Have these on hand:

• Raspberry Pi 5 (or Compute Module 5 + IO board) and a power supply
• A microSD card (or, for CM5, the eMMC + an IO board for flashing)
• An IP camera or other supported video source on the same LAN
• A USB-wired gamepad (optional but recommended – wired only)
• A workstation with Raspberry Pi Imager

1. Flash the OpenFollow image

Both the Raspberry Pi 5 and the Compute Module 5 run a ready-made OpenFollow image – Raspberry Pi OS Lite with OpenFollow pre-installed. It boots straight into the app on HDMI, so there’s no OS to install and nothing to set up on the device itself.

Download the image for your board from the OpenFollow releases page, then flash it with Raspberry Pi Imager: Use custom, select the .img.xz file, Choose Storage, then Write.

• Raspberry Pi 5 – openfollow-pi5_<version>.img.xz, written to a microSD card.
• Compute Module 5 – openfollow-cm5_<version>.img.xz, written to the eMMC. Put the CM5 IO board into rpiboot/usbboot mode first so the eMMC appears as a USB drive – see Installation → Compute Module 5 for the steps.

Insert the card (or reboot the CM5) and power up. The Pi comes up running OpenFollow full-screen on HDMI.

Once it boots, OpenFollow shows the Pi’s IP address in the bottom-left of the screen. Use this group of numbers whenever this manual refers to the Pi’s IP address with <pi-ip>.

You won’t need a command line to set OpenFollow up – everything is in the web UI. If you later want one for diagnostics, SSH into the Pi with ssh openfollow@<pi-ip> using the username openfollow and the password openfollow.

2. Open the Web UI

From any device on the same network, browse to:

http://<pi-ip>

You should land on the Overview tab. There’s no PIN configured by default – set one under General → Web Access before going further on a non-bench network.

If you need to set custom network settings to get access to the Web UI, you can change them in the on-screen menu Settings → Network with a keyboard connected to the Pi.

3. Position the camera

The wizard’s Camera Position step asks for a measured position in metres relative to the Reference Point. Get the camera physically mounted first – the numbers come off a tape measure.

OpenFollow-specific constraints:

• Pitch must be negative. Roughly −15° to −60°. The calibration solver rejects a flat horizontal angle.
• All four grid corners must fit inside the image, with a little headroom. Clipping a corner at the edge drops accuracy fast.
• Frame the performers, not just the grid. The grid is a calibration target – performers can move outside it. Centre the area you actually want to track in frame.
• Disable auto-focus and auto-zoom. Both change the effective field of view and break the calibration.

Typical position

A common starting point for a mid-sized stage: camera at FOH balcony rail, ~6 m up, ~10 m back from the downstage edge, pitch ≈ −25°, yaw 0°, roll 0°. Adjust to what your venue actually allows.

Try your numbers in the interactive Positioning the Camera sketch first – it shows where the field of view lands on the grid before you mount anything.

Measure relative to the Reference Point

Once mounted, take three measurements with a tape:

• Pos X – distance left/right from the Reference Point to the point on the floor directly under the camera (positive = stage left).
• Pos Y – distance front/back from the Reference Point to that same floor point (positive = upstage).
• Pos Z – height of the camera above the Reference Point.

Pitch / yaw / roll are estimates – start with pitch ≈ −25°, yaw 0°, roll 0° and let the wizard refine them in step 6 (Corner Pinning). Have the camera’s horizontal field of view from the datasheet handy too, or its sensor size and lens focal length.

For the full theory and edge cases see Camera & Grid Calibration.

4. Run the Setup Wizard

Open the Camera & Grid tab and click Open Setup Wizard. The wizard has seven steps. The shortest path:

1. Preparation. Mark the Reference Point and the four grid corners on stage with tape – they have to be visible on camera.
2. Grid Setup. Enter the width, depth, and offset of the rectangle you marked.
3. Video Source. Pick the input. For bench testing without a real camera, choose Media Gallery. For the full per-protocol setup (RTSP, NDI® ^{1 2}, Pi camera, USB), see Video Inputs.
4. Camera Position. Enter the camera’s X/Y/Z position and pitch/yaw/roll relative to the Reference Point – the values you measured in step 3.
5. Reference Mapping. Drag the on-screen crosshair onto the Reference Point mark in the live image.
6. Corner Pinning. Drag each of DSL/DSR/USR/USL onto the matching grid corner. Use the Fine adjust button for a 4× zoom view.
7. Review & Apply. Confirm the solved camera values look reasonable, then Apply & Finish.

The full step-by-step with screenshots and tips for each step is in Camera & Grid Calibration.

5. Verify PSN output

Open Output → PSN Output. Confirm the multicast IP (default 236.10.10.10) and the System Name (auto-generated on first boot, e.g. OpenFollow brave-otter). PSN is enabled by default for this station’s Controlled markers (default just marker 1).

Plug in a gamepad (or use the keyboard – see Controls) and move marker 1. On a console that subscribes to PSN – for example grandMA3, ETC Hog 5, or ChamSys MagicQ – you should see the marker’s position update at ~60 Hz.

To verify without a console handy, run a PSN listener on a workstation on the same subnet and watch the data packets.

ETC Eos does not accept PSN – it receives tracking via OSC (Augment3D Position) only. See OSC Transmitters to wire one up.

Common gotchas

• No PSN packets received. Verify with tcpdump -ni any host 236.10.10.10. If the multicast isn’t reaching, check IGMP snooping on the managed switch.
• Markers drift after a few minutes. The camera was bumped or the lens auto-focused. Recalibrate.
• Web UI is slow. The Pi is probably running detection without a GPU. Disable Person Detection Experimental and try again.

1. NDI® is a registered trademark of Vizrt NDI AB.

2. OpenFollow does not contain any NDI® code by itself. NDI® requires closed source NDI® Tools / NDI® SDK on the host system that need to be installed separately.