Kable Documentation

Bluetooth Low Energy uses UUIDs to identify services, characteristics, and descriptors. Kable provides several ways to handle them:

1. Short-form UUIDs: You can create a full 128-bit Uuid by adding a 16-bit or 32-bit integer to Bluetooth.BaseUuid.
2. Web Bluetooth Names: You can use extension functions to resolve UUIDs from human-readable strings (e.g., Uuid.service("heart_rate")).

Shorthand Reference Table:

val uuid16bit = 0x180D
val heartRateServiceUuid = Bluetooth.BaseUuid + uuid16bit
println(heartRateServiceUuid) // Output: 0000180d-0000-1000-8000-00805f9b34fb

val heartRateServiceUuidByName = Uuid.service("heart_rate")
println(heartRateServiceUuidByName) // Output: 0000180d-0000-1000-8000-00805f9b34fb

A Peripheral represents a remote Bluetooth device and provides methods for connection handling and I/O operations. You create a Peripheral from an Advertisement using the Peripheral builder function.

Lifecycle and Coroutines

• Scope: A Peripheral provides a CoroutineScope via its scope property. Use this for long-running tasks that should persist across reconnections but be cancelled when the peripheral is disposed.
• Connection-specific tasks: For tasks that should only run while a single connection is active (and shut down on disconnect), use the CoroutineScope returned from Peripheral.connect() or the scope property of the Connected state.
• Disposal: You must call peripheral.close() when the peripheral is no longer needed. Once closed, the peripheral cannot be reused (e.g., calling connect will throw an IllegalStateException).

val peripheral = Peripheral(advertisement) {
    // Configure peripheral
}

// Long running task tied to peripheral lifecycle
peripheral.scope.launch {
    // ...
}

// Cleanup
peripheral.close()

BLE devices use a tree structure of Services, Characteristics, and Descriptors. You can access these in two ways:

1. Lazy Search (characteristicOf / descriptorOf): These functions search the GATT profile for the first match based on the provided UUIDs. When performing I/O, the search also respects the required properties (e.g., searching for a characteristic that supports writeWithoutResponse).
2. Manual Traversal (Peripheral.services): You can traverse the discovered services tree. This is useful if multiple items share the same UUID. Warning: Objects obtained via Peripheral.services hold strong references to platform types; ensure you remove references when they are no longer needed to avoid leaks.

Note: read and write operations will throw NotConnectedException if the peripheral is not connected.

// Lazy access to a descriptor
val descriptor = descriptorOf(
    service = Bluetooth.BaseUuid + 0x1815,
    characteristic = Bluetooth.BaseUuid + 0x2A56,
    descriptor = Uuid.descriptor("gatt.client_characteristic_configuration"),
)

// Manual traversal
val services = peripheral.services.value ?: error("Services not discovered")
val descriptor = services
    .first { it.serviceUuid == Bluetooth.BaseUuid + 0x1815 }
    .characteristics
    .first { it.characteristicUuid == Bluetooth.BaseUuid + 0x2A56 }
    .descriptors
    .first { it.descriptorUuid == Uuid.descriptor("gatt.client_characteristic_configuration") }

The Scanner provides an advertisements Flow that emits Advertisement objects (containing name and RSSI) as they are seen.

Configuration

You can configure the Scanner using a DSL to define filters and logging settings.

Filtering

Scan results are filtered by providing Filters. Only Advertisements matching at least one filter will be emitted. Supported filters include:

• Service (Recommended for optimization)
• Name
• NamePrefix
• Address (Android only)
• ManufacturerData

Note: Providing Filter.Service is recommended as it is natively supported on all platforms and allows for system-level scan optimizations.

Lifecycle

Scanning begins when the advertisements Flow is collected and stops when the collection is terminated.

// Scan until the first advertisement matching a specific name is found
val advertisement = Scanner {
    filters {
        match {
            name = Filter.Name.Exact("Example")
        }
    }
}.advertisements.first()

In JavaScript environments, instead of processing a stream of advertisements, you can use requestPeripheral(options) to trigger a browser-native device picker.

Usage Requirements

• The browser will show a list of peripherals matching your filters.
• Crucial: If you use name filters, you must also include any services you intend to access in the optionalServices list. Otherwise, the origin will not have permission to access those services after the user selects the device.
• If the user cancels the dialog, requestPeripheral returns null.

val options = Options {
    filters {
        match {
            name = Filter.Name.Prefix("Example")
        }
    }
    optionalServices = listOf(
        Uuid.parse("f000aa80-0451-4000-b000-000000000000"),
        Uuid.parse("f000aa81-0451-4000-b000-000000000000"),
    )
}
val peripheral = requestPeripheral(options)