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

Companion Buttons 1.2.0: back to picking any buttons from any pages, without the header row

Browse Source 
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>
This commit is contained in:
christian
2026-10-15 12:09:31 -04:00
co-authored by Claude Opus 5.5
parent 0a6cec88aa
commit a3097481e7
8 changed files with 772 additions and 605 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+40 -36
View File
@@ -1,11 +1,14 @@
# 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.
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.
@@ -18,27 +21,29 @@ anything else that says what is happening right now.
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.
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.
Hover a button for its page and Companion location (`page/row/column`).
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
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.
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
@@ -51,23 +56,22 @@ last pictures to grey, so nobody reads them as live. ProdDash keeps retrying
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.
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.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) |
| `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 |
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.
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
@@ -82,9 +86,9 @@ per page and a status board can show more buttons than that.
| File | |
| --- | --- |
| `module.json` | Manifest |
| `server.js` | ＋ entries, routes, button subscriptions, the per-tile streams |
| `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 mode |
| `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` |