Build Your Own Custom iOS BLE App From Scratch: A Maker's Guide to CoreBluetooth

Connecting your iPhone to custom hardware opens up an amazing world of possibilities. Whether you are building a smart thermometer, a custom remote control for your drone, or a garage door opener, Bluetooth Low Energy (BLE) is the standard tool for the job. However, if you look at Apple's official documentation, you might easily get overwhelmed by the mountain of delegate methods and structural requirements. We are going to strip away the complexity and build a working BLE scanner and controller from scratch using Swift and CoreBluetooth.

Getting Your Xcode Project Ready for BLE
Scanning for Peripherals and Establishing Connections
Discovering Services, Characteristics, and Exchanging Data
Frequently Asked Questions

Getting Your Xcode Project Ready for BLE

Before we write a single line of Swift code, we have to deal with Apple's strict privacy rules. If you do not explicitly tell iOS why your app needs to use Bluetooth, the operating system will crash your application the very millisecond it tries to initialize the Bluetooth chip. This is a safety feature to stop apps from tracking user locations without consent.

Open your Xcode project and head straight to your Info.plist file, or click on your project target settings and find the Info tab. You need to add a new key named Privacy - Bluetooth Always Usage Description (internally known as NSBluetoothAlwaysUsageDescription). In the value field, write a clear, friendly sentence that your users will see when the app asks for permission. Something like, "This app needs Bluetooth access to connect to your custom IoT sensor device" works perfectly. If you plan on supporting older iOS versions, you should also add the legacy key Privacy - Bluetooth Peripheral Usage Description just to cover your bases.

Xcode Info.plist configuration screen showing the NSBluetoothAlwaysUsageDescription key and its corresponding user-facing string value.

With the permissions configured, we can set up our code structure. We need to import the CoreBluetooth framework. Instead of cluttering your main ViewController, it is best practice to create a dedicated class to manage your Bluetooth connections. Let's call this class BLEManager. This class needs to inherit from NSObject and conform to CBCentralManagerDelegate and CBPeripheralDelegate. These protocols are the communication highways Apple uses to tell us what the Bluetooth chip is doing.

Scanning for Peripherals and Establishing Connections

To start scanning, we first need to initialize our CBCentralManager. The "central" in BLE terminology is your iPhone; it acts as the hub that searches for, connects to, and consumes data from external accessories, which we call "peripherals" (like your microcontroller or sensor beacon).

Pro-Tip: Always declare your CBCentralManager as an instance-level property. If you initialize it inside a temporary setup function, Swift's automatic reference counting will destroy it as soon as the function ends, and your scan will never start.

Honestly, I've tried this myself quite a few times when building a custom controller for my DIY smart garden project using an ESP32. I remember spending a solid three hours tearing my hair out because my app kept crashing or silently failing. I realized I had declared my manager as a local variable inside a setup function instead of holding a strong reference to it at the class level. As soon as the setup function finished executing, the manager was garbage-collected, killing the Bluetooth connection instantly. Always make sure your manager lives as a class-level property!

Once your manager is initialized, iOS will immediately call the centralManagerDidUpdateState(_:) delegate method. You must wait for this method to trigger and verify that the state is .poweredOn before you call scanForPeripherals(withServices:options:). Trying to scan when the state is .poweredOff or .unauthorized will result in errors.

Architectural diagram showing the communication flow between CBCentralManager on the iPhone, CBPeripheral, and the external ESP32 or Arduino BLE device.

When your scanner finds a device, the delegate method centralManager(_:didDiscover:advertisementData:rssi:) fires. Here, you get access to the CBPeripheral object, the advertisement data (like the device name), and the RSSI value which indicates signal strength. Once you find the peripheral you want, you call centralManager.connect(peripheral, options: nil) to establish a stable connection.

Discovering Services, Characteristics, and Exchanging Data

Connecting to the peripheral is only half the battle. Now we need to explore what it has to offer. BLE devices organize their data into a hierarchy of Services and Characteristics. Think of a Service as a folder (e.g., "Environmental Sensor Data") and a Characteristic as an individual file inside that folder (e.g., "Temperature Reading"). Each of these has a unique identifier called a UUID.

Once the connection succeeds, the central manager calls the centralManager(_:didConnect:) delegate method. Inside this method, you must set the peripheral's delegate to your class and call peripheral.discoverServices(nil). If you want your app to run efficiently, replace nil with an array of specific service UUIDs you are interested in. This prevents your phone from wasting precious battery life querying services it doesn't care about.

After services are discovered, we loop through them and discover their characteristics using peripheral.discoverCharacteristics(nil, for: service). When these characteristics are found, we can finally read, write, or subscribe to them. If you want your app to update automatically whenever a sensor value changes, use peripheral.setNotifyValue(true, for: characteristic).

Flowchart depicting the step-by-step delegate callbacks from centralManagerDidUpdateState to didDiscoverCharacteristicsFor service.

When sending data back to your hardware, you convert your data into a byte array using Swift's Data type. For instance, sending a simple text string or a byte value to toggle an LED looks like this: peripheral.writeValue(data, for: characteristic, type: .withResponse). By choosing .withResponse, iOS will confirm that the peripheral successfully received the packet, making your app's communication reliable and robust.

Frequently Asked Questions

Why does my app crash as soon as I instantiate CBCentralManager?

This is almost always caused by a missing NSBluetoothAlwaysUsageDescription key in your project's Info.plist file. iOS requires this description text to show to the user when requesting Bluetooth permissions. If it is missing, the OS terminates the app immediately for security reasons.

Can I test my BLE app using the official iOS Simulator?

No, the iOS Simulator does not support Bluetooth Low Energy emulation. You must build your project on a real physical iPhone or iPad to test any BLE scanning, connection, or data transfer code.

What is the difference between writing with response and without response?

Writing with response (.withResponse) acts like a handshake; your iOS app waits for the peripheral to acknowledge it received the data, which is highly reliable but slightly slower. Writing without response (.withoutResponse) sends the data out immediately without waiting for confirmation, which is faster but offers no guarantee that the peripheral actually received the packet.

How do I convert a byte value from a characteristic into a readable number in Swift?

When you receive data in peripheral(_:didUpdateValueFor:error:), the value is stored as a Data object. You can extract integers or strings by converting these raw bytes. For example, a single byte can be extracted using let byteValue = [UInt8](data)[0], which you can then easily display in your user interface.