core_bluetooth #

A clean Dart wrapper around Apple's CoreBluetooth framework for iOS and macOS.

Both central mode and peripheral mode are supported.

Status #

✅ Fully implemented.

Apple CoreBluetooth symbol names are the primary public API. Helper wrapper types exist where Dart needs them, but they intentionally do not use the CB prefix.

Example #

The package includes a working example app:

cd ./example
flutter run

Usage - Central Mode #

For connecting to devices.

Initialize Central Manager #

Use the shared app-wide manager:

final central = CBCentralManager.shared;

Or configure the shared manager before first use:

CBCentralManager.ensureShared(
  options: const CentralManagerOptions(
    showPowerAlert: true,
    restoreIdentifier: "my_restore_id",
  ),
);

final central = CBCentralManager.shared;

Or create an isolated manager:

final central = CBCentralManager.createIsolated(
  options: const CentralManagerOptions(
    showPowerAlert: true,
    restoreIdentifier: "my_restore_id",
  ),
);

Bluetooth On & Off #

final central = CBCentralManager.shared;

final subscription = central.onDidUpdateState.listen((state) {
  print(state);
  if (state == CBManagerState.poweredOn) {
    // start scanning, connecting, etc
  }
});

Scan for Devices #

final subscription = central.onDidDiscoverPeripheral.listen((result) {
  print(result.peripheral.identifier.uuidString);
  print(result.advertisementData.localName);
  print(result.rssi);
});

await central.scanForPeripherals(
  withServices: [CBUUID("180D")],
  options: const CentralManagerScanOptions(
    allowDuplicates: true,
  ),
);

await central.stopScan();

Connect to a Device #

await central.connect(peripheral);

await central.cancelPeripheralConnection(peripheral);

Discover Services #

final subscription = peripheral.onDidDiscoverServices.listen((result) {
  print(result.services);
});

await peripheral.discoverServices();

Iterate Services & Characteristics #

for (final service in peripheral.services ?? const <CBService>[]) {
  print('service: ${service.uuid.uuidString}');

  for (final characteristic in service.characteristics ?? const <CBCharacteristic>[]) {
    print('  characteristic: ${characteristic.uuid.uuidString}');

    for (final descriptor in characteristic.descriptors ?? const <CBDescriptor>[]) {
      print('    descriptor: ${descriptor.uuid.uuidString}');
    }
  }
}

Read, Write, and Notify #

await peripheral.readValue(characteristic);

await peripheral.writeValue(
  Uint8List.fromList([0x01, 0x02]),
  forAttribute: characteristic,
  type: CBCharacteristicWriteType.withResponse,
);

await peripheral.setNotifyValue(true, characteristic);

final subscription = peripheral.onDidUpdateValueForCharacteristic.listen((result) {
  print(result.characteristic.value);
});

L2CAP #

final subscription = peripheral.onDidOpenL2CAPChannel.listen((result) async {
  final channel = result.channel;
  if (channel == null) {
    return;
  }

  final incoming = await channel.inputStream.read();
  print(incoming);

  await channel.outputStream.write(Uint8List.fromList([0x01, 0x02]));
});

await peripheral.openL2CAPChannel(1234);

Usage - Peripheral Mode #

For advertising yourself as a device.

Initialize Peripheral Manager #

Use the shared app-wide manager:

final peripheralManager = CBPeripheralManager.shared;

Or configure the shared manager before first use:

CBPeripheralManager.ensureShared(
  options: const PeripheralManagerOptions(
    showPowerAlert: true,
    restoreIdentifier: "my_restore_id",
  ),
);

final peripheralManager = CBPeripheralManager.shared;

Or create an isolated manager:

final peripheralManager = CBPeripheralManager.createIsolated(
  options: const PeripheralManagerOptions(
    showPowerAlert: true,
    restoreIdentifier: "my_restore_id",
  ),
);

Start Advertising #

final peripheralManager = CBPeripheralManager.shared;

final service = CBMutableService.type(
  type: CBUUID("1234"),
  primary: true,
);

final characteristic = CBMutableCharacteristic.type(
  type: CBUUID("ABCD"),
  properties: const CBCharacteristicProperties(
    CBCharacteristicProperties.read.rawValue | CBCharacteristicProperties.notify.rawValue,
  ),
  value: null,
  permissions: CBAttributePermissions.readable,
);

service.characteristics = [characteristic];

await peripheralManager.add(service);

await peripheralManager.startAdvertising(
  const PeripheralManagerAdvertisingData(
    localName: "core_bluetooth",
    serviceUUIDs: [CBUUID("1234")],
  ),
);

Peripheral Read / Write Requests #

final readSubscription = peripheralManager.onDidReceiveReadRequest.listen((result) async {
  final request = result.request;

  request.value = Uint8List.fromList([0x01, 0x02, 0x03]);

  await peripheralManager.respond(
    to: request,
    withResult: CBATTErrorCode.success,
  );
});

final writeSubscription = peripheralManager.onDidReceiveWriteRequests.listen((result) async {
  for (final request in result.requests) {
    print(request.value);
  }
});

Update Subscribed Centrals #

final didSend = await peripheralManager.updateValue(
  Uint8List.fromList([0x10, 0x20]),
  forCharacteristic: characteristic,
  onSubscribedCentrals: null,
);

print(didSend);

Peripheral L2CAP #

final publishSubscription = peripheralManager.onDidPublishL2CAPChannel.listen((result) {
  print(result.psm);
});

final openSubscription = peripheralManager.onDidOpenL2CAPChannel.listen((result) async {
  final channel = result.channel;
  if (channel == null) {
    return;
  }

  await channel.outputStream.write(Uint8List.fromList([0x10, 0x20]));
});

await peripheralManager.publishL2CAPChannel(withEncryption: false);

Contract #

Below is the CoreBluetooth API map we should treat as the contract.

Legend:

• ✅ fully implemented

Top-Level Framework #

• ✅ CBManager
• ✅ CBPeer
• ✅ CBUUID
• ✅ CBError
• ✅ CBATTRequest
• ✅ CBL2CAPChannel
• ✅ CBL2CAPPSM

Central Role #

• ✅ CBCentralManager
• ✅ CBCentralManagerDelegate
• ✅ CBCentral
• ✅ CBConnectionEvent

CBCentralManager #

• ✅ shared
• ✅ ensureShared(options: ...)
• ✅ createIsolated()
• ✅ var delegate
• ✅ var isScanning
• ✅ class func supports(_ feature: CBCentralManager.Feature) -> Bool
• ✅ struct CBCentralManager.Feature
• ✅ func scanForPeripherals(withServices:options:)
• ✅ func stopScan()
• ✅ func retrievePeripherals(withIdentifiers:)
• ✅ func retrieveConnectedPeripherals(withServices:)
• ✅ func connect(_:options:)
• ✅ func cancelPeripheralConnection(_:)
• ✅ func registerForConnectionEvents(options:)
• ✅ class var authorization
• ✅ inherited from CBManager: var state

CBCentralManagerDelegate #

• ✅ centralManagerDidUpdateState(_:)
• ✅ centralManager(_:willRestoreState:)
• ✅ centralManager(_:didDiscover:advertisementData:rssi:)
• ✅ centralManager(_:didConnect:)
• ✅ centralManager(_:didFailToConnect:error:)
• ✅ centralManager(_:didDisconnectPeripheral:error:)
• ✅ centralManager(_:didDisconnectPeripheral:timestamp:isReconnecting:error:)
• ✅ centralManager(_:connectionEventDidOccur:for:)
• ✅ centralManager(_:didUpdateANCSAuthorizationFor:)

CBCentral #

• ✅ inherits CBPeer
• ✅ var maximumUpdateValueLength

Peripheral Role #

• ✅ CBPeripheral
• ✅ CBPeripheralDelegate
• ✅ CBPeripheralManager
• ✅ CBPeripheralManagerDelegate

CBPeripheral #

• ✅ var delegate
• ✅ var name
• ✅ var identifier
• ✅ var state
• ✅ var services
• ✅ var ancsAuthorized
• ✅ var canSendWriteWithoutResponse
• ✅ func readRSSI()
• ✅ func discoverServices(_:)
• ✅ func discoverIncludedServices(_:for:)
• ✅ func discoverCharacteristics(_:for:)
• ✅ func discoverDescriptors(for:)
• ✅ func readValue(for: CBCharacteristic)
• ✅ func readValue(for: CBDescriptor)
• ✅ func writeValue(_:for: CBCharacteristic,type:)
• ✅ func writeValue(_:for: CBDescriptor)
• ✅ func setNotifyValue(_:for:)
• ✅ func maximumWriteValueLength(for:)
• ✅ func openL2CAPChannel(_:)

CBPeripheralDelegate #

• ✅ peripheralDidUpdateName(_:)
• ✅ peripheral(_:didModifyServices:)
• ✅ peripheral(_:didReadRSSI:error:)
• ✅ peripheral(_:didDiscoverServices:)
• ✅ peripheral(_:didDiscoverIncludedServicesFor:error:)
• ✅ peripheral(_:didDiscoverCharacteristicsFor:error:)
• ✅ peripheral(_:didDiscoverDescriptorsFor:error:)
• ✅ peripheral(_:didUpdateValueFor:error:) for CBCharacteristic
• ✅ peripheral(_:didUpdateValueFor:error:) for CBDescriptor
• ✅ peripheral(_:didWriteValueFor:error:) for CBCharacteristic
• ✅ peripheral(_:didWriteValueFor:error:) for CBDescriptor
• ✅ peripheral(_:didUpdateNotificationStateFor:error:)
• ✅ peripheralIsReady(toSendWriteWithoutResponse:)
• ✅ peripheral(_:didOpen:error:)

CBPeripheralManager #

• ✅ shared
• ✅ ensureShared(options: ...)
• ✅ createIsolated()
• ✅ init()
• ✅ init(delegate:queue:)
• ✅ init(delegate:queue:options:)
• ✅ var delegate
• ✅ var isAdvertising
• ✅ func add(_:)
• ✅ func remove(_:)
• ✅ func removeAllServices()
• ✅ func startAdvertising(_:)
• ✅ func stopAdvertising()
• ✅ func updateValue(_:for:onSubscribedCentrals:) -> Bool
• ✅ func respond(to:withResult:)
• ✅ func setDesiredConnectionLatency(_:for:)
• ✅ func publishL2CAPChannel(withEncryption:)
• ✅ func unpublishL2CAPChannel(_:)
• ✅ class var authorization
• ✅ inherited from CBManager: var state

CBPeripheralManagerDelegate #

• ✅ peripheralManagerDidUpdateState(_:)
• ✅ peripheralManager(_:willRestoreState:)
• ✅ peripheralManagerDidStartAdvertising(_:error:)
• ✅ peripheralManager(_:didAdd:error:)
• ✅ peripheralManager(_:central:didSubscribeTo:)
• ✅ peripheralManager(_:central:didUnsubscribeFrom:)
• ✅ peripheralManagerIsReady(toUpdateSubscribers:)
• ✅ peripheralManager(_:didReceiveRead:)
• ✅ peripheralManager(_:didReceiveWrite:)
• ✅ peripheralManager(_:didPublishL2CAPChannel:error:)
• ✅ peripheralManager(_:didUnpublishL2CAPChannel:error:)
• ✅ peripheralManager(_:didOpen:error:)

GATT Model Types #

• ✅ CBAttribute
• ✅ CBService
• ✅ CBMutableService
• ✅ CBCharacteristic
• ✅ CBMutableCharacteristic
• ✅ CBDescriptor
• ✅ CBMutableDescriptor

CBAttribute #

• ✅ var uuid

CBService #

• ✅ var peripheral
• ✅ var isPrimary
• ✅ var includedServices
• ✅ var characteristics

CBMutableService #

• ✅ writable versions of service properties

CBCharacteristic #

• ✅ var service
• ✅ var value
• ✅ var descriptors
• ✅ var properties
• ✅ var isNotifying
• ✅ var isBroadcasted

CBMutableCharacteristic #

• ✅ init(type:properties:value:permissions:)

CBDescriptor #

• ✅ var characteristic
• ✅ var value

CBMutableDescriptor #

• ✅ init(type:value:)

Supporting Enums / Option Sets / Constants #

• ✅ CBManagerState
• ✅ CBManagerAuthorization
• ✅ CBPeripheralState
• ✅ CBCharacteristicWriteType
• ✅ CBCentralManager.Feature
• ✅ CBCharacteristicProperties
• ✅ CBAttributePermissions
• ✅ CBPeripheralManagerConnectionLatency
• ✅ CBATTError.Code
• ✅ advertisement-data keys
• ✅ peripheral-scanning option keys
• ✅ peripheral-connection option keys
• ✅ peripheral-manager initialization option keys
• ✅ peripheral-manager restoration keys
• ✅ central-manager restoration keys
• ✅ connection-event matching option keys