26.3 26.2 26.1 25.3 25.2 25.1 24.3 24.2 24.1 23.4 23.3 23.2 23.1
26.3 26.2 26.1 25.3 25.2 25.1 24.3 24.2 24.1 23.4 23.3 23.2 23.1

Using Bitfocus Buttons with Pixotope

Bitfocus Buttons can drive Pixotope from hardware control surfaces such as an Elgato Stream Deck. The Pixotope (Gateway API) module sends each key press to Pixotope Gateway, which passes it on to a control panel, the Engine or any other Pixotope service. The same module also works in Bitfocus Companion 4.x.

This page covers the setup both workflows share. Then continue with the workflow that fits your show.

Learn more about How to use Pixotope Gateway

Prerequisites

  • Pixotope 26.3 or later, with Director running and a project open

  • Pixotope Gateway reachable from the Buttons machine on port 16208

    • Gateway is started and stopped with Director. Closing Director shuts down Gateway and the other Pixotope services, and every key stops working

  • Bitfocus Buttons 1.8.10 or later, installed on the machine the Stream Deck is connected to. The Pixotope module (v1.1.0 or later) ships with it, see Install Buttons below

  • A Stream Deck (or another supported surface) connected to the Buttons machine

Choose an approach

Approach

How it works

Use it when

Requires

Trigger control panel actions

Each key fires a Remote Call on a control panel, which clicks one of the panel's buttons

The show logic already lives in a control panel, or operators use the panel and the Stream Deck side by side

The control panel open in LIVE mode

Control Engine and Director directly

Each key calls a Blueprint event, sets a property or changes a Store value directly

You need a few quick actions without a panel, or want live values shown on the keys

The level open. Events that depend on BeginPlay or runtime state need LIVE mode. Object names are hard-coded in Buttons, so renaming or re-placing an actor breaks its keys

Both approaches can be mixed on the same Stream Deck.

Set up Buttons

Install Buttons

  1. Download Bitfocus Buttons from bitfocus.io and run the installer with the default settings

  2. Close the Elgato Stream Deck app if it is installed. It holds the device, and Buttons cannot use it while that app runs

  3. Start Buttons. The user interface opens in a browser at http://localhost:4440

  4. Create the local user account it asks for, then sign in

    • The account is local to this Buttons install, not a Bitfocus cloud account. Operators need these credentials on show day

  5. The dashboard lists No positions, No surfaces and No connections on a fresh install

Check the Pixotope module

The Pixotope module ships with Buttons 1.8.10 and is installed on first launch. Older installs may not have it, or have a version older than 1.1.0.

  1. Go to Connect > Connection and click + Add (1)

  2. Type pixotope in the search field of the Add Connection Type dialog

    • The search also lists modules with similar names. The Pixotope row shows the installed module version in its dropdown (2)

  3. If Pixotope is missing or older than 1.1.0, click Download modules (3)

    • The Upgrade Modules dialog lists every module with a newer version available

    hub_00a_add_connection_type-20261104-123914.png
  4. Click Download

    • All listed modules are downloaded, Pixotope included. They are small, so there is no need to pick them individually

    hub_00b_upgrade_modules-20261104-123914.png
  5. Click Close and check the Pixotope version again

Downloading a new module version does not upgrade existing connections. Select the connection under Connect > Connection, pick the new version in the Module dropdown and click Save.

Add the Pixotope connection

  1. In Buttons go to Connect > Connection

  2. Click + Add, then Add → on the Pixotope row

  3. In Create Connection, keep the Label Pixotope and click Create. Close the Add Connection Type dialog

    • The label becomes the connection's Variable Key, which the $(Pixotope.…) variables on the following pages assume is Pixotope

  4. The connection opens on its Variables tab and connects with the default settings right away when Buttons runs on the Pixotope machine. To change a setting, open the Config tab, edit it and click Save

    • The connection header turns green and shows Connected once Gateway responds

    • If it stays red, check that Director is running on the Gateway machine and that the IP and port are right

    hub_01_connection_settings-20261103-145803.png

Setting

Default

Description

Gateway IP

127.0.0.1

IP address of the Pixotope machine running Gateway

Gateway Port

16208

Port Gateway listens on

Gateway API Version

2.2.0

Version segment of the publish URL. Leave as default

Default Engine Target

~LOCAL~-Engine

Engine used when an action does not name a target

Live Value Poll Interval

1000 ms

How often live values shown on keys are refreshed

Connection Check Interval

5000 ms

Heartbeat used while no live values are shown. 0 disables it

The module has no passkey setting. Keep the Gateway passkey empty when using Buttons, otherwise its requests are rejected.

Learn more about Passkey protection

Assign the Stream Deck to a position

A Position is the page of keys a surface shows.

  1. Go to Connect > Surface

  2. Click Discovered surfaces and select the Stream Deck

  3. Click Adopt → Create Position, enter a Label for the new position, for example Studio A, and click Adopt → Create

  4. Check that Assigned to Position shows the new position and that Brightness is above 0

    hub_02_surface-20261103-145803.png

If the Stream Deck stays dark, check Brightness in the same panel.

Create a key

  1. Go to Position and click Edit on your position

  2. Select an empty key and press B

    • Or right click the key and click Create > Button

    hub_03_create_button-20261103-145803.png
  3. In the Inspector on the right, open the Actions tab (lightning icon)

  4. Under Press, click Add Action… and type Pixotope to list the module's actions

    hub_04_add_action-20261103-145803.png
  5. Fill in the action. The options depend on the approach, see the pages below

    • With more than one Pixotope connection, pick the right one in Connection

  6. Open the Design tab (brush icon)

    1. Remove the icon and enter the key Text (1)

    2. Set a Background Color (2)

    hub_05_style-20261103-145804.png
  7. Click Apply at the top of the editor

    • The key appears on the Stream Deck

Duplicate keys

  1. Select a finished key and press Ctrl+C

    • This replaces the clipboard, so paste any copied URL first

  2. Select an empty key and press Ctrl+V

    hub_06_paste-20261103-145804.png
  3. Change only what differs, for example the action target, Text and colour

  4. Click Apply

Test a key

  1. Click the lightning icon on the action header to run the action once, without the hardware

    • Variables are resolved the same way as on a key press

    hub_07_run_action-20261103-145804.png
  2. Go to Connect > Connection, select the Pixotope connection and check Connection Logs

    • Each request is logged as Gateway request {…} -> 200 together with its HTTP status

    • The Debug filter is on by default but drawn grey. If no request lines show, click Debug to turn it on

    hub_08_connection_logs-20261103-145804.png

Status 200 means Gateway accepted the request. It does not confirm that the target reacted. A misspelled function name or a control panel that is not open in LIVE mode also returns 200. Always check the result in Pixotope as well.

To see whether the target reacted: a Blueprint event that prints to the log shows up in the Engine Output Log, a property can be read back by opening its GetProperty URL in a browser, and a Store value by opening the Store URL with the full path, see the pages below. A Director Health call only returns a status, so nothing is visible in Pixotope.

Next steps