christianandClaude Opus 5.5
0a6cec88aa
The picker row (page list, Clear, Done) is gone. Each Companion page is now its own ＋ entry, titled with the page's name, showing the whole page minus page up/down. The grid icon switches the tile to choosing: click buttons to take them out or put them back, click the icon again when done. The gear holds one switch, Page layout (Companion's rows and columns, or packed). - Tiles follow their page by Companion's page id and buttons by row/column, so inserted pages and re-imported pages keep showing. - A tile remounted after a settings change asks GET /state for the snapshot the already-open stream sent, instead of waiting blank. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
5.0 KiB
Companion Buttons
A ProdDash module that shows Bitfocus Companion pages on dashboard tiles — a whole page, or just the buttons you pick from it — every button 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.
- 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: every Companion page is listed under Companion Buttons. Pick one — "19 Status", say — and the tile shows that page, titled with its name. Page up/down buttons are left out.
- To show only some buttons, click the grid icon in the tile's title bar. The whole page appears; click a button to take it out (it fades) or put it back. Click the icon again when done. Putting every button back means the whole page again, including buttons added to it later.
- The gear has one switch, Page layout: on, the buttons keep Companion's rows and columns; off, they are packed into whatever grid makes each one biggest.
Hover a button for its page and Companion location (page/row/column).
What a tile follows
A tile follows its page by Companion's own page id, so inserting or moving
pages changes nothing. Buttons are followed by their row and column on that
page, so a page re-imported from a .companionconfig (every button gets a new
internal id) keeps showing. A chosen place that is emptied in Companion shows
a dashed outline. A page deleted in Companion leaves the tile empty; the
dashboard folds it away.
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 three read-only subscriptions:
pages.watch (pages, names, which button is where),
preview.graphics.controlId (a button's PNG, on every redraw) and
controls.watchControl (read once per button, to leave out page up/down).
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 /stream/<page>[/<row.col>/…] |
SSE for one tile: page (what to lay out) and button (one picture) on connect, then on every change |
GET /state/<page>[/<row.col>/…] |
The same as one snapshot, for a tile that joins a stream the dashboard already has open |
GET /page-options |
The pages, for a tile added without one (the gear's Page) |
The ＋ entries come from the server's tiles(), one per page. 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 |
＋ entries, 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 choosing mode |
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.