Restore QuickPlay ad-hoc MQTT protocol doc - #5
Open
theelims wants to merge 4 commits into
Open
Conversation
Recover docs/QuickPlay.md verbatim as it was before commit fbd811d ("Clean repo") removed it, to serve as the basis for further work on the ad-hoc play protocol. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01V3xZUzUsThbJPhFhkCMya5
Specifies Quick Play over connectionless BLE advertising, preserving the full message model of the MQTT spec: tags, intensity range, keep-alive and decay timing, absence-means-zero, highest-intensity-wins arbitration, coexisting sessions and per-device APIs. The broker and the Facilitator role are dropped: Quick Play messages are idempotent state, repeated and loss-tolerant, so they need no connection. Covers the wire format inside a 31-byte legacy advertisement, radio parameter sizing against the 1.5 s decay window, receiver state handling, allow-listing and optional payload authentication, a GATT fallback for platforms that cannot broadcast, BLE 5 extended advertising, and bridging back to the MQTT binding. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01V3xZUzUsThbJPhFhkCMya5
Android can emit Quick Play unmodified, but the legacy AdvertiseSettings API only offers three fixed intervals, of which just LOW_LATENCY satisfies the decay-window sizing rule; startAdvertisingSet with legacy PDUs gives exact interval control instead. The platform also rotates the advertiser address without exposing it, which breaks address-based origin identity and allow-listing. Add an optional 4-byte Source ID behind a new flags nibble in the version byte for emitters without a stable address, and note that it is a weaker basis for allow-listing than an address. Quantify scanning cost for an always-listening consumer: nRF52 figures per duty cycle against ESP32 variants, standby life on a 1000 mAh cell, and the two second-order costs (loss of controller-side accept-list filtering when addresses rotate, and host wake-ups in crowded rooms). Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01V3xZUzUsThbJPhFhkCMya5
A sub-100 ms sensor-to-actuator target does not survive the parameters previously recommended. Split the radio settings into two profiles: an Ambient profile matching the original spec's timing, and a Responsive profile at a 20-30 ms advertising interval with continuous scanning. Duty-cycled scanning cannot meet the target at any advertising rate, since the consumer must wait for a scan window and an advertising event to coincide; continuous scanning receives every event and costs roughly 3x the standby current. Add an adaptive rate - burst on change, back off to the keep-alive rate - to recover most of the airtime and room capacity. Document capacity: collision loss is an airtime limit that applies only to emitters, so listeners are unbounded. About 5 emitters are comfortable under the latency budget and 10 at the limit, against 20-30 for the Ambient profile. Also note Android's 100 ms advertising floor, which closes the Responsive profile to phone emitters. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01V3xZUzUsThbJPhFhkCMya5
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Recover docs/QuickPlay.md verbatim as it was before commit fbd811d
("Clean repo") removed it, to serve as the basis for further work on
the ad-hoc play protocol.
Co-Authored-By: Claude Opus 5 noreply@anthropic.com
Claude-Session: https://claude.ai/code/session_01V3xZUzUsThbJPhFhkCMya5