companion-buttons/README.md

# 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.