OpenFollow Preview

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

  1. Open Connections and add Generic: OSC.
  2. Set Target Hostname or IP to the station's IP, or 127.0.0.1 when Companion runs on the station. Use an IP, not localhost.
  3. 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:

ButtonCompanion actionOSC PathValue / Arguments
Preset positionSend message with multiple arguments/marker/21.5 -2.0 0.0
Set one axisSend float/marker/2/z1.2
ParkSend message without arguments/marker/2/park–
UnparkSend message without arguments/marker/2/unpark–
Cue cardSend message with multiple arguments/message"Standby downstage" "Q 51" 2 8
Clear cardsSend 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 (0 for every station) and the seconds it stays up (0 until 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.

  1. In Companion, open Settings → Protocols and switch on OSC Listener. Note the OSC Listen Port (default 12321).
  2. In OpenFollow, add a destination under Output → OSC Destinations: the Companion computer's IP (127.0.0.1 on the same Pi), port 12321, 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.

  1. In Companion, open the key's Options tab and switch on Allow style changes. Without it, the key ignores colour commands.
  2. Select the zone under Markers & Zones → Zone Editor and open its Settings tab. Set OSC Destination to the Companion destination.
  3. 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.

Companion's full OSC command list is in its OSC Control guide.