CoreBluetooth that
actually works in production.

The 5 bugs that break every BLE project

CoreBluetooth has been Apple's worst-documented framework for a decade. Same five bugs in every hardware-company iOS codebase I've worked in. Each one quietly burns 1–3 weeks of engineering time before someone figures it out.

1. 1

   State restoration is silently misconfigured.

   Forget the CBCentralManagerOptionRestoreIdentifierKey, and your background scanning quietly dies after the first suspend cycle. Users report "the app doesn't reconnect" and you can't repro it on your dev iPhone.

2. 2

   Background scans drop without a service-UUID filter.

   It's in the docs if you know where to look. Most devs don't, and ship a feature that works in foreground only.

3. 3

   OTA firmware update has no first-party example.

   Every hardware company reimplements chunked-transfer-with-CRC from scratch. Most get the MTU math wrong.

4. 4

   Write-with-response queuing.

   Two simultaneous writes-with-response = silently dropped data. The fix is in one obscure WWDC video.

5. 5

   The didUpdateValueFor callback fires for both reads and notifications.

   Get the routing wrong and you'll spend a week chasing phantom "extra" reads.

Antenna fixes all five. The fixes have shipped to App Store apps and stayed there. 111 unit tests so you can verify before you trust.

What's inside

Nine modules. One import:

import Antenna

The whole API in five snippets

Copy-pasteable from the actual kit. Compiles today.

let manager = BLEManager(restoreIdentifier: "tech.acme.central")
try await manager.waitForReady()

let stream = await manager.startScanning(serviceUUIDs: [CBUUID(string: "180D")])
for await peripheral in stream {
    print(peripheral.name, peripheral.rssi)
}

let connected = try await manager.connect(to: peripheral)

let services = try await connected.discoverServices()
let chars = try await connected.discoverCharacteristics(for: services[0].id)

let heartRate = try await connected.read(chars[0])
try await connected.write(Data([0x01]), to: chars[1], withResponse: false)

let notifications = try await connected.notifications(for: chars[2])
for await data in notifications {
    print("BPM:", GATTExplorer.decodeHeartRate(data) ?? 0)
}

let updater = OTAUpdater(
    peripheral: connected,
    writeCharacteristic: otaChar,
    mtu: 182
)

let crc = try await updater.transfer(firmwareData) { progress in
    print("OTA \(Int(progress.fraction * 100))% — chunk \(progress.chunkIndex)/\(progress.totalChunks)")
}
// Hand crc to the peripheral's verify endpoint

let sm = ConnectionStateMachine(policy: .default)
// 5 attempts, 1s → 2s → 4s → 8s → 16s, ±20% jitter
let connected = try await sm.connect(to: peripheral, via: manager)

let mock = MockPeripheral(name: "Test HR Monitor")
await mock.addCharacteristic(
    CBUUID(string: "2A37"), to: CBUUID(string: "180D"),
    properties: [.read, .notify],
    initialValue: Data([0x00, 72])
)

let bpm = try await yourHeartRateReader(from: mock)
XCTAssertEqual(bpm, 72)

The same function signature takes a real ConnectedPeripheral in production and a MockPeripheral in tests. Plain protocol polymorphism, so you skip Sourcery, Mockingbird, and the rest of the mocking-framework tax.

"Just ask AI to write it"

Already tried. So has every other engineer at every hardware company. Cursor, Claude, Copilot all output CoreBluetooth code that:

• ✗ Compiles cleanly
• ✗ Runs in the simulator (where BLE doesn't actually work)
• ✗ Skips state restoration entirely
• ✗ Botches background-mode scan filters
• ✗ Treats didUpdateValueFor as if it's only for reads
• ✗ Forgets NSBluetoothAlwaysUsageDescription (app crashes on first scan)
• ✗ Implements OTA as "send the bytes", with no MTU chunking, CRC, or resume

Not AI's fault. The public CoreBluetooth corpus is Apple's toy-grade samples plus a decade of broken Stack Overflow threads. Garbage in, confident garbage out.

Antenna is the part that doesn't exist on the public internet: decisions you only learn by shipping this stuff to the App Store. Hand the kit to your AI tool and it'll happily extend it for you. That's the right way to use both.

Pricing

Pay once. Keep the source forever. 12 months of free updates with every tier. Gumroad handles VAT, GST, and US sales tax, and you get a proper invoice at checkout.

Add-ons

30-day money-back guarantee. If Antenna doesn't compile cleanly into your project, email me and I'll refund + try to help.

Who made this

Things people ask before buying

If yours isn't here: hello@antennakit.dev. I read every email.