Emit device ids in lower-case on every platform (breaking, next major)

[postmaxin]

Follow-up to #269 (merged in 2.1.1): make the emitted device-id case consistent too — the fully-universal, breaking version discussed there for the next major.

What changes

Device ids are now canonicalised to lower-case throughout the Dart layer and emitted lower-case on every platform (scan results + connection / value / pairing / connection-parameter callbacks and streams). Previously each platform reported its native case — Android upper-cased MACs, Windows/WinRT lower-cased them — so a caller holding the id in the "wrong" case could split state or (before #269) miss events.

How — Dart-only, no Kotlin / Swift / C++ changes

• The update* handlers lower-case on ingestion, so every event, callback and per-device map key is lower-case. This also lets Match device ids case-insensitively across event streams #269's dual-case stream matching collapse to a single lower-case compare.
• Native BLE calls still need the platform's case (Android's getRemoteDevice requires upper-case and throws otherwise; Apple's peripheral cache is keyed by the upper-case uuidString, Windows parses the address either way, Linux's BlueZ address is upper-case), so the platform implementations convert back at their boundary: a single _nativeId() helper at the pigeon-channel native-op sites, and one line in the Linux instance's device lookup (the single point every Linux op funnels through).

Note the native side receives the same upper-case id it always has — it's just reconstructed at the Dart boundary now instead of being supplied by the caller — so native behaviour is unchanged.

Breaking

Callers that stored or compared an emitted id by exact case (e.g. an Android upper-case MAC) must now lower-case it, or compare case-insensitively. CHANGELOG updated under "next major".

Testing

• 97 Dart tests pass (flutter test) and flutter analyze is clean — including 5 new tests asserting lower-case emission from every update* handler, with the existing Match device ids case-insensitively across event streams #269 case-insensitive-matching / dedup / cache tests still green.
• Verified on a real Android device. I pointed a consumer app (a BLE pet-tracker gateway that round-trips scanned ids straight back into connect()) at this branch and confirmed the whole path: scan → connect() → auth → characteristic streaming → and the reconnect/self-heal path. That's exactly the round-trip this change relies on — Android's getRemoteDevice throws on a lower-case MAC, so a successful connect proves the boundary conversion is doing its job.

Developed with AI assistance (noted via the commit's Co-Authored-By trailer).

[Copilot]

Pull request overview

This PR standardizes BLE device IDs to a single canonical form in the Dart layer by lower-casing them on ingestion and ensuring all emitted IDs from streams/callbacks are lower-case, while converting back to the native-required case at platform boundaries (Pigeon channel + Linux BlueZ lookup). This is a breaking change intended for the next major release and is documented in the changelog.

Changes:

• Canonicalize device IDs to lower-case in UniversalBlePlatform update handlers and simplify stream matching to a single lower-case compare.
• Upper-case device IDs at the Dart→native boundary for Pigeon platform operations, and normalize Linux device lookup to BlueZ’s expected case.
• Add tests asserting lower-case emission from update handlers; update changelog and example lockfile.

Reviewed changes

Copilot reviewed 5 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
test/device_id_case_insensitivity_test.dart	Adds tests asserting lower-case emission from update* handlers.
lib/src/universal_ble_pigeon/universal_ble_pigeon_channel.dart	Introduces _nativeId() and applies it to Pigeon native calls; keeps emitted IDs lower-case.
lib/src/universal_ble_linux/universal_ble_linux.dart	Normalizes Linux device lookup by upper-casing IDs before BlueZ resolution.
lib/src/interfaces/universal_ble_platform_interface.dart	Canonicalizes IDs to lower-case on ingestion and simplifies stream filters accordingly.
example/pubspec.lock	Bumps the path-dependency version recorded for the example app.
CHANGELOG.md	Documents the breaking change for “next major”.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[rohitsangwan01]

@postmaxin instead of parsing id's, it would be better to use DeviceId object in interface api

class DeviceId {
  final String _id;
  const DeviceId(this._id);

  String get native => id.toLowerCase();
  
  // Code conversion will remain in this class only

  @override
  String toString() => native;
}

[postmaxin]

Happy to go that way if you'd like it in this PR — one thing to check first: in the sketch, native => id.toLowerCase(), but the native side needs the upper-case form (Android's getRemoteDevice throws on a lower-case MAC; Apple's peripheral cache is keyed by the upper-case uuidString). So there are two directions to hold: a canonical form for what the Dart layer emits and compares, and a native form at the channel boundary — the PR currently has them as canonicalDeviceId() and nativeDeviceId().

Also worth noting the canonical form can't be a constant toLowerCase(): per @fotiDim's review above, Web Bluetooth ids are opaque case-sensitive browser tokens, so canonicalisation has to be platform-supplied. A DeviceId type would delegate to that rather than replace it.

The cost is scope: every public String deviceId parameter, BleDevice.deviceId, and the string-based Low-Level API change type, on top of an already-breaking PR. Want me to do it here, or land the case fix and do the DeviceId type as a follow-up before 3.0.0?

[rohitsangwan01]

@postmaxin public apis should still remain same, except the case difference, DeviceId should be use internally only

[postmaxin]

Done in a3c7c27 — DeviceId is internal (not exported from the barrel) and the public APIs are unchanged, still taking and returning ids as String.

It carries both forms an id needs and is the only place either conversion happens:

DeviceId.address('AA:BB:CC:DD:EE:FF')  // canonical 'aa:bb:...', native 'AA:BB:...'
DeviceId.opaque('mHZbW+PZqBpUlZlVQrPzOQ==')  // both forms verbatim (Web)

canonical is what the Dart layer emits, matches and keys per-device state by; native is what channel calls take. Platforms now declare only which kind they report — UniversalBlePlatform.hasAddressDeviceIds, which Web overrides to false — and the interface derives both forms from that, so emission and matching can't drift apart. nativeDeviceId() and its file are gone, folded into DeviceId, along with the Linux device lookup and the service-cache key; there is no toLowerCase()/toUpperCase() on a device id left anywhere else in the package.

130 tests pass (flutter analyze clean), including a new test/device_id_test.dart covering both directions, round-trip stability, and that two cases of an address are one device while two cases of an opaque id are not.

[Copilot]

🟡 Changes recommended

Cache keying currently case-folds opaque Web Bluetooth IDs (risking collisions/incorrect per-device cached state) and the example lockfile changes appear unrelated and should be clarified or reverted.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 13/14 changed files
• Comments generated: 1
• Review effort level: Lite