feat: satellite 1.10

[Julusian]

bitfocus/companion#4043

Summary by CodeRabbit

• Documentation

  • Reorganized Satellite API into a "Connection" section with clearer send/receive distinctions; moved server-sent ping under receive and kept client-sent ping under send.
  • Added "Surfaces" section describing simple vs. advanced registration and adjusted headings; updated table-of-contents depth.
  • Documented server behavior for runtime capability changes (CAPS SUBSCRIPTIONS=1) and required reconnection/read of CAPS.

• New Features

  • Button Subscriptions (since v1.10.0): ADD-SUB, REMOVE-SUB, SUB-PRESS, SUB-ROTATE, and SUB-STATE updates.
  • KEY-STATE messages now support an optional LOCATION parameter (page/row/column).

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: f4a269db-b52d-491b-a5e8-a53eff6649b7

📥 Commits

Reviewing files that changed from the base of the PR and between f2f606d and cebcc9e.

📒 Files selected for processing (1)

• for-developers/Satellite-API.md

🚧 Files skipped from review as they are similar to previous changes (1)

• for-developers/Satellite-API.md

---

📝 Walkthrough

Walkthrough

Documentation-only updates to Satellite-API: frontmatter set toc_max_heading_level: 4; top-level section renamed to "Connection"; message send/receive structure reorganized; added Surfaces section (simple/advanced); KEY-STATE gains LOCATION (page/row/column); and a Button Subscriptions feature (v1.10.0) with client/server commands and runtime CAPS behavior.

Changes

Cohort / File(s)	Summary
Documentation Core for-developers/Satellite-API.md	Frontmatter: toc_max_heading_level: 4. Renamed top-level "API Spec" → "Connection". Reorganized headings into explicit "Messages to send" and "Messages to receive".
Ping / CAPS Behavior for-developers/Satellite-API.md	Moved/duplicated PING docs: client-sent PING stays under "Messages to send"; added server-sent PING handling under "Messages to receive". Added v1.10.0 server capability: after BEGIN server may send CAPS SUBSCRIPTIONS=1; documented runtime-change behavior (server may close connection; client should reconnect/re-read CAPS).
Surfaces & Registration for-developers/Satellite-API.md	Added Surfaces section describing registration modes (simple vs advanced) and lifecycle; existing surface command docs nested under this section with heading-level adjustments (no command text changes).
KEY-STATE Extension for-developers/Satellite-API.md	Extended KEY-STATE ("State change for key") with a new LOCATION parameter (since v1.10.0) in page/row/column format; applies to all button types but may be unset.
Button Subscriptions (v1.10.0) for-developers/Satellite-API.md	Introduced "Button Subscriptions" docs: client→server commands ADD-SUB, REMOVE-SUB, SUB-PRESS, SUB-ROTATE; server→client SUB-STATE updates; documented both simple and advanced parameter schemas and streamed optional parameters.

Poem

🛰️ A tidy spec, with headings cleared,
Surfaces grouped and states endeared.
Location set and subs in play,
CAPS and pings now find their way. ✨

🚥 Pre-merge checks | ✅ 1 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title 'feat: satellite 1.10' is vague and generic, using abbreviation without context about what feature or capability is being added for Satellite v1.10.	Consider a more descriptive title like 'feat: add Satellite API v1.10 support with capabilities and subscriptions' to clarify the main changes being introduced.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

for-developers/Satellite-API.md (1)

281-283: Please clarify LOCATION index bases (page vs row/col).

PAGE/ROW/COL is introduced with examples, but row/column base (0-based vs 1-based) isn’t explicit here. A one-line clarification would prevent off-by-one client bugs.

🧭 Suggested clarification

-A location is expressed as `PAGE/ROW/COL` using Companion's native location syntax, e.g. `1/2/3` for page 1, row 2, column 3.
+A location is expressed as `PAGE/ROW/COL` using Companion's native location syntax.
+`PAGE` is 1-based, while `ROW` and `COL` follow Companion's button coordinates (explicitly document whether these are 0-based or 1-based here), e.g. `1/2/3`.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 930c006d-2380-4c28-8135-55a5b16505fe

📥 Commits

Reviewing files that changed from the base of the PR and between 1176650 and 7e3ad62.

📒 Files selected for processing (1)

• for-developers/Satellite-API.md