christian/companion-buttons
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Companion Buttons 1.0.0: any Companion button from any page, live on a ProdDash tile

Browse Source 
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>
This commit is contained in:
christian
2026-10-14 20:12:23 -04:00
co-authored by Claude Opus 5.5
commit 415453ef5f
9 changed files with 2085 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+104
View File
@@ -0,0 +1,104 @@
# Companion Buttons
A [ProdDash](http://chronicles-ab.waterschurch.org:3000/michael/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.