Manual / How To
Control OpenFollow with Companion
Bitfocus Companion turns a Stream Deck into a button panel for OpenFollow: preset positions, park and unpark, and cue cards on the Operator Screen. In the other direction, OpenFollow can light Companion buttons when a zone is occupied or show a marker's position on a key. Both directions use OSC.
Companion can run on its own computer or on the station itself. For the second, see Run Companion on the OpenFollow Pi.
Before you start
On OpenFollow, under Input → OSC Input:
- Tick OSC server (Listen for OSC messages) and note the UDP Port (default
8765). - Add the Companion computer's IP to Allowed sender IPs. With Companion on the station itself, that is
127.0.0.1. - For operator cards, also tick Input → Operator Messages → Operator messages.
Add the connection in Companion
- Open Connections and add Generic: OSC.
- Set Target Hostname or IP to the station's IP, or
127.0.0.1when Companion runs on the station. Use an IP, notlocalhost. - Set Target Port to OpenFollow's OSC Input port (
8765) and leave Protocol on UDP (Default).
One connection drives one station. Add a connection per station, or send to OpenFollow's OSC Input Multicast group (default 239.20.20.20) to reach every station at once. Companion sends multicast out of its computer's default route, so that route must lead to the show network. On the station itself, use 127.0.0.1.
Buttons that drive OpenFollow
Add an action from the OSC connection to a button's press step. Every message OpenFollow accepts is listed in the OSC Dictionary; these are the ones a button panel uses most:
| Button | Companion action | OSC Path | Value / Arguments |
|---|---|---|---|
| Preset position | Send message with multiple arguments | /marker/2 | 1.5 -2.0 0.0 |
| Set one axis | Send float | /marker/2/z | 1.2 |
| Park | Send message without arguments | /marker/2/park | – |
| Unpark | Send message without arguments | /marker/2/unpark | – |
| Cue card | Send message with multiple arguments | /message | "Standby downstage" "Q 51" 2 8 |
| Clear cards | Send message without arguments | /message/clear | – |
- Positions are X, Y, Z in metres from the Reference Point (X = stage left, Y = upstage, Z = up). The marker jumps there; the operator takes over from that point with the gamepad.
- OpenFollow moves only the markers the station controls. Messages for any other marker are ignored.
- In Arguments, spaces separate values and quotes group text. Whole numbers are sent as integers, which OpenFollow reads as numbers too.
- A cue card's arguments are the main line, a second line, the marker it is for (
0for every station) and the seconds it stays up (0until cleared). See Operator Messages.
No state comes back on this connection. OpenFollow does not answer OSC, so a Park button can't show whether the marker is parked. Use a two-step button (park, then unpark) so the key shows the last command sent, or set up feedback as below.
Feedback from OpenFollow
OpenFollow sends OSC to Companion through an OSC Destination, from trigger zones and OSC Transmitters.
- In Companion, open Settings → Protocols and switch on OSC Listener. Note the OSC Listen Port (default
12321). - In OpenFollow, add a destination under Output → OSC Destinations: the Companion computer's IP (
127.0.0.1on the same Pi), port12321, UDP.
Keep port 12321 free. Don't enter Companion's OSC Listen Port as the Source Port of the OSC connection (Listen for Feedback). The connection then holds the port and Companion's OSC Listener can't open it.
Companion addresses a button by page, row and column, as shown on its button grid. Rows and columns count from 0: 1/0/2 is the third key in the top row of page 1. The button must already exist.
Turn a key red while anyone is in a zone, black again when it is empty.
- In Companion, open the key's Options tab and switch on Allow style changes. Without it, the key ignores colour commands.
- Select the zone under Markers & Zones → Zone Editor and open its Settings tab. Set OSC Destination to the Companion destination.
- Fill in First Entry Address and Final Exit Address, and leave the other two blank:
First Entry Address: /location/1/0/2/style/bgcolor 255 0 0
Final Exit Address: /location/1/0/2/style/bgcolor 0 0 0
Switch Trigger zones on under Markers & Zones → Trigger Zones.
Show marker 2's X position on a key.
- In Companion, add a custom variable
marker2_xunder Variables → Custom Variables. - On a key, switch the text to expression mode and enter
toFixed($(custom:marker2_x), 2). OSC carries the position as a float, so1.23arrives as1.2300000190734863;toFixedrounds it to two decimals. - In OpenFollow, add a transmitter under Output → OSC Transmitters: Default markers
2, Destination the Companion destination. - On its Trigger tab, choose Stream, Rate (Hz)
5, Send only on change. - On its Settings tab, enter the message, then switch the transmitter on and click Save:
/custom-variable/marker2_x/value [x]
Add a transmitter per axis for Y and Z.
Let the operator fire a Companion button from the gamepad.
- Add a transmitter under Output → OSC Transmitters with the Companion destination.
- On its Trigger tab, choose Controller button, a free button, and Press.
- On its Settings tab, enter the message, then switch the transmitter on and click Save:
/location/1/0/4/press
A Hotkey trigger does the same from the keyboard.
Companion's full OSC command list is in its OSC Control guide.