companion-buttons/README.md

Companion Buttons

A ProdDash module that shows any button from Bitfocus Companion — any page, any button — on a dashboard tile, exactly as Companion draws it: colours, text, icons and live feedback. It is meant for status buttons and anything else that says what is happening right now.

• One tile, one or many buttons. A single button fills the tile; several share it in whatever grid makes each one biggest, and resizing the tile re-flows them.
• Live. Every time Companion redraws a button (a status turning red, a tally lighting up), the tile shows it. Identical redraws — a status page that repaints every second with the same picture — are not re-sent.
• Read-only. Nothing in the module can press a button or change anything in Companion.

Using it

1. Admin → Companion Buttons: enter Companion's address — the machine running Companion and its web interface port (8000 unless changed in Companion's settings). Use 127.0.0.1 when Companion runs on the same machine as ProdDash.
2. ＋ Add tile → Companion Buttons. A new tile opens the picker: choose a page from the list and tap the buttons to show. The numbers on the picked buttons are the order they appear in. Done shows them.
3. To change the buttons later, use the grid icon in the tile's title bar. The gear has one switch, Captions, which writes the page name under each button.

Hover a button for its page and Companion location (page/row/column).

What a tile follows

Each picked button is saved with its Companion id and its page, row and column. While Companion still has that button anywhere, the tile follows it, so dragging it to another spot or inserting a page in front changes nothing. If the id is gone — a page re-imported from a .companionconfig gives every button a new id — the tile shows whatever is at the saved page, row and column instead. Either way the tile saves back what it found, so it stays current.

A button that is gone with nothing at its place shows Not in Companion, and the status dot turns amber.

When Companion is down

The status dot turns red, the tile says Companion offline and fades the last pictures to grey, so nobody reads them as live. ProdDash keeps retrying (1, 2, 5, then every 10 seconds) and the tile recovers by itself.

How it works

Companion 4 and 5 have no HTTP route that returns a button's picture. Their own web buttons and emulator get them from the tRPC websocket on the web interface port (ws://<host>:<port>/trpc). The module's server holds one such connection for all dashboards and uses two read-only subscriptions: pages.watch (pages, names, which button is where) and preview.graphics.controlId (a button's PNG, on every redraw). That is Companion's internal API rather than a documented one, so a future Companion release could change it; it was built and tested against Companion 5.0.7.

Route	What it serves
GET /pages	Every page and the buttons on it — the picker's list
GET /image/<id>	One button's current picture as PNG — picker thumbnails
GET /stream/<page.row.column.id>/…	SSE button events for a tile's buttons: all of them on connect, then each redraw or move

A tile holds one stream for all its buttons, because ProdDash carries at most 32 streams per page and a status board can show more buttons than that.

Requirements

• ProdDash 1.10.0 or newer.
• Node.js 22 or newer for the built-in WebSocket. The packaged macOS app and the Windows bundle ship Node 24; on an older Node the admin page says so.
• Companion 4 or newer, reachable from the ProdDash machine.
• No dependencies, nothing to install.

Files

File
module.json	Manifest
server.js	Routes, button subscriptions, the per-tile streams
companion.js	The connection to Companion's tRPC websocket and the page list
client.js, style.css	The tile and its picker
test/companion.test.js	Tests: node test/companion.test.js
test/companion-mock.js	A stand-in Companion: node test/companion-mock.js 18000, then point the module at 127.0.0.1 port 18000

Installing

This module lives in its own repository rather than in ProdDash's catalog, so Available modules in the admin page does not list it. Install it the way the module guide allows for any module: copy this folder (without .git) into the ProdDash data directory as modules/companion-buttons/ and restart ProdDash.

OS	Folder
macOS	~/Library/Application Support/ProdDash/modules/companion-buttons/
Windows	%APPDATA%\ProdDash\modules\companion-buttons\

To update, replace the folder's files and restart. Bump version in module.json with every change.