Elgato Stream Deck 3D Printer Control with Bitfocus Companion

What you’ll need

  • Raspberry Pi 4B or newer (recommended) with a good power supply
  • microSD card + network connection
  • Elgato Stream Deck (any supported model) + USB cable/adapter as needed
  • A computer/phone on the same network to access Companion’s web UI
  • A working Home Assistant instance (local or remote)

Bitfocus’s own CompanionPi project is geared around arm64 and recommends Pi 4B+ for best results. 

Installation of the CompanionPi Image

1. Download the CompanionPi image

  • Go to the Bitfocus CompanionPi page/download (prebuilt image).
  • Download the Raspberry Pi image that matches your hardware.
  • (CompanionPi is explicitly intended as a “prebuilt image…setup to run Bitfocus Companion.”) 

2. Flash it to your SD card

  • Use Raspberry Pi Imager or Balena Etcher
  • If using wifi, set up the config in Raspberry Pi Imager
  • Flash the image
  • Eject safely

3. First boot

  • Insert SD/SSD into the Pi
  • Plug in Ethernet if possible (best for reliability)
  • Power it on
  • Give it a couple minutes to fully boot

4. Find the Pi on your network

  • Pick one:
    • Check your router’s DHCP clients list
    • Use a network scanner app
    • If you use mDNS, try resolving the hostname if the image provides one

5. Open Companion in a browser

  • From your laptop/phone: open the Companion web UI (CompanionPi typically exposes a web interface on your LAN).
  • If you can’t find the port, don’t guess endlessly—jump to Troubleshooting → “Can’t reach the web UI”.

6. Plug in the Stream Deck

  • Plug the Stream Deck into the Pi (not through a sketchy unpowered hub)
  • The device should be detected by Companion as a controller

  • If it’s not detected, it’s usually permissions/udev rules—see Troubleshooting → “Stream Deck not detected”.

Home Assistant: Create a Long-Lived Access Token

Companion’s Home Assistant Server connection uses a token and talks to HA over its API (HA’s WebSocket API endpoint is /api/websocket). 

1. In Home Assistant

  • Click your Profile (bottom left in HA UI)
  • Scroll down to Long-Lived Access Tokens
  • Create a token, copy it somewhere safe

Bitfocus’s HA module instructions point you to the Profile page and Long-Lived Access Tokens section. 

Companion: Add the Home Assistant Connection

1. In Companion, open Connections

  • Add a new connection/module: Home Assistant Server
  • Enter your Home Assistant base URL (example: http://homeassistant.local:8123 or http://<HA_IP>:8123)
  • Paste your Long-Lived Access Token

Bitfocus’s connection page specifically describes pasting the token into the Home Assistant Server module settings. 

2. Confirm it connects

  • You should see the instance go “OK/Connected”
  • If it fails, see Troubleshooting → “Home Assistant won’t connect”

Create Stream Deck buttons to Control Home Assistant

  • In Companion, you’ll usually work in:
    • Buttons (what happens when you press)
    • Feedbacks (how the button looks depending on state)
    • Variables (text you can show on the button: state, attributes, etc.)

The HA module supports variables for entity names and (in newer versions) entity attributes. 

Example 1: Toggle a chamber light + show ON/OFF

  • Go to Buttons
  • Select a button location (page/grid)
  • Add an Action:
  • Home Assistant → Toggle (or Call Service: light.toggle)
  • Entity: light.bambu_chamber_light (example)
  • Add Feedback:
  • Home Assistant → Light state feedback (or Boolean-style feedback)
  • Configure:
  • When ON: change background color / add “ON” style
  • When OFF: different style

Example 2: Run a script / automation

  • Button → Action:
  • Home Assistant → Call Service
  • Service: script.turn_on
  • Entity: script.toggle_all_3d_printer_power(example)
  • Optional: Feedback to indicate “running” (if your entity supports it) or show last run timestamp via a sensor/template.

Example 3: Display a sensor value (temperature, humidity, power, etc.)

  • Button → set a label like:
  • Office
  • Then on the next line insert a variable for the sensor’s state

Tip: Use Companion’s variable picker to insert the exact token format

A commonly requested format for attributes looks like:

$(homeassistant-server:entity.media_player.<name>.attributes.<attr>.value) 

…and the module’s changelog indicates attribute variables are supported in newer versions. 

If you don’t want to deal with attributes, make a Template Sensor in Home Assistant and display its state instead (cleanest long-term approach).

Make it feel "smart:" Pages, Folders, and Safety

Organize pages

Common layouts:

  • Page 1: “Daily drivers” (print progress, layer number, power toggle)
  • Page 2: Climate (temperature, humidity, air quality)
  • Page 3: Scenes & scripts

Add confirmation for risky actions

  • For things like "power toggle printer"
  • Use Companion’s button confirmation / press-and-hold style if available
  • Or require a two-step: press to arm → second press to execute

Troubleshooting

Stream Deck not detected by Companion

Most common causes:

  • USB power/hub issues (try direct connection)
  • Linux permissions/udev rules

Bitfocus issues commonly point to ensuring the proper udev rules are installed (often referenced as /etc/udev/rules.d/50-companion.rules). 

Practical checks:

lsusb | grep -i elgato
sudo journalctl -u companion -n 200 --no-pager

Home Assistant Won't Connect

Common causes:

  • Wrong base URL (missing scheme, wrong port, wrong host)
  • Token pasted incorrectly
  • HA is HTTPS but you used HTTP (or vice versa)
  • Network routing/VLAN rules

Remember: HA’s WebSocket API lives at /api/websocket. The Bitfocus HA connection expects a Long-Lived Access Token from your HA Profile. 

Can’t reach the Companion Web UI

Confirm service is running:

sudo systemctl status companion --no-pager

Check what IP the Pi got:

ip addr

If needed, open firewall (if you installed one) or verify LAN access.

Back to blog