Skip to content

BLE: UUIDs are stringly typed across the API #240

Open

Description

@jappeace-sloth

Problem

Every UUID in the BLE API is a wrapped Text: BleServiceUuid, BleCharacteristicUuid, NormalizedBleUuid, and (since #239) the advertisement service-data keys. Nothing stops a malformed literal ("not-a-uuid", a missing group, stray whitespace) from flowing all the way to the platform bridge before failing, and Hatter.BleAdvertisement hand-rolls hex rendering and Bluetooth base-UUID expansion that a typed UUID representation would mostly subsume. Case-insensitivity is handled by the NormalizedBleUuid smart-constructor convention rather than by construction.

The maintainer suggested the uuid package during review of #239. The small uuid-types package (just the type, parse and render) would fit; the full uuid package would not, since it pulls network-info (OS-specific ioctls) which is a poor fit for the Android/iOS cross builds.

Use case

Any consumer defining GATT constants, e.g. kbeacon-ota-tool with its FEA0/FEA1/FEA2 service and 0x2080 service-data lookups: a typo in one of those string literals today compiles fine and fails only at runtime against real hardware.

Current behaviour

  • UUID validity is checked nowhere; strings pass through withCString to the platforms as-is.
  • Case handling relies on the NormalizedBleUuid newtype convention (see its Decision comment).
  • Hatter.BleAdvertisement formats parsed advertisement UUIDs to lowercase text by hand.

Expected behaviour

One typed UUID representation across the whole BLE API (scan filters, GATT operations, characteristic keys, advertisement keys) where a malformed UUID cannot be represented, replacing the hand-rolled hex rendering. Constraints discovered so far: it must be all-or-nothing (a partial migration leaves two competing normalized representations), it changes normalizeBleServiceUuid-style totality (string parsing can fail, which the API has to surface), and uuid-types adds hashable, random and splitmix to the cross-compiled dependency closure, which the Android/iOS/watchOS builds need to tolerate.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions