christianandClaude Opus 5.5
a3097481e7
1.1.0 made each tile one page, so buttons picked on a second page never showed, choosing ended on every settings change, and a tile could go blank after a remount. This goes back to 1.0's model and keeps only the changes asked for: - Pick buttons from any pages; each gets a ring and its order number. - No Page / Clear / Done row: Page is in the gear, the grid icon starts and ends choosing, a second click on a button takes it out. - Choosing survives the remount a gear change causes, so switching Page carries straight on. - A tile joining a stream its dashboard already has open (another tile with the same buttons, or itself after a settings change) asks GET /state for the snapshot instead of waiting blank. - Gear: Captions and Page. The per-page ＋ entries are gone. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
110 lines
5.2 KiB
Markdown
110 lines
5.2 KiB
Markdown
# Companion Buttons
|
||
|
||
A [ProdDash](http://chronicles-ab.waterschurch.org:3000/michael/ProdDash) module
|
||
that shows any Companion buttons — from any pages — on a dashboard tile,
|
||
exactly as Companion draws them: 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, from any pages.** 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.** The new tile opens on a Companion page,
|
||
laid out as it is in Companion. Click the buttons to show: each gets a ring
|
||
and a number, the order it will appear in. Click again to take it out.
|
||
3. **Another page:** open the gear and change **Page**. The tile stays in
|
||
choosing and shows that page; what you already picked is kept.
|
||
4. **Done:** click the grid icon in the title bar. The tile shows your
|
||
buttons. Click the icon again any time to add or remove some.
|
||
|
||
The gear has two settings: **Captions** (the page name under each button) and
|
||
**Page** (which page choosing shows). 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 /stream/<page.row.column.id>/…` | SSE `button` events for a tile's buttons: all of them on connect, then each redraw or move |
|
||
| `GET /state/<page.row.column.id>/…` | The same as one snapshot — for a tile that joins a stream its dashboard already has open, as after a settings change |
|
||
| `GET /pages` | Every page and the buttons on it — choosing |
|
||
| `GET /image/<id>` | One button's current picture as PNG — choosing |
|
||
| `GET /page-options` | The pages — the gear's 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` | 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 |
|
||
| `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.
|