Manual / Setup

Installing Person Detection Experimental

On the pre-built OpenFollow image and .deb package, Person Detection ships ready to run: the inference engine and the quality-tier models are bundled, so detection works offline with nothing to install. You only need this page to add detection to a source or base-only build that ships without the engine, or to add the model-build toolchain on a workstation so Download Model can build or convert models beyond the bundled tiers.

Experimental – not for show use. Person Detection is an experimental feature. Accuracy, model defaults, and settings can change between releases, and the install procedure is not yet stable. Do not put it on a show-critical path. Use it for evaluation and rehearsal only.

Hardware-heavy. A source-build backend install is several hundred MB; the model-build toolchain (torch + ultralytics) is several gigabytes and needs at least ~4 GB free. Downloaded models need more still, so an NVMe drive is recommended when you keep many. Detection is also far more compute-heavy than marker-driven tracking and is really a workstation feature. Budget hardware accordingly – see Hardware.

Step by step

You run a single bundled installer on the device over SSH. You'll need a second computer – a Mac, or a PC running Linux or Windows – on the same network as the OpenFollow station, and the same VLAN if your network uses them. The device itself is headless, so all commands run on it from that computer.

Internet needed during install. This downloads the backend from the internet, so the OpenFollow station needs internet access for the whole process. Once the install finishes successfully, no internet access is required to run detection.

Your station's IP address Type it here and every <device-ip> in the commands below fills in automatically.

SSH refused with a host-key warning? If you see REMOTE HOST IDENTIFICATION HAS CHANGED, the device's SSH identity changed since you last connected at this IP (typically a reflash). Clear the stale key and try again: ssh-keygen -R <device-ip> (same command on macOS, Linux, and Windows PowerShell).

You'll use Terminal – a standard app for sending text-based commands to another computer without a graphical user interface. Type or paste each line exactly and press Enter. Where a command shows <device-ip>, replace it with your station's IP address (shown on the device screen) – or enter it in the box above to fill every command at once.

Open Terminal.
On a Mac: press Cmd+Space, type Terminal, press Enter. On Linux: press Ctrl+Alt+T, or open "Terminal" from your applications.
Connect to your station.
```
ssh openfollow@<device-ip>
```
When it asks for a password, type your device's password and press Enter. The characters won't appear as you type – that's normal. On stations set up from the prepared OpenFollow image, the default password is openfollow. From here on, what you type runs on the device.
Run the installer.
```
/usr/share/openfollow/install-detection.sh
```
It checks free space, then downloads and installs the backend for you. The whole process takes about 10–20 minutes; scrolling text is normal progress, not an error. If it stops with a space warning, free up storage (or fit an NVMe) and run it again.
Done.
When it prints Done. Detection works in the web UI once a model (.onnx) is present, the backend is installed. Open the web interface, turn on Show experimental features, and on the Person Detection tab use Download Model to fetch a model, then pick it as the active Model.

Windows 10 and 11 include the same ssh tool the other platforms use. You'll run it in PowerShell – a standard app for sending text-based commands to another computer without a graphical user interface. Type or paste each line exactly and press Enter. Where a command shows <device-ip>, replace it with your station's IP address (shown on the device screen) – or enter it in the box above to fill every command at once.

Open PowerShell.
Click Start, type PowerShell (or Terminal on Windows 11), and press Enter. A text window opens.
Connect to your station.
```
ssh openfollow@<device-ip>
```
The first time you connect it may ask "Are you sure you want to continue connecting?" – type yes and press Enter. When it asks for a password, type your device's password (it won't appear as you type – that's normal). On stations set up from the prepared OpenFollow image, the default password is openfollow. From here on, what you type runs on the device.
Run the installer.
```
/usr/share/openfollow/install-detection.sh
```
It checks free space, then downloads and installs the backend for you. The whole process takes about 10–20 minutes; scrolling text is normal progress, not an error. If it stops with a space warning, free up storage (or fit an NVMe) and run it again.
Done.
When it prints Done. Detection works in the web UI once a model (.onnx) is present, the backend is installed. Open the web interface, turn on Show experimental features, and on the Person Detection tab use Download Model to fetch a model, then pick it as the active Model.

ssh "not recognized"? On older Windows, add the client under Settings → Apps → Optional features → Add a feature → OpenSSH Client, then close and reopen PowerShell.

The packages the install script installs – for advanced users, or when the script isn't available. They go into the application's Python environment so they serve both the openfollow service and command-line tests. The interpreter is /opt/openfollow/venv/bin/python.

Check free space first. The download is several hundred MB and the install needs at least ~4 GB free. On a unit with an NVMe, keep the download cache and temp files off the small onboard storage (the bundled installer does this for you).

1. Connect to the device

ssh openfollow@<device-ip>

2. Install a CPU-only build of the tensor runtime

Install this first, from the CPU package index, so the install doesn't pull the large unused GPU libraries:

sudo /opt/openfollow/venv/bin/python -m pip install \
  --index-url https://download.pytorch.org/whl/cpu torch torchvision

3. Install the inference backend and model toolchain

sudo /opt/openfollow/venv/bin/python -m pip install \
  "onnxruntime>=1.17" "opencv-python>=4.8" ultralytics

4. Verify

/opt/openfollow/venv/bin/python -c "import onnxruntime, cv2"

It should print nothing and exit cleanly. An ImportError means a package above didn't install – re-run the step that installs it and watch for errors in its output.

5. Restart the service

sudo systemctl restart openfollow

Detection is now available in the web UI. Open the Person Detection tab (turn on Show experimental features first), use Download Model to fetch a model, and pick it as the active Model. On a unit with an NVMe, point Storage Path at the fast drive so models have room.

Model-build toolchain. To build or convert your own models with Download Model, add the export tools on a workstation by running the installer with --with-export: /usr/share/openfollow/install-detection.sh --with-export. They pull in torch and ultralytics (large, and AGPL-licensed), and aren't needed on a show Pi.