Repository navigation
Neutral API support tables, pairing notes, and Apple/Web pairing-state fix - #343
Merged
Merged
Conversation
- Footnote ¹: say pair() "reads or writes" an encrypted characteristic, and reword the Web caveat to key off the browser host OS instead of the duplicated "on Web … on Web/Windows and Web/Linux" phrasing. - isPaired: mark iOS/macOS/Web ⏺ (needs a pairingCommand, returns null without one) and note it in footnote ³, consistent with pair/unpair. - Give each footnote its own paragraph so GitHub does not collapse them into a single wrapped blob. - Move the legend above the client table so ⏺/— are defined before first use, and drop the duplicate below the peripheral table.
Note on _connectAndExecuteBleCommand that updateCallbackValue is false at every call site, so nothing emits pairing state from there on any platform (including iOS/macOS/Web, which have no native pairing-state callback), and that enabling it on those platforms would require flipping the README's onPairingStateChange row back to ⏺.
fotiDim
changed the title
Apple and Web have no native bond API, so onPairingStateChange / pairingStateStream were never wired there even though pair() drives pairing by executing an encrypted characteristic. The 0.12.0 changelog claimed support, but updateCallbackValue was false at every call site. pair() now reports the probe outcome: updatePairingState(true) on success and updatePairingFailure(false) when it throws. isPaired() keeps running the same probe as a query without emitting. - Wire updateCallbackValue: true from pair()'s Apple/Web branch, and make _connectAndExecuteBleCommand report success for both the pairingCommand and the read-all probes. - Add test/apple_web_pairing_state_test.dart covering success, failure, the no-command read-all path, and that isPaired() stays silent. - README: onPairingStateChange is ⏺ on iOS/macOS/Web again; rewrite footnote ⁴ and note the behaviour in the Pairing state section. - CHANGELOG: document the fix and the incorrect 0.12.0 claim.
fotiDim
force-pushed
the
docs/api-support-icons
branch
from
October 14, 2026 11:07
78f837a to
951b109
Compare
The no-command pair() path emitted isPaired=true unconditionally once the device exposed a readable characteristic, because _attemptPairingReadingAll swallowed every read error. It now returns whether any read succeeded and the probe reports failure (false) when none could be read. Scope the pairing-failure event to the probe step so connection/discovery failures no longer surface as pairing state changes, and add tests for the failing read-all and connection-failure paths.
isPaired relies on the same encrypted-characteristic probe as pair, so mark it supported (checkmark) on iOS/macOS to match pair, keeping the Web column at partial. Also replace the word 'bond' in the pairing notes with 'pairing'.
The Web probe reads an already-paired device's encrypted characteristic on any host OS, so the query returns a correct answer regardless of whether the browser can trigger ConfirmOnly pairing.
Put the superscript indicators next to the ⏺ circle instead of the API name, and only circle rows carry one (isPaired is now all-checkmark). Drop the onPairingStateChange and pair notes that repeated the Pairing section, and shorten the 'Pairing state changes' prose to point at the note.
rohitsangwan01
approved these changes
Oct 14, 2026
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.
Summary
Makes the API Support tables in
README.mdaccurate and easier to read, and fixes Apple/WebonPairingStateChange, which the tables previously described incorrectly.API tables
—), matchinguniversal_bluetooth_classic, and placed the legend above the tables so the markers are defined before their first use.⏺marker. It now means partial support (see notes) instead of the vague "platform-dependent".unpairon iOS. It was—, but iOS 18+ removes accessories authorized through AccessorySetupKit, so it is now⏺with a note. macOS and Web remain—.isPairedon iOS/macOS/Web. Now⏺: it needs apairingCommandand otherwise returnsnull(and triggers pairing as a side effect).Fix:
onPairingStateChangeon Apple/WebApple and Web have no native bond-state API, so
onPairingStateChange/pairingStateStreamwere never wired there. The 0.12.0 changelog claimed this support, butupdateCallbackValuewasfalseat every call site.pair()now reports the outcome of its encrypted-characteristic probe:trueviaupdatePairingStatewhen the probe succeeds — on both thepairingCommandand the no-command read-all paths.false) viaupdatePairingFailurewhen it throws.isPaired()still runs the same probe as a query and does not emit. The tables showonPairingStateChangeas⏺for iOS/macOS/Web:pair()drives it, but there is no system-initiated bond event andunpairdoes not report.Footnotes added
pair¹— no dedicated pairing API on iOS/macOS/Web;pair()connects and reads or writes an encrypted characteristic so the OS triggers pairing. Works for all pairing methods on iOS/macOS. On Web the outcome depends on the browser's host OS: ConfirmOnly ("Just Works") pairing can be triggered on Web/macOS and Web/Android, but not on Web/Windows or Web/Linux — hence the conservative⏺.unpair²— iOS 18+ only, and only for accessories authorized through AccessorySetupKit (requestDevice); other devices fail withdeviceNotFound.isPaired³— on iOS/macOS/Web it needs apairingCommandwith an encrypted read or write characteristic and returnsnullwithout one; it also triggers pairing if the device is not already paired.onPairingStateChange⁴— on iOS/macOS/Webpair()reports the outcome it drove:truewhen the encrypted-characteristic probe succeeds andfalseon failure. There is no system-initiated bond event andunpairdoes not report; read the state withisPaired(pairingCommand:).Scope
README.md,CHANGELOG.md, a fix inlib/src/universal_ble.dart, and a newtest/apple_web_pairing_state_test.dart.Test plan
flutter test— all tests pass (4 new).flutter analyze lib test— no issues.