christianandClaude Opus 5.5
415453ef5f
A ProdDash module for status buttons and what's happening: pick buttons from any Companion page in the tile's own picker; each is shown exactly as Companion draws it and redraws live. One tile can hold one button or many. - One read-only connection to Companion's tRPC websocket (pages.watch and preview.graphics.controlId), shared by every dashboard; identical redraws are not re-sent. - A tile follows its button by id, and by page/row/column when the id is gone (a re-imported page), saving back what it resolved to. - One SSE stream per tile, within ProdDash's 32-streams-per-page limit. - Red dot and a faded "Companion offline" view when Companion is down; recovers by itself. - Tests against a mock Companion: node test/companion.test.js Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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
- 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.1when Companion runs on the same machine as ProdDash. - ＋ 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.
- 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.