dpx-buttonode manual · v0.8.0 GitHub ↗
user manual — not developer docs

Flash it. Plug in a Stream Deck. Power on.

dpx-buttonode turns an ARM single-board computer — or a real Raspberry Pi 4/5 — into a Bitfocus Companion Satellite node, a full Bitfocus Companion instance, or a Bitfocus Buttons USB Relay, switchable at runtime with no re-flash. This page covers using a built device day to day. For build pipeline internals, contributing, or CI details, see the developer README.

Read the quickstart
Latest recommended release checking… all releases ↗
looking up the latest build…
01

Quickstart

Three steps, no configuration required for the common case.

1 — Flash

Grab the .img.gz for your board from Releases and write it with Balena Etcher (handles the .gz automatically), or dd from a terminal. Pick lite (Buttons + Satellite) or full (adds Companion itself).

2 — Plug in

Insert the SD card, connect an Elgato Stream Deck via USB, connect Ethernet, then power on. First boot takes roughly 30 seconds.

3 — Done

The device boots into Satellite mode by default. Open Bitfocus Companion and add it as a Satellite surface — or open http://dpx-buttonode-XXXX.local:8080 to configure it.

Hostname Every device gets a stable hostname derived from its Ethernet MAC address: dpx-buttonode-XXXX.local, where XXXX is the last four hex characters of the MAC. The same physical board always gets the same name, so it's safe to bookmark.

Go to Releases ↗

02

Hardware

Two separate build pipelines feed the same on-device software — pick the release that matches your actual board.

Non-Pi ARM SBCs

Armbian base image

Rock Pi S, Orange Pi Zero 3, Rock Pi 4B/4B+, Rock S0 — auto-built on every Buttons release. 150+ other Armbian-supported boards can be built on demand. These are Rockchip/Allwinner/Amlogic boards; Armbian is built specifically for this hardware family.

Raspberry Pi 4 / 5

Official Raspberry Pi OS — never Armbian

Real Pi hardware runs the official Raspberry Pi OS Lite (64-bit), the same image Raspberry Pi Imager uses — not Armbian's rpi4b/rpi5b dropdown entries. Armbian's Pi support is secondary to the boards it's actually built for, which matters for GPU/HDMI/VideoCore (relevant if you plan to run Dashboard). One universal image covers both Pi 4 and Pi 5.

Stream Deck compatibility

Any Elgato Stream Deck supported by the streamdeck Python library works, over USB. The on-device boot splash (below) adapts its layout to the deck's key count — a 2-row Mini shows IP and hostname only, while a 3-row deck (Original, MK.2, XL) unlocks the full stage-then-GO config screen with mode/network controls, SSH password reveal, and the Dashboard toggle key.

Companion Dashboard needs a real display

Requires attached HDMI display Companion Dashboard is an X11/Electron kiosk — it needs a real screen with GPU-backed video output. It will not run usefully on a headless board with no display attached (e.g. a Rock Pi S doing Buttons-relay duty in a rack). See Dashboard below for the low-RAM warning threshold as well.
03

The Stream Deck config screen

stage → review → GO

Before Buttons, Satellite, or Companion claims the attached Stream Deck, the device draws a live configuration screen directly onto its keys — no web UI or SSH required for first setup. Everything you press stages a pending change; nothing is actually applied to the system until you press GO. This is deliberate: a single mis-press of MODE or NET can't switch anything by itself.

MODE Short press cycles the pending mode candidate: Buttons → Satellite → Companion (skips Companion if the Full variant isn't installed). Shown as a colored label (BTN/SAT/CMP). Never commits by itself.
NET Short press toggles the pending network choice between DHCP and STATIC, shown as the actual word. Never commits by itself.
SUBNET Cycles the pending prefix length through /24 → /22 → /16 → /8. Only meaningful when STATIC is staged, but harmless to change regardless.
octets The four IP-octet keys in the top row are editable only while STATIC is staged. Hold one down to spin its value 0–255; release to lock it in. While DHCP is staged, these keys are locked and dimmed — there's nothing to build a static address out of.
SSH Press-to-toggle reveal, not always-on-display. At rest it shows a neutral "SSH" hint. Press it once and it shows the actual random root password generated at first boot; press again to hide it. This is the only place that password is ever shown — not the web UI — because revealing it should require physically being at the device, not just LAN access. Goes blank once you've set a real password from the web UI's SSH tab. Only present on decks with 5 or more columns.
GO The only key that actually changes anything. One press commits everything currently staged as a single combined operation: a mode switch if the candidate differs from the active mode, and a network change if DHCP/STATIC differs from the live state. Flashes a checkmark to confirm the press registered — the deck's screen typically goes dark for a moment right after, because switching modes restarts the service that owns the USB device.
D Only shown if Companion Dashboard is installed on this image. Press-to-toggle: turns Dashboard on or off directly from the device, no web UI needed. Red when Dashboard is actually running, dark gray when installed but off — it reflects real service state, not just "was it toggled on."

The rest of the screen is informational: the live DHCP/static IP address across the four octet keys (plus the web UI's port, :8080, alongside them), and the device's mDNS hostname spelled out across the second row.

04

Switching modes

All three modes are installed on every image (Companion only on the Full variant) — switching is instant and requires no re-flash. Use the deck's MODE + GO keys, or the web UI's Mode tab at http://dpx-buttonode-XXXX.local:8080.

Buttons

USB Relay mode

Runs Bitfocus Buttons USB Relay, exposing the attached Stream Deck as a physical relay controller. Announces itself on port 3040 via mDNS — Buttons finds it automatically, no configuration needed for most setups.

Satellite

Companion Satellite mode

Connects outbound to a running Bitfocus Companion instance elsewhere on the network and exposes the Stream Deck as a remote surface. Needs Companion v3.4.0+ with Settings → Surfaces → Enable Satellite turned on, and TCP port 16622 reachable. Set the Companion server IP/port from the Mode tab. This is the default mode on a fresh image.

Companion

Full Companion mode

Runs full Bitfocus Companion itself on the device — only available on the full image variant. Companion's own web UI runs on port 8000. Useful for a standalone, all-in-one control surface with no separate Companion host needed.

A stuck mode after a crash still shows "already active" The persisted mode file (/etc/dpx-mode) records intent, not live state — if a mode's service dies (a crash, or a reboot right after one), the device now checks whether the service is actually running before treating "same mode selected" as nothing-to-do, and relaunches it. If you're on a build older than this fix and a mode seems dead, re-select it and press GO (or use the Mode tab's Switch button) again — it'll restart the service either way.
05

Network

DHCP is the default. Static IP is available from either the deck or the web UI, and both persist across reboots.

From the Stream Deck

  1. Press NET to stage STATIC.
  2. Press SUBNET to cycle to the prefix length you want (/24, /22, /16, or /8).
  3. Hold each octet key to spin its value; release to lock it in.
  4. Press GO to commit.

From the web UI

Open the Network tab and switch between DHCP and static there instead. After an IP change, navigate to the new address directly — the mDNS hostname (dpx-buttonode-XXXX.local) resolves again within a few seconds.

Fixed — network settings not persisting An earlier build had network settings fail to survive a reboot on some Armbian boards using NetworkManager instead of systemd-networkd. This is resolved — settings written from either the deck or the web UI now persist correctly across reboots on all supported boards.
06

Companion Dashboard

Companion Dashboard is an opt-in kiosk display that runs alongside whatever mode is currently active (Buttons, Satellite, or Companion), on units with a real HDMI display attached. It's installed on every image but disabled by default.

Enable it

  1. Open the web UI's Mode tab, find the Companion Dashboard section, and click Turn On — or press the deck's D key if your deck has one.
  2. Dashboard boots into its own first-run screen on the attached display. Point it at your Companion instance from there — Dashboard manages its own connection settings independently of this project.
  3. Use Toggle Fullscreen in the web UI to send F11 into the running kiosk remotely — no keyboard needed at the physical display.
Needs a real display, and real RAM Dashboard needs an attached HDMI display with GPU-backed video output — it will not work on a headless board. A non-blocking warning appears in the web UI on boards reporting under 1 GB of RAM: Dashboard's X11/Electron stack needs real headroom to run reliably alongside a mode service. It's still your call whether to enable it in that case — the warning just sets expectations.
Fixed — Dashboard not surviving a reboot An earlier build had Dashboard's autostart flag not persist correctly, so it wouldn't come back after a reboot even when it had been turned on. This is fixed — Dashboard's on/off state now survives reboots, and the deck's D key reflects the service's actual running state rather than just whether it was toggled on.
07

Troubleshooting

real fixes from real hardware

Everything below was found and fixed on physical devices, not simulated. Items marked fixed should not recur on a current build; items marked known issue are open as of the current recommended release (v0.8.0).

Stream Deck not picked up after a mode switch

fixed

After heavy mode-switch activity, the kernel could still see the Stream Deck (bound to hid-generic) while udev never (re)created its /dev/hidraw* device node — invisible to Companion's hidraw-only driver even though libusb-based tools (the deck splash, Satellite) still worked fine. The fix re-triggers udev (udevadm trigger for both the HID and USB subsystems) automatically before every mode's service starts, which resolves this without a physical replug in the common case. If a Stream Deck still doesn't show up in Companion after switching to Companion mode, try the web UI's Devices tab, which offers a manual USB power-cycle as a fallback.

Network settings not surviving a reboot

fixed

On Armbian boards using NetworkManager rather than systemd-networkd, a static IP or DHCP choice set from the deck or web UI could silently revert on the next boot. Persistence now works correctly across both network stacks. If you're still seeing this, confirm your build is current — it should not reproduce on the recommended release.

Dashboard didn't come back after a reboot

fixed

See the callout in the Dashboard section above — the autostart flag now persists correctly, and the deck's D key shows the service's real running state.

The deck seems stuck / unresponsive

The Stream Deck's screen isn't live video — it holds whatever image was last drawn. A few things to check, in order:

  • It just switched modes. A successful GO press restarts whichever service now owns the device, which briefly (and sometimes visibly) claims the USB connection. Give it a few seconds — the splash screen only comes back if a mode isn't currently claiming the deck.
  • A mode is already active. Once Buttons, Satellite, or Companion has claimed the Stream Deck, the boot splash intentionally steps aside — that's expected, not a hang. Use the web UI to change settings at that point instead of the deck.
  • Genuinely unresponsive keys. Try a physical USB replug. If that doesn't help, the web UI's Devices tab has a USB power-cycle action as a further fallback.

D key doesn't reliably launch Dashboard or reflect its state

known issue — #17

On the current recommended release, the deck's D key can be unreliable about actually launching Dashboard or showing its true running state. If pressing D doesn't seem to work, use the web UI's Mode tab toggle instead — it's the more reliable path for now.

Splash-recovery hasn't been deliberately crash-tested

known issue — #11

The mechanism that brings the boot splash screen back after a mode's service dies is live and running in production, but hasn't yet been put through a deliberate crash/reboot test. It's expected to work; if you hit a case where the splash doesn't reappear after a service actually goes down, that's useful information for an issue report.

Can't get in over SSH

SSH ships disabled with no hardcoded credential. On first boot a random root password is generated automatically — the only place it's ever shown is the Stream Deck's SSH key (press to reveal, press again to hide). If you don't have a deck attached, connect one temporarily just long enough to read the password, enable SSH and set your own password from the web UI's SSH tab, then disconnect if you like. There is currently no remote way to recover the generated password by design — see the web UI's SSH tab and the README's SSH section for the full model.

Didn't find your issue here? Check the latest release notes for the current known-issues list, or open an issue.

08

Updates

Every device can update itself in place from the web UI's Updates tab — no re-flash needed for routine updates.

Web UI

Updates the config interface itself (dpx-buttonode-ui.py) in place.

Buttons

Pulls the latest mirrored Bitfocus Buttons USB Relay package and reinstalls it.

Satellite

Rebuilds Companion Satellite from source via the official installer.

Companion

Full-variant only. Companion's real update source is Bitfocus's own hosted package API — the Updates tab checks and applies from there directly, not from GitHub.

Open the Updates tab, check for a new version of whichever component you're interested in, and apply it. The device stays on its current mode and settings through the process.