OpenFollow Preview

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.
Type it here and every <device-ip> below fills in automatically.
Leave empty on the prepared OpenFollow image. On a .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.

  1. Open Terminal.

    On a Mac: Cmd+Space, type Terminal, Enter. On Linux: Ctrl+Alt+T.

  2. Connect to the station.
    ssh openfollow@<device-ip>

    The default password on the prepared OpenFollow image is openfollow; on a .deb install, use your own. It doesn't show as you type.

  3. Run the companion-pi installer.
    curl https://raw.githubusercontent.com/bitfocus/companion-pi/main/install.sh | sudo bash
  4. Start Companion.
    sudo systemctl start companion

    It also starts by itself on every boot from now on.

  5. Open Companion.

    Go to http://<device-ip>:8000 in a browser. OpenFollow's web interface stays on its own address.

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:

AppPortUse
OpenFollow80 (TCP)Web interface
OpenFollow8765 (UDP)OSC Input
Companion8000 (TCP)Web interface
Companion16622, 16623 (TCP)Satellite
Companion12321 (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.