Bluetooth Low Energy (BLE) Integration in Mobile Applications
BLE integration is not simply "connect a device". It's a finite state machine with a dozen states, each of which can fail: adapter is off, device is out of range, service not found, characteristic doesn't support writing. Applications that don't explicitly handle these states reliably crash on first real-world use.
BLE Stack Architecture
BLE works by the GATT model (Generic Attribute Profile). A peripheral device (sensor, bracelet, lock) provides Services—logical groups of functions. Each Service contains Characteristics—specific values for reading, writing, or subscription (notify/indicate).
Example: a fitness bracelet has Service 0x180D (Heart Rate). In it, Characteristic 0x2A37—current heart rate with notify flag. The application subscribes and receives data without polling.
Connection State Machine
Minimum set of states to handle:
IDLE → SCANNING → DISCOVERED → CONNECTING → CONNECTED → DISCOVERING_SERVICES
→ SERVICES_READY → SUBSCRIBING → READY
And errors on each transition: scan timeout, connection break in CONNECTING, gattStatus != GATT_SUCCESS during discovery, connection loss in READY.
iOS: CoreBluetooth
import CoreBluetooth
class BLEManager: NSObject, CBCentralManagerDelegate, CBPeripheralDelegate {
var centralManager: CBCentralManager!
var targetPeripheral: CBPeripheral?
override init() {
super.init()
centralManager = CBCentralManager(delegate: self, queue: DispatchQueue(label: "ble.queue"))
}
func centralManagerDidUpdateState(_ central: CBCentralManager) {
guard central.state == .poweredOn else {
// handle .poweredOff, .unauthorized, .unsupported
return
}
startScanning()
}
func startScanning() {
let serviceUUID = CBUUID(string: "180D")
centralManager.scanForPeripherals(withServices: [serviceUUID], options: [
CBCentralManagerScanOptionAllowDuplicatesKey: false
])
}
func centralManager(_ central: CBCentralManager, didDiscover peripheral: CBPeripheral,
advertisementData: [String: Any], rssi RSSI: NSNumber) {
guard RSSI.intValue > -80 else { return } // signal filter
centralManager.stopScan()
targetPeripheral = peripheral
centralManager.connect(peripheral, options: nil)
}
func centralManager(_ central: CBCentralManager, didConnect peripheral: CBPeripheral) {
peripheral.delegate = self
peripheral.discoverServices([CBUUID(string: "180D")])
}
func peripheral(_ peripheral: CBPeripheral, didDiscoverServices error: Error?) {
guard error == nil, let services = peripheral.services else { return }
for service in services {
peripheral.discoverCharacteristics([CBUUID(string: "2A37")], for: service)
}
}
func peripheral(_ peripheral: CBPeripheral,
didDiscoverCharacteristicsFor service: CBService, error: Error?) {
guard let characteristics = service.characteristics else { return }
for char in characteristics where char.properties.contains(.notify) {
peripheral.setNotifyValue(true, for: char)
}
}
func peripheral(_ peripheral: CBPeripheral,
didUpdateValueFor characteristic: CBCharacteristic, error: Error?) {
guard let data = characteristic.value else { return }
// parse data per GATT characteristic specification
}
}
Common Issues
didDisconnectPeripheral without warning. BLE connection breaks when out of range, device dies, system intervenes. Auto-reconnect is needed: on didDisconnectPeripheral, call centralManager.connect(peripheral) with exponential backoff.
Scanning with allowDuplicates: true kills battery. Enable only if constant RSSI updates are needed for distance measurement. For normal search—false.
State restoration. If the application is killed by system during BLE session, CBCentralManagerOptionRestoreIdentifierKey allows restoring state on next launch. Without it, the device thinks it's connected, but the application doesn't know.
Android: BluetoothGatt
val gattCallback = object : BluetoothGattCallback() {
override fun onConnectionStateChange(gatt: BluetoothGatt, status: Int, newState: Int) {
if (status != BluetoothGatt.GATT_SUCCESS) {
// status contains error code, e.g. 133 (GATT_ERROR) - needs reconnect
gatt.close()
return
}
if (newState == BluetoothProfile.STATE_CONNECTED) {
gatt.discoverServices()
}
}
override fun onServicesDiscovered(gatt: BluetoothGatt, status: Int) {
val characteristic = gatt
.getService(UUID.fromString("0000180d-0000-1000-8000-00805f9b34fb"))
?.getCharacteristic(UUID.fromString("00002a37-0000-1000-8000-00805f9b34fb"))
?: return
gatt.setCharacteristicNotification(characteristic, true)
val descriptor = characteristic.getDescriptor(
UUID.fromString("00002902-0000-1000-8000-00805f9b34fb") // Client Characteristic Configuration
)
descriptor.value = BluetoothGattDescriptor.ENABLE_NOTIFICATION_VALUE
gatt.writeDescriptor(descriptor)
}
override fun onCharacteristicChanged(gatt: BluetoothGatt, characteristic: BluetoothGattCharacteristic) {
val data = characteristic.value
// parse
}
}
device.connectGatt(context, false, gattCallback, BluetoothDevice.TRANSPORT_LE)
Status 133 (GATT_ERROR) is the most common during Android connection. Causes: device already connected in another process, GATT cache is stale. Fix: gatt.close() + gatt.refresh() (via reflection) + reconnect after 1-2 seconds.
Android 12+ permissions. BLUETOOTH_SCAN and BLUETOOTH_CONNECT are mandatory. Old BLUETOOTH and BLUETOOTH_ADMIN don't work on API 31+.
Performance and Battery
Default MTU is 23 bytes. Request via gatt.requestMtu(512) / peripheral.maximumWriteValueLength(for: .withResponse). On large transfers (firmware OTA, sensor data), this is the difference between 30 seconds and 3 minutes.
Integration timeline: 3-5 days—basic connection with notify. Complex scenarios (OTA update, multi-peripheral, background mode)—1-2 weeks. Cost is calculated individually.