universal_ble_server library
Native BLE clients and declarative servers, messages and optional sessions.
Classes
- BleCapabilities
- Snapshot of peripheral support, consent and Bluetooth power state.
- BleCharacteristic
- Describes a BLE characteristic exposed by the server.
- BleClientEvent
- Subscription events represent channel readiness, not physical connections.
- BleClientTransport
- One peripheral connection per transport. Implementations own their resources.
-
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.
- BleDiscoveredServer
-
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.
- BleFieldUpdate
- One decoded update with its shared field definition.
-
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.
- BleMessageClient
- Matching central for BleMessageServer, including protocol verification.
- 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.
- BleMessageProtocol
- Stable, custom UUIDs for the bidirectional message protocol, version 1.
- BleMessageServer
- A ready-to-use framed BLE message service. Clients write RX with response, subscribe to TX notifications and read NAME for the logical server name. Both peers must implement BleMessageFramer's version 1 wire format.
- 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.
- BleRawNotification
- BleReadEvent
- Event emitted when a central reads a characteristic.
- BleReceivedMessage
- BleReconnectPolicy
- Optional fixed-delay reconnection; disabled by default.
- BleRemoteCharacteristic
- 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.
- BleSession
- BleSessionClient
- Reopens a logical session and fetches a fresh snapshot after BLE reconnects.
- BleSessionServer
- Optional admitted sessions + request handlers + public shared-state snapshots. Start this wrapper before clients connect; it owns its message subscriptions, not the underlying server lifecycle. Authentication is application-supplied.
- BleWriteEvent
- Event emitted when a central writes to a characteristic.
- MethodChannelUniversalBleServer
- NativeBleClientTransport
- Direct platform-channel adapter. No external Bluetooth plugin is used. One native central connection per Flutter engine; each device runs its own.
- UniversalBleClient
- One remote server, with serialized ATT operations and reference-counted watches.
- UniversalBleServer
- A custom GATT server whose profile describes client-readable/writable fields.
- UniversalBleServerPlatform
Enums
- BleAdapterState
- BleAttStatus
- BleClientEventKind
- BleConnectionState
- 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.
Extensions
- BleAdapterStateConvenience on BleAdapterState
- Readiness checks without a top-level helper function.
- BleMessageClientConvenience on BleMessageClient
- Typed fields and finite discovery on the same connection as complete messages.
- BleMessageServerConvenience on BleMessageServer
- Common message-server operations without exposing the underlying GATT server.
- UniversalBleServerConvenience on UniversalBleServer
- Explicit permission-and-start helper for custom GATT servers.
Functions
-
bleBytes(
List< int> value) → Uint8List - Copies and validates a complete ATT attribute value (at most 512 bytes).
-
bleJsonCopy(
Object? value) → Object? - Detached JSON copy prevents application mutation after queueing/snapshotting.
-
bleRandomToken(
) → String -
normalizeBleUuid(
String value) → String - Canonicalizes Bluetooth SIG short UUIDs and full 128-bit UUIDs.
-
requireClientReady(
BleAdapterState state) → void
Typedefs
-
BleRequestHandler
= Future<
Map< Function(Map<String, Object> >String, Object?> request) -
BleRpcHandler
= FutureOr<
Object?> Function(String method, Object? payload) -
BleSessionRequestHandler
= FutureOr<
Object?> Function(BleSession session, 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.