ble_protocol library
Framework-independent BLE definitions, framing and JSON request/reply.
Import this library from Dart protocol tools or custom transports. It does not initialize Flutter channels, request permissions or own a radio.
Classes
- BleCapabilities
- Snapshot of peripheral support, consent and Bluetooth power state.
- BleCharacteristic
- Describes a BLE characteristic exposed by the server.
-
BleCodec<
T> - Converts application values to the wire format understood by the peer.
- BleCodecs
- Built-in codecs; custom protocols can implement BleCodec.
- BleDiagnostic
- Counters and operation names omit payloads and tokens. Application-supplied errors may contain sensitive information; filter them before logging.
-
BleField<
T> - Declarative characteristic with typed validation and optional request hooks. authorizeWrite authorizes a proposed value before committing it; returning false rejects the write. Avoid irreversible side effects in authorization hooks.
-
BleFieldDefinition<
T> - Share this definition with the client; initial values and hooks stay on server.
-
BleJsonCodec<
T> - JSON characteristic codec; GATT values still have a 512-byte limit.
- BleMessageAssembler
- One bounded, ordered message assembly per peer. Create a separate instance per connection; reset on disconnect. Duplicate/reordered fragments are errors.
- BleMessageConfiguration
- Both peers share this contract. Metadata is checked before client readiness.
- BleMessageFramer
- Optional, versioned message framing. Both peers MUST implement this format. Header: version:u8 (=1), messageId:u16le, index:u16le, count:u16le. This is framing only: no encryption, acknowledgement, retry or replay defense.
- BlePeerInfo
- Platform-local peer information. A null physical connection state means the OS exposes subscription events rather than a complete connection inventory.
- BleProfile
- All services are exposed over GATT. Only advertisedServiceUuid is placed in advertisements, keeping the default compatible with legacy BLE packets. Name advertisement is best effort unless requireAdvertisedName is set.
- BleReadEvent
- Event emitted when a central reads a characteristic.
- BleRequestCache
- Bounded deduplication window. Share across resumed channels for one session. This is not durable storage or an exactly-once execution guarantee.
- BleRequestContext
- Identity is opaque, platform-local and not an authentication credential.
- BleRpcChannel
- Optional JSON request/reply protocol carried inside complete BLE messages. A response acknowledges handler completion, not a durable application commit.
- BleRpcEvent
- BleRpcReply
- BleService
- An immutable group of characteristics exposed under one service UUID.
- BleWriteEvent
- Event emitted when a central writes to a characteristic.
Enums
- BleAttStatus
- BleErrorCode
- Stable error categories shared by the new client and session layers.
- BleNameSupport
- How the platform can expose a requested advertising name.
- BleProperty
- BLE characteristic properties.
- BleSecurity
- Link-level protection for GATT reads and writes, enforced by the OS. Does not provide application-layer encryption or peer identity verification.
- BleServerState
- Lifecycle state of a server instance.
Functions
Typedefs
-
BleRpcHandler
= FutureOr<
Object?> Function(String method, Object? payload)
Exceptions / Errors
- BleException
- A categorized communication failure with an optional underlying cause.
- BleRequestException
- A protocol-level rejection sent to the requesting central.