Manual / How To
Run Companion on the OpenFollow Pi
Bitfocus Companion runs alongside OpenFollow on the same Raspberry Pi, so a Stream Deck can plug straight into the station without a separate computer. This guide installs Companion with Bitfocus's own companion-pi installer. To build the buttons, see Control OpenFollow with Companion.
Tested with Companion 5.1.1 on a Raspberry Pi 5 (4 GB).
Before you start
- SSH access to the station. See Installation.
- An internet uplink on the Pi for the install. Companion runs offline afterwards, like OpenFollow.
<device-ip> below fills in automatically.
.deb install, enter the user you created.
Install Companion
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 device'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: Cmd+Space, type
Terminal, Enter. On Linux: Ctrl+Alt+T. -
Connect to the station.
ssh openfollow@<device-ip>The default password on the prepared OpenFollow image is
openfollow; on a.debinstall, use your own. It doesn't show as you type. -
Run the companion-pi installer.
curl https://raw.githubusercontent.com/bitfocus/companion-pi/main/install.sh | sudo bash -
Start Companion.
sudo systemctl start companionIt also starts by itself on every boot from now on.
-
Open Companion.
Go to
http://<device-ip>:8000in a browser. OpenFollow's web interface stays on its own address.
You'll use PowerShell (Windows 10) or Terminal (Windows 11) – a standard app for sending text-based commands to another computer without a graphical user interface. Both include the ssh command. Type or paste each line exactly and press Enter. Where a command shows <device-ip>, replace it with your device's IP address (shown on the device screen) – or enter it in the box above to fill every command at once.
-
Open PowerShell or Terminal.
Click Start, type
PowerShell(Windows 10) orTerminal(Windows 11), Enter. -
Connect to the station.
ssh openfollow@<device-ip>On first connect, confirm with
yes. The default password on the prepared OpenFollow image isopenfollow; on a.debinstall, use your own. It doesn't show as you type. -
Run the companion-pi installer.
curl https://raw.githubusercontent.com/bitfocus/companion-pi/main/install.sh | sudo bash -
Start Companion.
sudo systemctl start companionIt also starts by itself on every boot from now on.
-
Open Companion.
Go to
http://<device-ip>:8000in a browser. OpenFollow's web interface stays on its own address.
ssh "not recognized"? Add the client under Settings → Apps → Optional features → Add a feature → OpenSSH Client, then reopen the window.
Companion installs as its own service under its own user. It does not change OpenFollow, the station's network settings, its hostname, or the boot configuration. OpenFollow updates leave Companion alone, and the reverse.
Ports
The two apps use different ports:
| App | Port | Use |
|---|---|---|
| OpenFollow | 80 (TCP) | Web interface |
| OpenFollow | 8765 (UDP) | OSC Input |
| Companion | 8000 (TCP) | Web interface |
| Companion | 16622, 16623 (TCP) | Satellite |
| Companion | 12321 (UDP) | OSC Listener, when switched on |
Keep the ports apart if you change any of them.
Talking to OpenFollow
Companion reaches OpenFollow on the same Pi at 127.0.0.1, port 8765. Use the IP, not localhost. If Input → OSC Input → Allowed sender IPs is set, add 127.0.0.1 to it.
OpenFollow sends to Companion the same way: an OSC Destination at 127.0.0.1, port 12321.
Load
An idle Companion uses almost no CPU and about 500 MB of memory. Each connection and every button with live feedback adds to that. OpenFollow's video decoding, the Operator Screen and Person Detection share the same four cores.
- Build the full Companion page before the show and watch Statistics → Device with it running.
- If the Operator Screen or tracking stops running smoothly, use fewer polling connections in Companion.
Stream Deck
Plug the Stream Deck into any USB port on the Pi. Companion finds it by itself; use Surfaces → Surfaces & Groups → Rescan USB in Companion if it does not show up. OpenFollow does not use Stream Decks, so the two apps don't compete for it.
One app per USB device. Gamepads and 3D mice are OpenFollow's. Don't add them to Companion as well.
Update or remove Companion
Update Companion:
sudo companion-update
Stop it and keep it from starting at boot:
sudo systemctl disable --now companion
Diagnostics bundles and OpenFollow's settings backups don't include Companion. Back up the Companion configuration under Import / Export in Companion.