How to Use LightBlue®: The Go-To BLE Development Tool
We at Punch Through first began developing LightBlue® for iOS back in 2012 out of internal necessity. We were a young company carving out a determined niche in the exciting new world of Bluetooth Low Energy (BLE), the revolutionary new iteration of the Bluetooth spec released in 2010. In 2011, Apple’s iPhone 4S arrived as the first mobile device to support Bluetooth 4.0 (aka Bluetooth Low Energy or Bluetooth Smart), and the rest of the mobile world soon followed. The potential applications were endless. We dove in headfirst and were immediately swept up by the first development wave of BLE devices and the apps that would control them.
As with any new technology, rapid prototyping was the name of the game, and we needed to bring all of our cards to the table. Every embedded device we worked on needed the same basic tests—ensure all the intended BLE components (services, characteristics) were there, were set up correctly, and that we could successfully communicate with them. There was a distinct lack of good tools available for this at the time, so the obvious thing to do was build one ourselves. Thus begat LightBlue®.
The app turned out to be an absolutely crucial element of our success, and we saw no reason to keep it to ourselves. So pretty soon after its development, we released LightBlue®, completely free, to the App Store. It was joined by an Android version in 2017. At its core, Punch Through is just a group of people who are passionate about learning and building things, and we’re much better served when we contribute back to the greater developer community that’s allowed us to thrive. We’re immensely proud of how LightBlue® has helped others in many different capacities, and we hope this exploration of its major applications and features might help and inspire you too!
The Device Detector (Where’s my Fitbit?)
To interact with any BLE device, the first thing you need to do is, obviously, locate it. For many of you, this is literally the only thing you’re interested in doing. Although it was not our target audience, we’ve had tens of thousands of users successfully locate their lost Fitbits and other BLE devices dropped under beds, left in cars, carried off by pets, etc.
As an engineer, you might want a quick way to check the signal strength of your peripheral, see which ones are close by and actively advertising, or identify the one on your desk in an office full of similar devices. All of this and more can be done easily from the very first screen of LightBlue®.
⚠️ In general, LightBlue® can only see your device if it’s advertising. Most of the time, if the device is already connected to something, it won’t advertise, and LightBlue® will not be able to see it—even if it’s connected to the same phone or tablet you’re using LightBlue® on. Go to your phone or tablet’s Settings->Bluetooth page and “Forget” the device if you see it listed there.
In addition to making sure Bluetooth is on, there are a couple more platform-specific notes to be aware of:
- On iOS, ensure you’ve given the app permission to use Bluetooth (check this in the LightBlue® page in your iOS device’s standard Settings app).
- For Android, ensure that you’ve provided the app access to Location Services in order to see BLE scan results. Our app doesn’t use nor track your location — this is an Android SDK requirement as dictated by Google to use Bluetooth at all.
Breakdown of the Scan Screen
The Device List
When you launch the app, you should be greeted with a list of nearby BLE devices by name. If the device is not advertising a name, it’ll simply be listed as “Unnamed”. Most of the “Unnamed” devices you see are likely nearby phones and laptops, which can be a lot if you’re in an office or even near a crowded street.
Signal Strength
One of the most important pieces of information LightBlue® provides is the device’s current RSSI. This is a relative measure of the estimated signal strength received by the mobile device, and because it’s in decibels, it’s shown as a negative number between -99 and -30. The perceived power of a remote device’s signal to a mobile device is determined by many different factors, one of which is relative distance. The closer you are to the peripheral device, the stronger the signal should appear to be. Next to each device’s name in the app, you should see a regularly-changing negative number, which is the RSSI, accompanied by an image of signal bars. The closer you are, the closer the RSSI will be to 0, and the more signal bars will turn from gray to blue.
So, How do I Use LightBlue® to Find a Lost Device?
To locate a specific Bluetooth device using the app, look for it by name in the device list. If you do not see it, ensure the device is not already connected to your mobile device or anything else, because most devices will stop advertising when they are connected and LightBlue® will not be able to detect it. Also remember that if you’re out of range of the device, or the battery is dead, no app can detect it.
Watch the RSSI value and signal strength bars next to your device’s name in the list, and start walking around, bringing the app with you. As you get closer, the RSSI value will get less negative and, within a certain range, the more of the signal bars will turn blue.
Sorting
At the top of the screen, you should see a “Sort” button. Tapping this will sort the devices in the list by RSSI, from strongest signal to weakest. Note that since RSSIs are constantly changing, the list will not remain sorted for very long. Automatically reordering them as they change would just be chaos to look at, so we don’t do that. Instead, just tap the “Sort” button any time you’d like to re-sort the list.
Filtering
If you’re in a setting with a lot of extraneous Bluetooth devices, sorting by RSSI might not be enough to easily keep track of those nearest you. Instead, you can simply set the app to filter the scan list for devices with a minimum RSSI level.
Tap the “Filter” button at the top of the scan screen, and you should see a toggle to filter by RSSI. Toggle this on, and a slider should appear that lets you set a minimum RSSI value. Return to the main scan list, and you should only see devices with a signal strength above that threshold. Newly discovered devices thereafter will only be added to the list if they have a strong enough signal strength.
You can also filter the device list by name, using the search bar on iOS, or the search button on Android at the top of the scan screen.
Stale Devices (Currently on iOS Only)
If a peripheral device has not been detected for more than 30 seconds, either because it has been powered off, has stopped advertising (e.g., because it’s connected to something), or is out of range, it’ll turn “stale” and become grayed out in the scan list. You’ll no longer be able to connect to it at this point. If the device is re-detected, it’ll no longer be grayed out in the list and you may once again tap to connect.
Refreshing Your Scan List
If you’re finding your list has become too cluttered and you’d like to clear it and start over, simply pull down on the list to refresh it. Also, if you have a filter applied, then tapping the Sort button will automatically clear all stale devices on iOS.
What’s on My Device? Connecting and Browsing the GATT Table
What kind of data does your device hold? Maybe you just spun up a new BLE profile on an embedded BLE development kit and want to make sure it looks right from the central perspective, or maybe you have an existing BLE device and just want to see what kind of information is on it. Whatever your end goal, the first step to investigating a BLE device is to connect to it.
Connecting to Your Device
Once you’ve located the device in the scan list as described above, simply tap on it and LightBlue® will connect. If the connection is successful, you should be presented with a screen that lists the device’s name at the top, followed by advertisement data, and then its services and characteristics.
Advertisement Data
When Bluetooth peripheral devices advertise, they can optionally provide certain kinds of information with those advertising packets. The kinds of data that can be included in these packets is defined by the Bluetooth SIG and is standard across all BLE devices.
When you connect to a device in LightBlue®, you should see a line labeled “Advertisement Data” near the top of the screen, and if on iOS, a button to show or hide the data.
LightBlue® will only display the data fields that were included in the advertisement packet for that particular device.
Browsing the GATT Table
As mentioned, the main device connection screen will display a list of all services and characteristics available on the connected peripheral device.
⚠️ iOS does not allow apps access to a few standard services, like the Generic Attribute and Generic Access services. These services therefore will not show up in the iOS app’s services view.
LightBlue® will recognize a long list of common services and characteristics defined by the Bluetooth SIG. If LightBlue® recognizes a particular service or characteristic, it’ll display it by name. it’ll also try to read known characteristics’ values and display them in the appropriate format.
If LightBlue® does not recognize a service or characteristic, it’ll instead display the Universally Unique Identifier (UUID) by which that service or characteristic is known.
Interacting with a Device: Reading, Writing, and Subscribing to Characteristics
What’s the point of connecting to a device if the fun stops there? If you’ve gotten as far as browsing a device’s services and characteristics, chances are you want to interact with them in some way. Perhaps you need to quickly test that BLE dev kit you’ve been working on to ensure a given BLE command triggers some expected LED sequence. Or the heart rate monitor you have actually updates at regular intervals and fires notifications when it does. Whatever you need to do, LightBlue® makes it easy.
From the main device connection screen, tap on a given characteristic to pull up the characteristic interaction screen. From here, you should see details such as the characteristic’s name, UUID, properties, and descriptors (if any).
Depending on the properties of the characteristic, you may also see UI for reading or writing the value of the characteristic, and/or subscribing to notifications.
Reading from a Characteristic
If a characteristic is readable (i.e., contains the “Read” property), then reading its value is as simple as tapping on the “Read again” button. Each time you perform a new read, the value will show up in the list below with a timestamp of when the read occurred. The list will display the five most recent values.
Writing to a Characteristic
If a characteristic is writable, you should see a button to “Write new value” on iOS, or “Write” on Android. Tapping this should take you to a screen with a special keyboard based on the currently selected write type* where you can input a value to write to the characteristic. Once you’ve written the value, you should be returned to the main screen where the recently written value should appear under the write new value button. If the characteristic is readable, you should also see the value added to the recently read list.
Pro tip: On iOS, you can change the format of the data you’re reading and writing by tapping the button at the top right corner of the characteristic interaction screen. By default, it’ll be set to Hex, but you can also use UTF-8, binary, decimal, and octal. You can also toggle the endianness of the values from little to big.
On Android, you can select the desired data format by tapping on the “Data format” dropdown. Tap on the text field under the “Written values” section and start inputting your data before tapping “Write” to have LightBlue® send the data out.
Subscribing to Notifications
If the characteristic includes the notify or indicate property, a button should appear opposite the “Read” button to start listening for notifications. When toggled on, you should see the read value list update automatically with the latest values as they come in. On iOS, if you leave that characteristic’s detail screen or background the app, you should see these updates come through as system notifications.
⚠️ For iOS system notifications to work, ensure you have enabled notifications for LightBlue® in the Settings app. LightBlue® will never send you notifications other than subscribed characteristic value updates.
Cloud Connect
On iOS, the Cloud Connect feature of the characteristic interaction screen allows you to automatically pipe incoming notifications or indications to Amazon’s AWS IoT platform or Adafruit IO. For more details, check out our blog post, Introducing Cloud Connect for LightBlue®.
Becoming the Device: Adopting the Peripheral Role
One of our favorite LightBlue® features for iOS* is the ability to create your own “virtual” peripheral, and make your iOS device advertise as that peripheral. There are many possible uses of this feature, but our mobile team finds it especially useful for quickly testing our mobile BLE apps!
*We hope to see this feature soon on LightBlue® Android!
Adding a New Virtual Peripheral
To use this feature, navigate to the bottom tab labeled “Virtual Devices.” If it’s your first time using the feature, you should see an empty list. Tap the plus sign at the top of the screen to add a new virtual peripheral. You will be presented with a list of standard GATT profiles to choose from (if you just want to start from scratch, choose “Blank”). Select one, tap “Save” and your new virtual peripheral should now appear in the list.
Pro tip: Did you know you can copy entire profiles of devices you’re connected to and use them as virtual peripherals? When you’re connected to a device in LightBlue®, simply tap the “Clone” button at the top of the main services and characteristics screen. A virtual peripheral with the same GATT profile will appear in your list of Virtual Devices.
Advertising as Your Virtual Peripheral
To start your mobile device advertising as a particular virtual peripheral, tap on the empty bubble to the left of its name in the list. A blue checkmark will fill the bubble and your mobile device will now be discoverable as that peripheral. You can only advertise as one virtual peripheral at a time. Tap the checkmark again to stop advertising.
Configuring Your Virtual Peripheral
Once you’ve created a virtual peripheral, you can configure its services and characteristics however you want! Tap on your peripheral from the list, and you should see an overview of its existing services and characteristics. Just as with the normal connected peripheral screen, known GATT services and characteristics will display their human readable names. At the top, under “General”, you can set the peripheral name and device UUID.
Adding Services and Characteristics
To add a service or characteristic, tap on the “Options” button at the top of the virtual peripheral’s configuration screen. You should see a menu with options to add a service or characteristic.
Tapping “Add service” will create a new service with a randomly assigned UUID, as well as a new characteristic under that service, also with a randomly assigned UUID.
Tapping “Add characteristic” will prompt you to select one of the existing services to add the new characteristic to. A new characteristic with a randomly assigned UUID will be created under the selected service.
Editing Services and Characteristics
To edit a service’s UUID, tap the info icon to the right of that service. The UUID you specify must be 16 or 128 bits.
To edit a characteristic, tap on it from the virtual peripheral configuration screen. You should be brought to a characteristic configuration screen. From here, you can edit the characteristic’s UUID, user description, value, and properties.
Pro tip: Just like when reading and writing to a connected peripheral, you can edit the data format used when setting the characteristic’s value from the top right of the characteristic configuration screen.
Deleting Services and Characteristics
To delete a characteristic, swipe left on that row from the main virtual peripheral configuration screen, which will reveal a Delete button. To delete a service, delete all of its characteristics.