Companion Module

The FrenschPress module for Bitfocus Companion reverses the direction: instead of the FrenschPress operating Companion, Companion operates the FrenschPress. One show button in Companion can then start the video and switch the FrenschPress to set B, colour its LEDs or arm a timeline.

Route	Who drives whom	Documented under
Companion Mode / Satellite	The FrenschPress (and optionally a Stream Deck attached to it) acts as a surface for Companion	Companion Mode, Stream Deck as a Companion surface
Companion module	Companion controls the FrenschPress	this page

You can combine the two: Companion uses one FrenschPress as a surface and controls another as a device.

---

Installation

The module comes as a package file (.tgz) for download.

1. In Companion, open Settings → Modules → Import module package.
2. Select the .tgz file.

Once the module is in the Bitfocus module store, you no longer need to import it. Searching for FrenschPress is then enough.

note

A version installed from the store takes precedence over an imported one. Once the store version is available, remove the imported build.

Setting up the connection

Requirement: Companion and the FrenschPress can reach each other on the same network. The module speaks OSC over UDP.

1. Add a new connection in Companion.
2. Choose FrenschConnection FrenschPress.
3. Pick the FrenschPress under Discovered devices, or enter Host and Port by hand.
4. Save. If the connection stays red, see Troubleshooting.

Field	Meaning	Default
Discovered devices	FrenschPress units announcing themselves on the network. Picking one fills in host and port.	–
Host	IP address or hostname of the device	–
Port	The device's OSC input port	53001
HTTP port	Used only to read the device's preset list. No login required.	80
Poll device status	Queries the device state at regular intervals. Off: no variables and no feedbacks, the module only sends.	–
Poll interval (ms)	Time between queries	1000

Discovery is optional

The device list comes from mDNS. mDNS does not cross a VLAN boundary and often fails when Companion runs inside a Docker container. Entering host and port by hand is a normal way to set this up, not a workaround.

---

Actions

Action	What it does
Set mode	Switches between QLab, Custom and Companion
Switch button set	Switches to set A, B or C, optionally for selected buttons only
Apply preset	Loads a preset. The list is read from the device; you can also give a preset by name or through a variable. Optionally into a specific set.
Press a FrenschPress button	Fires STOP, GO or PAUSE virtually, as tap, press or release
Run a macro	Starts a macro by name or ID. on, off and toggle apply to snapshot macros.
Arm timeline / Disarm timeline	Arms or disarms one timeline, by number, name or ID
Arm all timelines / Disarm all timelines	The same for every timeline at once
Set LED colour	Colours one LED (STOP, GO, PAUSE or all) from the colour picker
Release LED override	Hands the LED back. It then shows its normal colour again.
Stream Deck: press a key	Fires a key on the attached Stream Deck by row and column
Stream Deck: set key feedback	Sets a deck key's state: a single key, row/column, all keys, or everything back to local
Set device variable	Writes a value into a variable on the FrenschPress
Clear device variable	Clears one variable by name
Clear all device variables	Clears all 64 variables at once

The module reads the dropdowns for Apply preset and Arm / Disarm timeline from the device and refreshes them once a minute, so a newly added preset or timeline shows up on its own. Both fields also accept free text: a number, display name, ID or a Companion variable. If the device is unreachable over HTTP, the list stays empty, but a typed value is still sent.

Feedbacks

Feedback	True when
Mode is	the device is in the selected mode
Button set is	the selected set is active, either for the whole FrenschPress or for a single button
QLab has running cues	at least one cue is running in QLab
QLab is paused	QLab is paused
Sync variable to FrenschPress	No visual effect. Continuously mirrors a Companion variable into a device variable.

---

Setting a device variable from Companion

The FrenschPress can insert variables into Stream Deck captions: a key reading CUE $cue shows whatever cue currently holds. Companion is the most convenient way to fill those values.

Once, on press: Set device variable

The action takes a Name and a Value. Both fields accept Companion variables, and Companion resolves them before sending. The FrenschPress always receives a finished string and knows nothing about Companion.

Name:  cue
Value: $(internal:time_hms)

A deck key captioned $cue then shows the new value each time the action fires.

Rule	Value
Name	1–24 characters of A-Z, a-z, 0-9, _
Reserved names	anything starting with sys_ belongs to the device and is refused
Value length	over 48 characters the device truncates without warning
$$ in a caption	reserved, and refused when saving

Continuously: the Sync variable to FrenschPress feedback

If a value should stay current by itself rather than being tied to a button press, add the feedback to any Companion button. Give it a fixed FrenschPress name and an expression as its value. It does not change how the Companion button looks.

Companion reruns a feedback whenever a variable it references changes. The module coalesces rapid changes and sends at most ten updates per second, always the newest value only.

The module also reasserts its mappings slowly: one per second, and no more often than once every ten seconds per mapping. After a FrenschPress reboot, the device variables are therefore refilled on their own without every mapping going out in one burst.

The feedback is active as long as it exists. Delete it and the mirroring stops.

Clearing

Clear device variable removes one variable. If a caption references it, only that $name drops out: CUE $cue becomes CUE , and a caption that is only $cue goes blank. The text in the editor is untouched.

Clear all device variables wipes all 64 at once and has no options.

Check older buttons from version ≤ 0.4.0

Up to 0.4.0, "clear all" was the same action as "clear one", triggered by leaving the Name field blank. That was also the default of a freshly added action. A Clear device variable with a blank name now clears nothing. If a button relied on that, switch it to the dedicated Clear all device variables action.

---

Variables

The module provides these Companion variables under $(frenschpress:…):

Variable	Contents
device_name · fw · mac · ip	Device name, firmware version, MAC address, IP address
mode	qlab, macro or companion
transport · midimode	QLab transport (osc/msc) and the internal transport code
set_active	Active button set
set_buttons	Eight letters, one set per button, in the order stop, go, pause, encoder push, left, right, push+left, push+right
qlab_running · qlab_paused · qlab_subscribed	QLab state: running, paused, feedback subscribed

note

After a masked set switch the buttons can sit on different sets. set_active then only reflects the last switch that covered the whole FrenschPress. set_buttons is the accurate value in that case.

These are Companion variables and have nothing to do with the device variables stored on the FrenschPress. To get from one kind to the other, use the action or the feedback described above.

Bundled buttons (presets)

Ready-made Companion buttons with matching feedbacks: Mode QLab / Macro / Companion, Set A / B / C, STOP / GO / PAUSE, QLab running, QLab paused, plus two LED buttons (hold a colour while pressed, and release).

---

Troubleshooting

Symptom	Cause	Fix
No variables, no feedbacks	Poll device status is off	Switch it on
Connection stays red	Wrong host or port	The port must match the device's OSC input port
Preset list empty	Wrong HTTP port, or the device is not reachable over HTTP	Check the HTTP port and reachability
State updates sluggishly	Poll interval too long	Reduce the poll interval, minimum 250 ms

note

The FrenschPress answers status queries at most once every 100 ms per sender, so a poll interval below 250 ms gains you nothing.