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>
106 lines
5.0 KiB
Markdown
106 lines
5.0 KiB
Markdown
# Companion Buttons
|
||
|
||
A [ProdDash](http://chronicles-ab.waterschurch.org:3000/michael/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
|
||
|
||
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:** 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.
|
||
3. **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.
|
||
4. **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.
|