But the underlying technology hasn't kept pace with how we actually use it. True wireless earbuds, all-day hearing aids, shared audio experiences – none of these were anticipated when the original Bluetooth audio stack was designed.

LE Audio, introduced by the Bluetooth SIG and finalized in 2022, is a ground-up redesign that replaces the Classic Bluetooth audio stack with an entirely new architecture built on Bluetooth Low Energy. It introduces a new codec (LC3), new transport primitives (isochronous channels), new profiles for unified audio streaming, and an entirely new broadcast capability called Auracast.

Together, these changes address long-standing limitations around audio quality, power consumption, multi-device streaming, and accessibility.

This handbook is a comprehensive technical deep dive into LE Audio: what it is, why it exists, how it works at every layer of the stack, and how it's implemented in Android (AOSP). We'll start with the history and motivation, build up an intuitive understanding of the core concepts, and then go deep into the architecture and code.

Here's what you'll learn:

• Why Classic Bluetooth audio hit its limits, the relay problem, the two-profile split, power constraints, and the lack of broadcast or hearing aid support

• How the LC3 codec works, and why it delivers better audio at roughly half the bitrate of SBC

• What isochronous channels are, the new transport primitive that replaces SCO and ACL for audio, in both unicast (CIS) and broadcast (BIS) forms

• How the LE Audio profile stack is organized, from foundational services like BAP and PACS up through use-case profiles like TMAP and HAP

• How multi-stream audio eliminates the earbud relay hack, with native synchronized streams to each earbud

• What Auracast enables, one-to-many broadcast audio and the infrastructure that supports it

• How all of this is implemented in Android (AOSP), a full walkthrough of the architecture from framework APIs through the native C++ stack to the Bluetooth controller, including the state machines, codec negotiation, and data flow

Whether you're a Bluetooth engineer, an embedded developer, an Android platform engineer, or just someone curious about how your devices actually work, this guide aims to make one of the most complex parts of modern wireless systems feel approachable.

If you've ever wondered why your earbuds sound great for music but terrible on calls, why one earbud always dies first, or why you can't easily share audio with people around you, read on. The answers are all here.

Table of Contents

1. Once Upon a Time in Bluetooth Land

2. The Problems With Classic Bluetooth Audio

3. Enter LE Audio: The Hero We Needed

4. The LC3 Codec: Better Sound, Less Power, More Magic

5. Isochronous Channels: The New Plumbing

6. The LE Audio Profile Stack: A Layer Cake of Specifications

7. Multi-Stream Audio: No More Left Earbud Relay

8. Auracast: Broadcast Audio for the Masses

9. LE Audio in Android/AOSP: The Implementation

10. The AOSP Architecture: From App to Antenna

11. Server-Side (Source) Implementation

12. Client-Side (Sink) Implementation

13. The State Machine That Runs It All

14. Putting It All Together: A Day in the Life of an LE Audio Packet

15. Wrapping Up

1. Once Upon a Time in Bluetooth Land

Picture this: it's 2003. Flip phones are cool. The first Bluetooth headsets hit the market, and suddenly you can walk around looking like a cyborg while taking calls.

That mono, telephone-quality audio? Powered by a little thing called HFP (Hands-Free Profile) using the CVSD codec at a whopping 64 kbps. It sounded like your caller was speaking from inside a submarine, but hey, no wires!

Fast forward a few years. We got A2DP (Advanced Audio Distribution Profile) for streaming music, bringing us SBC (Sub-Band Codec), the audio codec equivalent of a Honda Civic. Not flashy, not terrible, gets the job done. A2DP gave us stereo music streaming, and life was good.

For a while.

The Bluetooth SIG (Special Interest Group), the consortium of thousands of companies that governs Bluetooth, kept iterating on the classic Bluetooth audio stack. We got better codecs like aptX, AAC, and LDAC. But here's the thing: all of these were built on top of the same ancient plumbing. It's like renovating your kitchen while the house's foundation is slowly cracking.

The Bluetooth audio stack was built on BR/EDR (Basic Rate/Enhanced Data Rate), the "Classic Bluetooth" radio. This is the same radio technology from the early 2000s, designed when streaming audio from a phone to a single headset was the pinnacle of innovation. Nobody imagined true wireless earbuds, hearing aids that stream directly from your phone, or broadcasting audio to an entire airport terminal.

By the late 2010s, Bluetooth audio was showing its age. Badly.

2. The Problems With Classic Bluetooth Audio

Let's catalogue the issues of Classic Bluetooth Audio, because they're educational:

Issue #1: The Two-Profile Personality Disorder

Classic Bluetooth had a split personality. Want to listen to music? Use A2DP with SBC/AAC at nice quality. Want to make a phone call? Switch to HFP, which uses a completely different codec (CVSD or mSBC) at dramatically lower quality.

Ever noticed how your wireless earbuds sound amazing playing Spotify, but the moment you jump on a Zoom call, it sounds like you're talking through a paper towel tube? That's the A2DP-to-HFP switchover. Different profiles, different codecs, different audio paths. The switch isn't even graceful, there's often an audible glitch.

The above diagram shows the audio quality drop when switching from A2DP (music streaming with SBC/AAC at high quality) to HFP (voice call with CVSD/mSBC at low quality). The switch causes an audible glitch and dramatic reduction in audio fidelity.

Issue #2: The Relay Problem (True Wireless Earbuds)

When you have true wireless earbuds (left and right earbuds with no wire between them), Classic Bluetooth has a dirty little secret: A2DP can only stream to one device at a time.

So what actually happens with your fancy earbuds?

1. Your phone sends the stereo audio stream to the primary earbud (usually the right one)

2. The primary earbud receives both left and right channels

3. It then relays the other channel to the secondary earbud via a separate Bluetooth link

This relay architecture has a few important consequences. First, you have double the battery drain on the primary earbud (it dies first, you've noticed this). You also get higher latency to the secondary earbud

There are also potential synchronization issues between left and right channels. And if the primary earbud runs out of battery or loses connection, both earbuds go silent.

Issue #3: Power Hungry

BR/EDR was designed in an era when "low power" meant "runs on AA batteries." Streaming audio over Classic Bluetooth is relatively power-hungry. The radio has to maintain a constant, high-bandwidth connection. For devices like hearing aids that need to run all day on tiny batteries, this was a dealbreaker.

Issue #4: One-to-One Only

Classic Bluetooth audio is fundamentally point-to-point. One source, one sink (or at best, a very hacky "dual audio" implementation where the phone maintains two separate A2DP connections). There's no way to broadcast audio to multiple listeners simultaneously without establishing individual connections to each one.

Imagine you're at an airport gate and want to stream the boarding announcements to everyone's earbuds. With Classic Bluetooth, you'd need to pair with every single person's device individually. Good luck with that at Gate B47.

Issue #5: No Standard for Hearing Aids

Before LE Audio, there was no official Bluetooth standard for hearing aids. Apple created its own proprietary MFi (Made for iPhone) hearing aid protocol. Google created ASHA (Audio Streaming for Hearing Aid) as a semi-proprietary BLE-based solution for Android. Neither was an official Bluetooth standard, and interoperability was... let's call it "aspirational."

3. Enter LE Audio: The Hero We Needed

In January 2020, at CES, the Bluetooth SIG unveiled LE Audio, a complete reimagining of Bluetooth audio built on top of Bluetooth Low Energy (BLE) instead of Classic BR/EDR.

The core transport features (isochronous channels, EATT, LE Power Control) shipped in the Bluetooth Core Specification v5.2 in late 2019/early 2020. But the full suite of LE Audio profiles and services wasn't completed until July 12, 2022, when the Bluetooth SIG officially announced that all LE Audio specifications had been adopted.

The effort involved over 25 working groups, thousands of engineers from hundreds of companies, and took approximately 7 years from initial concept to completion. This wasn't a minor spec update. It was a ground-up redesign.

Here's what LE Audio brings to the table:

Think of it this way: Classic Bluetooth Audio is like a landline telephone system: reliable, well-understood, but fundamentally limited.

LE Audio is like the transition to VoIP and streaming: same goal (getting audio from A to B), but entirely new infrastructure that unlocks capabilities the old system could never support.

4. The LC3 Codec: Better Sound, Less Power, More Magic

At the heart of LE Audio is a new mandatory codec called LC3: Low Complexity Communication Codec. If SBC is the Honda Civic, LC3 is a Tesla Model 3. It's more efficient, more capable, and designed from the ground up for the modern era.

What Even Is a Codec?

For the uninitiated: a codec (coder-decoder) is an algorithm that compresses audio so it can be transmitted over a limited-bandwidth wireless link, and then decompresses it on the other side. The better the codec, the better the audio sounds at a given bitrate, and the less battery it eats doing the math.

LC3 Technical Specs

LC3 was developed by Fraunhofer IIS (the same folks who brought us MP3 and AAC, they know a thing or two about audio coding) and Ericsson.

Here are the key specs:

• Sample rates: 8, 16, 24, 32, 44.1, and 48 kHz

• Bit depth: 16, 24, or 32 bits

• Frame durations: 7.5 ms and 10 ms

• Bitrate range: 16 to 320 kbps per channel

• Algorithmic latency: 7.5 ms (for 7.5 ms frames) or 10 ms (for 10 ms frames)

• Channels: Mono or stereo

Why LC3 Is Better Than SBC

The big headline: LC3 delivers equivalent or better audio quality at roughly half the bitrate of SBC.

In listening tests conducted by Fraunhofer, participants rated LC3 at 160 kbps as equivalent to or better than SBC at 345 kbps. That's not a marginal improvement, it's nearly a 2x efficiency gain.

The above bar chart compares subjective audio quality ratings of LC3 and SBC at various bitrates. LC3 at 160 kbps is rated equivalent to or better than SBC at 345 kbps, demonstrating roughly 2x efficiency improvement.

This efficiency gain translates directly into one of two things (or a combination of both):

1. Better audio quality at the same power, more bits for quality, less wasted

2. Same audio quality at lower power, the device runs longer on a charge

How LC3 Actually Works (The Simplified Version)

LC3 uses a modified discrete cosine transform (MDCT), a mathematical technique that converts audio from the time domain (a waveform) to the frequency domain (which frequencies are present). This is similar to what AAC and other modern codecs do, but LC3's transform is optimized for low computational complexity.

Here's the encoding pipeline, simplified:

This is a flowchart of the LC3 encoding pipeline. PCM audio input passes through an MDCT (Modified Discrete Cosine Transform) to convert from time domain to frequency domain. Then spectral noise shaping applies a psychoacoustic model to hide quantization noise in inaudible frequency regions, followed by quantization and entropy coding to produce the compressed LC3 bitstream.

The key insight is spectral noise shaping: LC3 uses a psychoacoustic model (a model of how humans perceive sound) to ensure that the quantization noise (the artifacts introduced by compression) is shaped to fall in frequency regions where it's least audible. Your ears literally can't hear the distortion. Clever, right?

LC3 vs. LC3plus

You might also hear about LC3plus, an enhanced version that adds:

• Super-wideband and fullband modes (up to 48 kHz audio bandwidth)

• Additional frame sizes (2.5 ms, 5 ms) for ultra-low-latency applications

• Higher quality at very low bitrates

LC3plus is not part of the base LE Audio spec but is used in some implementations (like DECT NR+ for cordless phones).

5. Isochronous Channels: The New Plumbing

Here's where things get architecturally interesting. Classic Bluetooth audio used SCO (Synchronous Connection-Oriented) links for voice and L2CAP over ACL (Asynchronous Connection-Less) links for A2DP streaming. These were okay, but they're like using garden hoses for different purposes, functional but not optimized for audio.

LE Audio introduces a brand-new transport mechanism at the link layer: Isochronous Channels. These are purpose-built pipes for time-sensitive data like audio.

What "Isochronous" Means

"Isochronous" (from Greek: iso = equal, chronos = time) means "occurring at regular time intervals." An isochronous channel guarantees that data arrives at a predictable, regular cadence, exactly what you need for audio.

Think of it this way:

• Asynchronous (ACL): "Here's some data. It'll get there when it gets there." (Great for file transfers, bad for audio)

• Synchronous (SCO): "Here's data that MUST arrive on time, and if it doesn't, too bad." (Old voice links, no retransmissions)

• Isochronous: "Here's data that should arrive on time, and we'll try our best to make that happen with some smart retransmission." (Best of both worlds)

This above chart is a comparison of three Bluetooth transport types: Asynchronous (ACL) delivers data without timing guarantees, Synchronous (SCO) delivers data on a fixed schedule with no retransmission, and Isochronous delivers data on a regular schedule with smart retransmission, combining the reliability of ACL with the timing guarantees of SCO.

Two Flavors: CIS and BIS

Isochronous channels come in two flavors, and this is where the magic happens:

CIS — Connected Isochronous Stream

CIS is for point-to-point audio (unicast). It's what your phone uses to stream music to your earbuds.

The aboe is a diagram of a Connected Isochronous Stream (CIS) setup: a phone (Unicast Client) sends two synchronized CIS streams within a single CIG (Connected Isochronous Group), one to the left earbud and one to the right earbud. Arrows show bidirectional audio flow, with music going to the earbuds and microphone audio returning to the phone.

Key features of CIS:

• Bidirectional: Audio can flow in both directions simultaneously (unicast to earbuds AND microphone audio back)

• Acknowledged: The receiver sends acknowledgments, enabling retransmissions of lost packets

• Grouped into CIGs: Multiple CIS streams are grouped into a CIG (Connected Isochronous Group), ensuring they're synchronized

That last point is crucial. A CIG ensures the left and right earbud receive their audio packets with tight synchronization, no more "my left ear is 50ms ahead of my right ear" issues.

BIS — Broadcast Isochronous Stream

BIS is for one-to-many audio (broadcast). It's the foundation of Auracast.

The above is a diagram of a Broadcast Isochronous Stream (BIS) setup: a single broadcast source transmits audio via a BIG (Broadcast Isochronous Group) containing multiple BIS streams. Multiple receivers (broadcast sinks) independently receive the same audio without any connection to the source, similar to FM radio.

Key features of BIS:

• Unidirectional: One-way only (source to listeners), makes sense, you can't have a million people talking back

• Unacknowledged: No acks from listeners (the source doesn't even know who's listening)

• Grouped into BIGs: Multiple BIS streams form a BIG (Broadcast Isochronous Group)

• Scalable: No upper limit on listeners, it's actual radio broadcasting

The ISO Data Path

Under the hood, isochronous data follows a specific path through the controller:

The above is a diagram of the isochronous data path through the Bluetooth controller. Audio frames from the host pass through HCI, then through the ISO Adaptation Layer (ISO-AL) which handles segmentation, timestamping, and flush timeout management, before reaching the Link Layer for transmission over the air.

The key innovation is the ISO-AL (Isochronous Adaptation Layer), which sits between HCI and the Link Layer. It handles:

• Segmentation: Breaking audio frames into link-layer-sized pieces

• Time-stamping: Each audio frame gets a timestamp so the receiver knows exactly when to play it

• Flush timeout: If a frame can't be delivered in time, it's flushed (better to skip a frame than play it late)

6. The LE Audio Profile Stack: A Layer Cake of Specifications

If you've ever looked at the list of LE Audio specifications and felt your eyes glaze over, you're not alone. There are a LOT of them. But they're organized in a logical hierarchy, and once you understand the structure, it all makes sense.

Visual: The Profile Stack

Here's a three-tier diagram of the LE Audio profile stack:

Tier 1 (foundation) contains BAP, VCP, MCP, CCP, MICP, CSIP, and BASS. Tier 2 (grouping layer) contains CAP, which coordinates the Tier 1 profiles. Tier 3 (use-case profiles) contains TMAP for telephony and media, HAP for hearing aids, and PBP for public broadcasts. Each tier builds on the one below it.

Think of it as a wedding cake with three tiers:

Tier 1: The Foundation (Core Services and Profiles)

These are the building blocks everything else is built on:

BAP — Basic Audio Profile

The big kahuna. BAP defines the fundamental procedures for discovering, configuring, and establishing LE Audio streams. It defines two roles:

• Unicast Client: The device that initiates and controls audio streams (typically your phone)

• Unicast Server: The device that renders or captures audio (typically your earbuds)

BAP relies on several GATT services:

• PACS (Published Audio Capabilities Service): "Hey, here's what audio formats I support"

• ASCS (Audio Stream Control Service): "Let's set up and manage audio streams"

VCP — Volume Control Profile

Handles remote volume control. Your phone can control the volume on your earbuds (and vice versa) using the VCS (Volume Control Service).

MCP — Media Control Profile

Allows remote control of media playback. Pause, play, skip, and so on, through the MCS (Media Control Service). Like AVRCP for LE Audio.

CCP — Call Control Profile

Manages phone call state. Answer, reject, hold calls via the TBS (Telephone Bearer Service). This replaces HFP's call control functionality.

MICP — Microphone Control Profile

Handles remote mute/unmute of a device's microphone. Simple but essential, ever been on a call where you couldn't figure out how to mute? MICP standardizes it.

CSIP — Coordinated Set Identification Profile

This is the "these two earbuds belong together" profile. It uses the CSIS (Coordinated Set Identification Service) to tell the phone: "Hey, I'm the left earbud, and my buddy over there is the right earbud. We're a set."

Without CSIP, your phone would treat each earbud as a completely independent device. CSIP is what enables seamless "coordinated set" behavior.

BASS — Broadcast Audio Scan Service

Handles the discovery of broadcast audio sources. A device with BASS can scan for nearby broadcasts and help another device (like hearing aids) tune into them.

Tier 2: The Grouping Layer

CAP — Common Audio Profile

CAP sits on top of the Tier 1 profiles and provides common procedures that higher-level profiles use. It handles things like:

• Discovering a coordinated set of devices (using CSIP)

• Setting up unicast audio streams to a coordinated set (using BAP)

• Initiating broadcast audio streams

Think of CAP as the "orchestrator" that coordinates all the Tier 1 profiles to work together.

Tier 3: The Use-Case Profiles

These are the profiles that map to actual user scenarios:

TMAP — Telephony and Media Audio Profile

The "all-in-one" profile for typical audio use cases. TMAP defines roles like:

• Call Terminal (CT): Can make and receive calls

• Unicast Media Sender (UMS): Can send media audio (your phone)

• Unicast Media Receiver (UMR): Can receive media audio (your earbuds)

• Broadcast Media Sender (BMS): Can broadcast media audio

• Broadcast Media Receiver (BMR): Can receive broadcast media audio

If you're building a typical phone + earbuds experience, TMAP is your profile.

HAP — Hearing Access Profile

The standardized profile for hearing aids. This replaces the proprietary MFi and ASHA solutions with an official Bluetooth standard. HAP defines procedures for:

• Streaming audio to hearing aids

• Adjusting hearing aid presets

• Controlling volume on hearing aids

This is a huge deal. For the first time, hearing aids can interoperate across all Bluetooth devices using a standard protocol.

PBP — Public Broadcast Profile

Defines how to set up and discover public broadcasts (Auracast). This is what enables "broadcast audio in the airport terminal" scenarios.

7. Multi-Stream Audio: No More Left Earbud Relay

Remember the relay problem with Classic Bluetooth? LE Audio eliminates it entirely with multi-stream audio.

With LE Audio, the source device (your phone) can send independent, synchronized audio streams directly to each earbud:

This diagram compares Classic Bluetooth relay architecture (phone sends stereo to primary earbud, which relays to secondary) with LE Audio multi-stream architecture (phone sends independent synchronized streams directly to each earbud via separate CIS channels within a CIG). The LE Audio approach provides balanced battery drain and lower latency.

How It Works

1. Both earbuds connect to the phone independently via BLE

2. The phone identifies them as a coordinated set using CSIP

3. The phone establishes a CIG (Connected Isochronous Group) with two CIS streams, one per earbud

4. The phone sends the left channel on CIS #1 and the right channel on CIS #2

5. The CIG ensures both streams are synchronized, the earbuds play their respective channels at exactly the same time

Benefits:

• Balanced battery drain: Both earbuds do equal work

• Lower latency: No relay hop means fewer delays

• Better reliability: If one earbud loses connection, the other keeps playing

• True stereo: Each earbud gets its own independent stream, no need to decode and split

8. Auracast: Broadcast Audio for the Masses

Auracast is LE Audio's broadcast feature, and it's arguably the most revolutionary part. It's like FM radio for Bluetooth: one source, unlimited listeners.

How Auracast Works

1. A Broadcast Source creates a BIG (Broadcast Isochronous Group) containing one or more BIS streams

2. The source advertises the broadcast using Extended Advertising with metadata (stream name, language, codec config)

3. A Broadcast Sink discovers the advertisement, syncs to the Periodic Advertising train to get stream parameters

4. The sink joins the BIG and starts receiving audio

The above diagram shows the Auracast broadcast flow: a broadcast source advertises via Extended Advertising, broadcast sinks discover the advertisement and sync to Periodic Advertising to receive stream parameters, then join the BIG to receive audio. There is no limit on the number of sinks.

Auracast Use Cases

The use cases are actually compelling:

• Airports/Train Stations: Broadcast gate announcements directly to travelers' earbuds (in multiple languages!)

• Gyms: Every TV on the wall can broadcast its own audio, pick which one to listen to

• Museums: Audio guides streamed to visitors' own earbuds

• Bars/Sports Events: Watch the game on the big screen with commentary in your earbuds, without blasting everyone

• Conferences: Live translation channels broadcast to attendees

• Silent Discos: Obviously

The BASS Role: Broadcast Assistants

There's a neat supporting concept called a Broadcast Assistant. This is a device (typically your phone) that helps another device (typically your earbuds) discover and tune into broadcasts.

Why? Because tiny earbuds might not have the processing power or UI to scan for and select broadcasts themselves. So your phone does the scanning, shows you available broadcasts, and tells your earbuds which one to tune into via the BASS (Broadcast Audio Scan Service).

The above diagram showes the Broadcast Assistant role: a phone scans for available Auracast broadcasts and displays them to the user. When the user selects a broadcast, the phone (acting as Broadcast Assistant) instructs the user's earbuds to tune into the selected broadcast via BASS (Broadcast Audio Scan Service), since the earbuds may lack the UI or processing power to scan on their own.

9. LE Audio in Android/AOSP: The Implementation

Now let's get into the code. This is where the rubber meets the road.

Timeline of Android LE Audio Support

• Android 12 (2021): Initial LE Audio APIs introduced (developer preview quality)

• Android 13 (2022): Full LE Audio support, including unicast client/server, broadcast source/sink

• Android 14 (2023): Improved stability, broadcast audio enhancements, LE Audio source role support

• Android 15 (2024): Auracast Broadcast Sink support, Broadcast Assistant role, improved audio context switching

• Android 16 (2025): Native Auracast UI in Quick Settings/Bluetooth settings, enhanced audio sharing experience

The LE Audio implementation in AOSP lives primarily in the Bluetooth module (packages/modules/Bluetooth), which is a Mainline module, meaning it can be updated via Google Play System Updates independent of full Android OS updates.

Key AOSP Source Locations

If you want to dive into the code yourself, here's your treasure map:

High-Level Architecture

The AOSP Bluetooth stack for LE Audio follows Android's classic layered architecture:

In this layered architecture diagram of the AOSP Bluetooth LE Audio stack, here's what's shown from top to bottom: Application layer, Framework APIs (BluetoothLeAudio, BluetoothLeBroadcast), LeAudioService (Java), JNI Bridge, Native C++ stack (le_audio_client, codec_manager, state_machine, iso_manager), HCI layer, and Bluetooth Controller hardware.

10. The AOSP Architecture: From App to Antenna

Let's walk through each layer in detail.

Layer 1: The Framework APIs

Android exposes LE Audio functionality through several public API classes in android.bluetooth:

BluetoothLeAudio

The main API for unicast LE Audio. Apps use this to:

• Connect to LE Audio devices

• Set active device for audio playback/capture

• Query group information (coordinated sets)

• Select codec configuration

// Example: Connect to an LE Audio device
BluetoothLeAudio leAudio = bluetoothAdapter.getProfileProxy(
    context, listener, BluetoothProfile.LE_AUDIO);

// Set the LE Audio device as active for media playback
leAudio.setActiveDevice(leAudioDevice);

BluetoothLeBroadcast

API for broadcast audio (Auracast). Apps use this to:

• Start/stop broadcast audio

• Set broadcast metadata (name, language)

• Configure broadcast code (encryption password)

// Start a broadcast
BluetoothLeBroadcast broadcast = bluetoothAdapter.getProfileProxy(
    context, listener, BluetoothProfile.LE_AUDIO_BROADCAST);

broadcast.startBroadcast(contentMetadata, audioConfig, broadcastCode);

BluetoothLeBroadcastAssistant

API for the broadcast assistant role, helping another device tune into a broadcast.

BluetoothVolumeControl

API for remote volume control via VCP.

BluetoothHapClient

API for the Hearing Access Profile, controlling hearing aid presets and streaming.

Layer 2: LeAudioService (The Brain)

The LeAudioService is the central service within the Bluetooth app that orchestrates all LE Audio functionality. This is where the magic happens.

Key responsibilities:

• Device Management: Tracking connected LE Audio devices and their capabilities

• Group Management: Managing coordinated sets (which devices belong together)

• Audio Routing: Deciding which device(s) should be active for playback/capture

• State Machine Management: Handling the lifecycle of audio connections

• Profile Coordination: Coordinating BAP, VCP, MCP, CCP, and CSIP

Here's a simplified view of how LeAudioService is structured:

public class LeAudioService extends ProfileService {
    
    // Map of device address -> state machine
    private Map<BluetoothDevice, LeAudioStateMachine> mStateMachines;
    
    // Map of group ID -> group information
    private Map<Integer, LeAudioGroupDescriptor> mGroupDescriptors;
    
    // Native interface bridge
    private LeAudioNativeInterface mNativeInterface;
    
    // Active device tracking
    private BluetoothDevice mActiveAudioOutDevice;
    private BluetoothDevice mActiveAudioInDevice;
    
    // Codec configuration
    private BluetoothLeAudioCodecConfig mInputLocalCodecConfig;
    private BluetoothLeAudioCodecConfig mOutputLocalCodecConfig;
    
    public void connect(BluetoothDevice device) {
        // 1. Check if device supports LE Audio (PACS)
        // 2. Create state machine for device
        // 3. Initiate connection via native stack
        // 4. Discover GATT services (PACS, ASCS, VCS, etc.)
        // 5. Read audio capabilities
    }
    
    public void setActiveDevice(BluetoothDevice device) {
        // 1. Look up device's group
        // 2. Find all devices in the coordinated set
        // 3. Configure audio streams via BAP
        // 4. Set up isochronous channels
        // 5. Start audio routing
    }
}

Layer 3: The Native Stack (C++)

Below the Java layer, the heavy lifting happens in C++. The native LE Audio implementation lives in the Bluetooth stack (historically called "Fluoride," with newer components in "Gabeldorsche").

Key native components:

le_audio_client.cc / le_audio_client_impl

The main C++ implementation of the LE Audio client. This handles:

• GATT client operations (discovering services, reading characteristics)

• ASE (Audio Stream Endpoint) state machine management

• Codec negotiation with remote devices

• CIS/BIS creation and management

state_machine.cc

Manages the connection state machine for each LE Audio device:

The above is a state diagram of the native LE Audio connection state machine with states: Disconnected, Connecting, Connected, and Disconnecting. The state machine is managed per-device in the native C++ layer and drives GATT connection setup, service discovery, and characteristic reads before transitioning to Connected.

codec_manager.cc

Handles codec configuration:

• Enumerates supported codec capabilities

• Selects optimal codec configuration based on device capabilities and use case

• Interfaces with the LC3 encoder/decoder

iso_manager.cc

Manages isochronous channels:

• Creates and tears down CIG/CIS for unicast

• Creates and tears down BIG/BIS for broadcast

• Handles the HCI interface for isochronous data

audio_hal_client.cc

Bridges the Bluetooth stack with the Android audio HAL:

• Receives PCM audio from the Android audio framework

• Passes it to the LC3 encoder

• Sends encoded audio over isochronous channels

Layer 4: The Controller (Hardware)

The Bluetooth controller handles the low-level radio operations:

• Link layer scheduling of isochronous events

• PHY layer (1M, 2M, or Coded PHY)

• Packet formatting and CRC

• Retransmission of lost isochronous PDUs

The host (Android) communicates with the controller via HCI (Host Controller Interface), using specific HCI commands for isochronous channels:

• HCI_LE_Set_CIG_Parameters: Configure a Connected Isochronous Group

• HCI_LE_Create_CIS: Create Connected Isochronous Streams

• HCI_LE_Create_BIG: Create a Broadcast Isochronous Group

• HCI_LE_Setup_ISO_Data_Path: Set up the path for ISO data (HCI vs. vendor-specific)

• HCI_LE_BIG_Create_Sync: Synchronize to a BIG (for broadcast receivers)

11. Server-Side (Source) Implementation

The "server side" in LE Audio terminology is actually the Unicast Server, the device that renders audio (your earbuds). Yes, it's confusing that the receiver is called the "server." Think of it as a GATT server: it hosts the GATT services that the client connects to.

What the Unicast Server Does

The Unicast Server (earbud) hosts several GATT services:

The above diagram shows the GATT services hosted by a Unicast Server (earbud). The server exposes four key services:

• PACS (Published Audio Capabilities Service), which advertises the device's supported codecs, sample rates, frame durations, and audio contexts

• ASCS (Audio Stream Control Service), which contains one or more ASE (Audio Stream Endpoint) characteristics that the client writes to in order to configure and control audio streams

• VCS (Volume Control Service), which allows the client to read and set the device's volume level

• and CSIS (Coordinated Set Identification Service), which identifies this device as part of a coordinated set (for example, "I am the left earbud, and my partner is the right earbud").

The Unicast Client (phone) connects to these services via GATT to discover capabilities, configure streams, and control playback.

The ASE State Machine (Server Side)

Each ASE (Audio Stream Endpoint) on the server has a state machine. This is the heart of audio stream management:

The above is a state diagram of the ASE (Audio Stream Endpoint) state machine on the Unicast Server. States: Idle, Codec Configured, QoS Configured, Enabling, Streaming, Disabling, and Releasing. The client drives transitions by writing operations (Config Codec, Config QoS, Enable, Disable, Release) to the ASE Control Point characteristic.

State transitions:

1. IDLE → CODEC_CONFIGURED: The client writes a Config Codec operation to the ASE Control Point, specifying codec type (LC3), sample rate, frame duration, and so on.

2. CODEC_CONFIGURED → QoS_CONFIGURED: The client writes a Config QoS operation, specifying:

   • SDU interval (how often audio frames are sent)

   • Framing (framed or unframed)

   • Max SDU size

   • Retransmission number

   • Max transport latency

   • Presentation delay

3. QoS_CONFIGURED → ENABLING: The client writes an Enable operation. The server prepares to receive audio.

4. ENABLING → STREAMING: The CIS is established and audio data starts flowing. This transition happens after the client creates the CIS and both sides are ready.

5. STREAMING → DISABLING: The client writes a Disable operation, or the connection is being torn down.

6. Any state → IDLE: The client writes a Release operation, tearing down the stream configuration.

Standard Codec Configurations

BAP defines a set of named codec configurations that map to specific LC3 parameters. These are the "presets" that devices negotiate:

For most consumer earbuds, you'll see 48_4 (96 kbps at 48 kHz) for media and 16_2 (32 kbps at 16 kHz) for phone calls. That single LC3 codec handles both use cases – no more switching between SBC and mSBC!

Audio Context Types

LE Audio defines Audio Context Types, metadata that tells the receiving device what kind of audio is being streamed. This allows the device to optimize its behavior (for example, enabling noise cancellation for calls or boosting bass for music):

This is way more granular than Classic Audio, which basically only knew two states: "you're playing music" (A2DP) or "you're on a call" (HFP). With LE Audio, the device can make intelligent decisions, like "this is a game, use 7.5ms frames for minimum latency" or "this is a notification, mix it in without interrupting the music stream."

AOSP Unicast Server Implementation

In AOSP, the Unicast Server functionality is implemented primarily for cases where the Android device acts as a receiver (for example, an Android-powered hearing aid or a Chromebook receiving audio).

Key classes:

• LeAudioService.java: Handles server-side operations when the device is in sink role

• In native code: le_audio_server.cc manages the GATT server hosting PACS, ASCS, and so on.

Broadcast Source Implementation

For broadcast audio (Auracast), the source side in AOSP involves:

// In LeAudioService.java / BroadcastService
public void startBroadcast(BluetoothLeBroadcastSettings settings) {
    // 1. Configure LC3 encoder with broadcast parameters
    // 2. Set up Extended Advertising with broadcast metadata
    // 3. Set up Periodic Advertising for stream parameters
    // 4. Create BIG via HCI
    // 5. Start sending ISO data on BIS streams
}

The native implementation:

• broadcaster.cc / broadcaster_impl: Manages broadcast lifecycle

• Configures Extended Advertising with the broadcast name and metadata

• Configures Periodic Advertising to carry the BASE (Broadcast Audio Source Endpoint) data structure

• Creates a BIG with the appropriate number of BIS streams

• Routes encoded audio to the BIS data path

12. Client-Side (Sink) Implementation

The "client side" is the Unicast Client, typically your phone. It discovers, connects to, and controls LE Audio devices.

Connection Flow

Here's what happens when you connect to LE Audio earbuds, step by step:

Steps: BLE scan and discovery, GATT connection, service discovery (finding PACS, ASCS, CSIP, VCS), reading PAC records to learn audio capabilities, reading CSIS to identify coordinated set membership, then ASE configuration (Config Codec, Config QoS, Enable) followed by CIS creation and audio streaming.

AOSP Client Implementation in Detail

Step 1-3: Discovery and Connection

// LeAudioService.java
public void connect(BluetoothDevice device) {
    // Creates a new LeAudioStateMachine for this device
    LeAudioStateMachine sm = getOrCreateStateMachine(device);
    sm.sendMessage(LeAudioStateMachine.CONNECT);
    
    // The state machine handles:
    // - GATT connection
    // - Service discovery
    // - Characteristic reads
}

The LeAudioStateMachine manages the connection lifecycle:

// LeAudioStateMachine.java (simplified)
class LeAudioStateMachine extends StateMachine {
    
    class Disconnected extends State {
        void processMessage(Message msg) {
            if (msg.what == CONNECT) {
                // Initiate GATT connection via native
                mNativeInterface.connectLeAudio(mDevice);
                transitionTo(mConnecting);
            }
        }
    }
    
    class Connecting extends State {
        void processMessage(Message msg) {
            if (msg.what == CONNECTION_STATE_CHANGED) {
                if (newState == CONNECTED) {
                    transitionTo(mConnected);
                }
            }
        }
    }
    
    class Connected extends State {
        void enter() {
            // GATT services have been discovered
            // Audio capabilities have been read
            // Device is ready for streaming
            broadcastConnectionState(BluetoothProfile.STATE_CONNECTED);
        }
    }
}

Step 4-6: Capability Discovery

The native layer reads PACS to understand what the remote device supports:

// In native le_audio_client_impl (C++)
void OnGattServiceDiscovery(BluetoothDevice device) {
    // Read PAC records from PACS
    ReadPacsCharacteristics(device);
    
    // Read CSIS for coordinated set info
    ReadCsisCharacteristics(device);
    
    // Read ASCS for ASE count and state
    ReadAscsCharacteristics(device);
}

void OnPacsRead(BluetoothDevice device, PacRecord sink_pac) {
    // sink_pac contains:
    //   codec_id: LC3
    //   sampling_frequencies: 48000, 44100, 32000, 24000, 16000, 8000
    //   frame_durations: 10ms, 7.5ms
    //   channel_counts: 1
    //   octets_per_frame: 40-155  (maps to bitrate range)
    //   supported_contexts: MEDIA, CONVERSATIONAL, GAME
    
    // Store capabilities for later codec negotiation
    device_info.sink_capabilities = sink_pac;
}

Step 7-12: Stream Setup

When audio playback begins, the client configures and enables streams:

// In native codec_manager (C++)
CodecConfig SelectCodecConfiguration(
    PacRecord remote_capabilities,
    AudioContext context  // MEDIA, CONVERSATIONAL, etc.
) {
    // For media playback, prefer high quality:
    //   48 kHz, 10ms frames, 96 kbps per channel
    
    // For voice calls, optimize for latency:
    //   16 kHz, 7.5ms frames, 32 kbps per channel
    
    // Negotiate: intersect local and remote capabilities
    // Select the best configuration both sides support
}

// In native le_audio_client_impl
void GroupStreamStart(int group_id, AudioContext context) {
    auto group = GetGroup(group_id);
    auto codec_config = SelectCodecConfiguration(
        group->GetRemoteCapabilities(), context);
    
    // For each device in the group:
    for (auto& device : group->GetDevices()) {
        // For each ASE on the device:
        for (auto& ase : device->GetAses()) {
            // Step 8: Config Codec
            WriteAseControlPoint(device, OPCODE_CONFIG_CODEC, {
                .ase_id = ase->id,
                .codec_id = LC3,
                .codec_specific = {
                    .sampling_freq = 48000,
                    .frame_duration = 10ms,
                    .channel_allocation = LEFT,  // or RIGHT
                    .octets_per_frame = 120
                }
            });
        }
    }
    // After codec configured notification:
    //   Step 9: Config QoS → Step 10: Enable → Step 11: Create CIS
}

Step 13: Audio Data Flow

Once streaming, here's how audio data flows through the AOSP stack:

The above diagram shows audio data flow during LE Audio streaming: PCM audio from the Android audio framework reaches the Bluetooth Audio HAL, is encoded by the LC3 encoder, packetized into ISO SDUs with timestamps, sent over HCI to the controller, transmitted over the air via CIS, received by the earbud's controller, decoded by the earbud's LC3 decoder, and rendered as audio.

Broadcast Sink Implementation

For receiving broadcast audio (Auracast), AOSP implements:

// Broadcast sink flow (native)
void OnBroadcastSourceFound(AdvertisingReport report) {
    // Parse Extended Advertising for broadcast metadata
    BroadcastMetadata metadata = ParseBroadcastMetadata(report);
    
    // Display: "Airport Gate B47 - English"
    NotifyBroadcastSourceFound(metadata);
}

void SyncToBroadcast(BroadcastMetadata metadata) {
    // 1. Sync to Periodic Advertising
    HCI_LE_Periodic_Advertising_Create_Sync(metadata.sync_info);
    
    // 2. On PA sync established, parse BASE
    BASE base = ParseBASE(periodic_adv_data);
    
    // 3. Select subgroup and BIS streams
    // 4. Sync to BIG
    HCI_LE_BIG_Create_Sync(base.big_params, selected_bis);
    
    // 5. Set up ISO data path
    HCI_LE_Setup_ISO_Data_Path(bis_handle, HCI_DATA_PATH);
    
    // 6. Start receiving and decoding audio
}

13. The State Machine That Runs It All

The AOSP LE Audio implementation uses several interconnected state machines:

Connection State Machine

Manages the overall connection lifecycle for each device:

This state diagram shows the LE Audio connection state machine with four states: Disconnected, Connecting, Connected, and Disconnecting.

Transitions: CONNECT event moves from Disconnected to Connecting, successful connection moves to Connected, DISCONNECT event moves to Disconnecting, and completion returns to Disconnected. Timeout or failure from Connecting also returns to Disconnected.

Group Audio State Machine

Manages the audio state for a group of devices (coordinated set):

This is a state diagram showing the group audio state machine with states: Idle, Codec Configured, QoS Configured, Enabling, Streaming, and Disabling. The forward path proceeds through each state in order as audio streams are set up. The Release operation returns any state to Idle.

How the Pieces Fit Together (Code Walkthrough)

Here's a simplified walkthrough of what happens when you press "play" on your music app with LE Audio earbuds connected:

The above diagram traces the sequence of events when a user presses "play" in a music app with LE Audio earbuds connected.

The flow is:

1. The music app writes PCM audio to an AudioTrack.

2. The Android AudioFlinger routes the audio to the Bluetooth Audio HAL.

3. The HAL notifies LeAudioService that audio is starting.

4. LeAudioService looks up the active group and triggers GroupStreamStart in the native stack.

5. The native stack configures ASEs on both earbuds (Config Codec → Config QoS → Enable) by writing to the ASCS control point on each device.

6. The native stack creates a CIG with two CIS channels via HCI.

7. Both CIS channels are established to the earbuds.

8. The ISO data path is set up.

9. PCM audio flows from the HAL to the LC3 encoder, which produces compressed frames

10. The compressed frames are sent as ISO SDUs over HCI to the controller

11. The controller transmits the frames over the air on the scheduled CIS intervals

12. The earbuds receive, decode, and render the audio at the agreed presentation delay.

14. Putting It All Together: A Day in the Life of an LE Audio Packet

Let's follow a single audio packet from your music app to your earbud:

The above diagram follows a single audio packet through every stage of the LE Audio pipeline.

Starting at the top: the music app generates PCM audio, which passes through Android's AudioFlinger to the Bluetooth Audio HAL. The HAL feeds 10ms of PCM samples (480 samples at 48 kHz) to the LC3 encoder, which compresses them into a ~120-byte frame.

This frame is wrapped in an ISO SDU with a timestamp and sequence number, then passed over HCI to the Bluetooth controller. The controller segments the SDU into link-layer PDUs, schedules them on the next CIS event, and transmits them over the air using the negotiated PHY (for example, 2M PHY).

On the earbud side, the controller receives the PDUs, reassembles the ISO SDU, and passes the LC3 frame to the earbud's decoder. The decoder reconstructs 480 PCM samples, which are buffered until the presentation delay timestamp is reached, then rendered to the speaker driver.

Total latency: ~40ms from phone to earbud (with 10ms frame + transport + presentation delay). Compare this to Classic Bluetooth A2DP which typically runs at 100-200ms!

The Presentation Delay: The Synchronization Secret

The presentation delay is a crucial LE Audio concept. It's a fixed delay that both sides agree upon during stream setup. All audio must be rendered (played) at exactly:

rendering_time = reference_anchor_point + presentation_delay

This ensures:

• Left and right earbuds play audio at the exact same instant

• Even if transport latency varies between the two CIS channels

• The presentation delay provides a "buffer" for the receiver to absorb jitter

Think of it like a choir director: "Everyone sing at the count of 3. Not before, not after. Exactly at 3."

15. Wrapping Up

Bluetooth LE Audio is the most significant upgrade to Bluetooth audio since... well, since Bluetooth audio was invented. Let's recap:

What It Solves

• Better codec (LC3) — equivalent quality at half the bitrate, or better quality at the same bitrate

• Multi-stream — no more relay earbud architecture, balanced battery life

• Broadcast audio (Auracast) — one-to-many streaming, opening up entirely new use cases

• Hearing aid support (HAP) — finally a standard, interoperable solution

• Unified audio (BAP) — one profile for both music and calls, no more A2DP/HFP switching

The AOSP Stack

• Framework layer: BluetoothLeAudio, BluetoothLeBroadcast APIs

• Service layer: LeAudioService orchestrates everything

• Native layer: C++ le_audio_client_impl handles GATT, ASE state machines, codec negotiation

• Controller layer: CIS/BIS isochronous channels managed via HCI

What's Next?

LE Audio is still maturing. Key areas of development:

• Better interoperability across devices from different manufacturers

• Auracast infrastructure — venues need to install broadcast transmitters

• Dual-mode support — many devices will support both Classic and LE Audio during the transition period

• Higher quality — as Bluetooth bandwidth improves, LC3 can scale to even higher bitrates

• Gaming — ultra-low-latency configurations (7.5ms frames, minimal presentation delay)

The transition from Classic Audio to LE Audio won't happen overnight. It's more like the transition from IPv4 to IPv6 – gradual, sometimes painful, but ultimately necessary. The good news is that both can coexist, and the AOSP implementation supports fallback to Classic Audio for devices that don't support LE Audio.

So the next time you connect your earbuds and marvel at the audio quality (or lack thereof), you'll know exactly which parts of this massive protocol stack are working (or failing) to get those sound waves from your phone to your ears.

Happy coding, and may your packets always be isochronous!

References

1. Bluetooth SIG — LE Audio Specifications

2. Bluetooth SIG — A Technical Overview of LC3

3. AOSP Bluetooth Module — packages/modules/Bluetooth

4. Zephyr Project — LE Audio Stack Documentation

5. Fraunhofer IIS — LC3 Codec

For years, Android developers have been locked in a dramatic, often tragic, romance with Bluetooth. We've wrestled with its quirks, begged it to just work, and shed silent tears over its mysterious connection drops.

But what if I told you that things are about to get better? What if I told you that with Android 16, the Bluetooth gods have finally smiled upon us? It's not a dream, my friends. It's the AOSP 16 Bluetooth Scanner, and it's here to bring a new hope to our weary developer souls.

In this handbook, we're going on a journey. A journey into the heart of AOSP 16's new Bluetooth features. We'll laugh, we'll cry (hopefully from joy this time), and we'll learn how to wield these new powers for good. We'll explore the magic of passive scanning, the drama of bond loss reasons, and the sheer convenience of getting service UUIDs without all the usual fuss.

By the end of this epic saga, you'll be able to:

• Build a Bluetooth scanner that's so efficient, it's practically psychic.

• Debug connection issues like a seasoned detective.

• Impress your friends and colleagues with your newfound Bluetooth mastery.

Prerequisites:

Before we dive in, it's a good idea to have a basic understanding of Android development and Kotlin. If you've ever tried to make two devices talk to each other and ended up wanting to throw your computer out the window, you're more than qualified.

So grab your favorite beverage, put on your coding cape, and let's get ready for the Bluetooth awakening!

Table of Contents

1. A Brief History of Bluetooth in Android

2. What's New in AOSP 16: The Three Musketeers

3. Deep Dive #1: Passive Scanning

4. Understanding the BluetoothLeScanner

5. Hands-On: Building Your First Passive Scanner

6. Deep Dive #2: Bluetooth Bond Loss Reasons

7. Deep Dive #3: Service UUIDs from Advertisements

8. Advanced Topics: Leveling Up Your Scanning Game

9. Real-World Use Cases: Where the Bluetooth Hits the Road

10. API Version Checking: How to Not Crash Your App

11. Testing and Debugging: The Fun Part (Said No One Ever)

12. Performance and Best Practices: How to Be a Good Bluetooth Citizen

13. Conclusion: The Future is Passive (and That's Okay)

A Brief History of Bluetooth (Or: How We Learned to Stop Worrying and Love the Radio Waves)

The Dark Ages: Classic Bluetooth

In the beginning, there was Classic Bluetooth. It was the digital equivalent of a loud, boisterous party guest. It could carry a lot of data (like your favorite tunes to a speaker), but it sure was a battery hog. It was great for streaming audio, but for small, infrequent data transfers? It was like using a fire hose to water a houseplant. Overkill, and frankly, a little messy.

Developers in this era spent their days wrestling with BluetoothAdapter, BluetoothDevice, and the dreaded BluetoothSocket. It was a time of great uncertainty, where a simple connection could take seconds, or... well, let's just say you could go make a cup of coffee. And the battery drain? Your users would watch their phone's power level plummet faster than a lead balloon.

The Renaissance: Enter Bluetooth Low Energy (BLE)

Then, with Android 4.3, a new hero emerged: Bluetooth Low Energy, or BLE. This wasn't your dad’s Bluetooth. BLE was sleek, efficient, and mysterious. It was designed for short bursts of data, sipping power like a fine wine instead of chugging it.

BLE was the cool kid on the block. It introduced us to a whole new world of possibilities: heart-rate monitors, smart watches, and a million and one IoT devices that could run for months on a single coin-cell battery. It was a game-changer.

But with great power came... great complexity. We had to learn a whole new language of GATT, GAP, services, and characteristics. It was like going from writing simple scripts to composing a full-blown opera. The potential was huge, but the learning curve was steep.

The Problem Child: Scanning

And then there was scanning. The act of finding these new, power-sipping devices. In the early days of BLE, scanning was still a bit of a wild west. It was an active, noisy process. Your phone would shout into the void, "IS ANYONE OUT THERE?", and then listen for replies. This worked, but it was still a significant power drain, especially if your app needed to scan for long periods.

It was the classic developer dilemma: you need to find devices, but you don't want to be the reason your user's phone is dead by lunchtime. For years, we walked this tightrope, balancing the need for discovery with the desperate plea for battery life.

This is the world that AOSP 16 was born into. A world crying out for a better way to scan. A world ready for a hero. And that hero, my friends, is passive scanning. But more on that in a bit...

What's New in AOSP 16? (Spoiler: It's Actually Cool)

Alright, let's get to the good stuff. What shiny new toys did the Android team give us in AOSP 16? It turns out, quite a few! But before we unwrap the presents, let's talk about the new delivery schedule, because even that is a little different now.

A Tale of Two Releases

In a shocking plot twist, Android decided to grace us with two major API releases in 2025. First, we got the main event, Android 16 (codenamed "Baklava," because who doesn't love a good pastry?), which landed in Q2. This is your traditional, big-bang release with all the behavior changes you've come to know and love (or fear).

But then, in Q4, we get a surprise second act: a minor release, which is where our new Bluetooth goodies made their grand entrance. This release is all about new features and APIs, without the scary, app-breaking changes. It's like getting a free dessert after you've already paid the bill.

The Three Musketeers of Bluetooth

So, what did this Q4 release bring to the Bluetooth party? I'm glad you asked. It brought three new heroes, ready to save us from our Bluetooth woes. I call them... The Three Musketeers.

These aren't just minor tweaks, folks. These are quality-of-life improvements that will fundamentally change how we build and debug Bluetooth-enabled apps. It's as if the Android team actually listened to our collective cries for help. (I know, I'm shocked too.)

In the next few sections, we're going to get up close and personal with each of these new features. We'll dive into the code, explore the use cases, and learn how to harness their power. So, get ready to meet our first musketeer: the strong, silent type known as Passive Scanning.

Deep Dive #1: Passive Scanning

Imagine you're in a library. You're looking for a friend, but you don't know where they are. You have two options:

• Active Scanning: You stand in the middle of the library and shout, "HEY, STEVE! ARE YOU HERE?" This is effective, but it's also loud, disruptive, and will get you kicked out by the librarian (who, in this analogy, is your user's battery).

• Passive Scanning: You quietly walk around the library, listening for your friend's distinctive, wheezing laugh. You don't say a word. You just listen. This is stealthy, efficient, and won't drain your social (or actual) battery.

For years, Android's Bluetooth scanning has been the guy shouting in the library. But with AOSP 16, we can finally be the quiet listener. This is the magic of passive scanning.

Active vs. Passive: The Technical Showdown

In the world of BLE, devices send out little packets of information called "advertisements." It's their way of saying, "Hey, I'm here, and this is what I do!"

• Active Scanning: When your phone performs an active scan, it hears an advertisement and then sends back a SCAN_REQ (Scan Request). It's basically saying, "Tell me more!" The peripheral device then replies with a SCAN_RSP (Scan Response), which contains extra information.

• Passive Scanning: With passive scanning, your phone hears the advertisement... and that's it. It doesn't send anything back. It just takes note of the initial advertisement and moves on. It's a one-way conversation.

Why Go Passive? The Power of Silence

So, why is this such a big deal? Two words: power consumption. Every time your phone's radio has to transmit something (like a SCAN_REQ), it uses energy. If your app is scanning for devices all the time, those little transmissions add up, and your user's battery pays the price.

By switching to passive scanning, you're telling the radio to just listen. No talking, just listening. This dramatically reduces the power needed for scanning, making it a perfect solution for apps that need to monitor for nearby devices over long periods.

The Code: How to Become a Bluetooth Ninja

So, how do we implement this newfound stealth mode? It's surprisingly simple. It all comes down to the ScanSettings you use when you start your scan.

Previously, you might have done something like this:

val settings = ScanSettings.Builder()
    .setScanMode(ScanSettings.SCAN_MODE_LOW_LATENCY)
    .build()

Now, with AOSP 16, we have a new option. To enable passive scanning, you simply set the scan type:

// This is the magic line!
.setScanMode(ScanSettings.SCAN_TYPE_PASSIVE)

Wait, that can't be right. The documentation says SCAN_TYPE_PASSIVE is a scan type, not a scan mode. And you're right! My apologies, I got a little too excited. The correct way to do this is by setting the scan mode to passive. Let's try that again.

val settings = ScanSettings.Builder()
    // The actual magic line!
    .setScanMode(ScanSettings.SCAN_MODE_OPPORTUNISTIC) // This is the closest to passive
    .build()

Hold on, that's not quite right either. It seems I've gotten my wires crossed. Let's consult the official scrolls... Ah, here it is! The ScanSettings.Builder has a new method in Android 16 QPR2. It's not setScanMode, it's a whole new setting.

Let's get this right once and for all. Here is the correct way to enable passive scanning:

// Available in Android 16 QPR2 and later
val settings = ScanSettings.Builder()
    // This is the REAL magic line, I promise!
    .setScanType(ScanSettings.SCAN_TYPE_PASSIVE) 
    .build()

And there you have it. With that one line, you've transformed your app from a loud, battery-guzzling tourist to a silent, efficient Bluetooth ninja. Your users' batteries will thank you.

Of course, there's a trade-off. Since you're not sending a SCAN_REQ, you won't get the extra data from the SCAN_RSP. But for many use cases, the initial advertisement is all you need. And the power savings are more than worth it.

Now that we've mastered the art of silent scanning, let's move on to the next piece of the puzzle: understanding the BluetoothLeScanner itself.

Understanding BluetoothLeScanner (The Star of Our Show)

Before we can truly master the art of Bluetooth scanning, we must first understand our primary weapon: the BluetoothLeScanner. Think of it as the PKE Meter from Ghostbusters. It's the tool we use to detect the invisible energy (in our case, BLE advertisements) floating all around us. But how does this ghost-hunting gadget actually work?

The Architecture: A Peek Behind the Curtain

At a high level, the process is pretty straightforward. Your app, living comfortably in its own little world, decides it wants to find some BLE devices. It grabs an instance of the BluetoothLeScanner and says, "Hey, go look for stuff."

Under the hood, a lot is happening. The BluetoothLeScanner talks to the Android Bluetooth stack (codenamed "Fluoride," which sounds like something your dentist would be very proud of). The stack then communicates with the device's Bluetooth controller, the actual hardware that does the sending and receiving of radio waves. It's a classic case of "it's more complicated than it looks."

The Alphabet Soup: GATT, GAP, and Friends

When you venture into the world of BLE, you'll quickly run into a whole bunch of acronyms. Don't panic! They're not as scary as they look. The two most important ones to understand are GAP and GATT.

• GAP (Generic Access Profile): This is all about how devices discover and connect to each other. Think of GAP as the bouncer at a nightclub. It decides who gets to talk to whom. It manages advertising (the device shouting "I'm here!") and scanning (your app listening for those shouts). Our BluetoothLeScanner is a key player in the GAP-verse.

• GATT (Generic Attribute Profile): Once two devices are connected, GATT takes over. It defines how they exchange data. Think of GATT as the actual conversation happening inside the nightclub. It's all about Services, Characteristics, and Descriptors. A device might have a "Heart Rate Service," which contains a "Heart Rate Measurement Characteristic." Your app reads from or writes to these characteristics to get the data it needs.

For the purpose of scanning, we're mostly living in the world of GAP. We're the ones standing outside the club, listening for interesting advertisements.

The Scanning Lifecycle: A Dramatic Play in Three Acts

The life of a Bluetooth scan is a simple, yet elegant, drama.

• Act I: The Preparation. Your app decides it's time to scan. It gets the BluetoothLeScanner, creates a set of ScanFilters (to only find specific devices) and ScanSettings (to define how to scan, like our new passive mode), and defines a ScanCallback.

• Act II: The Scan. Your app calls startScan(). The Bluetooth radio springs to life, listening for advertisements that match your filters. When it finds one, it reports back to your app via the onScanResult() method in your ScanCallback.

• Act III: The End. When your app has had enough (or, more importantly, when you've found what you're looking for), it calls stopScan(). The radio powers down, and all is quiet once more. It's crucial to always stop your scan when you're done. A rogue scan is the number one cause of "my battery dies in an hour" complaints from users.

And that's the BluetoothLeScanner in a nutshell. It's our gateway to the world of BLE discovery. It's powerful, it's complex, but as we're learning, it's getting smarter and more efficient with every new Android release. Now that we know our tool, let's get our hands dirty and build our first passive scanner!

Hands-On: Building Your First Passive Scanner

Theory is great, but let's be honest, we're developers. We learn by doing (or by copying pasting from Stack Overflow). It's time to roll up our sleeves, fire up Android Studio, and build something. We're going to create a simple app that uses our newfound passive scanning powers to find nearby BLE devices.

Step 1: The Permission Inquisition

Before we write a single line of Kotlin, we must appease the Android permission gods. This is a sacred and often frustrating ritual. For Bluetooth scanning, the rules have changed a bit over the years.

First, open your AndroidManifest.xml and add the following:

<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />

<!-- For Android 12 (API 31) and above -->
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />

<!-- For older versions, you needed location permissions -->
<!-- You might still need this if you support older devices -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

Looking at the permissions we've declared above, you can see the evolution of Android's Bluetooth permission model playing out in real-time.

The first two permissions, BLUETOOTH and BLUETOOTH_ADMIN, are the old guard. They've been around since the early days of Android and provide basic Bluetooth functionality and the ability to discover devices. Then we have BLUETOOTH_SCAN, which was introduced in Android 12 (API 31) and represents a major shift in how Google thinks about privacy.

Yes, you're seeing that right. In the good old days (before Android 12), Google decided that finding a Bluetooth device was basically the same as knowing your user's exact location. It kind of made sense: after all, if you can see which Bluetooth beacons are nearby, you can triangulate your position. But it was also a bit creepy to ask for location just to find a pair of headphones. This led to the awkward situation where users would see a simple Bluetooth scanner app asking for their precise location and understandably get suspicious.

Thankfully, with Android 12, they introduced the BLUETOOTH_SCAN permission, which is much more sensible. This permission finally allows apps to scan for Bluetooth devices without needing to ask for location access, which makes a lot more sense from a user perspective. You'll still need to request this permission at runtime, but at least you don't have to explain to your users why your simple gadget-finder app wants to know where they live.

However, notice those last two permissions for location access. Those are the remnants of the old system. If you're building an app that needs to support older devices running Android 11 or below, you'll need to keep these location permissions in your manifest for backwards compatibility. On modern devices, the BLUETOOTH_SCAN permission alone will do the job.

Step 2: The Code Awakens

Alright, let's get to the fun part. Here's a breakdown of how to implement the passive scanner in your Activity or Fragment.

Get the Scanner

First, we need to get an instance of the BluetoothLeScanner.

private val bluetoothAdapter: BluetoothAdapter? by lazy {
    val bluetoothManager = getSystemService(Context.BLUETOOTH_SERVICE) as BluetoothManager
    bluetoothManager.adapter
}

private val bleScanner: BluetoothLeScanner? by lazy {
    bluetoothAdapter?.bluetoothLeScanner
}

Let's break down what's happening in the code above. We're using Kotlin's lazy delegation, which is a fancy way of saying "don't create this object until I actually need it." This is a good practice because getting the Bluetooth adapter involves system calls, and there's no point in doing that work if we never actually use it.

First, we grab the BluetoothManager from the system services. Think of the BluetoothManager as the gatekeeper to all things Bluetooth on your device. From this manager, we get the BluetoothAdapter, which represents your device's physical Bluetooth hardware. Notice that we're declaring it as nullable (BluetoothAdapter?) because, believe it or not, not every Android device has Bluetooth. Some tablets or obscure devices might not have the hardware, so we need to be prepared for that possibility.

Once we have the adapter, we can ask it for the BluetoothLeScanner. This is the actual object we'll use to perform our scans. Again, we're using the safe call operator (?.) because if the adapter is null (no Bluetooth hardware), we definitely can't get a scanner from it. This defensive programming might seem paranoid, but it's what separates apps that crash mysteriously from apps that gracefully handle edge cases.

Define the Callback

This is where the magic happens. The ScanCallback is an object that will listen for scan results. We need to override two methods: onScanResult and onScanFailed.

private val scanCallback = object : ScanCallback() {
    override fun onScanResult(callbackType: Int, result: ScanResult) {
        // We found a device! 
        // The 'result' object contains the device, RSSI, and advertisement data.
        Log.d("BleScanner", "Found device: ${result.device.address}, RSSI: ${result.rssi}")
    }

    override fun onScanFailed(errorCode: Int) {
        // This is the universe's way of telling you to take a break.
        // Or that something went horribly wrong.
        Log.e("BleScanner", "Scan failed with error code: $errorCode")
    }
}

The ScanCallback we've defined above is your app's ears in the Bluetooth world. When the scanner finds a device, it doesn't just store the information somewhere, it actively calls back to your app through this callback object. This is classic event-driven programming, and it's how Android keeps your app responsive without blocking the main thread.

The onScanResult method is called every time the scanner discovers a device that matches your filters (or any device if you're not using filters). The result parameter is a treasure trove of information. It contains the BluetoothDevice object (which has the device's MAC address and name), the RSSI value (Received Signal Strength Indicator – basically how close the device is, with higher numbers meaning closer), and the raw advertisement data that the device is broadcasting.

In our simple example above, we're just logging the MAC address and RSSI, but in a real app, you'd probably want to update your UI, add the device to a list, or trigger a connection.

The callbackType parameter tells you why this callback was triggered. It could be CALLBACK_TYPE_ALL_MATCHES (the default, meaning "here's every device we found"), CALLBACK_TYPE_FIRST_MATCH (the first time we saw this device), or CALLBACK_TYPE_MATCH_LOST (we haven't seen this device in a while, so it probably left). We'll dive deeper into these types in the advanced section.

Then there's onScanFailed, the method we all hope never gets called but that we absolutely need to handle. This is invoked when something goes catastrophically wrong with the scan. Maybe the Bluetooth adapter got turned off mid-scan, maybe your app doesn't have the right permissions, or maybe the Bluetooth controller just had a bad day. The errorCode will give you a hint about what went wrong, and you should always log this and handle it gracefully – perhaps by showing a message to the user or attempting to restart the scan after a delay.

Configure the Scan

Now, we create our ScanSettings. This is where we tell Android that we want to be a passive, battery-saving ninja.

val scanSettings = ScanSettings.Builder()
    .setScanMode(ScanSettings.SCAN_MODE_LOW_POWER) // Let's be nice to the battery
    .setCallbackType(ScanSettings.CALLBACK_TYPE_ALL_MATCHES)
    .setMatchMode(ScanSettings.MATCH_MODE_AGGRESSIVE)
    .setNumOfMatches(ScanSettings.MATCH_NUM_ONE_ADVERTISEMENT) // Report each ad once
    .setReportDelay(0L) // Report immediately
    // And here's the star of the show!
    .setScanType(ScanSettings.SCAN_TYPE_PASSIVE)
    .build()

The ScanSettings object we're building above is like a detailed instruction manual for the Bluetooth scanner. Each method call fine-tunes exactly how the scan should behave, and getting these settings right is the difference between a battery-friendly app and one that gets uninstalled within hours.

Let's walk through each setting. First, setScanMode(SCAN_MODE_LOW_POWER) tells the scanner to use a low-power scanning mode, which means it will scan in intervals rather than continuously. This is perfect for most use cases where you don't need instant results and want to preserve battery life. The scanner will wake up, scan for a bit, sleep, and repeat. It's the Bluetooth equivalent of taking power naps.

Next, setCallbackType(CALLBACK_TYPE_ALL_MATCHES) means we want to be notified every time the scanner finds a matching device. This is the default behavior and is what you'll use most of the time. As we mentioned earlier, you can also use CALLBACK_TYPE_FIRST_MATCH or CALLBACK_TYPE_MATCH_LOST for more sophisticated presence detection.

The setMatchMode(MATCH_MODE_AGGRESSIVE) setting controls how aggressively the hardware should try to match devices against your filters. MATCH_MODE_AGGRESSIVE means "report matches quickly, even if you're not 100% certain," while MATCH_MODE_STICKY means "wait until you're really sure before reporting." Aggressive mode gives you faster results but might occasionally give you false positives.

Then we have setNumOfMatches(MATCH_NUM_ONE_ADVERTISEMENT), which tells the scanner to report a device after seeing just one advertisement from it. The alternative is MATCH_NUM_FEW_ADVERTISEMENT, which waits for multiple advertisements before reporting. Using one advertisement gives you faster discovery, while waiting for a few reduces false positives from devices that are just passing by.

The setReportDelay(0L) setting is crucial. A delay of 0 means "report results immediately." If you set this to, say, 5000 milliseconds, the scanner would batch up results and deliver them every 5 seconds. Batching is great for background scanning (as we discussed in the advanced section), but for foreground scanning where the user is actively waiting, immediate reporting is what you want.

And finally, the star of our show: setScanType(SCAN_TYPE_PASSIVE). This is the new API from Android 16 QPR2 that transforms our scanner into a silent listener. Instead of actively sending scan requests to every device it hears, it just listens to the advertisements floating through the air. This single setting can dramatically reduce your app's battery consumption during scanning. It's the feature we've been waiting for, and it's glorious.

Start and Stop the Scan

Finally, we need functions to start and stop our scan. Remember: always stop your scan! A forgotten scan is a battery-killing monster.

private fun startBleScan() {
    // Don't forget to request permissions first!
    if (bleScanner != null) {
        // You can add ScanFilters here to search for specific devices
        val scanFilters: List<ScanFilter> = listOf() 
        bleScanner.startScan(scanFilters, scanSettings, scanCallback)
        Log.d("BleScanner", "Scan started.")
    } else {
        Log.e("BleScanner", "Bluetooth is not available.")
    }
}

private fun stopBleScan() {
    if (bleScanner != null) {
        bleScanner.stopScan(scanCallback)
        Log.d("BleScanner", "Scan stopped.")
    }
}

These two functions above are the on/off switches for your Bluetooth scanner, and they're deceptively simple for how important they are. Let's break down what's happening in each one.

In startBleScan(), we first check if the bleScanner is not null. This is our safety net: if the device doesn't have Bluetooth hardware or if Bluetooth is disabled, the scanner will be null, and we don't want to crash by trying to call methods on a null object. If the scanner exists, we call startScan() with three parameters: a list of ScanFilter objects, our carefully crafted ScanSettings, and the ScanCallback we defined earlier.

The scanFilters list is currently empty in our example, which means "find all BLE devices." In a real-world app, you'd typically add filters here to narrow down your search.

For instance, if you're building an app that only works with heart rate monitors, you'd create a filter that only matches devices advertising the Heart Rate Service UUID. This is crucial for both performance and battery life: why wake up your app for every random Bluetooth toothbrush when you only care about fitness trackers?

The startScan() method kicks off the scanning process. From this point on, the Bluetooth radio is actively (or in our case, passively) listening for advertisements, and your scanCallback will start receiving results. This is an asynchronous operation, meaning your code doesn't block here waiting for results – rather, it continues executing, and the results come in through the callback whenever they're available.

Now let's talk about stopBleScan(), which might be the most important function you write. When you call stopScan() with your callback, you're telling the Bluetooth radio, "Okay, we're done here, you can go back to sleep." This immediately stops the scanning process and releases the resources.

The critical thing to understand is that if you don't call this, the scan will continue running indefinitely, draining your user's battery like a vampire at an all-you-can-eat blood bank. This is why we emphasize it so much: a forgotten stopScan() call is one of the most common causes of battery drain complaints in Bluetooth apps.

Notice that we're passing the same scanCallback object to stopScan() that we used in startScan(). This is how Android knows which scan to stop – you might theoretically have multiple scans running with different callbacks (though that's rarely a good idea). Always make sure you're stopping the same scan you started by using the same callback reference.

Putting It All Together

Here's a complete example you can drop into an Activity. Just remember to handle the runtime permissions!

// In your Activity class

class MainActivity : AppCompatActivity() {

    // ... (lazy properties for adapter and scanner from above)

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // ... your UI setup ...

        // Example: Start scan on button click
        val startButton = findViewById<Button>(R.id.startButton)
        startButton.setOnClickListener {
            // You MUST request permissions before calling this!
            startBleScan()
        }

        // Example: Stop scan on another button click
        val stopButton = findViewById<Button>(R.id.stopButton)
        stopButton.setOnClickListener {
            stopBleScan()
        }
    }

    // ... (scanCallback, startBleScan, stopBleScan functions from above)

    override fun onPause() {
        super.onPause()
        // Always stop scanning when the activity is not visible.
        stopBleScan()
    }
}

The complete example above shows how all the pieces fit together in a real Activity. This is a minimal but functional Bluetooth scanner that you can actually run. Let's highlight a few important patterns we're using here.

First, notice how we're tying the scan lifecycle to user actions through button clicks. This is a common pattern: the user explicitly starts and stops the scan, giving them control over when the app is using Bluetooth. This is both good UX and good for battery life, as the scan only runs when the user wants it to.

But here's the really important part: the onPause() override. This is a critical safety net. When your Activity goes into the background (maybe the user pressed the home button, or they switched to another app), onPause() is called, and we immediately stop the scan. This is essential because if the user can't see your app, they don't need scan results, and there's no reason to drain their battery. This pattern ensures that even if the user forgets to press the "Stop" button, the scan won't run forever in the background.

You might be wondering, "What about onResume()? Shouldn't we restart the scan when the user comes back?" That's a design decision. In some apps, you might want to automatically restart scanning in onResume(). In others, you might want the user to explicitly press "Start" again. It depends on your use case. For a device-finding app where the user is actively searching, auto-resuming makes sense. For a monitoring app that runs in the background, you might want more explicit control.

One crucial thing we haven't shown in this example is runtime permission handling. Remember those permissions we declared in the manifest? On Android 6.0 and above, you can't just declare them, you have to actually request them from the user at runtime. Before calling startBleScan(), you should check if you have the necessary permissions and, if not, request them using ActivityCompat.requestPermissions(). If you try to start a scan without the proper permissions, it will fail silently (or loudly, depending on the Android version), and you'll be left scratching your head wondering why nothing is working.

And there you have it! You've just built your first AOSP 16 passive Bluetooth scanner. It's lean, it's mean, and it's incredibly power-efficient. The scanner listens silently for BLE advertisements, reports them through your callback, and stops gracefully when it's not needed.

Now, let's move on to our next topic: what to do when things go wrong. It's time to talk about breakups... Bluetooth bond breakups, that is.

Deep Dive #2: Bluetooth Bond Loss Reasons

Ah, the Bluetooth bond. It's a beautiful, sacred thing. It's the digital equivalent of exchanging friendship bracelets. When you bond your phone with your headphones, you're creating a long-term, trusted relationship. They share secret keys, they remember each other, and they promise to connect automatically, saving you the hassle of pairing every single time. It's a beautiful romance.

Until it's not.

Suddenly, one day, they just... forget each other. The connection is gone. The trust is broken. And your app is left in the middle, trying to play therapist, with no idea what went wrong. You've been ghosted. And until now, Android has been no help. You'd get a notification that the bond state is now BOND_NONE, but that's it. No explanation. No closure. Just the cold, hard silence of a failed connection.

Finally, Some Closure!

But our friends on the Android team have clearly been through some tough breakups, because in AOSP 16, they've given us the gift of closure. Introducing BluetoothDevice.EXTRA_BOND_LOSS_REASON. It's a new extra that comes with the ACTION_BOND_STATE_CHANGED broadcast, and it's here to tell you why the bond was lost. It's like getting a breakup text that actually explains what happened!

Now, when a bond is broken, you can get a specific reason code. Think of them as the classic breakup excuses, but for Bluetooth:

The Code: Playing Detective

So, how do we get this juicy gossip? We need to set up a BroadcastReceiver to listen for bond state changes.

// Create a BroadcastReceiver to listen for bond state changes
private val bondStateReceiver = object : BroadcastReceiver() {
    override fun onReceive(context: Context, intent: Intent) {
        if (intent.action == BluetoothDevice.ACTION_BOND_STATE_CHANGED) {
            val device: BluetoothDevice? = intent.getParcelableExtra(BluetoothDevice.EXTRA_DEVICE)
            val bondState = intent.getIntExtra(BluetoothDevice.EXTRA_BOND_STATE, BluetoothDevice.ERROR)
            val previousBondState = intent.getIntExtra(BluetoothDevice.EXTRA_PREVIOUS_BOND_STATE, BluetoothDevice.ERROR)

            // Check if we went from bonded to not bonded
            if (bondState == BluetoothDevice.BOND_NONE && previousBondState == BluetoothDevice.BOND_BONDED) {
                Log.d("BondBreakup", "We got dumped by ${device?.address}!")

                // Now, let's find out why...
                val reason = intent.getIntExtra(BluetoothDevice.EXTRA_BOND_LOSS_REASON, -1)

                when (reason) {
                    // Note: The actual constant values are in the Android SDK
                    BluetoothDevice.BOND_LOSS_REASON_REMOTE_DEVICE_REMOVED -> {
                        Log.d("BondBreakup", "Reason: The remote device removed the bond.")
                        // You could show a message to the user: "Your headphones seem to have forgotten you. Please try pairing again."
                    }
                    // ... handle other reasons ...
                    else -> {
                        Log.d("BondBreakup", "Reason: It's complicated (Unknown reason code: $reason)")
                    }
                }
            }
        }
    }
}

// In your Activity or Service, register the receiver
override fun onResume() {
    super.onResume()
    val filter = IntentFilter(BluetoothDevice.ACTION_BOND_STATE_CHANGED)
    registerReceiver(bondStateReceiver, filter)
}

override fun onPause() {
    super.onPause()
    // Don't forget to unregister!
    unregisterReceiver(bondStateReceiver)
}

The code above implements a detective system for Bluetooth bond breakups, and it's more sophisticated than it might first appear. Let's walk through how this broadcast receiver pattern works and why it's so powerful.

First, we're creating a BroadcastReceiver, which is Android's way of letting your app listen for system-wide events. Think of it as subscribing to a notification service, whenever something interesting happens in the Android system (like a bond state change), the system broadcasts an "intent" to all registered listeners. Our receiver is one of those listeners.

In the onReceive() method, we first check if the incoming intent's action is ACTION_BOND_STATE_CHANGED. This is crucial because broadcast receivers can potentially receive many different types of intents, and we only care about bond state changes. Once we've confirmed this is the right type of event, we extract the relevant information from the intent using getParcelableExtra() and getIntExtra().

The device object tells us which Bluetooth device this event is about. After all, you might be bonded to multiple devices (your headphones, your smartwatch, your car), and we need to know which one just broke up with us. The bondState tells us the current state (are we bonded, bonding, or not bonded?), and previousBondState tells us what the state was before this change occurred.

The key logic happens in our conditional check: if (bondState == BluetoothDevice.BOND_NONE && previousBondState == BluetoothDevice.BOND_BONDED). This is checking for the specific transition from "bonded" to "not bonded," which is the digital equivalent of a breakup. We're not interested in the bonding process itself (going from none to bonding to bonded) – we only care about when an existing bond is lost.

Once we've detected a breakup, we extract the new EXTRA_BOND_LOSS_REASON from the intent. This is the star feature from AOSP 16 that finally gives us closure. The reason code tells us exactly why the bond was lost – was it the remote device that ended things? Did the user manually forget the device? Did authentication fail? Each reason code corresponds to a different scenario, and you can handle each one appropriately.

In the example above, we're using a when expression to handle different reason codes. For BOND_LOSS_REASON_BREDR_INCOMING_PAIRING, we know the other device initiated the breakup, so we can show a helpful message like "Your headphones seem to have forgotten you. Please try pairing again." For other reasons, you'd add more branches to handle them specifically.

Now, notice the lifecycle management at the bottom. We register our receiver in onResume() and unregister it in onPause(). This is critical: if you forget to unregister a broadcast receiver, it will continue to receive broadcasts even after your Activity is destroyed, which can cause memory leaks and crashes. The pattern of registering in onResume() and unregistering in onPause() ensures that we only listen for bond changes when our Activity is visible and active.

This is a huge step forward for debugging and for user experience. Instead of just telling the user "Connection failed," you can now give them actionable advice based on the specific reason the bond was lost. It's like being a helpful, informed relationship counselor instead of a confused bystander who can only shrug and say "I don't know what happened."

Now that we've dealt with the emotional baggage of breakups, let's move on to something a little more lighthearted: speed dating for Bluetooth devices.

Deep Dive #3: Service UUIDs from Advertisements

Let's talk about finding a compatible partner... for your app. In the world of BLE, not all devices are created equal. A heart rate monitor is very different from a smart lightbulb. So how does your app know if it's talking to the right kind of device? The answer is the Service UUID.

What in the World is a Service UUID?

A Service UUID (Universally Unique Identifier) is like a device's job title. It's a unique, 128-bit number that says, "I am a device that provides a Heart Rate Service" or "I am a device that provides a Battery Service." It's the single most important piece of information for determining what a device can do.

The Old Way: The Awkward First Date

Traditionally, finding out a device's services was a whole ordeal. It was like going on a full, three-course dinner date just to find out the other person's job. The process went something like this:

1. Scan: Find the device.

2. Connect: Establish a connection (a slow and power-hungry process).

3. Discover Services: Ask the device, "So... what do you do for a living?" and wait for it to list all its services.

4. Evaluate: Check if the list of services contains the one you're interested in.

5. Disconnect (or stay connected): If it's not the right device, you have to break up (disconnect) and move on. What a waste of time and energy!

This is incredibly inefficient, especially if you're in a crowded room with dozens of BLE devices and you're only looking for one specific type.

The New Way: The Glorious Name Tag

Wouldn't it be great if everyone at a party just wore a name tag with their job title on it? That's exactly what AOSP 16 has given us with BluetoothDevice.EXTRA_UUID_LE. Many BLE devices are already polite enough to include their primary service UUID in their advertisement packets. It's their way of shouting, "I'M A HEART RATE MONITOR!" to the whole room.

Before AOSP 16, getting this information out of the advertisement packet was a messy, manual process of parsing the raw byte array of the scan record. It was doable, but it was the kind of code that you'd write once, pray it worked, and never touch again.

Now, Android does the dirty work for us! The system automatically parses the advertising data and, if it finds any service UUIDs, it conveniently hands them to you in the ScanResult.

The Code: Reading the Name Tag

This new feature makes our ScanCallback even more powerful. We can now check the device's job title the moment we discover it, without ever having to connect.

private val scanCallback = object : ScanCallback() {
    override fun onScanResult(callbackType: Int, result: ScanResult) {
        Log.d("BleSpeedDating", "Found device: ${result.device.address}")

        // Let's check their name tag!
        val serviceUuids = result.scanRecord?.serviceUuids
        if (serviceUuids.isNullOrEmpty()) {
            Log.d("BleSpeedDating", "This one is mysterious. No service UUIDs in the ad.")
            return
        }

        // Define the UUID we're looking for (e.g., the standard Heart Rate Service UUID)
        val heartRateServiceUuid = ParcelUuid.fromString("0000180D-0000-1000-8000-00805F9B34FB")

        if (serviceUuids.contains(heartRateServiceUuid)) {
            Log.d("BleSpeedDating", "It's a match! This is a heart rate monitor. Let's connect!")
            // Now you can proceed to connect to result.device, knowing it's the right one.
            stopBleScan() // We found what we were looking for
            // connectToDevice(result.device)
        } else {
            Log.d("BleSpeedDating", "Not a match. Moving on.")
        }
    }

    // ... onScanFailed ...
}

The code above demonstrates the power of reading service UUIDs directly from advertisement data, and it's a game-changer for device discovery. Let's break down exactly what's happening and why this is such a significant improvement.

When we receive a scan result in our callback, the result object contains a scanRecord property. This scan record is essentially the raw advertisement packet that the BLE device broadcast into the air.

Before AOSP 16, if you wanted to extract service UUIDs from this data, you'd have to manually parse the byte array, understand the BLE advertisement format, handle different data types, and pray you didn't make an off-by-one error. It was the kind of code that worked once and then you never touched it again out of fear.

Now, with the improvements in AOSP 16, Android does all that messy parsing for us. We can simply call result.scanRecord?.serviceUuids and get back a nice, clean list of ParcelUuid objects. The safe call operator (?.) is important here because not all devices include a scan record in their results, and we need to handle that gracefully.

After retrieving the service UUIDs, we check if the list is null or empty. Some devices don't include service UUIDs in their advertisements. They might be using a proprietary format, or they might just be poorly configured. If there are no UUIDs, we log a message and return early. There's no point in continuing if we can't identify what the device does.

Next, we define the UUID we're looking for. In this example, we're searching for heart rate monitors, so we use the standard Heart Rate Service UUID: 0000180D-0000-1000-8000-00805F9B34FB. This is a UUID defined by the Bluetooth SIG (Special Interest Group), and any compliant heart rate monitor will advertise this UUID. You can find a complete list of standard service UUIDs in the Bluetooth specifications, or you can use custom UUIDs if you're building your own BLE peripherals.

The magic happens in the if (serviceUuids.contains(heartRateServiceUuid)) check. This is where we're doing our speed dating: we're checking the device's "name tag" to see if it matches what we're looking for.

If it does, we've found our match! We can immediately stop scanning (because why keep looking when we've found what we need?) and proceed to connect to the device. We know, with certainty, that this device is a heart rate monitor, so we won't waste time and battery connecting to random devices only to discover they're not what we need.

If the UUID doesn't match, we simply log "Not a match" and move on. The callback will be called again when the next device is found, and we'll repeat this process until we find our heart rate monitor or the user stops the scan.

This is a massive performance improvement over the old approach. Previously, you'd have to connect to every device you found, perform service discovery (which involves multiple round-trip communications with the device), check if it has the services you need, and then disconnect if it doesn't. Each connection attempt takes time, uses battery, and creates unnecessary radio traffic.

Now, you can filter and identify devices at lightning speed, all at the scanning stage. No more awkward first dates where you connect to a smart lightbulb thinking it might be a fitness tracker. Just efficient, targeted connections.

This is particularly useful for apps that need to find a specific type of sensor or peripheral in a sea of irrelevant devices. Imagine you're in a hospital with hundreds of BLE-enabled medical devices, or in a smart home with dozens of sensors and actuators. Being able to instantly identify the right device from its advertisement is the difference between a responsive, professional app and one that feels sluggish and unreliable.

We've now met all three of our Bluetooth musketeers: passive scanning for battery efficiency, bond loss reasons for better debugging, and service UUIDs from advertisements for faster device identification. But our journey isn't over. It's time to venture into the deep woods of advanced scanning techniques.

Advanced Topics: Filtering, Batching, and Other Sorcery

Alright, you've mastered the basics. You can scan passively, you can get closure on your connection breakups, and you can speed-date devices like a pro. You're no longer a Bluetooth padawan. It's time to become a Jedi Master.

Let's dive into the advanced arts of filtering, batching, and other optimization sorcery that will make your app a true battery-saving champion.

Hardware Filtering: Your Personal Assistant

Imagine you're a celebrity, and you've hired a personal assistant. You don't want to be bothered by every single person who wants an autograph. So, you give your assistant a list: "Only let me know if you see my agent or my mom." Your assistant then stands at the door and only bothers you when someone on the list shows up.

This is exactly what hardware filtering does. Instead of your app's code (the celebrity) being woken up for every single Bluetooth device the radio sees, you can offload the filtering logic to the Bluetooth controller itself (the personal assistant). This is a feature that's been around since Android 6.0, but it's more important than ever.

Why is this so great? Because your app's code can stay asleep. The main processor (the AP) doesn't have to wake up every time a random Bluetooth toothbrush advertises itself. The Bluetooth controller, which is much more power-efficient, handles the filtering. The AP only wakes up when the controller finds a device that matches your criteria.

The Code: Building Your VIP List

You implement this using ScanFilter. You can filter by a device's name, its MAC address, or, most usefully, by the Service UUID it's advertising.

// We only want to be bothered if we see a heart rate monitor.
val heartRateServiceUuid = ParcelUuid.fromString("0000180D-0000-1000-8000-00805F9B34FB")

val filter = ScanFilter.Builder()
    .setServiceUuid(heartRateServiceUuid)
    .build()

val scanFilters: List<ScanFilter> = listOf(filter)

// Now, when you start your scan, pass in this list
bleScanner.startScan(scanFilters, scanSettings, scanCallback)

The code above shows how to create a hardware-level filter that dramatically improves both battery life and app performance. Let's dive deep into what's happening here and why this is such a powerful technique.

We start by defining the service UUID we're interested in – in this case, the standard Heart Rate Service UUID. This is the same UUID we used in the previous example, but now we're using it in a fundamentally different way. Instead of checking the UUID in our app's code after receiving scan results, we're telling the Bluetooth hardware itself to only report devices that match this UUID.

The ScanFilter.Builder() is our tool for constructing this filter. It's a builder pattern, which means we can chain multiple methods together to configure exactly what we're looking for. In this example, we're calling setServiceUuid(heartRateServiceUuid), which tells the filter to only match devices that advertise this specific service.

But the builder has many other options you can use:

• setDeviceName() – Match devices with a specific name (like "My Heart Monitor")

• setDeviceAddress() – Match a specific device by its MAC address (useful if you've already paired with a device and want to find it again)

• setManufacturerData() – Match devices based on manufacturer-specific data in their advertisements

• setServiceData() – Match based on service data included in the advertisement

You can even combine multiple criteria in a single filter. For example, you could create a filter that matches devices with a specific service UUID and a specific manufacturer ID. The more specific your filter, the fewer false positives you'll get.

After building our filter, we create a list containing it. Why a list? Because you can have multiple filters, and a device will match if it satisfies any of the filters in the list. For instance, you might create one filter for heart rate monitors and another for blood pressure monitors, and your scan will report devices that match either one. This is an OR operation: the device doesn't need to match all filters, just one of them.

Finally, we pass this list of filters to startScan() along with our scan settings and callback. This is where the magic happens. When you provide filters, Android doesn't just filter the results in your app's code. It pushes these filters down to the Bluetooth controller hardware itself. This means the filtering happens at the lowest level, before your app is even notified.

Here's why this is so powerful: without filters, every time the Bluetooth radio hears an advertisement from any device (your neighbor's smart toaster, someone's fitness tracker walking by, the Bluetooth speaker three rooms away), it has to wake up your app's process, deliver the scan result, and let your code decide if it cares about this device. Each of these wake-ups costs battery and processing time.

With hardware filters, the Bluetooth controller silently ignores all the devices that don't match your criteria. Your app stays asleep. The main processor stays asleep. Only when a heart rate monitor is detected does the hardware wake up your app and deliver the result. It's like having a bouncer at a club who only lets in people on the VIP list. Everyone else is turned away at the door, and you never even know they were there.

By using a ScanFilter, you're telling the hardware, "Don't wake me up unless you see a heart rate monitor." It's the ultimate power-saving move for background scanning. Combined with passive scanning and batch reporting, you can create a Bluetooth scanning system that runs for hours or even days with minimal battery impact. This is how professional-grade apps handle long-term device monitoring without destroying battery life.

Batch Scanning: The Daily Report

Let's go back to our celebrity analogy. Sometimes, you don't need to be interrupted the moment your mom shows up. You'd rather just get a report at the end of the day: "Today, your mom stopped by twice, and your agent called once." This is batch scanning.

Instead of delivering scan results to your app in real-time, the Bluetooth controller can collect them and deliver them in a big batch. This is another incredible power-saving feature. Your app can sleep for long periods, then wake up, process a whole bunch of results at once, and go back to sleep.

You enable this with the setReportDelay() method in your ScanSettings.

val scanSettings = ScanSettings.Builder()
    // ... other settings ...
    // Deliver results every 5 seconds (5000 milliseconds)
    .setReportDelay(5000)
    .build()

When you use a report delay, your onScanResult callback will be replaced by onBatchScanResults, which gives you a List<ScanResult>.

private val scanCallback = object : ScanCallback() {
    override fun onBatchScanResults(results: List<ScanResult>) {
        Log.d("BatchScanner", "Here's your daily report! Found ${results.size} devices.")
        for (result in results) {
            // Process each result
        }
    }

    // ... onScanFailed ...
}

The batch scanning mechanism shown above is one of the most underutilized power-saving features in Android Bluetooth, and understanding how it works can transform your app's battery profile. Let's break down exactly what's happening under the hood and when you should use this technique.

When you set a report delay of 5000 milliseconds (5 seconds) in the code above, you're fundamentally changing how the scanning pipeline works. Instead of the Bluetooth controller immediately waking up your app every time it sees a device, it acts like a diligent assistant taking notes. For those 5 seconds, the controller silently collects every scan result it encounters, storing them in its own internal buffer. Your app remains completely asleep during this time – no CPU cycles wasted, no battery drained by context switches or process wake-ups.

After the 5-second delay expires, the controller delivers all the accumulated results in one batch to your onBatchScanResults() callback. This is where the power savings come from: instead of waking up your app 50 times if 50 devices were detected, it wakes up once and hands you all 50 results at the same time. Your app can then efficiently process this batch – maybe updating a UI list, logging the data, or checking for specific devices – and then go back to sleep until the next batch arrives.

The results parameter in onBatchScanResults() is a List<ScanResult>, and each ScanResult in the list represents a single advertisement that was heard during the batching period. It's important to note that if the same device advertises multiple times during the delay period, you might receive multiple results for that device in the batch. The list isn't automatically deduplicated – that's your job if you need it.

In the example above, we're simply logging the number of devices found and then iterating through each result. In a real application, you might want to do more sophisticated processing. For instance, you could build a map of devices keyed by MAC address to track how many times each device advertised, calculate average RSSI values to estimate distance, or filter the batch to only process devices that meet certain criteria.

Warning: Batch scanning is a powerful tool, but it's not for every situation. If you need to react to a device's presence immediately (for example, if you're building a "find my keys" app where the user is actively searching), a report delay is not your friend. The user doesn't want to wait 5 seconds to see results – they want instant feedback. In these cases, set setReportDelay(0) for immediate reporting.

But for long-term monitoring or data collection scenarios, batch scanning is a battery's best friend. Consider these use cases:

• Background presence monitoring: Your app checks every minute to see if the user's smartwatch is still in range, but doesn't need second-by-second updates.

• Environmental sensing: You're collecting data from temperature sensors throughout a building and only need to update your dashboard every 30 seconds.

• Beacon analytics: You're tracking how many people pass by a retail location based on their phone's BLE advertisements, and you aggregate the data every 10 seconds.

The sweet spot for report delay depends on your use case. Too short (like 1 second), and you're not getting much benefit, you're still waking up frequently. Too long (like 60 seconds), and your app might feel unresponsive or miss time-sensitive events. For most background monitoring tasks, delays between 5 and 30 seconds work well.

One more thing to be aware of: batch scanning has limits. The Bluetooth controller has a finite buffer for storing scan results. If you set a very long delay and you're in an environment with hundreds of BLE devices, the buffer might fill up before the delay expires. When this happens, the oldest results get dropped. Android doesn't give you a warning when this occurs, so if you're missing data, consider reducing your report delay or using more aggressive filters to reduce the number of results being collected.

OnFound/OnLost: The Drama of Presence

Since Android 8.0, scanning has gotten even more dramatic. You can now ask the hardware to not only tell you when it finds a device, but also when it loses one. This is done using the CALLBACK_TYPE_FIRST_MATCH and CALLBACK_TYPE_MATCH_LOST flags in your ScanSettings.

val scanSettings = ScanSettings.Builder()
    .setCallbackType(ScanSettings.CALLBACK_TYPE_FIRST_MATCH or ScanSettings.CALLBACK_TYPE_MATCH_LOST)
    .build()

Now, in your ScanCallback, the callbackType parameter in onScanResult will tell you what happened.

override fun onScanResult(callbackType: Int, result: ScanResult) {
    when (callbackType) {
        ScanSettings.CALLBACK_TYPE_FIRST_MATCH -> {
            Log.d("PresenceDetector", "Found them! ${result.device.address} has entered the building.")
        }
        ScanSettings.CALLBACK_TYPE_MATCH_LOST -> {
            Log.d("PresenceDetector", "They're gone! ${result.device.address} has left the building.")
        }
    }
}

The presence detection mechanism shown above represents a fundamental shift in how we think about Bluetooth scanning. Instead of treating scanning as a continuous stream of "here's what I see right now," we're now working with events: "this device appeared" and "this device disappeared." Let's dive deep into how this works and why it's so powerful.

When you set the callback type using the bitwise OR operator (or in Kotlin, | in Java), you're telling the Bluetooth hardware to track the presence state of devices over time. The code CALLBACK_TYPE_FIRST_MATCH or CALLBACK_TYPE_MATCH_LOST combines both flags, meaning you want to be notified both when a device first appears and when it disappears. You can use these flags individually if you only care about one type of event, but using both together gives you complete presence awareness.

Let's understand what "first match" and "match lost" actually mean. When the Bluetooth controller hears an advertisement from a device that matches your filters for the first time, it triggers a CALLBACK_TYPE_FIRST_MATCH event. This is different from CALLBACK_TYPE_ALL_MATCHES (the default), which would trigger every single time the device advertises. A device might advertise multiple times per second, so the difference is significant. With FIRST_MATCH, you get one notification when the device enters your scanning range, not a flood of notifications as it continues to advertise.

The CALLBACK_TYPE_MATCH_LOST event is even more interesting. The Bluetooth controller keeps track of when it last heard from each device. If a device stops advertising (because it moved out of range, was turned off, or its battery died), the controller notices the absence and triggers a MATCH_LOST event. This happens automatically: you don't have to manually track timestamps or implement timeout logic in your app. The hardware does it for you.

But how does the hardware know when a device is "lost"? It uses an internal timeout. If the controller hasn't heard from a device for a certain period (typically a few seconds, though the exact duration is implementation-dependent and not exposed to apps), it considers the device lost. This means there's a slight delay between when a device actually leaves range and when you get the MATCH_LOST callback, but this delay is usually acceptable for presence detection use cases.

In the code example above, we're using a when expression to handle the different callback types. When we receive a FIRST_MATCH, we know the device has just entered our scanning range, so we log "Found them!" This is perfect for triggering actions like unlocking a door when your phone comes near, or starting to sync data when your fitness tracker is detected.

When we receive a MATCH_LOST, we know the device has left our scanning range or stopped advertising, so we log "They're gone!" This is ideal for triggering cleanup actions like locking the door when your phone leaves, or stopping a data sync when your tracker disconnects.

This is incredibly useful for presence detection scenarios. Is your smart lock in range? Is your fitness tracker still connected? Is the user's phone nearby? Now you can know, with hardware-level certainty, and you can react to changes in presence without constantly polling or maintaining complex state machines in your app code.

Here's a practical example of how you might use this in a smart home app:

private val presenceCallback = object : ScanCallback() {
    override fun onScanResult(callbackType: Int, result: ScanResult) {
        when (callbackType) {
            ScanSettings.CALLBACK_TYPE_FIRST_MATCH -> {
                // User's phone detected - they're home!
                Log.d("SmartHome", "Welcome home! Unlocking door and turning on lights.")
                unlockFrontDoor()
                turnOnLights()
                adjustThermostat(COMFORTABLE_TEMP)
            }
            ScanSettings.CALLBACK_TYPE_MATCH_LOST -> {
                // User's phone is gone - they left!
                Log.d("SmartHome", "Goodbye! Locking door and entering away mode.")
                lockFrontDoor()
                turnOffLights()
                adjustThermostat(ENERGY_SAVING_TEMP)
                armSecuritySystem()
            }
        }
    }

    override fun onScanFailed(errorCode: Int) {
        Log.e("SmartHome", "Presence detection failed: $errorCode")
    }
}

One important consideration: FIRST_MATCH and MATCH_LOST are mutually exclusive with CALLBACK_TYPE_ALL_MATCHES. If you combine them with ALL_MATCHES, the behavior becomes undefined and varies by device. Stick to either ALL_MATCHES for continuous reporting, or FIRST_MATCH/MATCH_LOST for presence detection – don't try to use both at once.

Also, be aware that presence detection works best when combined with hardware filtering. If you're scanning for all devices without filters, the controller has to track the presence state of every single BLE device in range, which can overwhelm its internal tracking tables. Always use ScanFilter to narrow down which devices you care about when using presence detection.

By combining these advanced techniques – hardware filtering, batch scanning, and presence detection – you can build incredibly sophisticated and power-efficient Bluetooth applications. You're not just a developer anymore. You're a Bluetooth wizard, wielding the power to create apps that are aware of their surroundings, responsive to changes, and respectful of battery life.

Now, let's see where we can apply these magical powers in the real world.

Real-World Use Cases: Where the Bluetooth Hits the Road

Okay, we've learned a ton of cool new tricks. We're basically Bluetooth black belts at this point. But what's the use of all this power if we don't use it for good (or at least for a cool app)? Let's explore some real-world scenarios where the new features in AOSP 16 can turn a good app into a great one.

1. The "Find My Everything" App

We've all been there. You're late for work, and your keys have decided to play a game of hide-and-seek in another dimension. This is the classic use case for a BLE tracker.

• The Old Way: Your app would be constantly doing active scans, draining your battery while you frantically search. It would connect to every tracker in your house just to see if it's the right one.

• The AOSP 16 Way: Your app runs a passive scan in the background with a hardware filter for your tracker's specific Service UUID. The battery impact is minimal. When you open the app to find your keys, it already knows they're in the house because it's been listening silently. You hit the "Find" button, the app connects, and your keys start screaming from inside the couch cushions. And if the connection fails? Bond loss reason tells you if the tracker's battery died, so you're not looking for a dead device.

2. The Smart Supermarket

Imagine an app that gives you coupons for products as you walk past them in the store. This is the dream of proximity marketing, a dream that has been historically thwarted by, you guessed it, battery drain.

• The Old Way: The app would need to constantly scan for beacons, turning the user's phone into a hot potato and a dead battery by the time they reach the checkout line.

• The AOSP 16 Way: The supermarket places BLE beacons in each aisle. Your app uses a passive, batched scan. It wakes up every minute or so, gets a list of all the beacons it has seen, and then goes back to sleep. When it sees you've been loitering in the cookie aisle for five minutes (it knows, it always knows), it uses the Service UUID from the advertisement to identify the "Cookie Aisle Beacon" and sends you a coupon for Oreos. It's targeted, it's efficient, and it doesn't kill your battery before you can pay.

3. The Overly-Attached Smart Home

Your smart home should be, well, smart. It should know when you're home and when you've left. It should lock the door behind you and turn on the lights when you arrive.

• The Old Way: You'd have to rely on GPS (a notorious battery hog) or Wi-Fi connections, which can be unreliable. BLE was an option, but constant scanning was a problem.

• The AOSP 16 Way: Your phone is the key. Your smart hub (acting as a central device) runs a continuous, low-power passive scan. When it sees your phone's BLE advertisement, it knows you're home. But what if you just walk by the house? This is where the OnFound/OnLost feature comes in. The hub can be configured to only trigger the "Welcome Home" sequence after it has seen your device consistently for a minute (OnFound), and to trigger the "Goodbye" sequence only after it hasn't seen you for five minutes (OnLost). It's a smarter, more reliable presence detection system that finally makes the smart home feel... smart.

4. The Corporate Asset Tracker

In a large hospital or warehouse, keeping track of expensive, mobile equipment (like IV pumps or forklifts) is a huge challenge. BLE tags are the solution.

• The Old Way: Employees would have to walk around with a tablet, doing active scans to take inventory. It's slow, manual, and inefficient.

• The AOSP 16 Way: A network of fixed BLE gateways is installed throughout the building. Each gateway is a simple device (like a Raspberry Pi) running a continuous passive scan. They collect all the advertisement data from the asset tags and send it to a central server. The server can now see, in real-time, that IV Pump #34 is in Room 201, and Forklift #3 is currently in the loading bay. No manual scanning required. It's a low-cost, low-power, real-time location system, all thanks to the efficiency of passive scanning.

These are just a few examples. From fitness trackers to industrial sensors, the new Bluetooth features in AOSP 16 open up a world of possibilities for building apps that are not only powerful but also polite to your user's battery. Now, let's talk about how to make sure our shiny new app works on all devices, not just the new ones.

API Version Checking: How to Not Crash Your App

So, you've built a beautiful, battery-sipping app using all the new hotness from AOSP 16's Q4 release. You're ready to ship it, become a millionaire, and retire to a private island. But then, a bug report comes in. Your app is crashing on a brand new Android 16 device. What gives?!

Welcome, my friend, to the wonderful world of API version checking. With Android's new release schedule, this has become more important (and slightly more complicated) than ever.

The Problem: A Tale of Two Android 16s

As we discussed, 2025 gave us two Android 16 releases:

• The Q2 Release: The main "Baklava" release. Let's call this API level 36.0.

• The Q4 Release: The minor, feature-drop release. This is where our new Bluetooth toys live. Let's call this API level 36.1.

Our new passive scanning API, setScanType(), only exists on 36.1 and later. If you try to call it on a device that's running the initial Q2 release (36.0), your app will crash with a NoSuchMethodError. It's the digital equivalent of asking for a menu item that was only added last night. The chef (your app) just gets confused and has a meltdown.

The Old Guard: SDK_INT

For years, our trusty friend for checking API levels has been Build.VERSION.SDK_INT. It's simple and effective.

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
    // Use an API from Android 12 (S) or higher
}

But SDK_INT only knows about major releases. For both Android 16 Q2 and Q4, SDK_INT will just report 36. It has no idea about the minor version. It's like asking someone their age, and they just say "thirties." Not very specific.

The New Hotness: SDK_INT_FULL

To solve this, the Android team has given us a new, more precise tool: Build.VERSION.SDK_INT_FULL. This constant knows about both the major and minor version numbers. And to go with it, we have a new set of version codes: Build.VERSION_CODES_FULL.

So, to safely call our new passive scanning API, we need to do a more specific check:

// Let's build our ScanSettings
val scanSettingsBuilder = ScanSettings.Builder()
    .setScanMode(ScanSettings.SCAN_MODE_LOW_POWER)

// Now, let's check if we can go passive
if (Build.VERSION.SDK_INT_FULL >= Build.VERSION_CODES_FULL.BAKLAVA_1) {
    Log.d("ApiCheck", "This device is cool. Going passive.")
    // This is the new API from the Q4 release (36.1)
    scanSettingsBuilder.setScanType(ScanSettings.SCAN_TYPE_PASSIVE)
} else {
    Log.d("ApiCheck", "This device is old school. Sticking to active scanning.")
    // Fallback for devices that don't have the new API
    // We don't need to do anything here, as active is the default
}

val scanSettings = scanSettingsBuilder.build()

Graceful Degradation: The Art of Falling with Style

This brings us to a crucial concept: graceful degradation. It means your app should still work on older devices, even if it can't use the latest and greatest features. It should fall back gracefully.

In our example above, if the setScanType method isn't available, we just... don't call it. The app will default to a normal, active scan. It won't be as battery-efficient, but it will still work. The user on the older device gets a functional app, and the user on the newer device gets a more optimized experience. Everybody wins.

Here's a table to help you remember when to use which check:

Mastering this new API checking is non-negotiable. It's the key to writing modern Android apps that are both innovative and stable. Now that we know how to build a robust app, let's talk about how to fix it when it inevitably breaks.

Testing and Debugging: The Fun Part (Said No One Ever)

There are two universal truths in software development:

• It works on my machine, and

• It will break in the most spectacular way possible during a live demo.

Bluetooth development, in particular, seems to delight in this second truth. It's a fickle, invisible force that seems to have a personal vendetta against developers.

So, how do we fight back? With a solid testing and debugging strategy. It's not glamorous, but it's the only way to stay sane.

The Emulator: A Land of Make-Believe

Android Studio's emulator is a fantastic tool. It's fast, it's convenient, and it can simulate all sorts of devices. And for Bluetooth? It can... sort of help. The emulator does have virtual Bluetooth support. You can enable it, and your app will think it has a Bluetooth adapter. It's great for testing your UI and making sure your app doesn't crash when it tries to get the BluetoothLeScanner.

But here's the catch: it's not real. The emulator can't actually interact with the radio waves in your room. You can't use it to find your real-life BLE headphones. For that, you need to venture into the real world.

The Real World: Where the Bugs Live

There is no substitute for testing on real, physical devices. Every phone manufacturer has its own special flavor of Bluetooth stack, its own quirky antenna design, and its own unique way of making your life difficult. A scan that works perfectly on a Google Pixel might fail miserably on another brand. The only way to know is to test.

Your testing arsenal should include:

• A variety of phones: Different brands, different Android versions. The more, the better.

• A variety of BLE peripherals: Don't just test with one type of device. Get a few different beacons, sensors, or wearables. You'll be amazed at how differently they behave.

Common Errors: The Usual Suspects

When your scan inevitably fails, it will give you an error code. Here are a few of the most common culprits:

Debugging Tools: Your Ghost-Hunting Kit

When things go wrong, you need the right tools to see what's happening in the invisible world of Bluetooth.

• logcat: This is your best friend. Be generous with your log statements. Log when you start a scan, when you stop a scan, when you find a device, and when a scan fails. Create a filter for your app's tag so you can see the signal through the noise.

• Android's Bluetooth HCI Snoop Log: This is the holy grail of Bluetooth debugging. It's a developer option that records every single Bluetooth packet that goes in or out of your device. It's incredibly detailed and can be overwhelming, but it's the ultimate source of truth. You can open the generated log file in a tool like Wireshark to see the raw, unfiltered conversation between your phone and the BLE device. It's like having a wiretap on the radio waves.

• nRF Connect for Mobile: This is a free app from Nordic Semiconductor, and it's an essential tool for any BLE developer. It lets you scan for devices, see their advertising data, connect to them, and explore their GATT services. If your app can't find a device, the first thing you should do is see if nRF Connect can. If it can't, the problem is likely with the peripheral, not your app.

Testing and debugging Bluetooth is a marathon, not a sprint. It requires patience, a methodical approach, and a healthy dose of self-deprecating humor. But with the right tools and techniques, you can tame the beast.

Now, let's talk about how to make sure our well-behaved app is also a good citizen when it comes to performance.

Performance and Best Practices: How to Be a Good Bluetooth Citizen

Writing code that works is one thing. Writing code that works well, is efficient, and doesn't make your users want to throw their phone against a wall is another thing entirely. When it comes to Bluetooth, being a good citizen is all about one thing: battery, battery, battery.

The Bluetooth radio is a powerful piece of hardware, but it's also a thirsty one. Every moment it's active, it's sipping power. Your job is to make sure it's only sipping when absolutely necessary. Here are the golden rules of being a good Bluetooth citizen.

1. Don't Scan If You Don't Have To

This sounds obvious, but it's the most common mistake. Before you even think about starting a scan, ask yourself: "Do I really need to do this right now?" If the user is not on the screen that needs scan results, don't scan. If the app is in the background, be extra critical. Background scanning is a huge drain on battery and is heavily restricted by Android for that very reason.

2. Stop Your Scan!

I'm going to say it again because it's that important: always stop your scan when you're done. A scan that's left running is like a leaky faucet for your battery. It will drain and drain until there's nothing left. The best practice is to tie your scan lifecycle to your UI lifecycle.

override fun onPause() {
    super.onPause()
    // The user can't see the screen, so they don't need the results.
    stopBleScan()
}

override fun onResume() {
    super.onResume()
    // The user is back on the screen, let's start scanning again.
    startBleScan()
}

If you find the device you're looking for, stop the scan immediately. There's no need to keep looking.

3. Choose the Right Scan Mode

ScanSettings gives you a few different modes. Choose wisely.

• SCAN_MODE_LOW_POWER: This is your default, everyday mode. It scans in intervals, balancing discovery speed and battery life. Use this for most foreground scanning.

• SCAN_MODE_BALANCED: A middle ground. It scans more frequently than low power mode.

• SCAN_MODE_LOW_LATENCY: This is the "I need to find it NOW" mode. It scans continuously. This will find devices the fastest, but it will also drain your battery the fastest. Only use this for short, critical operations.

• SCAN_MODE_OPPORTUNISTIC: This is the ultimate passive mode. Your app doesn't trigger a scan at all. It just gets results if another app happens to be scanning. It uses zero extra battery, but you have no guarantee of getting results. Use this for non-critical background updates.

And of course, if you're on AOSP 16 QPR2 or later, use setScanType(SCAN_TYPE_PASSIVE) whenever you don't need the scan response data. It's the new king of power efficiency.

4. Use Hardware Filtering and Batching

We covered this in the advanced section, but it's a best practice that's worth repeating. If you're looking for a specific device, use a ScanFilter. If you're doing a long-running scan, use setReportDelay() to batch your results. These two techniques offload the work to the power-efficient Bluetooth controller and let your app's code sleep, which is the number one way to save battery.

5. Be Mindful of Memory

Every ScanResult object that your app receives takes up memory. If you're in a crowded area with hundreds of BLE devices, and you're not using filters, your app can quickly get overwhelmed and run out of memory. This is another reason why filtering is so important. Only get the results you actually care about.

By following these rules, you can build a Bluetooth app that is not only powerful and feature-rich but also respectful of your user's device. You'll be a true Bluetooth sensei. Now, let's wrap things up and look to the future.

Conclusion: The Future is Passive (and That's Okay)

We've been on quite a journey, haven't we? We've traveled back in time to the dark ages of Classic Bluetooth, witnessed the renaissance of BLE, and emerged into the brave new world of AOSP 16. We've learned to be silent ninjas with passive scanning, played detective with bond loss reasons, and mastered the art of speed dating with service UUIDs from advertisements.

If there's one big takeaway from all of this, it's that the future of Bluetooth on Android is smarter, more efficient, and a whole lot less frustrating. The Android team is clearly listening to the pain points of developers and giving us the tools we need to build better, more battery-friendly apps. The introduction of passive scanning isn't just a new feature – it's a change in philosophy. It's an acknowledgment that sometimes, the best way to communicate is to just listen.

As developers, these new tools empower us to move beyond the simple "connect and stream" use cases. We can now build sophisticated, context-aware applications that are constantly aware of their surroundings without turning our users' phones into expensive paperweights. The dream of a truly smart, seamlessly connected world is a little bit closer, and it's going to be built on the back of these power-efficient technologies.

So, what's next? The world of Bluetooth is always evolving. We have Bluetooth 5.4 with Auracast, mesh networking, and even more precise location-finding on the horizon. The one thing we can be sure of is that the tools will continue to get better, and the challenges will continue to get more interesting.

For now, take a moment to appreciate the progress we've made. The next time you start a Bluetooth scan and it just works, take a moment to thank the hardworking engineers who made it possible. And the next time your app's battery graph is a beautiful, flat line instead of a terrifying ski slope, give a little nod to the power of passive scanning.

The Bluetooth beast may never be fully tamed, but with AOSP 16, we've been given a much stronger leash. Now go forth and build amazing things. And for the love of all that is holy, remember to stop your scan.

GATT is the Generic Attribute Profile, and it provides the structure that makes Bluetooth Low Energy (BLE) devices exchange meaningful information. Without GATT, Bluetooth radios would simply move bits back and forth with no agreed format or interpretation. With GATT, devices can communicate in a predictable and understandable language.

Think of Bluetooth radios as two people speaking to each other in a room. The radio waves allow them to talk, but without a common language, the exchange is useless. GATT provides that common language. It defines the vocabulary, grammar, and sentence structure. Instead of random binary, we get clear messages like Heart Rate equals 78 bpm, Battery equals 92 percent, or Light Switch equals ON.

Because of GATT, devices from different manufacturers are able to interoperate. A Polar heart rate strap can connect to a Peloton bike. A Samsung phone can read temperature from a medical sensor. An Apple Watch can control Philips Hue smart lights. These devices do not share hardware, companies, or operating systems, yet they can cooperate because GATT defines a universal structure for exposing and accessing data.

Once you understand GATT, Bluetooth becomes far less mysterious. Communication becomes a matter of reading or writing values in a small structured database. Debugging becomes logical. BLE app development becomes straightforward. And building your own IoT device becomes achievable, even for beginners.

In this article, we’ll walk through GATT in depth. You’ll learn how devices organize data into services and characteristics, how phones discover and read values, how notifications deliver real time updates, and how embedded and Android code interact with GATT. By the end, you’ll be able to design a GATT database, understand BLE logs, and confidently build BLE applications.

Prerequisites

Before you continue, you should have a basic understanding of:

• What Bluetooth is at a high level (no deep protocol knowledge needed)

• How mobile apps connect to external devices (Android, iOS, or embedded)

• Very basic programming concepts (variables, functions, objects)

You’ll also need:

• A smartphone or laptop with Bluetooth Low Energy support

• A BLE-compatible development board or device (optional, but helpful if you want to try the code examples)

• A BLE debugging/scanning app such as nRF Connect, LightBlue, or BLE Scanner

If you’re completely new to BLE, don’t worry – this article walks through each concept step-by-step.

Table of Contents

• What is GATT?

• What Are Services and Why Do They Matter?

• What are Characteristics and How Do They Work?

• How to Design a GATT Profile for a Smart Plant Monitor

• Conclusion

What is GATT?

GATT stands for Generic Attribute Profile. It is the structured communication model used by Bluetooth Low Energy devices to exchange data in a clear and organized format.

GATT defines how data is stored, formatted, accessed, updated, and transmitted across BLE connections. Without GATT, Bluetooth devices would only exchange unstructured binary information that has no consistent meaning. With GATT, devices can share values such as battery percentage, heart rate, temperature readings, and status commands in a well-defined way.

GATT Client and Server Roles

All communication in BLE occurs between two roles. The GATT Server owns and exposes the data. The GATT Client requests, reads, writes, or subscribes to that data. The Server holds a database of values that the Client interacts with. A smartwatch usually acts as a GATT Server because it holds sensor values. A smartphone usually acts as a GATT Client because it retrieves that information.

These roles can switch depending on the task. For example, during a firmware update, the phone acts as the GATT Server providing firmware blocks and the wearable acts as the GATT Client requesting them.

Services, Characteristics, and UUIDs

The GATT Server stores its data in a structured database made up of Services and Characteristics. A Service is a container that groups related information. A Characteristic is a single data value inside a service.

For example, the Battery Service contains the Battery Level characteristic. The Heart Rate Service contains the Heart Rate Measurement characteristic.

All services and characteristics are identified using UUID values so that every device knows how to locate them. Standard Bluetooth SIG defined services such as Heart Rate and Battery use 16 bit UUIDs. Custom proprietary features use 128 bit UUIDs.

Example GATT Database Layout

Here is a conceptual breakdown of a simple GATT database layout:

Service: Battery Service (UUID 0x180F)
    Characteristic: Battery Level (UUID 0x2A19)
    Example value: 92 percent

Example: Reading a GATT Characteristic from Android

When a phone connects to a BLE device and acts as the client, it performs a sequence of steps. It connects to the device, discovers services, finds the characteristic of interest, and reads or subscribes to its value.

The following complete Java example shows an Android app acting as a GATT Client, discovering services and reading the battery level.

public class BleGattClientManager {

    private BluetoothGatt bluetoothGatt;

    private final BluetoothGattCallback gattCallback = new BluetoothGattCallback() {

        @Override
        public void onConnectionStateChange(BluetoothGatt gatt, int status, int newState) {
            if (newState == BluetoothProfile.STATE_CONNECTED) {
                Log.d(TAG, "Connected to device. Discovering services.");
                gatt.discoverServices();
            }
        }

        @Override
        public void onServicesDiscovered(BluetoothGatt gatt, int status) {
            UUID BATTERY_SERVICE_UUID =
                    UUID.fromString("0000180F-0000-1000-8000-00805F9B34FB");
            UUID BATTERY_LEVEL_UUID =
                    UUID.fromString("00002A19-0000-1000-8000-00805F9B34FB");

            BluetoothGattService service = gatt.getService(BATTERY_SERVICE_UUID);
            if (service != null) {
                BluetoothGattCharacteristic characteristic =
                        service.getCharacteristic(BATTERY_LEVEL_UUID);
                if (characteristic != null) {
                    gatt.readCharacteristic(characteristic);
                }
            }
        }

        @Override
        public void onCharacteristicRead(BluetoothGatt gatt,
                                         BluetoothGattCharacteristic characteristic,
                                         int status) {
            if (status == BluetoothGatt.GATT_SUCCESS) {
                int batteryValue = characteristic.getIntValue(
                        BluetoothGattCharacteristic.FORMAT_UINT8, 0);
                Log.d(TAG, "Battery Level: " + batteryValue + " percent");
            }
        }
    };

    public void connect(Context context, BluetoothDevice device) {
        bluetoothGatt = device.connectGatt(context, false, gattCallback);
    }
}

This Java class represents a Bluetooth Low Energy GATT client that connects to a BLE device and reads the battery level characteristic. The class holds a BluetoothGatt object that represents the active BLE connection. The BluetoothGattCallback handles events during the connection lifecycle.

When the device connection state changes and the new state indicates that the device is connected, the callback triggers service discovery by calling gatt.discoverServices().

After the services are discovered, the callback receives onServicesDiscovered, where two standard UUIDs are defined: the Battery Service with UUID 0000180F-0000-1000-8000-00805F9B34FB and the Battery Level characteristic with UUID 00002A19-0000-1000-8000-00805F9B34FB. The client retrieves the Battery Service using gatt.getService, then retrieves the Battery Level characteristic using getCharacteristic.

If both objects are found, the client calls gatt.readCharacteristic, which sends a read request to the server. When the server responds, onCharacteristicRead is invoked. If the response is successful, the characteristic value is extracted using getIntValue as an unsigned 8 bit integer at offset zero, producing a percentage from zero to one hundred. This value is printed to the log.

The connect method initiates the connection by calling device.connectGatt, which begins the communication and links all callbacks.

In summary, the flow is simple: connect to the device, discover services, locate the Battery Service, read the Battery Level characteristic, and print the result. This code shows the core pattern of how a BLE client interacts with a GATT server to request information.

Android as a GATT Server

The Android device can also act as a GATT Server. This is useful when the phone needs to expose its own characteristics that other BLE devices read or write, such as setup information, commands, or configuration data.

Below is a complete example of a custom GATT Server written in Java. It exposes a custom service and a custom characteristic that allows a BLE client to read and write values.

public class BleGattServerManager {

    private BluetoothGattServer gattServer;

    private final UUID SERVICE_UUID =
            UUID.fromString("12345678-1234-5678-1234-56789abcdef0");

    private final UUID CHARACTERISTIC_UUID =
            UUID.fromString("abcdef01-1234-5678-1234-56789abcdef0");

    private final BluetoothGattServerCallback serverCallback =
            new BluetoothGattServerCallback() {

        @Override
        public void onConnectionStateChange(BluetoothDevice device,
                                            int status,
                                            int newState) {
            Log.d(TAG, "Device connected: " + device.getAddress());
        }

        @Override
        public void onCharacteristicReadRequest(BluetoothDevice device,
                                                int requestId,
                                                int offset,
                                                BluetoothGattCharacteristic characteristic) {

            byte[] value = "HELLO_ANDROID_SERVER".getBytes(StandardCharsets.UTF_8);
            gattServer.sendResponse(device, requestId,
                    BluetoothGatt.GATT_SUCCESS, offset, value);
        }

        @Override
        public void onCharacteristicWriteRequest(BluetoothDevice device,
                                                 int requestId,
                                                 BluetoothGattCharacteristic characteristic,
                                                 boolean preparedWrite,
                                                 boolean responseNeeded,
                                                 int offset,
                                                 byte[] value) {

            String received = new String(value, StandardCharsets.UTF_8);
            Log.d(TAG, "Client wrote value: " + received);

            gattServer.sendResponse(device, requestId,
                    BluetoothGatt.GATT_SUCCESS, offset, value);
        }
    };

    public void startServer(Context context) {
        BluetoothManager bluetoothManager =
                (BluetoothManager) context.getSystemService(Context.BLUETOOTH_SERVICE);

        gattServer = bluetoothManager.openGattServer(context, serverCallback);

        BluetoothGattService customService =
                new BluetoothGattService(SERVICE_UUID,
                        BluetoothGattService.SERVICE_TYPE_PRIMARY);

        BluetoothGattCharacteristic customCharacteristic =
                new BluetoothGattCharacteristic(
                        CHARACTERISTIC_UUID,
                        BluetoothGattCharacteristic.PROPERTY_READ |
                        BluetoothGattCharacteristic.PROPERTY_WRITE,
                        BluetoothGattCharacteristic.PERMISSION_READ |
                        BluetoothGattCharacteristic.PERMISSION_WRITE
                );

        customService.addCharacteristic(customCharacteristic);
        gattServer.addService(customService);
    }
}

This Java class implements a Bluetooth Low Energy GATT Server on Android, meaning it exposes a service and characteristic that another BLE device can read or write.

The class holds a BluetoothGattServer instance which is created when the server starts. Two UUIDs are defined, one for the custom service and one for the custom characteristic. The BluetoothGattServerCallback handles incoming events from any remote BLE client that connects to this server.

When a device connects, onConnectionStateChange logs the connection. When a client sends a read request on the characteristic, onCharacteristicReadRequest responds by sending back a static string value, in this case the bytes of the text HELLO_ANDROID_SERVER, using sendResponse with a success status.

When the client writes data to the characteristic, onCharacteristicWriteRequest converts the incoming byte array to a string, logs what was written, and returns a success response to acknowledge that the server accepted the new value.

The startServer method initializes the GATT Server by requesting the BluetoothManager, opening the server, creating a custom primary service, and adding a characteristic to that service with both read and write properties and permissions. The service is then registered on the server through addService, which makes it available to any BLE client that connects.

In summary, this code demonstrates how an Android device can behave like a BLE peripheral and expose a custom readable and writable characteristic that other devices can interact with. This forms the foundation for features like configuration setup, provisioning, remote control commands, or device to device communication.

This example shows that GATT is simply a structured database of readable and writable values that represent meaningful application behavior. Whether the task is battery level reporting, real time health monitoring, remote control of smart devices, or secure provisioning, the exchange always follows this same pattern.

Understanding GATT at this level is the foundation for all Bluetooth Low Energy engineering and problem solving.

What Are Services and Why Do They Matter?

Services as Capability Containers

A Service in GATT is a logical container that groups related data. A single Bluetooth device can expose many services, and each service focuses on one capability or functional category.

For example, a smartwatch may expose a Heart Rate Service, a Battery Service, a Current Time Service, and a Device Information Service. A smart bulb may expose a Lighting Control Service with characteristics to change brightness and color. A medical thermometer may expose a Health Thermometer Service that continuously streams temperature values.

Services exist to separate different categories of information so that any client device can immediately understand what functions are available and how to interact with them.

A service does not hold raw values itself. Instead, it organizes characteristics, which contain the actual data elements. The service only defines the grouping and the type of behavior associated with that group. This design makes BLE communication extremely scalable. Applications only need to know which service to target, then they can discover and manipulate the characteristics inside it.

Standard vs Custom Services

Bluetooth SIG defines many standard services for interoperability. For example, the Battery Service exposes battery level in a characteristic called Battery Level. The Heart Rate Service exposes heart rate values so that any fitness application can subscribe to it. These standard services allow devices from different manufacturers to work together without custom integration.

Anyone building a custom device can also define their own original service using a 128 bit UUID. The structure is the same whether it is standard or custom.

Example: A Device with Multiple Services

Below is an example representation of a device that exposes two services at the same time:

Service: Battery Service (UUID 0x180F)
    Characteristic: Battery Level (UUID 0x2A19)
    Current value: 92 percent

Service: Heart Rate Service (UUID 0x180D)
    Characteristic: Heart Rate Measurement (UUID 0x2A37)
    Current value: 78 bpm

An Android phone acting as a client can discover these services and then interact with characteristics inside them. Discovery is always the first step after establishing a BLE connection.

Discovering Services in Android

The following example shows how to list all available services and log them in Java.

@Override
public void onServicesDiscovered(BluetoothGatt gatt, int status) {
    for (BluetoothGattService service : gatt.getServices()) {
        Log.d(TAG, "Service discovered: " + service.getUuid().toString());
    }
}

This method is called automatically after the BLE client has finished discovering all services exposed by the remote GATT server. When a connection is established, the client initiates a service discovery procedure, and once the server responds with the complete list of available services, the Android stack triggers onServicesDiscovered.

Inside this callback, the code iterates through every BluetoothGattService returned by gatt.getServices(), which represents all services implemented by the connected device. For each service in that list, the code prints its UUID to the log. This output helps developers inspect what services exist on the device, confirm that expected services such as Heart Rate, Battery, or a custom service are present, and identify the correct UUIDs needed for reading or writing characteristics later.

This method is especially useful during development or debugging, because it allows you to verify that a device correctly exposes its GATT database and that the client can access the list of services before attempting to interact with any characteristics.

Notifications for Continuously Changing Data

Once the service is found, the next step is to read or subscribe to its characteristics. Some characteristics contain static or rarely changing values, which makes direct reads appropriate. Others, such as heart rate or temperature, change continuously, and should use notifications.

Why Notifications Matter in Services

Notifications allow a device to receive updates automatically whenever the value changes instead of repeatedly reading the characteristic. This reduces energy usage and latency, which is essential for wearables and sensors.

Below is a Java example showing how to enable notifications for the Heart Rate Measurement characteristic:

private void enableHeartRateNotifications(BluetoothGatt gatt) {

    UUID HEART_RATE_SERVICE_UUID =
            UUID.fromString("0000180D-0000-1000-8000-00805F9B34FB");
    UUID HEART_RATE_MEASUREMENT_UUID =
            UUID.fromString("00002A37-0000-1000-8000-00805F9B34FB");

    BluetoothGattService service = gatt.getService(HEART_RATE_SERVICE_UUID);
    if (service != null) {
        BluetoothGattCharacteristic characteristic =
                service.getCharacteristic(HEART_RATE_MEASUREMENT_UUID);

        if (characteristic != null) {
            gatt.setCharacteristicNotification(characteristic, true);

            BluetoothGattDescriptor descriptor =
                    characteristic.getDescriptor(
                            UUID.fromString("00002902-0000-1000-8000-00805F9B34FB")
                    );

            if (descriptor != null) {
                descriptor.setValue(BluetoothGattDescriptor.ENABLE_NOTIFICATION_VALUE);
                gatt.writeDescriptor(descriptor);
            }
        }
    }
}

Enabling Notifications in Android

This method enables notifications for the Heart Rate Measurement characteristic so that the device can push new values automatically whenever the heart rate changes.

It begins by defining the UUIDs for the Heart Rate Service and the Heart Rate Measurement characteristic. Using gatt.getService, it retrieves the Heart Rate Service from the connected device. If that service exists, it locates the Heart Rate Measurement characteristic within it. Once the characteristic is found, the method enables local notification handling on the Android side using setCharacteristicNotification, which prepares the client to receive asynchronous updates.

But enabling local notifications is not enough. The BLE specification requires writing to a special descriptor called the Client Characteristic Configuration Descriptor, identified by UUID 00002902-0000-1000-8000-00805F9B34FB, so that the remote device also knows the client wants updates. The method retrieves this descriptor, sets its value to ENABLE_NOTIFICATION_VALUE, and writes it using writeDescriptor, which sends a request over the air to the server telling it to start sending notifications.

After this sequence completes, updates begin arriving automatically in the onCharacteristicChanged callback whenever the heart rate changes, without needing repeated read requests.

This is the preferred BLE pattern for continuous sensor data such as heart rate, temperature, step count, or motion values because it saves power and provides real time responsiveness.

When the device begins sending notifications, updates are received in the callback below. The values arrive whenever they change, making this very efficient for streaming.

@Override
public void onCharacteristicChanged(BluetoothGatt gatt,
                                    BluetoothGattCharacteristic characteristic) {

    UUID HEART_RATE_MEASUREMENT_UUID =
            UUID.fromString("00002A37-0000-1000-8000-00805F9B34FB");

    if (characteristic.getUuid().equals(HEART_RATE_MEASUREMENT_UUID)) {
        int flag = characteristic.getProperties();
        int format;
        if ((flag & 0x01) != 0) {
            format = BluetoothGattCharacteristic.FORMAT_UINT16;
        } else {
            format = BluetoothGattCharacteristic.FORMAT_UINT8;
        }
        int heartRate = characteristic.getIntValue(format, 1);
        Log.d(TAG, "Heart Rate: " + heartRate + " bpm");
    }
}

This method is called automatically whenever the Bluetooth device sends a notification indicating that the value of a characteristic has changed.

In this example, the method handles updates to the Heart Rate Measurement characteristic. The code first checks whether the characteristic that triggered the callback matches the Heart Rate Measurement UUID 00002A37-0000-1000-8000-00805F9B34FB, ensuring that only relevant updates are processed.

The heart rate data can be encoded in either one or two bytes, depending on the flags defined in the characteristic properties. The method reads these flags and determines the correct format to use when decoding the heart rate value. If the least significant bit is set, the heart rate uses a 16 bit format. Otherwise, it uses a single 8 bit format.

After selecting the appropriate format, the method extracts the heart rate value using getIntValue, beginning at offset 1 because byte 0 contains the flags.

Finally, the value is printed to the log as beats per minute. This method is typically called repeatedly, such as once per second, so the log receives live heart rate updates in real time.

This approach demonstrates how notifications deliver continuous sensor data without repeatedly polling the device, which reduces latency and power usage for both the client and server.

This example demonstrates how the client retrieves real time sensor data using subscription instead of polling. The same mechanism is used for air quality sensors, smart home lighting brightness notifications, industrial temperature monitors, and more.

To summarize this section, a Service is a structured container that organizes related data and is essential for exposing abilities and functionality over BLE. Understanding how to discover and interact with services is the first major step toward building or debugging real Bluetooth applications.

What Are Characteristics and How Do They Work?

The Role of a Characteristic

If a Service is a folder, then a Characteristic is a file inside that folder that actually holds the content. In GATT, the Characteristic is where the real data lives. Almost everything your application cares about will eventually be read from, written to, or subscribed to on a characteristic.

The Four Parts of a Characteristic

A characteristic is more than just a single number. It has four important parts. First, it has a UUID that identifies what it represents. It also has a value that stores the actual bytes. Then it has properties that describe what operations are allowed, such as read, write, or notify. And finally, it has permissions that control who can access it and under what security level. Understanding these pieces is the key to working confidently with BLE.

The UUID tells you what kind of data is inside the characteristic. For example, a standard Battery Level characteristic uses the UUID 0x2A19 and always contains a single byte that represents a percentage from zero to one hundred. A Heart Rate Measurement characteristic uses UUID 0x2A37 and packs heart rate and flags into a structured format. Custom characteristics use 128 bit UUIDs that developers define themselves.

The value is simply a sequence of bytes. On the wire, Bluetooth does not know about integers, floats, or strings. It only sees bytes. On the Android side, the BluetoothGattCharacteristic class helps interpret those bytes as different types. It provides helper methods such as getIntValue, getFloatValue, and getStringValue so that you can decode the data more easily.

The properties of a characteristic describe what kind of operations the client can perform. The most common properties are Read, Write, Notify, and Indicate.

Read means a client can ask the server to return the current value. Write means a client can send a new value to the server. Notify means the server can send updates to the client whenever the value changes. Indicate is similar to Notify, but with an extra confirmation. A characteristic may have one or many properties combined.

Permissions are related but slightly different. They focus on access control and security. For example, a characteristic may require encryption or authenticated pairing before it can be read or written. The Android BluetoothGattCharacteristic object contains these permission flags so that the stack enforces them correctly.

Example: Defining a Custom LED Characteristic

Let’s walk through a concrete example. Imagine a custom device that exposes a characteristic to control an LED state. The LED should be either ON or OFF. The characteristic needs to support both read and write, because the client may want to read the current state and also change it.

On the Android GATT Server side, you would define such a characteristic like this:

UUID SERVICE_UUID =
        UUID.fromString("12345678-1234-5678-1234-56789abcdef0");
UUID LED_CHAR_UUID =
        UUID.fromString("abcdef01-1234-5678-1234-56789abcdef0");

BluetoothGattService ledService =
        new BluetoothGattService(SERVICE_UUID,
                BluetoothGattService.SERVICE_TYPE_PRIMARY);

BluetoothGattCharacteristic ledCharacteristic =
        new BluetoothGattCharacteristic(
                LED_CHAR_UUID,
                BluetoothGattCharacteristic.PROPERTY_READ |
                BluetoothGattCharacteristic.PROPERTY_WRITE,
                BluetoothGattCharacteristic.PERMISSION_READ |
                BluetoothGattCharacteristic.PERMISSION_WRITE
        );

// Initial value
ledCharacteristic.setValue("OFF".getBytes(StandardCharsets.UTF_8));
ledService.addCharacteristic(ledCharacteristic);
gattServer.addService(ledService);

This code defines a custom GATT Service and a custom GATT Characteristic on an Android device acting as a Bluetooth Low Energy GATT Server.

Two UUIDs are created using UUID.fromString, one representing the custom service and the other representing the characteristic that belongs to that service. A new BluetoothGattService instance is then created, marked as a primary service to indicate that it is a main functional component rather than a secondary helper service.

Inside that service, a BluetoothGattCharacteristic object is created using the second UUID, and it’s configured to allow both reads and writes by a remote BLE client. The property flags indicate that a client can request the current value and can also send updates, and the permission flags define that both operations are permitted.

The characteristic is given an initial value of the string "OFF" encoded as bytes, which might represent the current state of a remote controlled LED, device mode, or some other configuration setting.

The characteristic is then added to the service, and finally the fully defined service is added to the GATT server using gattServer.addService, making it visible to any BLE client that connects.

At this point, another device can read the value "OFF" or write a new value such as "ON", which the server could then use to trigger real behavior, such as toggling actual hardware.

Handling Reads and Writes on the Server

Server-Side Handlers

On the GATT Server side, you must also respond to read and write requests. This happens inside BluetoothGattServerCallback.

private final BluetoothGattServerCallback serverCallback =
        new BluetoothGattServerCallback() {

    @Override
    public void onCharacteristicReadRequest(BluetoothDevice device,
                                            int requestId,
                                            int offset,
                                            BluetoothGattCharacteristic characteristic) {

        byte[] currentValue = characteristic.getValue();
        gattServer.sendResponse(device,
                requestId,
                BluetoothGatt.GATT_SUCCESS,
                offset,
                currentValue);
    }

    @Override
    public void onCharacteristicWriteRequest(BluetoothDevice device,
                                             int requestId,
                                             BluetoothGattCharacteristic characteristic,
                                             boolean preparedWrite,
                                             boolean responseNeeded,
                                             int offset,
                                             byte[] value) {

        String received = new String(value, StandardCharsets.UTF_8);
        Log.d(TAG, "LED characteristic write: " + received);

        characteristic.setValue(value);

        if ("ON".equalsIgnoreCase(received)) {
            turnLedOn();
        } else if ("OFF".equalsIgnoreCase(received)) {
            turnLedOff();
        } else {
            Log.e(TAG, "Unhandled case!");
            return;
        }

        if (responseNeeded) {
            gattServer.sendResponse(device,
                    requestId,
                    BluetoothGatt.GATT_SUCCESS,
                    offset,
                    value);
        }
    }
};

This callback handles read and write requests coming from a remote BLE client interacting with the custom LED characteristic on the GATT Server.

When a client performs a read operation, onCharacteristicReadRequest is triggered. The method retrieves the current stored value from the characteristic using getValue() and returns it to the client by calling sendResponse with a success status. This means whatever value was last set, such as "ON" or "OFF", is sent back to the requesting device.

When a client performs a write operation, onCharacteristicWriteRequest is called. The method converts the incoming byte array into a string so that the server can interpret the command. It logs the received text, sets the new value into the characteristic using setValue, and then checks whether the string equals "ON" or "OFF". Depending on the value, it calls either turnLedOn() or turnLedOff(), which would typically control real hardware or trigger an action inside the application.

If the client requested a response, the server sends back a confirmation by calling sendResponse with GATT_SUCCESS, acknowledging that the write completed successfully. This callback demonstrates how interactive BLE control works: the server receives a command, updates internal state, performs a real action, and reports status back to the client.

Here, the server reads whatever value is stored in the characteristic upon a read request and sends it back to the client. When the client writes a new value, the server decodes the bytes as a string and updates internal state, including physical behavior like toggling the LED.

Reading and Writing from the Client

Client-Side Handlers

On the client side, a typical Android app needs to read and write to this same characteristic. The code for the client looks similar to what we saw in earlier sections, but now it uses the custom UUIDs.

Reading a Custom Characteristic (Client)

Reading the LED state from the client:

public void readLedState(BluetoothGatt gatt) {
    UUID SERVICE_UUID =
            UUID.fromString("12345678-1234-5678-1234-56789abcdef0");
    UUID LED_CHAR_UUID =
            UUID.fromString("abcdef01-1234-5678-1234-56789abcdef0");

    BluetoothGattService service = gatt.getService(SERVICE_UUID);
    if (service != null) {
        BluetoothGattCharacteristic ledChar = service.getCharacteristic(LED_CHAR_UUID);
        if (ledChar != null) {
            gatt.readCharacteristic(ledChar);
        }
    }
}

@Override
public void onCharacteristicRead(BluetoothGatt gatt,
                                 BluetoothGattCharacteristic characteristic,
                                 int status) {
    if (status == BluetoothGatt.GATT_SUCCESS) {
        UUID LED_CHAR_UUID =
                UUID.fromString("abcdef01-1234-5678-1234-56789abcdef0");
        if (LED_CHAR_UUID.equals(characteristic.getUuid())) {
            String value = new String(characteristic.getValue(), StandardCharsets.UTF_8);
            Log.d(TAG, "LED state is: " + value);
        }
    }
}

This code shows how a Bluetooth Low Energy client reads the current state of a custom LED characteristic from a GATT server. The readLedState method begins by defining the UUIDs for the custom service and the LED characteristic so that the client knows exactly where to look inside the server’s GATT database.

It retrieves the service using gatt.getService, and if the service exists, it retrieves the LED characteristic using getCharacteristic. If that characteristic is found, the client calls readCharacteristic, which sends a read request to the remote device over BLE. Once the server responds, the callback method onCharacteristicRead is triggered.

This method first checks that the read was successful by confirming that the status equals GATT_SUCCESS. It then verifies that the characteristic being read is indeed the LED characteristic by comparing UUIDs. If it matches, the code converts the characteristic’s byte array into a string, which contains either "ON" or "OFF", and logs the current state.

This flow demonstrates how a BLE client reads stored values from a peripheral device and responds when the server returns the data, forming the basis for real world interactions such as checking the status of a smart light, a switch, or any sensor value exposed through a custom characteristic.

Writing to a Custom Characteristic (Client)

Writing a new LED state from the client:

public void writeLedState(BluetoothGatt gatt, String newState) {
    UUID SERVICE_UUID =
            UUID.fromString("12345678-1234-5678-1234-56789abcdef0");
    UUID LED_CHAR_UUID =
            UUID.fromString("abcdef01-1234-5678-1234-56789abcdef0");

    BluetoothGattService service = gatt.getService(SERVICE_UUID);
    if (service != null) {
        BluetoothGattCharacteristic ledChar = service.getCharacteristic(LED_CHAR_UUID);
        if (ledChar != null) {
            ledChar.setValue(newState.getBytes(StandardCharsets.UTF_8));
            gatt.writeCharacteristic(ledChar);
        }
    }
}

@Override
public void onCharacteristicWrite(BluetoothGatt gatt,
                                  BluetoothGattCharacteristic characteristic,
                                  int status) {
    if (status == BluetoothGatt.GATT_SUCCESS) {
        Log.d(TAG, "LED state write completed");
    }
}

This code demonstrates how a Bluetooth Low Energy client sends a command to update the LED state on a GATT server device.

The writeLedState method begins by defining the UUIDs for the custom service and LED characteristic, then retrieves the service from the connected GATT server. If the service is found, it accesses the LED characteristic inside it.

Once the characteristic is obtained, the new LED state, which will typically be the string "ON" or "OFF", is converted into a byte array and placed into the characteristic with setValue. The method then calls writeCharacteristic, which sends a write request to the remote device to update the stored value.

When the server processes the write and returns a response, the callback method onCharacteristicWrite executes. If the status indicates success, the code logs that the write completed. At this point, the server code on the other side can take action based on the new state, such as turning a real LED on or off.

This flow illustrates how clients modify values on a BLE peripheral and how acknowledgment is handled once the operation finishes, forming a typical example of device control over GATT.

This combination of server definitions and client interactions shows how characteristics are the real workhorses of GATT. Every meaningful piece of data flows through them. Reads, writes, and notifications all operate at the characteristic level.

Notifications and CCCD

Notifications are simply a special property on a characteristic. When enabled, the server can push new values to the client without the client asking every time. To support notifications, a characteristic needs the Notify property and usually a descriptor called the Client Characteristic Configuration Descriptor, often referred to as CCCD, with UUID 0x2902.

On the server side, you would update the value and call notifyCharacteristicChanged. On the client side, you set characteristic notification to true and write the descriptor with ENABLE_NOTIFICATION_VALUE. The code pattern is almost identical regardless of the type of data, which makes it easy to reuse once you understand it.

By this point, you can see that a characteristic is not just a static field. It is a complete unit of behavior. It defines what data exists, how it is represented, who can access it, and how it updates. Once you’re comfortable designing characteristics and manipulating them in Java, you’re very close to mastering practical BLE development.

How to Design a GATT Profile for a Smart Plant Monitor

To make GATT feel real, let’s design a complete profile for a simple but realistic device: a smart plant monitor.

Imagine a small BLE sensor that you stick into a flower pot. It measures soil moisture, reports its own battery level, and allows you to configure how often it sends updates. A phone app connects to it, reads the current moisture level, shows the battery percentage, and lets the user adjust the reporting interval.

We’ll design both sides in terms of GATT. First, we’ll decide which services and characteristics we need. Then, we’ll see how an Android device can act as a client. For teaching purposes, we’ll also show how Android could act as the server, although in a real product the plant monitor would normally be an embedded device.

Designing the GATT Profile

We need three logical pieces of information:

1. Soil moisture percentage – this is dynamic sensor data.

2. Battery level – this is standard, so we can reuse the Battery Service.

3. Reporting interval configuration – this is a setting that the client writes and the device uses.

We can express this with one custom service plus the standard Battery Service.

Profile plan:

Custom Service: Plant Monitor Service
    UUID: 12345678-1234-5678-1234-56789abc0001

    Characteristic: Soil Moisture
        UUID: 12345678-1234-5678-1234-56789abc0002
        Properties: Read, Notify
        Permissions: Read
        Format: uint8 (0 to 100 percentage)

    Characteristic: Reporting Interval
        UUID: 12345678-1234-5678-1234-56789abc0003
        Properties: Read, Write
        Permissions: Read, Write
        Format: uint16 (seconds)

Standard Service: Battery Service
    UUID: 0000180F-0000-1000-8000-00805F9B34FB

    Characteristic: Battery Level
        UUID: 00002A19-0000-1000-8000-00805F9B34FB
        Properties: Read, Notify (optional)
        Permissions: Read
        Format: uint8 (0 to 100 percentage)

Now we know exactly what exists inside the device. A client can connect, look for the Plant Monitor Service and Battery Service, and then interact with these three characteristics.

Implementing the GATT Server

In a real hardware product, the plant monitor would be written in embedded C or C++. But for learning, we can simulate the server on Android itself. This’ll help you understand how the server side works.

First, we’ll create the services and characteristics.

public class PlantMonitorGattServer {

    private BluetoothGattServer gattServer;

    private final UUID PLANT_SERVICE_UUID =
            UUID.fromString("12345678-1234-5678-1234-56789abc0001");
    private final UUID MOISTURE_CHAR_UUID =
            UUID.fromString("12345678-1234-5678-1234-56789abc0002");
    private final UUID INTERVAL_CHAR_UUID =
            UUID.fromString("12345678-1234-5678-1234-56789abc0003");

    private final UUID BATTERY_SERVICE_UUID =
            UUID.fromString("0000180F-0000-1000-8000-00805F9B34FB");
    private final UUID BATTERY_LEVEL_UUID =
            UUID.fromString("00002A19-0000-1000-8000-00805F9B34FB");

    // Simulated state
    private int currentMoisture = 55;      // percentage
    private int reportingIntervalSec = 60; // seconds
    private int batteryLevel = 87;         // percentage

    private BluetoothGattCharacteristic moistureCharacteristic;
    private BluetoothGattCharacteristic intervalCharacteristic;
    private BluetoothGattCharacteristic batteryLevelCharacteristic;

This class represents a Bluetooth Low Energy GATT Server that pretends to be a smart plant monitor device. It holds a BluetoothGattServer instance that will expose services and characteristics to any BLE client that connects.

Several UUIDs are defined to identify the custom Plant Monitor Service and its characteristics, as well as the standard Battery Service and Battery Level characteristic.

The custom Plant Monitor Service has two characteristics: one for soil moisture and one for the reporting interval. The Battery Service uses the standard UUIDs defined by the Bluetooth SIG so that any client can recognize and parse it.

The class also keeps some simulated internal state: currentMoisture starts at 55 percent, reportingIntervalSec is set to 60 seconds, and batteryLevel is set to 87 percent. These values act like sensor readings and configuration stored inside the device.

Finally, it declares three BluetoothGattCharacteristic fields that will later point to the actual moisture, interval, and battery level characteristics once they are created and added to their respective services.

These fields make it easy for the server to update values and send notifications later – for example, when moisture changes or when the battery level drops.

Next, we’ll set up the server and define the services and characteristics.

    public void startServer(Context context) {
        BluetoothManager bluetoothManager =
                (BluetoothManager) context.getSystemService(Context.BLUETOOTH_SERVICE);

        gattServer = bluetoothManager.openGattServer(context, serverCallback);

        // Plant Monitor Service
        BluetoothGattService plantService =
                new BluetoothGattService(
                        PLANT_SERVICE_UUID,
                        BluetoothGattService.SERVICE_TYPE_PRIMARY
                );

        moistureCharacteristic = new BluetoothGattCharacteristic(
                MOISTURE_CHAR_UUID,
                BluetoothGattCharacteristic.PROPERTY_READ |
                BluetoothGattCharacteristic.PROPERTY_NOTIFY,
                BluetoothGattCharacteristic.PERMISSION_READ
        );

        intervalCharacteristic = new BluetoothGattCharacteristic(
                INTERVAL_CHAR_UUID,
                BluetoothGattCharacteristic.PROPERTY_READ |
                BluetoothGattCharacteristic.PROPERTY_WRITE,
                BluetoothGattCharacteristic.PERMISSION_READ |
                BluetoothGattCharacteristic.PERMISSION_WRITE
        );

        // Set initial values
        moistureCharacteristic.setValue(new byte[]{(byte) currentMoisture});
        intervalCharacteristic.setValue(intToTwoBytes(reportingIntervalSec));

        // For notifications, add CCCD descriptor
        BluetoothGattDescriptor moistureCccd = new BluetoothGattDescriptor(
                UUID.fromString("00002902-0000-1000-8000-00805F9B34FB"),
                BluetoothGattDescriptor.PERMISSION_READ |
                BluetoothGattDescriptor.PERMISSION_WRITE
        );
        moistureCharacteristic.addDescriptor(moistureCccd);

        plantService.addCharacteristic(moistureCharacteristic);
        plantService.addCharacteristic(intervalCharacteristic);

        // Battery Service
        BluetoothGattService batteryService =
                new BluetoothGattService(
                        BATTERY_SERVICE_UUID,
                        BluetoothGattService.SERVICE_TYPE_PRIMARY
                );

        batteryLevelCharacteristic = new BluetoothGattCharacteristic(
                BATTERY_LEVEL_UUID,
                BluetoothGattCharacteristic.PROPERTY_READ |
                BluetoothGattCharacteristic.PROPERTY_NOTIFY,
                BluetoothGattCharacteristic.PERMISSION_READ
        );

        batteryLevelCharacteristic.setValue(new byte[]{(byte) batteryLevel});

        BluetoothGattDescriptor batteryCccd = new BluetoothGattDescriptor(
                UUID.fromString("00002902-0000-1000-8000-00805F9B34FB"),
                BluetoothGattDescriptor.PERMISSION_READ |
                BluetoothGattDescriptor.PERMISSION_WRITE
        );
        batteryLevelCharacteristic.addDescriptor(batteryCccd);

        batteryService.addCharacteristic(batteryLevelCharacteristic);

        gattServer.addService(plantService);
        gattServer.addService(batteryService);
    }

    private byte[] intToTwoBytes(int value) {
        byte[] data = new byte[2];
        data[0] = (byte) (value & 0xFF);
        data[1] = (byte) ((value >> 8) & 0xFF);
        return data;
    }

This method starts the Bluetooth Low Energy GATT server and builds the full GATT database for the smart plant monitor.

It first obtains the BluetoothManager from the Android system and uses it to open a BluetoothGattServer, passing in a callback that will handle read, write, and notification events from connected clients.

Then it creates the custom Plant Monitor Service using the PLANT_SERVICE_UUID and marks it as a primary service.

Inside this service it defines two characteristics. The moisture characteristic is created with the MOISTURE_CHAR_UUID and given the properties Read and Notify, meaning a client can read the current soil moisture and also subscribe to notifications when it changes. It is read only, so it uses a read permission. The reporting interval characteristic is created with the INTERVAL_CHAR_UUID and uses both Read and Write properties so that a client can check the current interval and update it. It uses both read and write permissions.

The code sets the initial values for these characteristics: the moisture characteristic gets the current moisture percentage stored as a single byte, and the interval characteristic gets a two byte representation of the reporting interval using the helper method intToTwoBytes, which splits a 16 bit integer into low and high bytes.

To allow notifications for moisture, it adds a Client Characteristic Configuration Descriptor (CCCD) with a standard UUID 0x2902 and read or write permissions, then attaches this descriptor to the moisture characteristic. Both characteristics are added to the plant service.

Next, the method creates the standard Battery Service as another primary service using the well-known battery UUID. It defines the Battery Level characteristic with read and notify properties and read permission.

The initial battery level is stored as a single byte. Just like with moisture, it adds a CCCD descriptor to support notifications and attaches it to the battery characteristic. The battery characteristic is then added to the battery service.

Finally, the method registers both the plant service and the battery service with the GATT server using addService, which makes them visible to any BLE client that connects. As a small utility, the intToTwoBytes method at the end converts a 16 bit integer into a two element byte array with the least significant byte first, which is a common way to encode integers in BLE characteristics.

Now we’ll implement the callback to handle read, write, and notification logic.

    private final BluetoothGattServerCallback serverCallback =
            new BluetoothGattServerCallback() {

        @Override
        public void onConnectionStateChange(BluetoothDevice device,
                                            int status,
                                            int newState) {
            Log.d(TAG, "Device connection state: " + newState);
        }

        @Override
        public void onCharacteristicReadRequest(BluetoothDevice device,
                                                int requestId,
                                                int offset,
                                                BluetoothGattCharacteristic characteristic) {

            if (characteristic.getUuid().equals(MOISTURE_CHAR_UUID)) {
                moistureCharacteristic.setValue(new byte[]{(byte) currentMoisture});
                gattServer.sendResponse(device, requestId,
                        BluetoothGatt.GATT_SUCCESS, offset,
                        moistureCharacteristic.getValue());
            } else if (characteristic.getUuid().equals(INTERVAL_CHAR_UUID)) {
                intervalCharacteristic.setValue(intToTwoBytes(reportingIntervalSec));
                gattServer.sendResponse(device, requestId,
                        BluetoothGatt.GATT_SUCCESS, offset,
                        intervalCharacteristic.getValue());
            } else if (characteristic.getUuid().equals(BATTERY_LEVEL_UUID)) {
                batteryLevelCharacteristic.setValue(new byte[]{(byte) batteryLevel});
                gattServer.sendResponse(device, requestId,
                        BluetoothGatt.GATT_SUCCESS, offset,
                        batteryLevelCharacteristic.getValue());
            } else {
                gattServer.sendResponse(device, requestId,
                        BluetoothGatt.GATT_FAILURE, offset, null);
            }
        }

        @Override
        public void onCharacteristicWriteRequest(BluetoothDevice device,
                                                 int requestId,
                                                 BluetoothGattCharacteristic characteristic,
                                                 boolean preparedWrite,
                                                 boolean responseNeeded,
                                                 int offset,
                                                 byte[] value) {

            if (characteristic.getUuid().equals(INTERVAL_CHAR_UUID)) {
                int newInterval = ((value[1] & 0xFF) << 8) | (value[0] & 0xFF);
                reportingIntervalSec = newInterval;
                Log.d(TAG, "New reporting interval: " + reportingIntervalSec + " sec");

                intervalCharacteristic.setValue(value);
            }

            if (responseNeeded) {
                gattServer.sendResponse(device, requestId,
                        BluetoothGatt.GATT_SUCCESS, offset, value);
            }
        }

        @Override
        public void onDescriptorWriteRequest(BluetoothDevice device,
                                             int requestId,
                                             BluetoothGattDescriptor descriptor,
                                             boolean preparedWrite,
                                             boolean responseNeeded,
                                             int offset,
                                             byte[] value) {

            if (descriptor.getCharacteristic().getUuid().equals(MOISTURE_CHAR_UUID)) {
                Log.d(TAG, "Moisture notifications enabled");
            } else if (descriptor.getCharacteristic().getUuid().equals(BATTERY_LEVEL_UUID)) {
                Log.d(TAG, "Battery notifications enabled");
            }

            if (responseNeeded) {
                gattServer.sendResponse(device, requestId,
                        BluetoothGatt.GATT_SUCCESS, offset, value);
            }
        }
    };
}

This callback handles all the important server side events for the smart plant monitor GATT Server, including connection changes, characteristic reads and writes, and descriptor writes for notifications.

When a device connects or disconnects, onConnectionStateChange is called and simply logs the new connection state so you can see when a client appears or disappears. The core logic lives in onCharacteristicReadRequest, which is invoked whenever a BLE client performs a read on one of the server’s characteristics.

The method checks which characteristic is being read by comparing its UUID. If it’s the moisture characteristic, it refreshes the characteristic value with the current moisture percentage, then responds with GATT_SUCCESS and the encoded value. If it’s the interval characteristic, it encodes the current reporting interval into two bytes using intToTwoBytes and sends that back. If it’s the battery level characteristic, it encodes the current battery percentage into a single byte and returns it. If the UUID does not match any known characteristic, the server responds with GATT_FAILURE, which tells the client that the request could not be fulfilled.

The onCharacteristicWriteRequest method handles writes from the client. In this implementation, only the reporting interval characteristic is writable. When a write targets this characteristic, the code decodes the two byte value sent by the client into an integer by reconstructing it from the low and high bytes. It updates the internal reportingIntervalSec field, logs the new interval, and stores the received bytes in the characteristic so that future reads return the updated value. If the client requested a response, the server sends back a success status and echoes the written value.

Finally, onDescriptorWriteRequest is called when a client writes to a descriptor, typically the Client Characteristic Configuration Descriptor that controls notifications. The code checks whether the descriptor belongs to the moisture or battery characteristic and logs that notifications have been enabled for the corresponding data source. If a response is needed, it sends back GATT_SUCCESS.

Altogether, this callback turns the server into a live plant monitor that can answer real time read requests, accept configuration updates, and honor notification subscriptions for moisture and battery level.

We now have a fully functioning GATT Server that supports read and write operations, and can also send notifications for moisture and battery when needed.

To simulate notifications, the server can periodically update values and call notifyCharacteristicChanged:

public void simulateSensorUpdate(BluetoothDevice device) {
    // Simulate moisture dropping slightly
    currentMoisture = Math.max(0, currentMoisture - 1);
    moistureCharacteristic.setValue(new byte[]{(byte) currentMoisture});
    gattServer.notifyCharacteristicChanged(device, moistureCharacteristic, false);
}

This method simulates a live update to the soil moisture sensor and demonstrates how a GATT Server sends notifications to a connected BLE client.

It decreases the current moisture reading by one percent, ensuring the value never falls below zero using Math.max. After adjusting the simulated value, the method stores the updated moisture value inside the moisture characteristic using setValue, which prepares the new data to be transmitted.

It then calls notifyCharacteristicChanged, which sends a BLE notification packet to the specified connected device, telling the client that the characteristic value has changed and delivering the new moisture reading immediately.

The final parameter false indicates that this is a notification rather than an indication, which means the server does not require an acknowledgment from the client. This method would typically be called on a timer or triggered by real sensor hardware, allowing the client application to receive continuous updates in real time without repeatedly polling the server.

Implementing the GATT Client in Java

On the Android client side, we connect to the plant monitor, discover services, then interact with the three characteristics.

First, we’ll discover the services and store references.

public class PlantMonitorClient {

    private BluetoothGatt bluetoothGatt;

    private final UUID PLANT_SERVICE_UUID =
            UUID.fromString("12345678-1234-5678-1234-56789abc0001");
    private final UUID MOISTURE_CHAR_UUID =
            UUID.fromString("12345678-1234-5678-1234-56789abc0002");
    private final UUID INTERVAL_CHAR_UUID =
            UUID.fromString("12345678-1234-5678-1234-56789abc0003");

    private final UUID BATTERY_SERVICE_UUID =
            UUID.fromString("0000180F-0000-1000-8000-00805F9B34FB");
    private final UUID BATTERY_LEVEL_UUID =
            UUID.fromString("00002A19-0000-1000-8000-00805F9B34FB");

    public void connect(Context context, BluetoothDevice device) {
        bluetoothGatt = device.connectGatt(context, false, gattCallback);
    }

    private final BluetoothGattCallback gattCallback = new BluetoothGattCallback() {

        @Override
        public void onConnectionStateChange(BluetoothGatt gatt,
                                            int status,
                                            int newState) {
            if (newState == BluetoothProfile.STATE_CONNECTED) {
                Log.d(TAG, "Connected. Discovering services.");
                gatt.discoverServices();
            }
        }

        @Override
        public void onServicesDiscovered(BluetoothGatt gatt, int status) {
            Log.d(TAG, "Services discovered.");

            // Read current moisture and battery once
            readMoisture(gatt);
            readBatteryLevel(gatt);

            // Enable notifications
            enableMoistureNotifications(gatt);
        }

This class represents the Bluetooth Low Energy client side of the smart plant monitor example. It holds a BluetoothGatt reference that represents the active connection to the BLE server device.

Several UUID constants are defined so the client knows how to find the Plant Monitor Service and its characteristics for moisture and reporting interval, as well as the standard Battery Service and Battery Level characteristic.

The connect method starts the BLE connection by calling device.connectGatt, passing in the Android Context, a flag indicating no automatic reconnection, and a BluetoothGattCallback instance that will receive connection and data events.

Inside the callback, onConnectionStateChange is called whenever the connection state changes. When the new state indicates that the device is connected, the client logs this and calls discoverServices to request the full list of GATT services from the server.

Once the service discovery procedure completes, onServicesDiscovered is triggered. In this method, the client logs that services have been discovered, then immediately reads the current values of the moisture and battery level using helper methods readMoisture and readBatteryLevel, and finally enables notifications for moisture updates using enableMoistureNotifications.

Together, these steps mean that as soon as the client connects to a plant monitor device, it learns what services are available, fetches one time snapshots of important values, and subscribes to real time updates for the most important sensor – which in this case is soil moisture.

Now, we’ll define methods for reading moisture and battery.

        private void readMoisture(BluetoothGatt gatt) {
            BluetoothGattService service = gatt.getService(PLANT_SERVICE_UUID);
            if (service != null) {
                BluetoothGattCharacteristic ch =
                        service.getCharacteristic(MOISTURE_CHAR_UUID);
                if (ch != null) {
                    gatt.readCharacteristic(ch);
                }
            }
        }

        private void readBatteryLevel(BluetoothGatt gatt) {
            BluetoothGattService service = gatt.getService(BATTERY_SERVICE_UUID);
            if (service != null) {
                BluetoothGattCharacteristic ch =
                        service.getCharacteristic(BATTERY_LEVEL_UUID);
                if (ch != null) {
                    gatt.readCharacteristic(ch);
                }
            }
        }

        @Override
        public void onCharacteristicRead(BluetoothGatt gatt,
                                         BluetoothGattCharacteristic characteristic,
                                         int status) {
            if (status == BluetoothGatt.GATT_SUCCESS) {
                if (MOISTURE_CHAR_UUID.equals(characteristic.getUuid())) {
                    int moisture = characteristic.getIntValue(
                            BluetoothGattCharacteristic.FORMAT_UINT8, 0);
                    Log.d(TAG, "Soil moisture: " + moisture + " percent");
                } else if (BATTERY_LEVEL_UUID.equals(characteristic.getUuid())) {
                    int battery = characteristic.getIntValue(
                            BluetoothGattCharacteristic.FORMAT_UINT8, 0);
                    Log.d(TAG, "Battery level: " + battery + " percent");
                } else if (INTERVAL_CHAR_UUID.equals(characteristic.getUuid())) {
                    int interval = characteristic.getIntValue(
                            BluetoothGattCharacteristic.FORMAT_UINT16, 0);
                    Log.d(TAG, "Reporting interval: " + interval + " sec");
                }
            }
        }

These methods handle reading values from the smart plant monitor GATT Server. The readMoisture method retrieves the Plant Monitor Service using its UUID, then looks up the soil moisture characteristic inside it. If the characteristic is found, it sends a read request using gatt.readCharacteristic, which asks the server to return the current moisture value.

The readBatteryLevel method behaves the same way but targets the standard Battery Service and Battery Level characteristic. When the server responds to either read request, the callback onCharacteristicRead is triggered. The method first checks whether the read was successful by confirming that the status equals GATT_SUCCESS. It then determines which characteristic was read by comparing UUIDs.

If the response is for the moisture characteristic, it decodes the value from a single byte into an integer percentage and logs it. If it is the battery characteristic, it similarly extracts the single byte battery percentage and logs that value. If the interval characteristic was read, it decodes two bytes into a 16 bit integer and logs the reporting interval in seconds.

This read flow provides the client with a snapshot of the current sensor and configuration values immediately after connecting, before monitoring changes through notifications.

Next, we’ll enable notifications for moisture so that the app receives updates when it changes.

        private void enableMoistureNotifications(BluetoothGatt gatt) {
            BluetoothGattService service = gatt.getService(PLANT_SERVICE_UUID);
            if (service != null) {
                BluetoothGattCharacteristic ch =
                        service.getCharacteristic(MOISTURE_CHAR_UUID);
                if (ch != null) {
                    gatt.setCharacteristicNotification(ch, true);

                    BluetoothGattDescriptor descriptor =
                            ch.getDescriptor(UUID.fromString(
                                    "00002902-0000-1000-8000-00805F9B34FB"));

                    if (descriptor != null) {
                        descriptor.setValue(
                                BluetoothGattDescriptor.ENABLE_NOTIFICATION_VALUE);
                        gatt.writeDescriptor(descriptor);
                    }
                }
            }
        }

        @Override
        public void onCharacteristicChanged(BluetoothGatt gatt,
                                            BluetoothGattCharacteristic characteristic) {
            if (MOISTURE_CHAR_UUID.equals(characteristic.getUuid())) {
                int moisture = characteristic.getIntValue(
                        BluetoothGattCharacteristic.FORMAT_UINT8, 0);
                Log.d(TAG,
                        "Soil moisture update: " + moisture + " percent");
            }
        }
    };

This code enables live moisture updates through notifications and handles them when they arrive.

The enableMoistureNotifications method first retrieves the Plant Monitor Service, then obtains the moisture characteristic using its UUID. If the characteristic is available, it calls setCharacteristicNotification with true, which tells the Android BLE stack to start listening for notifications on that characteristic.

But enabling notification support locally is not enough because the GATT specification requires that the client also write to the associated descriptor known as the Client Characteristic Configuration Descriptor, or CCCD, identified by the standard UUID 0x2902. The method retrieves this descriptor, sets its value to ENABLE_NOTIFICATION_VALUE, and writes it using writeDescriptor, which sends a request over the air to the server to enable notifications on the device side. Once this configuration is complete, updates are delivered whenever the characteristic value changes.

The onCharacteristicChanged callback is triggered automatically each time the server pushes a new moisture reading. The method checks that the changed characteristic is the moisture characteristic by comparing UUIDs, extracts the soil moisture percentage from a single byte using getIntValue, and logs the updated value. This allows the client app to receive real time sensor readings without constantly polling the server, which saves energy and improves responsiveness for applications such as plant monitoring dashboards or notification alerts.

Finally, the client can write a new reporting interval, for example changing from 60 seconds to 30 seconds.

    public void writeReportingInterval(int newIntervalSec) {
        if (bluetoothGatt == null) return;

        BluetoothGattService service =
                bluetoothGatt.getService(PLANT_SERVICE_UUID);
        if (service != null) {
            BluetoothGattCharacteristic ch =
                    service.getCharacteristic(INTERVAL_CHAR_UUID);
            if (ch != null) {
                byte[] data = new byte[2];
                data[0] = (byte) (newIntervalSec & 0xFF);
                data[1] = (byte) ((newIntervalSec >> 8) & 0xFF);
                ch.setValue(data);
                bluetoothGatt.writeCharacteristic(ch);
            }
        }
    }
}

This method allows the BLE client to update the reporting interval setting on the smart plant monitor by writing a new value to the interval characteristic on the GATT Server.

It first checks whether the bluetoothGatt object is valid, since no write can occur before a connection is established. It retrieves the Plant Monitor Service using its UUID and then looks up the reporting interval characteristic inside that service.

If the characteristic exists, the method converts the new interval value from an integer into a two byte array, placing the least significant byte first and the most significant byte second, which is the common little endian format used in Bluetooth characteristics. It sets this byte array as the characteristic’s new value and then calls writeCharacteristic, which sends a write request over the air to the server. When the server processes the command in its corresponding write request handler, it will update its internal interval value and acknowledge the change.

This method demonstrates how configuration settings are written from a BLE client to a BLE device, enabling interactive control of behavior instead of only reading sensor values.

With this design, our smart plant monitor system is complete. The GATT Server exposes well-defined services and characteristics. The Android client connects, discovers, reads, writes, and subscribes to notifications. The concept is always the same: services group features. Characteristics hold data and behavior. Clients manipulate characteristics. Servers store and protect them.

Once you can design and code such a profile end to end, you are effectively using GATT the way real products do. The same pattern scales to complex devices like glucose monitors, smart locks, smart glasses, and industrial sensors.

Conclusion

GATT is the foundation that makes Bluetooth Low Energy communication understandable and reliable. It transforms raw radio signals into meaningful structured information through the use of services and characteristics. Once you understand that every BLE device exposes a database of values that a client can read, write, or subscribe to, the entire system becomes logical instead of mysterious.

Whether you are reading heart rate from a smartwatch, checking the battery level of wireless earbuds, controlling a smart bulb, or configuring an industrial sensor, the interaction always happens through GATT characteristics inside services.

By examining both sides of the communication, the GATT Server and the GATT Client, and by walking through real Java code examples for reading, writing, and receiving notifications, you now have the practical knowledge needed to build and debug real BLE applications. You saw how to define custom services and characteristics, how to interpret data formats, how to enable notifications for dynamic sensor updates, and how to organize a complete device profile using a realistic example in the plant monitor project.

Everything in Bluetooth Low Energy development begins with understanding GATT at this level. Once you are comfortable designing and interacting with services and characteristics, you can confidently move into more advanced topics such as secure pairing and bonding, throughput tuning using MTU and connection interval, power optimization, OTA firmware updates, and tools like nRF Connect and HCI log analysis.

The best way to strengthen what you learned is to build something hands on. Even a simple read and write test project will help the concepts become intuitive.

Mastering GATT is the first major step toward professional Bluetooth development. Every complex system built with BLE, from consumer wearables to medical devices and smart home automation, sits on top of this technology. Now that you understand the structure and communication model, you are ready to explore more sophisticated capabilities and create your own applications with confidence.

You probably don’t even think about Bluetooth anymore. It’s just there, quietly doing its job every single day. It’s what keeps your earbuds connected, your smartwatch synced, your car infotainment system talking to your phone, and your warehouse sensors awake and reporting.

The funny thing is, while most of us stopped paying attention, Bluetooth never stopped evolving. It just kept getting smarter.

Now it’s 2025, and Bluetooth has grown into something much bigger than a way to stream music. It has become a core ecosystem that connects nearly everything around us. From audio gear and IoT sensors to industrial automation and secure building access, Bluetooth is everywhere.

The newest versions, Bluetooth 5.4 and 6.0, completely redefine how devices talk to each other. We’re talking about encrypted broadcasts, smarter advertising, centimeter-level distance tracking, and a level of scalability that feels closer to magic than engineering.

In this article, we’ll take a tour through the newest Bluetooth technologies and see what’s happening under the hood. You’ll get a feel for what’s new, how these features work in real projects, and how developers can actually take advantage of them.

Grab your favorite dev board, and let’s dive in.

Table of Contents

1. The Evolution: From Classic to Low Energy to 6.0

2. Deep Dive: Technical Enhancements

3. Real-World Applications in 2025

4. Developer Guide: Getting Started

5. Challenges and Trade-Offs

6. The Road Ahead: Bluetooth 6.1 and Beyond

7. Conclusion

The Evolution — From Classic to Low Energy to 6.0

If you’ve been around Bluetooth for a while, you probably remember the early days when pairing a headset felt like solving a riddle. Back then, Bluetooth Classic ruled the scene, focused mainly on short-range audio and simple data links. Over the years, though, the story changed completely.

Today, Bluetooth has transformed from a simple cable-replacement protocol into a flexible framework for everything from earbuds to industrial robots. Each new version added fresh layers of intelligence, speed, and energy efficiency. The table below gives a quick timeline of how that evolution unfolded.

The journey tells a bigger story. What started as a way to connect two devices for audio has turned into a foundation for massive IoT networks. Each revision introduced smarter physical layers, better energy profiles, and new roles for devices that once had very limited capability.

Source: MDPI Sensors (2025), Bluetooth Core Specification Summary.

Above figure provides a visual snapshot of how Bluetooth has evolved across its major versions. It shows a clear chronological progression of features—from the launch of Bluetooth Low Energy (BLE) in version 4.0, to the introduction of secure connections, long-range PHYs, and direction-finding capabilities, all the way up to the latest breakthroughs like Channel Sounding and decision-based filtering in Bluetooth 6.0. The color-coded timeline highlights how each version refined both the physical and logical layers of communication, gradually expanding Bluetooth’s reach from simple peripherals to high-precision industrial and spatial applications. In essence, it maps Bluetooth’s transformation from a short-range wireless cable into a sophisticated, context-aware connectivity fabric that underpins modern audio, IoT, and automation ecosystems.

If you zoom out a bit, you’ll notice a clear pattern: Bluetooth keeps finding new neighborhoods to move into. From cars and headphones to factories and hospitals, the technology now feels less like a cable replacement and more like an invisible nervous system for the modern world.

What’s New in Bluetooth 5.4 and 6.0

When you hear that Bluetooth has a “new version,” it’s easy to shrug it off. After all, your headphones already work, right? But the jump from 5.3 to 5.4 and then 6.0 isn’t just a tiny step. It’s more like Bluetooth quietly taking on Wi-Fi’s job in certain places and pulling it off surprisingly well.

Let’s break it down by version so it’s easier to see what’s going on.

Bluetooth 5.4: Building the IoT Backbone

This release might not have made flashy headlines, but engineers loved it. It focuses on letting thousands of low-power devices talk to a single gateway without choking the airwaves.

Let’s look at some of the key features and why they matter:

Periodic Advertising with Responses (PAwR)

Think of it as Bluetooth’s group chat for sensors. Devices can broadcast messages and still get short replies, all without the full connection setup that usually drains batteries. It’s perfect for large sensor networks like smart warehouses or retail stores with electronic shelf labels.

Source: Nordic Semiconductor Developer Zone (2024)

Above diagram illustrates the timing structure of Bluetooth 5.4’s Periodic Advertising with Responses (PAwR) mechanism. Along the horizontal axis, it shows a repeating sequence of PAwR events separated by the overall periodic advertising interval. Within each PAwR event are several subevents—labeled #0, #1, #2, #3, and so on—each representing a defined window of time during which specific sensors or devices are allowed to communicate. The figure highlights that every subevent occurs at a fixed periodic advertising subevent interval, meaning devices can wake up only during their assigned slot, transmit or receive data, and then return to sleep. This predictable scheduling dramatically reduces radio collisions and power consumption, allowing a single gateway to coordinate thousands of low-power nodes such as electronic shelf labels or environmental sensors within a shared advertising cycle.

Encrypted Advertising Data

Broadcasts used to be open for anyone to sniff. Now they can be private and secure, which is essential for medical monitors and retail beacons carrying sensitive info.

Source: Raytac Technology (2024)

Above diagram breaks down the structure of the Encrypted Data Advertising Data (AD) type introduced in Bluetooth 5.4. It visually shows how encrypted advertising payloads are organized within a broadcast packet. At the top, the full advertising payload is represented, which includes the length (Len), Encrypted Data (ED Tag), and flags. Inside the encrypted section, the fields are expanded to show the Randomizer, Payload, and Message Integrity Check (MIC). The payload itself may contain various elements such as the Electronic Shelf Label (ESL) Tag, ESL Payload, Local Name (LN Tag), or other advertising segments. The color-coding differentiates which parts are encrypted (blue) versus unencrypted (gray or yellow), highlighting how Bluetooth 5.4 secures sensitive data while retaining key advertising identifiers for discovery. This layout helps engineers understand where encryption is applied within the advertising packet and how privacy and integrity are preserved during broadcast communication.

Electronic Shelf Labels (ESL) Support

Bluetooth 5.4 was practically written with supermarkets in mind. Imagine thousands of digital price tags blinking updates at once, all running for months on coin-cell batteries.

Source: Dani Data Systems (2023)

Above image illustrates the working architecture of a Bluetooth-based Electronic Shelf Label (ESL) system. On the left, a computer running ESL management software is shown, which allows retail staff to configure product data, prices, and display templates. The software communicates over a TCP/IP network connection with a Base Station positioned in the center of the diagram. This base station acts as a Bluetooth gateway, wirelessly transmitting the updated price and product information to numerous shelf labels throughout the store. On the right, a digital ESL display is shown featuring a price tag for a product labeled “Kaju Katali,” complete with product details, QR codes for mobile payments, and expiry dates. The blue wireless icon between the base station and ESL tag symbolizes Bluetooth communication. Together, the components demonstrate how Bluetooth 5.4 enables synchronized, low-power, and remotely managed price updates across thousands of retail shelf labels.

In short, 5.4 was the version that said, “Sure, we can handle massive IoT networks.”

Bluetooth 6.0: The Game Changer

Bluetooth 6.0 feels like the point where the technology matured from “just wireless” into “smart wireless.” This version brings features that start blurring the line between Bluetooth and more advanced location systems.

Channel Sounding

This is a big one. Instead of using signal strength (which can be messy), Bluetooth 6.0 measures phase differences in radio waves to calculate distance. That means centimeter-level accuracy (enough for digital keys), precise tracking, and even AR interactions.

Source: Bluetooth SIG (2025)

Above image explains the concept of Bluetooth Channel Sounding, a new feature introduced in Bluetooth 6.0 that enables precise distance measurement between devices. The top half of the diagram compares three levels of spatial awareness—presence detection through advertising, coarse distance estimation using RSSI (Received Signal Strength Indicator), and fine-grained ranging achieved with Channel Sounding. It also shows how Direction Finding complements these methods by determining angular orientation. On the left, a smartphone (the initiator) communicates with a smart lock (the reflector), demonstrating how Bluetooth can estimate distance and direction simultaneously. The bottom portion visualizes two measurement techniques. The Phase-Based Ranging chart shows how two signals of different frequencies experience measurable phase shifts that correspond to distance. The Round Trip Time (RTT) diagram on the right depicts packets traveling between the initiator and reflector, with the elapsed time between transmission and reception used to calculate distance. Together, these visuals illustrate how Bluetooth 6.0 achieves centimeter-level accuracy for applications like digital keys, indoor navigation, and spatially aware IoT systems.

Decision-Based Advertising Filtering

Bluetooth devices now decide which advertisements to process and which to ignore, saving both power and bandwidth. It’s like teaching scanners to pay attention only when it’s worth it.

Source: Bluetooth SIG (2024)

Above diagram illustrates the architecture of Decision-Based Advertising Filtering, a new Bluetooth 6.0 feature that allows observers to process only relevant broadcast packets, reducing power consumption and unnecessary data handling. The figure depicts two parallel host–controller stacks: the Observer on the left and the Advertiser on the right. Each side includes an Application layer, Host Controller Interface (HCI), and Controller. On the advertiser side, the application generates Decision Data that passes through the HCI to the controller’s advertising engine, where it’s embedded into extended advertising packets known as Decision PDUs. On the observer side, incoming advertising data passes through a Filter Policy module in the controller, which selects or rejects packets according to preconfigured decision criteria before forwarding only the relevant Advertising Reports to the host application. Blue arrows show configuration and report flows, while the yellow HCI bands highlight the host–controller boundary. Together, the components show how Bluetooth 6.0 empowers devices to make intelligent, context-aware filtering decisions at the controller level, improving efficiency in dense radio environments.

Advertiser Monitoring

Gateways can now keep tabs on the state of nearby advertisers, which is critical when hundreds of devices are broadcasting at once.

Source: Bluetooth SIG (2024)

Above image depicts the fundamental interaction between two Bluetooth Low Energy (BLE) device roles — advertising and scanning. On the left, a smartphone icon represents the scanning device, which actively listens for nearby Bluetooth broadcasts. On the right, a small sensor or tag icon represents the advertising device, periodically transmitting packets that announce its presence, capabilities, or data updates. Blue concentric rings radiate outward from both devices, symbolizing the propagation of radio signals and the overlapping wireless coverage area where scanning and advertising events intersect. The minimalist design highlights the asymmetric nature of BLE communication: the advertiser periodically transmits small bursts of information, while the scanner remains receptive to detect, filter, or connect with those broadcasts — forming the foundation of all Bluetooth discovery, pairing, and data exchange processes.

Negotiable Inter-Frame Spacing

This lets devices adjust timing between packets to improve throughput and avoid interference in noisy environments.

Source: Bluetooth SIG (2024)

Above image illustrates the concept of Negotiable Inter-Frame Spacing (IFS) in Bluetooth 6.0, which optimizes the timing between consecutive data packets to improve throughput and reduce interference. The diagram shows two sequences of communication between a Central (C) and a Peripheral (P) device, represented as alternating blue (C→P) and green (P→C) data blocks. In the first sequence, packets are transmitted with a short, fixed inter-frame spacing labeled T_IFS, showing a rapid exchange of packets within a connection event. The second sequence demonstrates the enhanced Bluetooth 6.0 model, where devices can dynamically negotiate a longer spacing interval — indicated by the notation “≥ T_IFS” — to accommodate environmental conditions, controller processing delays, or congestion. The red horizontal arrows mark the overall connection event duration, while the vertical lines represent packet boundaries. By allowing flexible timing adjustments between frames, Bluetooth 6.0 reduces airtime collisions and improves coexistence with other 2.4 GHz systems, particularly in dense or interference-prone environments.

ISOAL Enhancements

Audio data, especially LE Audio streams, now move more smoothly thanks to improved support for large frames.

Source: Bluetooth SIG (2024)

Above diagram illustrates the internal data flow and timing structure of the Isochronous Adaptation Layer (ISOAL) in Bluetooth 5.2 and later, which supports synchronized audio and data transmission over LE Isochronous Channels. The figure is divided into three main sections: the Upper Layer, the ISOAL, and the Link Layer. At the top, the Upper Layer handles isochronous data in the form of Service Data Units (SDUs). Within the ISOAL layer, SDUs undergo several key processes — Fragmentation and Segmentation break data into smaller protocol units, while Recombination and Reassembly merge received fragments back into complete SDUs. Two important timing-related steps occur in parallel: the Inclusion of Timing Offsets, which ensures proper packet scheduling, and Timing Reconstruction, which synchronizes the playback or reassembly timing for received streams. These operations produce either Framed or Unframed Protocol Data Units (PDUs), which are then passed to the Link Layer at the bottom for transmission over the Isochronous Stream. The diagram highlights how ISOAL bridges the upper and lower layers, managing timing alignment and packet structure to deliver low-latency, synchronized LE Audio or data streams across multiple devices.

When you put all that together, Bluetooth 6.0 starts looking a lot like Ultra-Wideband in terms of precision, but without needing new hardware. It’s faster, smarter, and somehow more polite on the airwaves.

Deep Dive — Technical Enhancements

This is where Bluetooth starts to feel less like “a thing your phone just does” and more like a finely tuned machine. The new specs add layers of intelligence that make devices more aware of distance, timing, and context. It’s the kind of stuff that gets engineers grinning because it solves problems we’ve all quietly complained about for years.

Let’s walk through a few of the most important ones.

Channel Sounding and Distance Awareness

If you’ve ever used RSSI values to guess how far a device is, you know how unpredictable it can be. RSSI measures how strong the signal sounds, not where it actually came from. A wall, a metal shelf, even a human body can distort it. Channel Sounding solves this by looking at phase instead of strength.

Here’s the idea: two devices exchange carefully crafted packets at multiple frequencies. Each frequency behaves like a different musical note. When those notes reach the receiver, their phases – how the peaks and troughs line up – shift slightly depending on distance. The receiver compares the original and received phases, then crunches the math:

$$[ \text{Distance} = \frac{c \times \Delta \phi}{2\pi f} ]$$

where:

• ( c ) is the speed of light,

• ( \Delta \phi ) is the phase shift,

• ( f ) is the carrier frequency.

This approach allows for precise distance measurement, achieving accuracy down to a few centimeters by analyzing the phase differences of signals received at multiple frequencies.

That level of precision changes the game. Cars can unlock automatically only when you’re physically beside the door. Smart-building systems can tell which room you’re standing in. Mixed-reality headsets can map your movements without extra sensors.

From a development point of view, you’ll need hardware that supports the new Channel Sounding PHY. Nordic’s nRF54 and Silicon Labs’ BG24 families already expose low-level APIs for it. Expect to work closer to the metal than usual: calibration, antenna diversity, and clock stability all affect measurement accuracy. It’s worth the effort, though. Few wireless technologies can deliver this precision without expensive dedicated hardware.

Periodic Advertising with Responses (PAwR)

For years, BLE advertising worked like shouting into a room and hoping someone heard you. The moment you wanted a reply, you had to form a full connection. That model doesn’t scale when you have ten-thousand tiny sensors that each wake up once a minute.

PAwR flips the model. Think of it as a scheduled town-hall meeting. A coordinator (the gateway) broadcasts a timeline. Each sensor has a reserved time slot to respond within that cycle. Because everyone speaks only during their assigned moment, collisions disappear and energy use plummets.

In practice, this lets one gateway handle tens of thousands of devices without ever maintaining individual connections. Supermarkets use it for electronic shelf labels that update prices in seconds. Factories deploy it for environmental sensors that report temperature and vibration periodically.

Developers integrating PAwR will notice that it doesn’t replace connections, it complements them. You can still open a full GATT session for configuration, but routine data flows through lightweight PAwR exchanges. Most modern SDKs, including Zephyr and ESP-IDF, now include PAwR APIs under their extended-advertising modules.

Isochronous Audio Channels & LE Audio

Bluetooth’s original audio stack wasn’t built for what we expect today. It was designed for single-stream mono headsets, not for multi-earbud synchronized audio or broadcast systems. Isochronous Channels fix that by ensuring that every packet in a group shares the same clock reference.

Two modes exist:

• Connected ISO Streams (CIS) handle one-to-one cases like stereo earbuds

• Broadcast ISO Streams (BIS) allow a transmitter to serve an unlimited audience, such as a gym or theater.

Both rely on the LC3 codec, which delivers near-lossless sound at roughly half the bandwidth of SBC.

In real life, this means earbuds that stay perfectly in sync even if you walk between interference zones, hearing aids that seamlessly share the same stream, and venues that broadcast announcements directly to phones without dedicated receivers. Android 14 and iOS 17 have already exposed system-level LE Audio support, so app developers can finally build end-user experiences without vendor-specific hacks.

For embedded engineers, implementing LE Audio requires controller firmware that supports ISOAL (Isochronous Adaptation Layer) and host-side stack integration. Nordic, Qualcomm, and Dialog all provide reference implementations, but testing is key – timing drift between links can break audio quality faster than you might expect.

Power & Efficiency Improvements

Battery life has always been Bluetooth’s quiet superpower, and version 6.0 tightens the screws even more. Rather than one big change, it’s a collection of small ones that add up.

Negotiable inter-frame spacing lets devices adjust the delay between packets, smoothing out contention when the air is busy. Controllers now enter deeper sleep states automatically, waking only when the radio truly needs them. Smarter advertising filters prevent devices from wasting time processing duplicates, and new firmware offloads push repetitive tasks (like connection parameter updates) away from the CPU.

When engineers combine all these tricks, the numbers look impressive: about a ten to twenty percent battery gain in dense environments. That might not sound huge, but for a coin-cell tag meant to last three years, it’s the difference between hitting the spec or not.

Security & Privacy Upgrades

With great connectivity comes great responsibility. Bluetooth now sits at the heart of cars, locks, and health monitors, which makes security non-negotiable. The new stack finally treats it as a first-class citizen.

LE Secure Connections with numeric comparison are now standard, encrypted advertising data hides sensitive broadcasts, and Channel Sounding even enables distance-based access control. In plain language, a device can now verify that you’re physically nearby before sharing keys or unlocking features.

Still, protocol features alone aren’t enough. Developers should rotate identity-resolving keys regularly, invalidate old bonds on firmware updates, and avoid static passkeys. Security in Bluetooth is like security anywhere else: the spec provides the locks, but you’re responsible for turning the key.

Together, these improvements make Bluetooth feel more alive, more aware, and more efficient. The stack now senses distance, saves power, and defends privacy without breaking backward compatibility. It’s a quiet revolution hidden inside chips that most people never think about, yet it’s shaping how billions of devices will talk to each other over the next decade.

Real-World Applications in 2025

It’s one thing to read about Channel Sounding or PAwR in a spec sheet. It’s another to see these features come alive in everyday products.

Bluetooth has quietly spread into nearly every corner of our lives, from the shelves of supermarkets to the dashboards of cars. By 2025, it’s no exaggeration to call it the most widely deployed wireless ecosystem on Earth.

Let’s look at where these new capabilities are already making an impact.

Retail: Electronic Shelf Labels and Smart Inventory

Walk into a modern supermarket in 2025 and look closely at the price tags. They aren’t paper anymore. Those little digital labels, changing prices in real time, are powered by Bluetooth 5.4’s Periodic Advertising with Responses (PAwR) and Encrypted Advertising Data.

Each label is a low-power sensor node, quietly listening for broadcast schedules from a gateway mounted above the aisle. When it’s their turn, the tags wake up, confirm their slot, and update the display – all in milliseconds and without forming a traditional Bluetooth connection. The result is a network of tens of thousands of nodes that consumes almost no energy.

Security matters here too. Encrypted advertising ensures that a competing store or curious shopper can’t sniff price data or inject bogus updates. Everything runs on coin-cell batteries that last several years, which saves retailers both time and maintenance costs.

Smart Home: Context-Aware Unlocking and Personal Audio

If you’ve ever fumbled with your phone to unlock a smart door, Bluetooth 6.0 might finally fix that. Channel Sounding makes proximity detection precise enough to trust. The system can tell whether you’re standing by the door or ten meters away in the driveway. Only when you’re truly within range does it trigger the unlock sequence.

The same precision is reshaping personal audio. Imagine walking from your living room to the kitchen and having your smart speaker hand off the song to your earbuds automatically. That’s LE Audio working behind the scenes with isochronous channels, keeping streams perfectly aligned across multiple endpoints. It feels invisible, which is exactly how good technology should feel.

Healthcare: Reliable, Secure Patient Monitoring

Hospitals have long relied on wireless monitors, but interference and power limits made them tricky. With PAwR, a single access point can now coordinate thousands of small sensors that track vitals like heart rate, oxygen, or temperature. These devices communicate in brief, deterministic bursts, avoiding packet collisions that used to plague dense wards.

Privacy is critical, and that’s where encrypted advertising comes in. Patient identifiers and medical readings remain hidden even in broadcast form. Channel Sounding adds another layer by confirming proximity: only readers within a safe range can retrieve sensitive data.

Combined, these features help reduce misreads and protect patient confidentiality without adding extra setup steps for clinicians.

Industry 4.0: Asset Tracking and Condition Monitoring

Factories and warehouses are some of Bluetooth’s biggest playgrounds. Equipment now comes with embedded Bluetooth 6.0 modules that use Channel Sounding for ultra-precise location tracking. Pallets, forklifts, and tools broadcast their position continuously, helping logistics teams know what’s where, all the time.

Add PAwR, and you get scalable telemetry for thousands of machines. Vibration, temperature, or pressure data can flow reliably to a single gateway. Some systems even combine Bluetooth data with AI analytics to predict failures before they happen. The ability to measure distance accurately also helps robots navigate crowded spaces safely.

Wearables: Hearables, AR Glasses, and Health Bands

Wearable devices benefit more than any other category. Modern earbuds use LE Audio to keep both sides synchronized, whether you’re streaming a movie or on a call. Hearing aids receive direct broadcast audio in public venues without special adapters.

AR glasses are an even bigger frontier. They use Channel Sounding to sense spatial relationships between the wearer, nearby devices, and the environment. That allows context-aware overlays – navigation cues, health metrics, or notifications – that appear exactly where they make sense. Bluetooth’s low-power model keeps these systems lightweight enough to run all day.

Automotive: Digital Keys and Vehicle Telemetry

Cars are fast becoming Bluetooth hubs on wheels. Digital Key Systems already use Bluetooth 6.0’s distance measurement to ensure you’re physically close before unlocking or starting the engine. It’s safer than older RSSI-based solutions that could be fooled by signal relays.

Onboard sensors rely on secure connections and encrypted advertising to stream data about tire pressure, cabin air quality, or driver posture. Maintenance centers can access diagnostic data automatically when a car pulls in, without plugging in a cable. In short, Bluetooth has quietly replaced several proprietary systems once needed for short-range communication inside vehicles.

The Big Picture

What’s striking is how flexible Bluetooth has become. The same fundamental protocol now powers medical wearables, industrial sensors, and entertainment systems. Each use case leans on a different mix of features – PAwR for scale, Channel Sounding for precision, LE Audio for experience, and encrypted advertising for privacy – but the foundation is consistent.

It’s this adaptability that explains why Bluetooth continues to thrive despite predictions of its demise. Rather than being replaced by Wi-Fi or UWB, it’s learning from them, borrowing their strengths, and finding new roles.

Developer Guide — Getting Started

Bluetooth 6.0 may sound futuristic, but the good news is that you don’t have to wait years to use it. Most of the new features are already landing in chipsets, SDKs, and development kits. If you’re an engineer or hobbyist itching to get your hands dirty, this section walks you through what to look for, how to get started, and a few pitfalls to watch out for along the way.

Picking the Right Chipset

The chipset you choose sets the tone for your entire project. If you’re building something simple, like a smart tag or sensor, you’ll want a microcontroller with integrated Bluetooth Low Energy and minimal power draw. But if you plan to experiment with Channel Sounding, LE Audio, or PAwR, you’ll need silicon that explicitly supports Bluetooth 5.4 or 6.0 features.

Current front-runners include the Nordic nRF54 series, Dialog DA1470x, and Silicon Labs BG24 family. These are developer-friendly chips with mature SDKs and good documentation. They also have flexible radio subsystems, which matter a lot when you’re testing features like Channel Sounding that depend on timing and signal stability.

A small tip from experience: always check the vendor’s firmware release notes. Some Bluetooth 6.0-capable chips still require you to enable experimental PHY layers or SDK flags to unlock certain features.

SDK and Stack Support

Once you’ve got your hardware, the next step is setting up your software stack. Most Bluetooth development happens through vendor SDKs or open platforms like Zephyr RTOS, ESP-IDF, or BlueZ on Linux.

If you’re targeting embedded systems, Zephyr is a great place to start. It’s modular, stable, and already includes PAwR and LE Audio APIs under its bt_le_ext_adv and iso modules. Silicon Labs’ Simplicity Studio also has strong tooling around Bluetooth mesh and PAwR.

On desktop or gateway platforms, Linux’s BlueZ stack supports extended advertising and secure connections out of the box, and work is underway to integrate Channel Sounding support via new HCI commands.

Always verify that your controller firmware is up to date before testing new features. Many “missing API” errors trace back to outdated controller images that don’t yet recognize the relevant HCI opcodes.

Advertising Strategy

Advertising is still the heartbeat of Bluetooth, and now it’s smarter than ever. Here’s a simple example of setting up extended advertising in C-style pseudocode:

ble_adv_params params = {
    .type = ADV_EXTENDED,
    .interval = 160,   // 100ms interval
    .tx_power = 0      // default transmit power
};

ble_set_adv_data(payload, sizeof(payload));
ble_start_advertising(&params);

Above pseudocode demonstrates how a Bluetooth Low Energy (BLE) device initializes and starts broadcasting advertisements so that nearby devices can discover it. The first block defines a structure named ble_adv_params, which contains the configuration settings for advertising. The .type = ADV_EXTENDED field specifies that the device will use Extended Advertising, a feature introduced in Bluetooth 5.0 that allows for larger payloads, better range, and the use of secondary channels beyond the traditional 31-byte limit of legacy advertising. The .interval = 160 value sets the advertising interval, expressed in Bluetooth time units of 0.625 milliseconds, meaning the device transmits an advertising packet every 100 milliseconds—frequent enough for responsive discovery without excessive power consumption. The .tx_power = 0 field sets the transmit power level to 0 dBm, which is the default radio output power and provides a balanced tradeoff between energy efficiency and signal range. After configuring the parameters, the function ble_set_adv_data(payload, sizeof(payload)) loads the advertising data—typically a collection of identifiers such as the device name, UUIDs for available services, manufacturer-specific data, or other Bluetooth advertising fields. This is the information that other devices see when scanning nearby. Finally, ble_start_advertising(&params) begins the actual transmission, instructing the BLE controller to start broadcasting the configured data on the standard advertising channels (37, 38, and 39). Once active, the device periodically transmits these packets until advertising is stopped manually or a central device establishes a connection. In essence, this short snippet encapsulates the three fundamental steps of BLE advertising: configuring the radio parameters, defining the broadcast data, and enabling the periodic advertisements that make the device visible to others.

This kind of setup works well for extended advertising and PAwR broadcast scheduling. When designing your advertising payloads, remember that the new encrypted format (introduced in 5.4) limits available space slightly, so plan for tighter data packing if you’re including custom fields.

If you’re building something that needs connection-less updates (like a sensor network), use PAwR or periodic advertising. For interactive applications, where you expect users to connect via a phone or hub, extended connectable advertising remains the right choice.

Connection Optimization

Tuning connection parameters is half art, half science. You’ll often find yourself trading latency for battery life. For streaming or LE Audio applications, intervals around 24–40 ms usually strike the right balance. For sensors or telemetry, you can stretch that interval out to save energy.

Sniff subrating is another underrated feature. It lets a peripheral sleep longer while maintaining an active connection, reducing energy use without affecting responsiveness too much.

If you’re testing with multiple devices, simulate busy airspace using tools like Ellisys Bluetooth Analyzer or the nRF Sniffer. This helps uncover timing issues or packet loss that might only show up in dense radio environments.

Power Testing

It’s easy to claim low power on paper – but proving it is another story. Use your dev kit’s current profiling tools to measure sleep and active currents under different intervals and PHY settings.

Run your firmware through long-duration tests in “noisy” airspace – meaning multiple other Bluetooth or Wi-Fi devices nearby. The goal is to see how your firmware reacts when packet retries or interference increase. Sometimes small timing tweaks can make big differences in battery life.

As a general rule, always start testing on the 1M PHY (the default) and only switch to 2M for high-throughput use cases like audio. Long-range modes can be valuable for IoT, but remember that higher receive sensitivity often costs extra current.

Security Checklist

Bluetooth 6.0 brings much stronger built-in security, but you’ll still need to wire it up correctly. Make sure to:

• Use LE Secure Connections instead of legacy pairing.

• Rotate Identity Resolving Keys (IRK) periodically.

• Encrypt advertising payloads whenever transmitting private or medical data.

• Handle key storage securely on your device, preferably with hardware-backed encryption or secure flash.

Also, watch for privacy gaps in the connection flow. Even encrypted devices can leak identity information if they reuse resolvable addresses or fail to clear bonds properly on reset.

Backward Compatibility

Real-world devices won’t all jump to Bluetooth 6.0 overnight. Your code should always detect peer capabilities and fall back gracefully. The HCI layer provides read commands that reveal which features the remote device supports.

For example, if Channel Sounding isn’t available, default to RSSI-based proximity or skip distance-based logic entirely. Similarly, if LE Audio isn’t supported, fall back to classic A2DP. Designing your firmware with this flexibility keeps your products compatible with millions of existing devices.

Testing and Certification

Once your prototype works, you’ll need to qualify it through the Bluetooth SIG Qualification Program. This process ensures your product complies with the spec and interoperates correctly with others. It might sound intimidating, but many vendors offer pre-qualified modules or test reports you can reuse to simplify the paperwork.

For debugging and validation, tools like the Ellisys Bluetooth Analyzer, Frontline BPA 600, or Nordic’s nRF Sniffer can capture over-the-air traffic and help verify packet sequences, timing, and encryption states.

Bluetooth development can be frustrating at first, as there’s lots of acronyms, layers, and hidden dependencies. But once you start seeing the system as a living conversation between devices, it clicks. The more you experiment with advertising intervals, connection timing, and PHY modes, the more you’ll appreciate how elegant and flexible the stack really is.

If you’ve ever wanted to build something that talks wirelessly and runs for months on a battery, this is your moment. The ecosystem has matured, the tools are ready, and the possibilities keep expanding.

Challenges & Trade-Offs

It’s tempting to think of Bluetooth 6.0 as flawless – after all, it’s faster, more efficient, and infinitely scalable. But like every engineering advancement, it comes with trade-offs. Real deployments reveal quirks that the spec sheets don’t mention, and knowing these early can save hours of debugging (and a few late-night rants).

Adoption Lag

Every new Bluetooth spec sounds exciting on paper until you realize the hardware for it isn’t widely available yet. Controller vendors take time to integrate the latest features, and phone or OS support can lag by a year or two. You might find yourself reading about Channel Sounding or PAwR in the core spec, only to discover that your development kit still marks them as “experimental.”

This is normal. The Bluetooth SIG’s release cadence moves faster than the hardware ecosystem can follow. The best strategy is to design firmware that detects capabilities dynamically. Build your code to gracefully fall back to 5.0 or 5.2 modes if 6.0 features are missing. That way your product ships today, but it’s ready for the future.

Environmental Interference

Bluetooth still lives in the 2.4 GHz band, the same noisy neighborhood as Wi-Fi, microwaves, and countless IoT gadgets. In factories or dense apartments, you’ll see interference spikes that cause packet loss or delay. Even with adaptive frequency hopping, performance can dip if too many radios are talking at once.

Developers need to test in real environments, not just in quiet labs. Use spectrum analyzers or sniffers to visualize congestion. Adjust transmit power, advertisement intervals, or even antenna orientation to mitigate problems. Remember, radio design is part science, part art. Sometimes moving a board trace by a centimeter makes more difference than rewriting code.

Power Versus Performance

Every Bluetooth generation tries to squeeze more precision and range out of roughly the same battery. Channel Sounding and high-speed PHY modes improve accuracy and throughput, but they also increase radio-on time and CPU load. You gain features but spend more energy to get them.

There’s no universal setting that fits all products. A hearing aid might value low latency over battery life, while a temperature sensor prioritizes sleeping as much as possible. Developers must tune intervals, transmission power, and frame spacing through measurement, not guesswork. The good news is that once you find the sweet spot, Bluetooth tends to be remarkably stable over long periods.

Security Configuration

Modern Bluetooth has excellent built-in security, but only if you use it correctly. Misconfigured advertising, static passkeys, or unrotated identity keys can still leak information. Even encrypted advertising won’t help if your firmware accidentally reuses session data.

The takeaway: don’t assume “secure by default.” Review every pairing and bonding flow, handle key rotation on firmware updates, and wipe old bonds when a user resets the device. The protocol gives you powerful locks, but it’s up to you to actually turn the key.

Software Complexity

The Bluetooth stack is getting heavier. Features like PAwR, Channel Sounding, and Isochronous Audio require new roles, new timing models, and new APIs. Developers who are used to simple GATT servers now have to think about scheduling, synchronization, and PHY coordination. Testing these features on multi-role devices can be especially tricky, since a single controller might handle multiple concurrent roles (central, peripheral, broadcaster, and observer).

If you’re working on an embedded platform, modular firmware design becomes essential. Split radio control, connection management, and application logic into distinct layers. It’s easier to debug timing bugs when your architecture mirrors the Bluetooth stack’s separation of concerns.

Fragmentation

Perhaps the most persistent challenge is fragmentation. Not every OEM implements the same subset of features, and some phones or chipsets may partially support a spec while skipping optional sections. Developers quickly learn that “Bluetooth 6.0” can mean slightly different things depending on the vendor.

The practical fix is to build flexibility into your software. Use feature discovery at runtime, keep your update mechanism ready for OTA patches, and enable configuration flags for new features so you can toggle them per device. Testing across diverse hardware early in the process pays off more than any elegant design decision later.

Mitigation and Mindset

Despite these challenges, none of them are deal-breakers. They’re simply part of building systems that live in the real world. Think modular, plan for gradual rollouts, and make firmware updates painless. Bluetooth’s backward compatibility means your device won’t become obsolete overnight, and your users benefit from improvements as the ecosystem matures.

In short, the trick isn’t avoiding the trade-offs but managing them. When you design with flexibility, Bluetooth 6.0 becomes less of a moving target and more of a living platform that grows alongside your product.

The Road Ahead — Bluetooth 6.1 and Beyond

If Bluetooth 6.0 was about awareness – knowing distance, filtering intelligently, and optimizing communication – then Bluetooth 6.1 is about refinement. It takes what already works and polishes it into something smoother, faster, and a little more elegant. It’s not a revolution, but it’s an important step in Bluetooth’s quiet transformation from a “wireless cable” into a context-aware network fabric for everyday devices.

Small Tweaks, Big Payoffs

Bluetooth 6.1 focuses on tightening the nuts and bolts rather than changing the whole machine. The update improves Channel Sounding accuracy, enhances advertising efficiency, and introduces a few quality-of-life adjustments to make device coordination easier.

That might sound minor, but it matters. Channel Sounding, for example, becomes more reliable when multiple reflections or obstacles exist. In indoor positioning systems like airports, hospitals, or museums, even a five percent improvement in accuracy can reduce false detections by a wide margin. Advertising refinements also make large IoT deployments more predictable, allowing gateways to manage high-density environments with less radio congestion.

In simpler terms: Bluetooth 6.1 is like a firmware tune-up for an already fast car. You may not notice it day to day, but under heavy load, it performs better and wastes less energy.

The Emerging Themes

Beyond the incremental fixes, the Bluetooth community is thinking much bigger. The next few years will likely focus on four major themes: energy harvesting, AI-assisted radio optimization, hybrid positioning, and context-aware security.

1. Energy-Harvesting Bluetooth Devices

We’re starting to see early prototypes of Bluetooth tags and sensors that run entirely on harvested energy – light, heat, or vibration – with no traditional battery. This ties into the push for maintenance-free IoT devices, especially in logistics and environmental sensing. Future specifications will refine ultra-low-duty-cycle communication patterns to support these “powerless” nodes.

2. AI-Driven Radio Management

Imagine a Bluetooth controller that dynamically learns the noise profile of its environment and adjusts its PHY, transmit power, or advertising timing in real time. Instead of a static table of parameters, AI models embedded in the firmware could predict interference and choose the best channel map automatically. It sounds futuristic, but chipmakers are already experimenting with machine learning cores in connectivity modules.

3. Cross-Technology Fusion (Bluetooth + Wi-Fi + UWB)

The border between short-range radios is blurring. Some systems already use Wi-Fi for throughput, Bluetooth for discovery, and UWB for pinpoint accuracy – all orchestrated by a single chipset. The goal isn’t to replace one with another but to fuse them, creating hybrid location frameworks that are more reliable than any single technology. Bluetooth’s Channel Sounding makes it a perfect partner in this mix.

4. Context-Aware Security

Future Bluetooth devices might decide access rights based not just on identity, but on context. For example, your smartwatch could unlock your laptop only if it detects that you’re sitting still and within one meter. That combination of motion, distance, and authentication could drastically reduce spoofing or relay attacks.

The Quiet Backbone of Connectivity

What’s fascinating about Bluetooth’s evolution is how quietly it happens. While other technologies make noise about high throughput or low latency, Bluetooth’s progress feels invisible but omnipresent. It doesn’t chase raw speed anymore – it chases relevance. The protocol is learning to sense, adapt, and coordinate, all qualities that make it essential for the next generation of ambient computing.

So while you might not notice Bluetooth 6.1 when it arrives, you’ll definitely feel its effects. Devices will sync faster, connections will drop less, audio will sound cleaner, and proximity-based features will just “know” what you want them to do. That’s the beauty of mature engineering: when it works so seamlessly that people stop thinking about it altogether.

Conclusion

Bluetooth has come a long way from its early days as a clunky pairing protocol for headsets. It’s now one of the quietest yet most influential technologies shaping how devices around us communicate. The newer generations – 5.4, 6.0, and soon 6.1 – show that Bluetooth’s evolution isn’t about flashy upgrades. It’s about refinement, about making wireless communication more precise, more private, and more power-aware.

At its core, Bluetooth’s story is about context. It’s learning to understand where you are, how far you are from something, and what kind of connection makes sense in that moment. Channel Sounding adds spatial awareness, PAwR makes massive IoT networks practical, LE Audio brings synchronized sound to earbuds, hearing aids, and broadcast systems, and encrypted advertising protects the information flowing through all of it.

For developers, this era of Bluetooth is exciting because it’s full of creative possibilities. You can build smarter sensors, more responsive wearables, or secure access systems that simply know when you’re nearby. The ecosystem is mature enough that you don’t need to be a radio engineer to experiment, but it’s still evolving fast enough to keep pushing boundaries.

The challenge now is not whether Bluetooth can handle the future. It’s how we, as developers and designers, decide to use it. Whether it’s powering ambient computing, healthcare networks, or next-gen audio, the technology is already ready.

So maybe the next time you put on your earbuds or unlock your car, take a moment to appreciate the quiet genius working behind the scenes. Bluetooth is thriving, adapting, and quietly building the connective tissue of our digital lives.

And for those of us who like tinkering with the unseen layers of technology, that’s a future well worth exploring.

This post is a bit lengthy. If you prefer, signup to get the full PDF here. ?

After Particle's Mesh deprecation announcement, many have been left to figure out how to deploy their low power sensor networks. There was always the option of using Particle's Built in Bluetooth stack but as it stands today it's not secure.

Previously I had helped form a very simple nRF SDK-based hub and spoke IoT deployment. Unfortunately, it was closed source and the company is no longer around.

So what's a guy to do?

Build another one and make it open. (BSD licensed to be exact!) Open and free for anyone to use adopt and improve upon. Plus if you're building a product that's using the code, you don't have to share your improvements or proprietary code with anyone.

In this post I'll be talking about how to get started with Pyrinas. It uses Nordic's time tested SDK as a basis for the kernel of the system. The main concept of Pyrinas is to abstract as much IoT cruft away so you can focus on your application.

So without further ado, let's chat about what Pyrinas is and what it isn't.

What Pyrinas is

• Is an embedded "kernel", written in C. It's open and permissive IoT development environment you can use for anything you want. Seriously. It's BSD licensed and can be used in closed source applications.
• Using the power of Bluetooth 5.0 Long Range, Pyrinas allows you to communicate with many peripheral devices at one time. Currently Pyrinas has been tested with 3 simultaneous peripheral connections. Theoretically, it can support up to 20 simultaneous connections. (Thanks to Nordic's S140 Softdevice)

• Pyrinas transports its data in two ways

  • In a familiar string format used by Particle
  • A custom Protocol Buffer for raw data transmission.

  That way you have a choice of how you want to process and publish your data!

What Pyrinas isn't

• Pyrinas is not a RTOS (real time operating system). If you have a need to run multiple threaded applications on embedded, Pyrinas is not for you.
• Pyrinas, at this time, does not support Mesh.
• An OS for every single kind of Bluetooth SoC on the market. Due to the tight coupling with Nordic's nRF SDK, Pyrinas only works with Nordic's SoCs.
• A turnkey solution for IoT. Pyrinas is early on it it's development process. The aim is for it to become a viable option for anyone to develop and publish IoT applications the way they want to. There's no vendor lock in. There's no surprises.

Things you'll need

There are a few things you'll need in order to get going with Pyrinas.

• At least 2 Particle Xenons
• At least 1 nRF Development board or J-link programmer
• Associated USB cables

Getting started with an example

Getting started with Pyrinas involves two repositories.

• The OS respository
• The template

The OS directory has all the source, SDK dependencies and toolchain you need to use Pyrinas.

The template is where you add all your application code. The template provides a starting point for you and your project.

Here's how everything goes together:

Clone the OS directory to some place on your machine:

git clone https://github.com/pyrinas-iot/pyrinas-os.git --recurse-submodules

Once complete, change directories to pyrinas-os and run make setup

cd pyrinas-os
make setup

This will download your toolchain and SDK dependencies.

In order to use OTA DFU, you will need to also generate the DFU key for the process:

make gen_key

The files generated by this process will be used later.

Next, we'll want to use the template to make two new projects. In this example we'll have one "hub" and one "sensor." Simply navigate to the template repository and click the Use this template button.

Then name your new repository. Click the Create repository from template button when you're happy with everything.

Then clone your repository to the same directory as pyrinas-os. Make sure you replace <your username> and <repo name> with your own.

cd ..
git clone https://github.com/<your username>/<repo name>.git hub

After this is done, go back and create a new repository from the template. We'll be using this one for the sensor node.

Clone this repository once you're done setting it up in the same place as your hub and pyrinas-os repositories.

Now that we have all our repositories, let's start with our sensor node.

Setting up the sensor node repository

Open up the sensor repository using a program like Microsoft's VS Code. If you have the command line shortcuts you can use code to open it from the terminal:

code sensor

Before we do anything we'll need to set up the symbolic link to pyrinas-os. Make sure you're in the sensor directory and then run ln -s ../pyrinas-os/ using the terminal.

cd sensor
ln -s ../pyrinas-os/ .

This allows your project to use all the code, SDK and toolchains within the pyrinas-os repository! As an added bonus you can do this as many times as you want. Have multiple Pyrinas projects? No problem.

Alright! Now, let's check out the Makefile. You'll want to customize some of the definitions within the file:

# Start: Your configuration!

# Set this to the directory of pyrinas-os
# If you used a symbolic link this points to
# the `pyrinas-os` folder in this repository
OS_DIR := pyrinas-os

# This should be the serial number of your Jlink programmer.
# To find simply run `jlinkexe`
PROG_SERIAL=1234678

# This is your debugger port for Jlink's RTT. If you
# have mulitple, you will have to change this on each app
# your're using
PROG_PORT=19021

# This is where you set your board type. Here are the supported boards:
# xenon - Particle Xenon
BOARD=xenon

# This is where you can name your app something. Make it specific
APP_FILENAME=pyrinas-template

# This determines whether or not you're using debug mode
# Comment this out or change to false
DEBUG=true

# End: Your Configuration

For example, you may want to setup your programmer serial. This allows you to use multiple programmers at the same time. (Very helpful in debugging both devices at the same time) To get your programmer's serial plug in your development board and run jlinkexe.

jlinkexe SEGGER J-Link Commander V6.62a (Compiled Jan 31 2020 12:59:22) DLL version V6.62a, compiled Jan 31 2020 12:59:05

Connecting to J-Link via USB...O.K. Firmware: J-Link OB-SAM3U128-V2-NordicSemi compiled Jan 21 2020 17:30:48 Hardware version: V1.00 S/N: 581758669 License(s): RDI, FlashBP, FlashDL, JFlash, GDB VTref=3.300V

Type "connect" to establish a target connection, '?' for help J-Link>

Find the S/N area. This is your serial number!

Alternatively you can look at the sticker on your development kit. It will contain the serial number for your device.

For the PROG_PORT you want to use different ports for each device you're simultaneously debugging. I've found 19021 and 19020 are perfectly good options for most two-device debugging sessions.

The Makefile also includes the ability to choose a board. In our case there's only one option: xenon. Future revisions of Pyrinas will have multiple options.

APP_FILENAME is the name of your app. We'll rename ours to pyrinas-sensor

Finally, DEBUG is used to halt execution either on an error or restart. For production this should be commented out or set to false. We can leave it as is for now.

The Makefile is also the source for some of the most important commands you'll need during development:

• make build - builds your app.
• make clean - cleans all remnants of your app.
• make debug - opens up the jlinkexe debugger console.
• make erase - erases the chip attached to your programmer.
• make flash - flashes the current app to your connected device.
• make flash_softdevice - flashes the soft_device
• make rtt - opens up the debug console.
• make ota - generates a zip file used for BLE DFU

Basic sensor node code

Now that we have some of the basics out of the way, let's create a very simple application that publishes on a set interval. If you look at app.c, you'll see some code in the setup() function. Let's delete all the commented out code. (We'll use it later for the hub though)

Your code should now look something like:

#include "app.h"

void setup()
{
  BLE_STACK_PERIPH_DEF(init);

  // Configuration for ble stack
  ble_stack_init(&init);

  // Start advertising
  advertising_start();
}

void loop()
{
}

Now let's create a timer that we'll use to publish on a set interval. Under #include "app.h" create a new timer:

#include "app.h"

timer_define(m_sensor_timer);

We also need to set it up in the setup() function:

// Sensor timer
timer_create(&m_sensor_timer, TIMER_REPEATED, sensor_timer_evt);

You'll notice that timer_create is referring to a event callback called sensor_timer_evt. We'll need to create that guy as well:

static void sensor_timer_evt() {
    // We'll come back in a sec
}

The last thing is to start the timer. Let's do that underneath timer_create:

// Start
timer_start(&m_sensor_timer, 1000);

This will start our repeating timer on a 1 second interval. (timer_start is configured using milliseconds)

Now, inside sensor_timer_evt we'll publish some data. First though we need to make sure that Bluetooth is connected using ble_is_connected.

static void sensor_timer_evt
{
  // Check if we're connected
  if (ble_is_connected())
  {
    // Sends "ping" with the event name of "data"
    ble_publish("data", "ping");
  }
}

Inside the if statement, we'll use ble_publish. The first argument is the name of the event and the second is the value.

Next, in order to receive messages from the other end we'll need to setup a callback:

// Configuration for ble stack
ble_stack_init(&init);

// Setup BLE callback
ble_subscribe("data", ble_evt);

We'll define ble_evt at the top of the file:

static void ble_evt(char *name, char *data)
{
  NRF_LOG_INFO("%s: %s", name, data);
}

In this case we'll use NRF_LOG_INFO to print out the message from the hub.

Finally, in order to get the MAC address easily, we'll have to add a call to print it out in setup().

// Print the address
util_print_device_address();

In the end your file should look something like this:

#include "app.h"

timer_define(m_sensor_timer);

// Catch events sent over Bluetooth
static void ble_evt(char *name, char *data)
{
  NRF_LOG_INFO("%s: %s", name, data);
}

static void sensor_timer_evt()
{
  // Check if we're connected
  if (ble_is_connected())
  {
    // Sends "ping" with the event name of "data"
    ble_publish("data", "ping");
  }
}

void setup()
{
  BLE_STACK_PERIPH_DEF(init);

  // Configuration for ble stack
  ble_stack_init(&init);

  // Setup BLE callback
  ble_subscribe("data", ble_evt);

  // Start advertising
  advertising_start();

  // Sensor sensor timer.
  timer_create(&m_sensor_timer, TIMER_REPEATED, sensor_timer_evt);

  // Start
  timer_start(&m_sensor_timer, 1000);

  // Print the address
  util_print_device_address();
}

void loop()
{
}

Next, we'll program it to some hardware!

Flashing the basic sensor code:

For this step you'll need to have a Xenon handy. You'll also need a programmer, programming cable and two Micro-B USB cables. Here's a picture of everything connected:

Once connected and powered run these commands:

make erase
make flash_softdevice
make flash
make debug

Then in a separate terminal window run

make rtt

make debug and make rtt will create a debugging session. You can issue commands in the make debug terminal to control the device as well. For instance, r followed by Enter will restart the device. (By far my most common use case).

If you've flashed everything successfully, your device should start blinking green. That's a good sign!

Additionally, if you take a look at the make rtt side your output should be similar to this:

###RTT Client: Connecting to J-Link RTT Server via localhost:19021 ...

###RTT Client: Connected.

SEGGER J-Link V6.62a - Real time terminal output J-Link OB-SAM3U128-V2-NordicSemi compiled Jan 21 2020 17:30:48 V1.0, SN=581758669 Process: JLinkExe app_timer: RTC: initialized. app: Boot count: 4 app: Pyrinas started. app: Address: 11:22:33:44:55:66

Take note of the address displayed above. We'll need that for the hub code!

Setting up the hub repository

If you haven't already, clone your hub repository locally. We'll want to do some of the same steps as we did with the sensor repo like:

• Setting up the symbolic link
• Updating the Makefile
  • Setting your PROG_SERIAL
  • Setting PROG_PORT to a port not used by the sensor setup. 19020 in this case is fine.
  • Setting APP_FILENAME to pyrinas-hub

If you need a reminder how any of these steps work, go back and review the earlier section.

Next, we'll want to open app.c and uncomment the central/hub based code. Plus you'll want to remove the default un-commented code. Your setup() should look something like this:

void setup()
{
  // Default config for central mode
  BLE_STACK_CENTRAL_DEF(init);

  // Add an addresses to scan for
  ble_gap_addr_t first = {
      .addr_type = BLE_GAP_ADDR_TYPE_RANDOM_STATIC,
      .addr = {0x81, 0x64, 0x4C, 0xAD, 0x7D, 0xC0}};
  init.config.devices[0] = first;

  ble_gap_addr_t second = {
      .addr_type = BLE_GAP_ADDR_TYPE_RANDOM_STATIC,
      .addr = {0x7c, 0x84, 0x9d, 0x32, 0x8d, 0xe4}};
  init.config.devices[1] = second;

  // Increment the device_count
  init.config.device_count = 2;

  // Configuration for ble stack
  ble_stack_init(&init);

  // Start scanning.
  scan_start();
}

You'll notice immediately that there are two clients/devices defined here. Let's remove the second one. Should you, in the future, want to connect more devices this is an example of how to do it.

Reminder: also make sure that you change the init.config.device_count to 1.

Then, you'll want to update the .addr field in ble_gap_addr_t first to match the address we got earlier from make rtt:

// Add an addresses to scan for
ble_gap_addr_t first = {
    .addr_type = BLE_GAP_ADDR_TYPE_RANDOM_STATIC,
    .addr = {0x11,0x22,0x33,0x44,0x55,0x66}};
init.config.devices[0] = first;

The address field uses raw bytes, so it has to be represented that way. Remove the : and place 0x in front of each byte. We end up going from 11:22:33:44:55:66 to {0x11,0x22,0x33,0x44,0x55,0x66}

Now before we flash anything, let's also set up the Bluetooth event handler. As with earlier we'll use ble_subscribe to attach an event handler:

// Setup BLE callback
ble_subscribe("data", ble_evt);

Then place the function at the top of the file:

// Catch events sent over Bluetooth
static void ble_evt(char *name, char *data)
{
  NRF_LOG_INFO("%s: %s", name, data);

  ble_publish("data", "pong");
}

You'll notice we're printing out the message using NRF_LOG_INFO. We're also sending a message back to the sensor in the form of ble_publish("data","pong"); In other-words we're playing a game of ping-pong between the two devices!

In the end your code should look something like this:

#include "app.h"

// Catch events sent over Bluetooth
static void ble_evt(char *name, char *data)
{
  NRF_LOG_INFO("%s: %s", name, data);

  ble_publish("data", "pong");
}

void setup()
{
  // Default config for central mode
  BLE_STACK_CENTRAL_DEF(init);

  // Add an addresses to scan for
  ble_gap_addr_t first = {
      .addr_type = BLE_GAP_ADDR_TYPE_RANDOM_STATIC,
      .addr = {0x11, 0x22, 0x33, 0x44, 0x55, 0x66}};
  init.config.devices[0] = first;

  // Increment the device_count
  init.config.device_count = 1;

  // Configuration for ble stack
  ble_stack_init(&init);

  // Setup BLE callback
  ble_subscribe("data", ble_evt);

  // Start scanning.
  scan_start();
}

void loop()
{
}

Reminder: make sure you set ble_gap_addr_t first or the two devices will not connect!

To program, connect the Xenon to program as you did before. We'll flash it using the same methods as before:

make erase
make flash_softdevice
make flash
make debug

Then in a separate terminal window run

make rtt

Then take a look at each of the make rtt screens. There should be some output! For the hub it should look something like this:

Process: JLinkExe app: Boot count: 4 app: Pyrinas started. ble_m_central: Connected to handle 0x0 ble_m_central: Protobuf Service discovered app: data: ping app: data: ping

And the sensor side like this:

Process: JLinkExe app_timer: RTC: initialized. app: Boot count: 4 app: Pyrinas started. app: Address: 11:22:33:44:55:66 ble_m_periph: Notifications enabled! app: data: pong app: data: pong

The ping and pong messages should continue until you stop them. Awesome! If you get any warnings like this one:

Unable to write. Notifications not enabled!

Use the reset button on either of the devices. This should fix the problem.

Side note: the pairing process for Bluetooth is inherently insecure. Once the pairing process is complete though, the devices are secure. (With the caveat that no one was sniffing the pairing process!) There may be improvements on security in the future.

Congrats! ?If you've made it this far, you've deployed your first Pyrinas hub and sensor client!

For more information about what Pyrinas can do you should check out the header files under pyrinas-os/include/. Also, Pyrinas can do anything that you'd normally be able to do with Nordic's SDK. Nordic's Infocenter is a great resource for learning more about what the SDK has to offer.

What does the future hold for Pyrinas?

All future tasks for Pyrinas are shared openly on the Github Repo. Here are some of the high level improvements on the roadmap:

• Particle Boron + LTE support - That's right! Cellular will be coming to Pyrinas. As of this writing, the first board to support Pyrinas LTE will be Particle's Boron.
• MQTT (over TLS) and HTTPS support - Once we have cellular, we need something to communicate with. That's where MQTT and HTTPS come in. They're some of the most popular protocols for IoT today.
• Built in remote OTA support - As it stands today, devices programmed with Pyrinas uses Nordic's Secure Bootloader. That means they can be updated over the air by a computer or cellphone nearby. This isn't sustainable for long term deployments though! Instead, you will be able to push updates to Pyrinas devices over the Cloud. Yup. No reason to get off your couch, you can deploy your updates from anywhere.
• Dynamic configuration and management - adding and removing devices from a Pyrinas system currently takes some effort. In future revisions, it will be easier to add and remove devices on the fly. This allows for remote device management with zero headaches.
• Support for pre-certified modules and other development boards based on Nordic's nRF52840. Currently the Xenon is the only supported board. Development boards aren't great for full production though. Stay tuned for support for pre-certified modules from vendors like Fanstel and more..
• Support for more development environments. Currently Pyrinas supports Mac only.

Star and Watch!

This is only the tip of the iceberg! Stay tuned for more updates and make you you star and watch the repository.

Or, better yet, looking to help out? Contributions are welcome!

You can read other articles on my blog, jaredwolff.com

Ever want to add presence or location tracking to a project? Frustrated by the solutions (or lack thereof)?

Do not worry, you're not the only one!

In this post you'll learn how to implement a very basic tracking and notification application. We'll be using a Particle Argon and a Tile Mate.

By the end you'll be able to tell when the Tile is present or not. Plus we'll use Pushover to send push notifications to the devices of your choosing.

Let's get going!

Note before we get started, this post is lengthy. You can download the PDF version so you can save and view it later.

Initial investigation

The idea of using a Tile wasn't obvious at first glance. Ideally, using a phone seemed to make more sense. Unfortunately, this wasn't as a viable option. It would require some more research and the creation of a Bluetooth iOS app.

So, the idea of using a phone was out.

Then I thought, "What devices do advertise all the time?"

That is what led me down the path of a tracker like Tile.

After it arrived there was some customary testing. First stop, the Tile application.

I was able to connect and use the device. I even made it play a catchy tune. ?

Then, I moved on to using one of the Bluetooth scanner apps. I scrolled through all the results and Bingo. There was the Tile!

I even waited a few hours and checked it again. I wanted to make sure it didn't go to sleep after a while. Turns out, it's always advertising. As far as I can tell, about every 8 seconds.

All of this testing lead to one conclusion: it could be easily used for presence detection.

The next step in the process was trying to figure out how to get it working with an Argon.

Advertising

As we had gathered in the previous step, we know that the Tile is advertising about every 8 seconds. That means it should be easily scanned for using any device including an Argon, Zenon or Boron.

For this example I suggest you use an Argon. This is because Bluetooth and Mesh share the same radio. When scanning for the Tile, the Xenon connected to Mesh would often miss the advertising packets. This would lead to false negatives (and frustration!).

Along the same lines, you'll want to make sure your Argon is connected to no mesh network. You can remove it using the CLI. Connect your device to your computer and run the following command:

particle mesh remove <device name/ID>

Make sure that you replace with your device's name or ID.

Alright, back to the good stuff.

Advertising can have a few different purposes in Bluetooth. Typically though, it marks the beginning of the pairing phase. That way other devices know that the advertising device is available.

Additionally, the advertising device will indicate what services it has. We can use this knowledge to filter out devices that don't match.

For example, here's a screenshot of the services available on the Tile device:

When scanning we'll double check that the device we're connecting to has the service UUID of 0xfeed.

Before we get deep into Bluetooth land though, let's set up our app for debugging using the Logger.

Logging

In this tutorial we'll be using the Logger. It allows you to display log messages from your app using particle serial monitor.

One of the cooler features about the logger is the idea of message hierarchy. This allows you, the designer, to selectively mute messages that may not be necessary.

For example, if you have messages used for debugging. You could remove them or comment them out. Or, you could increase the LOG_LEVEL so they're effectively ignored.

Here are the logging levels which are available in logging.h in Particle's device-os repository:

// Log level. Ensure log_level_name() is updated for newly added levels
typedef enum LogLevel {
    LOG_LEVEL_ALL = 1, // Log all messages
    LOG_LEVEL_TRACE = 1,
    LOG_LEVEL_INFO = 30,
    LOG_LEVEL_WARN = 40,
    LOG_LEVEL_ERROR = 50,
    LOG_LEVEL_PANIC = 60,
    LOG_LEVEL_NONE = 70, // Do not log any messages
    // Compatibility levels
    DEFAULT_LEVEL = 0,
    ALL_LEVEL = LOG_LEVEL_ALL,
    TRACE_LEVEL = LOG_LEVEL_TRACE,
    LOG_LEVEL = LOG_LEVEL_TRACE, // Deprecated
    DEBUG_LEVEL = LOG_LEVEL_TRACE, // Deprecated
    INFO_LEVEL = LOG_LEVEL_INFO,
    WARN_LEVEL = LOG_LEVEL_WARN,
    ERROR_LEVEL = LOG_LEVEL_ERROR,
    PANIC_LEVEL = LOG_LEVEL_PANIC,
    NO_LOG_LEVEL = LOG_LEVEL_NONE
} LogLevel;

Cool, log levels. But how do we use them?

We can use them by invoking one of these functions:

Log.trace, Log.info, Log.warn, Log.error.

For example:

Log.trace("This is a TRACE message.");

If we set the log level to LOG_LEVEL_INFO we'll only see messages from Log.info, Log.warn, and Log.error. LOG_LEVEL_WARN? Only Log.warn and Log.error will show up. (Hopefully you get the idea.)

To set it up, we'll set the default level to LOG_LEVEL_ERROR. We'll also set the app specific LOG_LEVEL to LOG_LEVEL_TRACE. The end result should look something like this

// For logging
SerialLogHandler logHandler(115200, LOG_LEVEL_ERROR, {
    { "app", LOG_LEVEL_TRACE }, // enable all app messages
});

This way we don't get spammed with DeviceOS log messages. Plus, we get all the applicable messages from the app itself.

By the way, if you want to set your device to a single LOG_LEVEL you can set it up like this:

SerialLogHandler logHandler(LOG_LEVEL_INFO);

As you continue your journey using Particle's DeviceOS you'll soon realize how handy it can be. Now, let's move on to the good stuff!

Setting it up

First, we'll want to make sure we're using the correct version of DeviceOS. Any version after 1.3 will have Bluetooth. You can get the instructions here.

Next we'll want to start scanning for the Tile. We'll want do do this in the loop() function at a specified interval. We'll use a millis() timer in this case:

// Scan for devices
if( (millis() > lastSeen + TILE_RE_CHECK_MS) ){
    BLE.scan(scanResultCallback, NULL);
}

Make sure you define lastSeen at the top of the file like so:

system_tick_t lastSeen = 0;

We'll use it to track the last time the Tile has been "seen". i.e. when the last time the Argon saw an advertising packet from the Tile.

TILE_RE_CHECK_MS can be defined as

#define TILE_RE_CHECK_MS 7500

This way we're checking, at the very minimum, every 7.5 seconds for advertising packets.

In order to find the Tile device we'll use BLE.scan. When we call it, It will start the scanning process. As devices are found scanResultCallback will fire.

For now, we can define scanResultCallback at the top of the file:

void scanResultCallback(const BleScanResult *scanResult, void *context) {
}

You notice that it includes a BleScanResult. This will contain the address, RSSI and device name (if available) and available service information. This will come in handy later when we're looking for our Tile device!

Remember, that BLE.scan does not return until scanning has been completed. The default timeout for scanning is 5 seconds. You can change that value using BLE.setScanTimeout(). setScanTimeout takes units in 10ms increments. So, for a 500ms timeout would require a value of 50.

For the case of this app, I'd recommend using a value of 8s (8000ms). You can set it like this:

BLE.setScanTimeout(800);

In this case, the device will scan for as long as it takes the Tile to advertise. That way it's less likely to miss an advertising packet.

Handling Scan Results

Now that we have scanResultCallback lets define what's going on inside.

We first want to get the service information inside the advertising data. The best way is to use scanResult->advertisingData.serviceUUID. We'll pass in an array of UUIDs what will be copied for our use.

BleUuid uuids[4];
int uuidsAvail = scanResult->advertisingData.serviceUUID(uuids,sizeof(uuids)/sizeof(BleUuid));

This will populate uuids that way you can iterate over them. uuidsAvail will equal the amount of available UUIDs.

On our case we're looking for a particular UUID. We'll define it a the top of the file:

#define TILE_UUID 0xfeed

Normally UUIDs are much longer. A short UUID like this means it has been reserved or is part of the Bluetooth specification. In either case we'll be checking for it in the same way we would check a 32bit or 128bit version.

For diagnostic reasons we can also print out the device information. In this case the RSSI and the device MAC address is handy:

// Print out mac info
BleAddress addr = scanResult->address;
Log.trace("MAC: %02X:%02X:%02X:%02X:%02X:%02X", addr[0], addr[1], addr[2], addr[3], addr[4], addr[5]);
Log.trace("RSSI: %dBm", scanResult->rssi);

Finally let's set up a loop to see if the device found has the UUID:

// Loop over all available UUIDs
// For tile devices there should only be one
for(int i = 0; i < uuidsAvail; i++){

    // Print out the UUID we're looking for
    if( uuids[i].shorted() == TILE_UUID ) {
        Log.trace("UUID: %x", uuids[i].shorted());

        // Stop scanning
        BLE.stopScanning();

        return;
    }
}

We can easily compare the "shorted" version of the UUID with TILE_UUID. It's a simple integer so no complicated memory compare operations are necessary. So, using if( uuids[i].shorted() == TILE_UUID ) works just fine.

You can also use Log.trace to print out diagnostic information. In this case we're using it to print out the shorted() version of the UUID.

Test It!

Let's test what we have so far!

Program the app to your Argon. Open the terminal and run particle serial monitor to view the debug messages. Heres an example of what you may see:

0000005825 [app] TRACE: MAC: 65:C7:B3:AF:73:5C
0000005827 [app] TRACE: RSSI: -37Bm
0000005954 [app] TRACE: MAC: B3:D9:F1:F0:5D:7E
0000005955 [app] TRACE: RSSI: -62Bm
0000006069 [app] TRACE: MAC: C5:F0:74:3D:13:77
0000006071 [app] TRACE: RSSI: -62Bm
0000006217 [app] TRACE: MAC: 65:C7:B3:AF:73:5C
0000006219 [app] TRACE: RSSI: -39Bm
0000006224 [app] TRACE: MAC: B3:D9:F1:F0:5D:7E
0000006225 [app] TRACE: RSSI: -62Bm
0000006296 [app] TRACE: MAC: D7:E7:FE:0C:A5:C0
0000006298 [app] TRACE: RSSI: -60Bm
0000006299 [app] TRACE: UUID: feed

Notice how the message includes TRACE and also [app]? That means it's a trace message originating from the application code. Handy right?

This code does get spammy quick, especially if you're in an environment with lots of advertising Bluetooth devices. If you're Tile is on and running eventually you'll see a message UUID: feed. That means your Argon found the Tile!

Next we'll use the onboard Mode button to "program" the Tile's address to memory. That way we can filter out all the devices we don't care about.

Add Device On Button Push

First we need to figure out how to monitor the Mode button. The best bet, according to the documentation is to use System.on.

System.on(button_click, eventHandler);

The first argument is the name of the system event. In our case it's button_click. The second argument is an event handler function. We'll call it eventHandler for now.

Now let's create eventHandler

void eventHandler(system_event_t event, int duration, void* )
{

}

Important: you can't use the Log function inside eventHandler. An easy way to test it is to toggle the LED on D7. Let's set it up!

Initialize the LED in setup()

// Set LED pin
pinMode(D7,OUTPUT);

Then we can add this inside eventHandler

if( event == button_click ) {
    if( digitalRead(D7) ) {
        digitalWrite(D7,LOW);
    } else {
        digitalWrite(D7,HIGH);
    }
}

We can then write to D7 (the onboard blue LED). We can even use digitalRead to read what the state of the LED is. It will respond with HIGH or LOW depending on the situation.

Load the firmware onto the device and we'll have nice control over the blue LED!

In the next section, we'll use the Mode button to put the device into a "learning" mode. This will allow us to do a one touch setup with the target Tile device.

Storing Address to EEPROM

In this next step we'll store the address of the Tile into EEPROM. That way when the device is restarted or loses power we'll still be able to identify the Tile later on.

There is one lingering question though. How do we get it to save the address in the first place?

By monitoring the button press, we can put the device into a "learning" mode. The device will scan for a Tile, and save the address if it finds one.

First let's add a conditional within if( uuids[i].shorted() == TILE_UUID ):

// If we're in learning mode. Save to EEPROM
if( isLearningModeOn() ) {
    searchAddress = scanResult->address;
    EEPROM.put(TILE_EEPROM_ADDRESS, searchAddress);
    setLearningModeOff();
}

We'll use the status of D7 as a way of knowing we're in "learning mode". We do this by reading D7 using digitalRead(D7). Let's create a function that makes this more clear:

bool isLearningModeOn() {
    return (digitalRead(D7) == HIGH);
}

We can also replace the digitalWrite(D7,LOW); and digitalWrite(D7,HIGH); with similar functions. That way it's more straight forward what we're doing.

// Set "Learning mode" on
void setLearningModeOn() {
    digitalWrite(D7,HIGH);
}

// Set "Learning mode" off
void setLearningModeOff() {
    digitalWrite(D7,LOW);
}

Then, we assign a global variable searchAddress as the scan result. We setup searchAddress like this at the top of the file:

BleAddress searchAddress;

Next we want to save it to non-volatile memory using EEPROM.put. TILE_EEPROM_ADDRESS is defined as 0xa. You can define TILE_EEPROM_ADDRESS to use whatever memory address tickles your fancy. Here's the full definition placed at the top of the file.

#define TILE_EEPROM_ADDRESS 0xa

Finally, we turn off the LED and "learning mode" using setLearningModeOff()

Every time a device is found we'll use millis() to set lastSeen. Additionally, we can track the last RSSI using lastRSSI. It's a cheap way to to know approximately how close the device is. We'll use scanResult->rssi to get this information and set it to the lastRSSI variable.

Overall, your changes should look something like this:

...

// Print out the UUID we're looking for
if( uuids[i].shorted() == TILE_UUID ) {
    Log.trace("UUID: %x", uuids[i].shorted());

    // If we're in learning mode. Save to EEprom
    if( isLearningModeOn() ) {
        searchAddress = scanResult->address;
        EEPROM.put(TILE_EEPROM_ADDRESS, searchAddress);
        setLearningModeOff();
    }

    // Save info
    lastSeen = millis();
    lastRSSI = scanResult->rssi;

    // Stop scanning
    BLE.stopScanning();

    return;
}

Before this function, we can filter out devices that don't match our searchAddress. Add the following before if( uuids[i].shorted() == TILE_UUID ):

// If device address doesn't match or we're not in "learning mode"
if( !(searchAddress == scanResult->address) && !isLearningModeOn() ) {
    return;
}

This will skip over devices that don't match. It will only proceed if the address matches or we're in "learning mode".

Now, in order for us to load searchAddress on startup, we'll have to load it from flash. Add this line to your setup():

EEPROM.get(TILE_EEPROM_ADDRESS, searchAddress);

Then, check to make sure the address is valid. It won't be valid if all the bytes are 0xFF:

// Warning about address
if( searchAddress == BleAddress("ff:ff:ff:ff:ff:ff") ) {
    Log.warn("Place this board into learning mode");
    Log.warn("and keep your Tile near by.");
}

We should be able to "teach" our Argon the address of our Tile. Let's test it out!

Test it.

Now if we compile and run the app, notice how there's no more log output? We have to "teach" the Tile address to the Particle Device. So, hit the mode button. The blue LED should turn on.

Once your Tile has been found the LED will turn off and you'll see some output on the command line. Similar to what we've seen before:

0000006296 [app] TRACE: MAC: D7:E7:FE:0C:A5:C0
0000006298 [app] TRACE: RSSI: -60Bm
0000006299 [app] TRACE: UUID: feed

The device has been committed to memory!

You can also check if it's still saved after a reset. Hit the reset button and check for the same output as above. If it's showing up, we're still good!

Update the Cloud

Finally let's set up a function called checkTileStateChanged. We'll use it to check for changes to the state of the Tile on a regular interval.

bool checkTileStateChanged( TilePresenceType *presence ) {

}

The main purpose of this function is to compare the lastSeen variable with the "timeout" duration. In our case, our timeout duration is TILE_NOT_HERE_MS which should be set to

#define TILE_NOT_HERE_MS 30000

near the top of your program. There's also two more conditions to look for. One where lastSeen is equal to 0. This is usually because the app hasn't found the Tile yet after startup.

The last case would be if the device has been seen and lastSeen is not 0. So within checkTileStateChanged let's put everything together.

// Check to see if it's here.
if( millis() > lastSeen+TILE_NOT_HERE_MS ) {

} else if ( lastSeen == 0 ) {

} else {

}

return false;

Now we only want this function to return true if the state has changed. So we'll need to take advantage of the TilePresenceType pointer in the agreement.

TilePresenceType is simply an enumeration of all the possible states. You can stick it at the top of your file as well. Here it is:

typedef enum {
    PresenceUnknown,
    Here,
    NotHere
} TilePresenceType;

You'll also need a global variable that we can pass to the function. Set this at the top of your file as well:

// Default status
TilePresenceType present = PresenceUnknown;

Now, we can compare at each stage. Does it meet the criteria? Is the state different than the last one? If so, return true.

Remember, we'll want to set presence to the new updated value. So each condition should update the presence value. For example:

*presence = NotHere;

Here's what the fully flushed out function looks like:

bool checkTileStateChanged( TilePresenceType *presence ) {

    // Check to see if it's here.
    if( millis() > lastSeen+TILE_NOT_HERE_MS ) {
        if( *presence != NotHere ) {
            *presence = NotHere;
            Log.trace("not here!");
            return true;
        }
    // Case if we've just started up
    } else if ( lastSeen == 0 ) {
        if( *presence != PresenceUnknown ) {
            *presence = PresenceUnknown;
            Log.trace("unknown!");
            return true;
        }
    // Case if lastSeen is < TILE_NOT_HERE_MS
    } else {
        if( *presence != Here ) {
            *presence = Here;
            Log.trace("here!");
            return true;
        }
    }

    return false;
}

We can now use this function in the main loop underneath the timer to start Ble.scan(). We can use it to send a JSON payload. In this case we'll include important information like the Bluetooth Address, lastSeen data, lastRSSI data and a message.

// If we have a change
if( checkTileStateChanged(&present) ) {

}

We'll use an array of char to get our address in a string format. You can chain together toString() with toCharArray to get what we need.

// Get the address string
char address[18];
searchAddress.toString().toCharArray(address,sizeof(address));

An example payload string could look something like this:

// Create payload
status = String::format("{\"address\":\"%s\",\"lastSeen\":%d,\"lastRSSI\":%i,\"status\":\"%s\"}",
    address, lastSeen, lastRSSI, messages[present]);

status is simply a String defined at the top of the file:

// The payload going to the cloud
String status;

You notice that there's also a variable called messages. This is a static const array of strings. They're mapped to the values from the TilePresenceType. Here's what it looks like

const char * messages[] {
    "unknown",
    "here",
    "not here"
};

That way PresenceUnknown matches to "unknown", Here matches to "here", etc. It's a cheap easy way to associate a string with an enum.

Finally we'll publish and process. This allows us to send the update immediately.

// Publish the RSSI and Device Info
Particle.publish("status", status, PRIVATE, WITH_ACK);

// Process the publish event immediately
Particle.process();

The overall function should look something like this in the end:

// If we have a change
if( checkTileStateChanged(&present) ) {

    // Get the address string
    char address[18];
    searchAddress.toString().toCharArray(address,sizeof(address));

    // Create payload
    status = String::format("{\"address\":\"%s\",\"lastSeen\":%d,\"lastRSSI\":%i,\"status\":\"%s\"}",
        address, lastSeen, lastRSSI, messages[present]);

    // Publish the RSSI and Device Info
    Particle.publish("status", status, PRIVATE, WITH_ACK);

    // Process the publish event immediately
    Particle.process();

}

Now, let's test it!

Testing it!

We can test to make sure our Publish events are occurring without event leaving Particle Workbench. Open a new terminal by going to View → Terminal. Then use the following command:

particle subscribe --device <device_name> <event_name>

Replace <device_name> with the name or ID of your device.

Replace <event_name> with the name of the event. In our case it's status.

You can then test it all by removing the battery and waiting for the "not here" alert. Plug the battery back in and you should get a "here" alert.

Here's an example of the output

> particle subscribe --device hamster_turkey status

Subscribing to "status" from hamster_turkey's stream
Listening to: /v1/devices/hamster_turkey/events/status
{"name":"status","data":"{\"address\":\"C0:A5:0C:FE:E7:D7\",\"lastSeen\":40154002,\"lastRSSI\":-82,\"status\":\"not here\"}","ttl":60,"published_at":"2019-09-07T02:29:42.232Z","coreid":"e00fce68d36c42ef433428eb"}
{"name":"status","data":"{\"address\":\"C0:A5:0C:FE:E7:D7\",\"lastSeen\":40193547,\"lastRSSI\":-83,\"status\":\"here\"}","ttl":60,"published_at":"2019-09-07T02:29:50.352Z","coreid":"e00fce68d36c42ef433428eb"}

Configuring Webhook

In the last part of this tutorial we'll set up push notifications using a webhook. As mentioned before, we'll use Pushover and their handy API to send push notification(s) to the device(s) of your choice.

Pushover has a fantastically easy API to use. Their application is a Swiss army knife for situations where you don't want to code an app to send push notifications.

The first thing that you'll have to take note is your user key. You can get that by logging into Pushover. Note: you'll need to set up an account first if you haven't already.

It should look something like this:

If you're logged in and don't see this page, click on the Pushover logo and that should bring you back.

Next we'll want to create an application. Click on the Apps & Plugins at the top of the screen.

You should then click Create a New Application. This will allow us to get an API Token that will be needed in the Particle Webhook setup.

Set a name as you see fit. Fill in the description if you want a reminder. Click the box and then click Create Application.

You should go to the next page. Copy and save the API Token/Key we'll need this also in a few steps.

Now, let's setup the Webhook. Jump over to https://console.particle.io and create a new integration.

We'll set the Event Name to status.

The URL to https://api.pushover.net/1/messages.json

Also, if you want to filter by a specific device make sure you select it in the Device dropdown.

Under Advanced Settings we'll finish up by setting a few fields.

Create the following fields: token, user, title, and message. Then set token to the API Token we got earlier. Do the same for the User Key.

The title will show up as the title of your message. Make it whatever makes sense for you.

You can set the message as The Tile is currently {{{status}}}. RSSI: {{{lastRSSI}}}.

We are using mustache templates here. They allow you to use the data in the published payload and reformat it to your liking. In our case, we're using them to "fill in the blanks." The message once processed would look something like this:

The Tile is currently here. RSSI: -77

As a side note, i'll be talking more about these templates in my guide. So stay tuned for that!

Test it

Once your integration is in place, you can test doing what we did in the earlier step. Remove the battery, and wait for the "not here" message. Put it back and wait for the "here" message.

Here's what it would look like on an iPhone:

As you can see, I tested it a bunch! ?

If you've made it this far and everything is working, great work. You now have a Tile tracker for your house, office or wherever.

The Code

Looking for the finished code for this example? I would be too! It's hosted on Github and is available here.

Conclusion

As you can imagine, the techniques and technologies used in this article can be used in many ways. Let's summarize some of the key take aways:

1. Using Bluetooth Central to scan for and identify an off-the-shelf Tile device
2. Storing the Tile identifying information to EEPROM. That way it can be retrieved on startup.
3. Using our familiar Particle.publish to push updates to the cloud.
4. Using a Particle Integration Webhook to create push notifications on state change.

Now that you have it all working, expand on it, hack it and make it yours. Oh and don't forget to share! I'd love to hear from you. hello@jaredwolff.com

Like this post? Click one of the share links below and share it with the world. :)

This is a cross post from my blog. You can check out the original here.

Interested in learning more? I'm writing a guide on how to get the most out of the Particle Platform. Learn more about it here.

In a previous tutorial, you learned how to add Bluetooth to a Particle Xenon application. That way you could control the onboard RGB LED from a test app like nRF Connect or Light Blue Explorer.

In this post, we're going to take it one step further. We're going to develop a Swift app to control a Particle Mesh RGB led. If all goes well, you should have a working app in about 20 minutes!

Let's get started.

Don't have time right now to read the full article?

Download the PDF version here.

Getting set up

• Install Xcode. You can download it from the App store here.
• You'll also need an Apple login. I use my iCloud email. You can create a new account within Xcode if you don't have one yet.
• Install the RGB example code on a Particle Mesh board.

Create the project

Once everything is installed, let's get to the fun stuff!

Open Xcode and go to File → New Project.

Select Single View App.

Then update the Project Name to be to your liking. I've also changed my organization identifier to com.jaredwolff. Modify it as you see fit!

Select a location to save it.

Next find your Info.plist.

Update info.plist by adding Privacy - Bluetooth Peripheral Usage Description

The description I ended up using was App uses Bluetooth to connect to the Particle Xenon RGB Example

This allows you to use Bluetooth in your app if you ever want to release it.

Now, let's get everything minimally functional!

Minimally functional

Next, we'll get a minimally functional app to connect and do a services discovery. Most of the action will happen in the ViewController.swift.

Lets first import CoreBluetooth

    import CoreBluetooth

This allows us to control the Bluetooth Low Energy functionality in iOS. Then let's add both the CBPeripheralDelegate and CBCentralManagerDelegate to the ViewController class.

    class ViewController: UIViewController, CBPeripheralDelegate, CBCentralManagerDelegate {

Let's now create local private variables to store the actual central manager and peripheral. We'll set them up further momentarily.

    // Properties
    private var centralManager: CBCentralManager!
    private var peripheral: CBPeripheral!

In your viewDidLoad function, let's init the centralManager

    centralManager = CBCentralManager(delegate: self, queue: nil)

Setting delegate: self is important. Otherwise the central state never changes on startup.

Before we get further, let's create a separate file and call it ParticlePeripheral.swift. It can be placed anywhere but I placed it in a separate 'group' called Models for later.

Inside we'll create some public variables which contain the UUIDs for our Particle Board. They should look familiar!

    import UIKit
    import CoreBluetooth

    class ParticlePeripheral: NSObject {

        /// MARK: - Particle LED services and charcteristics Identifiers

        public static let particleLEDServiceUUID     = CBUUID.init(string: "b4250400-fb4b-4746-b2b0-93f0e61122c6")
        public static let redLEDCharacteristicUUID   = CBUUID.init(string: "b4250401-fb4b-4746-b2b0-93f0e61122c6")
        public static let greenLEDCharacteristicUUID = CBUUID.init(string: "b4250402-fb4b-4746-b2b0-93f0e61122c6")
        public static let blueLEDCharacteristicUUID  = CBUUID.init(string: "b4250403-fb4b-4746-b2b0-93f0e61122c6")

    }

Back in ViewController.swift let's piece together the Bluetooth bits.

Bluetooth bits

Everything to do with Bluetooth is event based. We'll be defining several functions that handle these events. Here are the important ones:

centralManagerDidUpdateState updates when the Bluetooth Peripheral is switched on or off. It will fire when an app first starts so you know the state of Bluetooth. We also start scanning here.

The centralManager didDiscover event occurs when you receive scan results. We'll use this to start a connection.

The centralManager didConnect event fires once the device is connected. We'll start the device discovery here. Note: Device discovery is the way we determine what services and characteristics are available. This is a good way to confirm what type of device we're connected to.

The peripheral didDiscoverServices event first once all the services have been discovered. Notice that we've switched from centralManager to peripheral now that we're connected. We'll start the characteristic discovery here. We'll be using the RGB service UUID as the target.

The peripheral didDiscoverCharacteristicsFor event will provide all the characteristics using the provided service UUID. This is the last step in the chain of doing a full device discovery. It's hairy but it only has to be done once during the connection phase!

Defining all the Bluetooth functions.

Now that we know what the functions events that get triggered. We'll define them in the logical order that they happen during a connection cycle.

First, we'll define centralManagerDidUpdateState to start scanning for a device with our Particle RGB LED Service. If Bluetooth is not enabled, it will not do anything.

    // If we're powered on, start scanning
        func centralManagerDidUpdateState(_ central: CBCentralManager) {
            print("Central state update")
            if central.state != .poweredOn {
                print("Central is not powered on")
            } else {
                print("Central scanning for", ParticlePeripheral.particleLEDServiceUUID);
                centralManager.scanForPeripherals(withServices: [ParticlePeripheral.particleLEDServiceUUID],
                                                  options: [CBCentralManagerScanOptionAllowDuplicatesKey : true])
            }
        }

Defining the centralManager didDiscover is our next step in the process. We know we've found a device if this event has occurred.

    // Handles the result of the scan
        func centralManager(_ central: CBCentralManager, didDiscover peripheral: CBPeripheral, advertisementData: [String : Any], rssi RSSI: NSNumber) {

            // We've found it so stop scan
            self.centralManager.stopScan()

            // Copy the peripheral instance
            self.peripheral = peripheral
            self.peripheral.delegate = self

            // Connect!
            self.centralManager.connect(self.peripheral, options: nil)

        }

So, we stop scanning using self.centralManager.stopScan(). We set the peripheral so it persists through the app. Then we connect to that device using self.centralManager.connect

Once connected, we need to double check if we're working with the right device.

    // The handler if we do connect succesfully
        func centralManager(_ central: CBCentralManager, didConnect peripheral: CBPeripheral) {
            if peripheral == self.peripheral {
                print("Connected to your Particle Board")
                peripheral.discoverServices([ParticlePeripheral.particleLEDServiceUUID])
            }
        }

By comparing the two peripherals we'll know its the device we found earlier. We'll kick off a services discovery using peripheral.discoverService. We can use ParticlePeripheral.particleLEDServiceUUID as a parameter. That way we don't pick up any services we don't care about.

Once we finish the discovering services, we'll get a didDiscoverServices event. We iterate through all the "available" services. (Though there will only be one!)

    // Handles discovery event
        func peripheral(_ peripheral: CBPeripheral, didDiscoverServices error: Error?) {
            if let services = peripheral.services {
                for service in services {
                    if service.uuid == ParticlePeripheral.particleLEDServiceUUID {
                        print("LED service found")
                        //Now kick off discovery of characteristics
                        peripheral.discoverCharacteristics([ParticlePeripheral.redLEDCharacteristicUUID,
                                                                 ParticlePeripheral.greenLEDCharacteristicUUID,
                                                                 ParticlePeripheral.blueLEDCharacteristicUUID], for: service)
                        return
                    }
                }
            }
        }

By this point this is the third time we're checking to make sure we have the correct service. This becomes more handy later when there are many characteristics and many services.

We call peripheral.discoverCharacteristics with an array of UUIDs for the characteristics we're looking for. They're all the UUIDs that we defined in ParticlePeripheral.swift.

Finally, we handle the didDiscoverCharacteriscsFor event. We iterate through all the available characteristics. As we iterate we compare with the ones we're looking for.

    // Handling discovery of characteristics
        func peripheral(_ peripheral: CBPeripheral, didDiscoverCharacteristicsFor service: CBService, error: Error?) {
            if let characteristics = service.characteristics {
                for characteristic in characteristics {
                    if characteristic.uuid == ParticlePeripheral.redLEDCharacteristicUUID {
                        print("Red LED characteristic found")
                    } else if characteristic.uuid == ParticlePeripheral.greenLEDCharacteristicUUID {
                        print("Green LED characteristic found")
                    } else if characteristic.uuid == ParticlePeripheral.blueLEDCharacteristicUUID {
                        print("Blue LED characteristic found");
                    }
                }
            }
        }

At this point we're ready to do a full device discovery of our Particle Mesh device. In the next section we'll test what we have to make sure things are working ok.

Testing our minimal example

Before we get started, if you run into trouble I've put some troubleshooting steps in the footnotes.

To test, you'll have to have an iPhone with Bluetooth Low Energy. Most modern iPhones have it. The last iPhone not to have it I believe was either the iPhone 4 or 3Gs. (so you're likely good)

First, plug it into your computer.

Go to the top by the play and stop buttons. Select your target device. In my case I chose my phone (Jared's iPhone). You can also use an iPad.

Then you can hit Command + R or hit that Play button to load the app to your phone.

Make sure you have your log tab open. Enable it by clicking the bottom pane button in the top right corner.

Make sure you have a mesh device setup and running the example code. You can go to this post to get it. Remember your Particle Mesh board needs to be running device OS 1.3.0 or greater for Bluetooth to work!

Once both the firmware and app is loaded, let's check the log output.

It should look something like this:

View loaded
Central state update
Central scanning for B4250400-FB4B-4746-B2B0-93F0E61122C6
Connected to your Particle Board
LED service found
Red LED characteristic found
Green LED characteristic found
Blue LED characteristic found

This means that your Phone has connected, found the LED service! The characteristics also being discovered is important here. Without those we wouldn't be able to send data to the mesh device.

Next step is to create some sliders so we can update the RGB values on the fly.

Slide to the left. Slide to the right.

Next we're going to add some elements to our Main.storyboard. Open Main.storyboard and click on the View underneath View Controller.

Then click on the Library button. (It looks like the old art Apple used for the home button)

You'll get a pop-up with all the choices that you can insert into your app.

Drag three Labels and copy three Sliders to your view.

You can double click on the labels and rename them as you go.

If you click and hold, some handy alignment tools will popup. They'll even snap to center!

You can also select them all and move them together. We'll align them vertically and horizontally.

In order for them to stay in the middle, let's remove the autoresizing property. Click the Ruler icon on the top right. Then click each of the red bars. This will ensure that your labels and sliders stay on the screen!

Next let's click the Show Assistant Editor button. (Looks like a Venn diagram)

Note: make sure that ViewController.swift is open in your Assistant Editor.

Then underneath the /properties section, Control-click and drag the Red Slider into your code.

Repeat with all the other ones. Make sure you name them something different. Your code should look like this when you're done:

        // Properties
        private var centralManager: CBCentralManager!
        private var peripheral: CBPeripheral!

        // Sliders
        @IBOutlet weak var redSlider: UISlider!
        @IBOutlet weak var greenSlider: UISlider!
        @IBOutlet weak var blueSlider: UISlider!

This allow us to access the value of the sliders.

Next, let's attach the Value Changed event to each of the sliders. Right click on the Red Slider in the folder view.

It should give you some options for events. Click and drag the Value Changed event to your code. Make sure you name it something that makes sense. I used RedSliderChanged for the Red Slider.

Repeat two more times. Your code should look like this at the end of this step:

        @IBAction func RedSliderChanged(_ sender: Any) {
        }

        @IBAction func GreenSliderChanged(_ sender: Any) {
        }

        @IBAction func BlueSliderChanged(_ sender: Any) {
        }

I've also selected each of the sliders to and un-checked Enabled. That way you can't move them. We'll enable them later on in code.

Also, this is a great time to change the maximum value to 255. Also set the default value from 0.5 to 0.

Back at the top of the file. Let's create some local variables for each of the characteristics. We'll use these so we can write the slider variables to the Particle Mesh board.

        // Characteristics
        private var redChar: CBCharacteristic?
        private var greenChar: CBCharacteristic?
        private var blueChar: CBCharacteristic?

Now, let's tie everything together!

In the didDiscoverCharacteristicsFor callback function. Let's assign those characteristics. For example

    if characteristic.uuid == ParticlePeripheral.redLEDCharacteristicUUID {
        print("Red LED characteristic found")
        redChar = characteristic

As we find each characteristic, we can also enable each of the sliders in the same spot.

            // Unmask red slider
            redSlider.isEnabled = true

In the end your didDiscoverCharacteristicsFor should look like:

    // Handling discovery of characteristics
        func peripheral(_ peripheral: CBPeripheral, didDiscoverCharacteristicsFor service: CBService, error: Error?) {
            if let characteristics = service.characteristics {
                for characteristic in characteristics {
                    if characteristic.uuid == ParticlePeripheral.redLEDCharacteristicUUID {
                        print("Red LED characteristic found")

                        redChar = characteristic
                        redSlider.isEnabled = true
                    } else if characteristic.uuid == ParticlePeripheral.greenLEDCharacteristicUUID {
                        print("Green LED characteristic found")

                        greenChar = characteristic
                        greenSlider.isEnabled = true
                    } else if characteristic.uuid == ParticlePeripheral.blueLEDCharacteristicUUID {
                        print("Blue LED characteristic found");

                        blueChar = characteristic
                        blueSlider.isEnabled = true
                    }
                }
            }
        }

Now, let's update the RedSliderChanged GreenSliderChanged and BlueSliderChanged functions. What we want to do here is update the characteristic associated with the Changed function. I created a separate function called writeLEDValueToChar. We'll pass in the characteristic and the data.

    private func writeLEDValueToChar( withCharacteristic characteristic: CBCharacteristic, withValue value: Data) {

            // Check if it has the write property
            if characteristic.properties.contains(.writeWithoutResponse) && peripheral != nil {

                peripheral.writeValue(value, for: characteristic, type: .withoutResponse)

            }

        }

Now add a call to writeLEDValueToChar to each of the Changed functions. You will have to cast the value to a Uint8. (The Particle Mesh device expects an unsigned 8-bit number.)

            @IBAction func RedSliderChanged(_ sender: Any) {
            print("red:",redSlider.value);
            let slider:UInt8 = UInt8(redSlider.value)
            writeLEDValueToChar( withCharacteristic: redChar!, withValue: Data([slider]))

        }

Repeat this for GreenSliderChanged and BlueSliderChanged. Make sure you changed red to green and blue for each!

Finally, to keep things clean, i've also added a function that handles Bluetooth disconnects.

    func centralManager(_ central: CBCentralManager, didDisconnectPeripheral peripheral: CBPeripheral, error: Error?) {

Inside, we should reset the state of the sliders to 0 and disable them.

            if peripheral == self.peripheral {
                print("Disconnected")

                redSlider.isEnabled = false
                greenSlider.isEnabled = false
                blueSlider.isEnabled = false

                redSlider.value = 0
                greenSlider.value = 0
                blueSlider.value = 0

It's a good idea to reset self.peripheral to nil that way we're not ever trying to write to a phantom device.

                self.peripheral = nil

Finally, because we've disconnected, start scanning again!

                // Start scanning again
                print("Central scanning for", ParticlePeripheral.particleLEDServiceUUID);
                centralManager.scanForPeripherals(withServices: [ParticlePeripheral.particleLEDServiceUUID],
                                                  options: [CBCentralManagerScanOptionAllowDuplicatesKey : true])
            }

Alright! We just about ready to test. Let's move on to the next (and final) step.

Test the sliders.

The hard work is done. Now it's time to play!

The easiest way to test everything is to click the Play button in the top left or the Command + R keyboard shortcut. Xcode will load the app to your phone. You should see a white screen proceeded by a screen with your sliders!

The sliders should stay greyed out until connected to your Particle Mesh board. You can check your log output if the connection has been established.

View loaded
Central state update
Central scanning for B4250400-FB4B-4746-B2B0-93F0E61122C6
Connected to your Particle Board
LED service found
Red LED characteristic found
Green LED characteristic found
Blue LED characteristic found

(Look familiar? We're connected!)

If you followed everything perfectly, you should be able to move the sliders. Better yet, the RGB LED on the Particle Mesh board should change color.

Conclusion

In this article you've learned how to connect your Particle Mesh board and iOS device over Bluetooth. We've learned how to connect to each of the available characteristics. Plus, on top of it all, make a clean interface to do it all in.

As you can imagine, you can go down the rabbit hole with Bluetooth on iOS. There's more coming in my upcoming guide: The Ultimate Guide to Particle Mesh. Subscribers to my list get access to pre-launch content and a discount when it comes out! Click here to get signed up.

Code

The full source code is available on Github. If you find it useful, hit the star button. ⭐️

This post is originally from www.jaredwolff.com

I was defeated.

I had spent the whole night trying to get a Bluetooth Low Energy project working. It was painful. It was frustrating. I was ready to give up.

That was during the early days of Bluetooth Low Energy. Since then it's gotten easier and easier to develop. The Particle Mesh Bluetooth Library is no exception.

In this walkthrough, i'll show you how to use Particle's Bluetooth API. We'll configure some LEDs and watch them change over all devices in the Mesh network. We'll be using an Argon and Xenon board.

Ready? Let's get started!

P.S. this post is lengthy. If you want something to download, click here for a beautifully formatted PDF.

Stage 1: Setting Up Bluetooth

1. Download/Install Particle Workbench

2. Create a new Project. I picked a suitable location and then named it ble_mesh

   

3. Go to your /src/ direcory and open your <your project name>.ino file

4. Then make sure you change the version of your deviceOS to > 1.3.0

   

Write the Code

We want to set up a service with 3 characteristics. The characteristics relate to the intensity of the RGB LEDs respectively. Here's how to get your Bluetooth Set Up:

1. In your Setup() function enable app control of your LED

    RGB.control(true);
   

2. Set up your UUIDs at the top of your .ino file

   const char serviceUuid = "6E400001-B5A3-F393-E0A9-E50E24DCCA9E"; const char red = "6E400002-B5A3-F393-E0A9-E50E24DCCA9E"; const char green = "6E400003-B5A3-F393-E0A9-E50E24DCCA9E"; const char blue = "6E400004-B5A3-F393-E0A9-E50E24DCCA9E";

   UUIDs are unique identifiers or addresses. They're used to differentiate different services and characteristics on a device.

   The above UUIDs are used in previous Particle examples. If you want to create your own you can use uuidgen on the OSX command line. You can also go to a website like Online GUID Generator.

   

   Use the above settings to get your own UUID. You can then create your service and characteristic UUIDS from this generated one:

   const char serviceUuid = "b4250400-fb4b-4746-b2b0-93f0e61122c6"; //service const char red = "b4250401-fb4b-4746-b2b0-93f0e61122c6"; //red char const char green = "b4250402-fb4b-4746-b2b0-93f0e61122c6"; //green char const char blue = "b4250403-fb4b-4746-b2b0-93f0e61122c6"; //blue char

   There's no right or wrong way to do this. But you have to be careful you're not using the UUIDs reserved by the Bluetooth SIG. This is highly unlikely. If you do want to double check you can go here and here.

   For now, we'll stick with the first set of UUIDs.

3. In Setup(), initialize your service.

   // Set the RGB BLE service BleUuid rgbService(serviceUuid);

   This is the first step of "registering' your service. More on this below.

4. Initialize each characteristic in Setup()

   BleCharacteristic redCharacteristic("red", BleCharacteristicProperty::WRITE_WO_RSP, red, serviceUuid, onDataReceived, (void)red); BleCharacteristic greenCharacteristic("green", BleCharacteristicProperty::WRITE_WO_RSP, green, serviceUuid, onDataReceived, (void)green); BleCharacteristic blueCharacteristic("blue", BleCharacteristicProperty::WRITE_WO_RSP, blue, serviceUuid, onDataReceived, (void*)blue);

   For this setup, we're going to use the WRITE_WO_RSP property. This allows us to write the data and expect no response. I've referenced the UUIDs as the next two parameters. The first being the characteristic UUID. The second being the service UUID.

   The next parameter is the callback function. When data is written to this callback, this function will fire.

   Finally the last parameter is the context. What does this mean exactly? We're using the same callback for all three characteristics. The only way we can know which characteristic was written to (in deviceOS at least) is by setting a context. In this case we're going to use the already available UUIDs.

5. Right after defining the characteristics, let's add them so they show up:

   // Add the characteristics BLE.addCharacteristic(redCharacteristic); BLE.addCharacteristic(greenCharacteristic); BLE.addCharacteristic(blueCharacteristic);

6. Set up the callback function.

   // Static function for handling Bluetooth Low Energy callbacks static void onDataReceived(const uint8_t data, size_t len, const BlePeerDevice& peer, void context) {

   }

   You can do this at the top of the file (above Setup()) We will define this more later.

7. Finally, in order for your device to be connectable, we have to set up advertising. Place this code at the end of your Setup() function

   // Advertising data BleAdvertisingData advData;

   // Add the RGB LED service advData.appendServiceUUID(rgbService);

   // Start advertising! BLE.advertise(&advData);

   First we create a BleAdvertisingData object. We add the rgbService from Step 3. Finally, we can start advertising so our service and characteristics are discoverable!

Time to test

At this point we have a minimally viable program. Let's compile it and program it to our Particle hardware. This should work with any Mesh enabled device. (Xenon, Argon, Boron)

1. Before we start testing, temporarily add SYSTEM_MODE(MANUAL); to the top of your file. This will prevent the device connecting to the mesh network. If the device is blinking blue on startup, you'll have to set it up with the Particle App before continuing.

2. Download the 1.3.0-rc.1 image here. For Xenon, you'll need xenon-system-part1@1.3.0-rc.1.bin. For others look for boron-system-part1@1.3.0-rc.1.bin and argon-system-part1@1.3.0-rc.1.bin. The files are at the bottom of the page under Assets

   

3. Put your device into DFU mode. Hold the Mode Button and momentarily click the Reset Button. Continue holding the Mode Button until the LED blinks yellow.

4. In a command line window, change directories to where you stored the file you downloaded. In my case the command is cd ~/Downloads/

5. Then run:

   particle flash --usb xenon-system-part1@1.3.0-rc.1.bin

   This will install the latest OS to your Xenon. Once it's done it will continue to rapidly blink yellow. Again if you have a different Particle Mesh device, change the filename to match.

6. In Visual Code, use the Command + Shift + P key combination to pop up the command menu. Select Particle: Compile application (local)

   

7. Fix any errors that may pop up.

8. Then, open the same menu and select Flash application (local)

   

9. When programming is complete, pull out your phone. Then, open your favorite Bluetooth Low Energy app. The best ones are NRF Connect and Light Blue Explorer. I'm going to use Light Blue Explorer for this example.

10. Check if a device named "Xenon-" is advertising. Insert with the unique ID for your device.

    

11. Find your device and click the name.

12. Look at the list of services & characteristics. Does it include the service and characteristic UUID's that we have set so far? For instance, does the service UUID show up as 6E400001-B5A3-F393-E0A9-E50E24DCCA9E?

    

    If everything shows up as you expect, you're in a good place. If not go through the earlier instructions to make sure everything matches.

Stage 2: Handling Data

The next stage of our project is to process write events. We'll be updating our onDataReceived function.

Write the Code

1. First, let's create a struct that will keep the state of the LEDs. This can be done at the top of the file.

   // Variables for keeping state typedef struct { uint8_t red; uint8_t green; uint8_t blue; } led_level_t;

2. The second half of that is to create a static variable using this data type

   // Static level tracking static led_level_t m_led_level;

   The first two steps allows us to use one single variable to represent the three values of the RGB LED.

3. Next, let's check for basic errors inside the onDataReceive function For instance we want to make sure that we're receiving only one byte.

   // We're only looking for one byte if( len != 1 ) { return; }

4. Next, we want to see which characteristic this event came from. We can use the context variable to determine this.

   // Sets the global level if( context == red ) { m_led_level.red = data[0]; } else if ( context == green ) { m_led_level.green = data[0]; } else if ( context == blue ) { m_led_level.blue = data[0]; }

   Remember, in this case context will be equal to the pointer of either the red, green, or blue UUID string. You can also notice we're setting m_led_level. That way we can update the RGB led even if only one value has changed.

5. Finally, once set, you can write to the RGB object

   // Set RGB color RGB.color(m_led_level.red, m_led_level.green, m_led_level.blue);

Test the Code

Let's go through the same procedure as before to flash the device.

1. Put your device into DFU mode. Hold the Mode Button and click the Reset Button. Continue holding the Mode Button until the LED blinks yellow.

2. Then, open the same menu and select Flash application (local)

   

3. Once it's done programming, connect to the device using Light Blue Explorer.

4. Tap on the characteristic that applies to the red LED.

5. Write FF. The red LED should turn on.

   

   

6. Write 00. The red LED should turn off.

7. Do the same for the other two characteristics. We now have full control of the RGB LED over Bluetooth Low Energy!

Stage 3: Sharing Via Mesh

Finally, now that we're successfully receiving BLE message, it's time to forward them on to our mesh network.

Write the Code

1. First let's remove MANUAL mode. Comment out SYSTEM_MODE(MANUAL);

2. At the top of the file let's add a variable we'll used to track if we need to publish

   // Tracks when to publish to Mesh static bool m_publish;

3. Then initialize it in Setup()

   // Set to false at first m_publish = false;

4. Then, after setting the RGB led in the onDataReceived callback, let's set it true:

   // Set RGB color RGB.color(m_led_level.red, m_led_level.green, m_led_level.blue);

   // Set to publish m_publish = true;

5. Let's add a conditional in the loop() function. This will cause us to publish the LED status to the Mesh network:

   if( m_publish ) { // Reset flag m_publish = false;

   // Publish to Mesh Mesh.publish("red", String::format("%d", m_led_level.red)); Mesh.publish("green", String::format("%d", m_led_level.green)); Mesh.publish("blue", String::format("%d", m_led_level.blue)); }

   Mesh.publish requires a string for both inputs. Thus, we're using String::format to create a string with our red, green and blue values.

6. Then let's subscribe to the same variables in Setup(). That way another device can cause the LED on this device to update as well.

   Mesh.subscribe("red", meshHandler); Mesh.subscribe("green", meshHandler); Mesh.subscribe("blue", meshHandler);

7. Toward the top of the file we want to create meshHandler

   // Mesh event handler static void meshHandler(const char event, const char data) { }

8. In this application, we need the event parameter and data parameter. In order use them, we have to change them to a String type. That way we can use the built in conversion and comparison functions. So, inside the meshHandler function add:

   // Convert to String for useful conversion and comparison functions String eventString = String(event); String dataString = String(data);

9. Finally we do some comparisons. We first check if the event name matches. Then we set the value of the dataString to the corresponding led level.

   // Determine which event we recieved if( eventString.equals("red") ) { m_led_level.red = dataString.toInt(); } else if ( eventString.equals("green") ) { m_led_level.green = dataString.toInt(); } else if ( eventString.equals("blue") ) { m_led_level.blue = dataString.toInt(); } else { return; }

   // Set RGB color RGB.color(m_led_level.red, m_led_level.green, m_led_level.blue);

   Then at the end we set the new RGB color. Notice how I handle an unknown state by adding a return statement in the else section. It's always good to filter out error conditions before they wreak havoc!

Test the Code

1. Open the Particle App on your phone

2. Let's set up the Argon first. If it's not blinking blue, hold the mode button until it's blinking blue.

   

   Note: if you've already programmed the app, the LED will be off by default. Hold the mode button for 5 seconds and then continue.

3. Go through the pairing process. The app walks you though all the steps. Make sure you remember the Admin password for your mesh network.

   

   

   

   

4. Program an Argon with the latest firmware (1.3.0) (see Stage 1 - Time to Test - Step 2 for a reminder on how to do this)

5. Once rapidly blinking yellow, program the Argon with the Tinker app. You can download it at the release page.

6. Once we have a nice solid Cyan LED (connected to the Particle Cloud) we'll program the app. Use the Cloud Flash option in the drop down menu.

   

   As far as I can tell, Particle forces any device flashed locally into safe mode when connecting to the cloud. It may be my setup. Your mileage may vary here. Best to use Cloud Flash.

   Make sure you select the correct deviceOS version (1.3.0-rc1), device type (Argon) and device name (What you named it during setup)

7. Connect to the Xenon using the phone app

8. Connect the Xenon to your Mesh network using the phone app

9. Flash your Xenon using Cloud Flash. Use the name that you gave it during the phone app setup. As long as the device is connected to Particle Cloud or in safe mode (Purple LED), it should program.

   

   

10. Once connected, let's get to the fun part. Open up Light Blue Explorer. Connect to either the Argon or the Xenon.

    

11. Select one of the LED characteristics and change the value.

    

    The LED should change on all devices!

Final Code

Here's the final code with all the pieces put together. You can use this to make sure you put them in the right place!!

/*

• Project ble_mesh
• Description: Bluetooth Low Energy + Mesh Example
• Author: Jared Wolff

• Date: 7/13/2019 */

  //SYSTEM_MODE(MANUAL);

  // UUIDs for service + characteristics const char serviceUuid = "6E400001-B5A3-F393-E0A9-E50E24DCCA9E"; const char red = "6E400002-B5A3-F393-E0A9-E50E24DCCA9E"; const char green = "6E400003-B5A3-F393-E0A9-E50E24DCCA9E"; const char blue = "6E400004-B5A3-F393-E0A9-E50E24DCCA9E";

  // Set the RGB BLE service BleUuid rgbService(serviceUuid);

  // Variables for keeping state typedef struct { uint8_t red; uint8_t green; uint8_t blue; } led_level_t;

  // Static level tracking static led_level_t m_led_level;

  // Tracks when to publish to Mesh static bool m_publish;

  // Mesh event handler static void meshHandler(const char event, const char data) {

  // Convert to String for useful conversion and comparison functions String eventString = String(event); String dataString = String(data);

  // Determine which event we recieved if( eventString.equals("red") ) { m_led_level.red = dataString.toInt(); } else if ( eventString.equals("green") ) { m_led_level.green = dataString.toInt(); } else if ( eventString.equals("blue") ) { m_led_level.blue = dataString.toInt(); } else { return; }

  // Set RGB color RGB.color(m_led_level.red, m_led_level.green, m_led_level.blue);

  }

  // Static function for handling Bluetooth Low Energy callbacks static void onDataReceived(const uint8_t data, size_t len, const BlePeerDevice& peer, void context) {

  // We're only looking for one byte if( len != 1 ) { return; }

  // Sets the global level if( context == red ) { m_led_level.red = data[0]; } else if ( context == green ) { m_led_level.green = data[0]; } else if ( context == blue ) { m_led_level.blue = data[0]; }

  // Set RGB color RGB.color(m_led_level.red, m_led_level.green, m_led_level.blue);

  // Set to publish m_publish = true;

  }

  // setup() runs once, when the device is first turned on. void setup() {

  // Enable app control of LED RGB.control(true);

  // Init default level m_led_level.red = 0; m_led_level.green = 0; m_led_level.blue = 0;

  // Set to false at first m_publish = false;

  // Set the subscription for Mesh updates Mesh.subscribe("red",meshHandler); Mesh.subscribe("green",meshHandler); Mesh.subscribe("blue",meshHandler);

  // Set up characteristics BleCharacteristic redCharacteristic("red", BleCharacteristicProperty::WRITE_WO_RSP, red, serviceUuid, onDataReceived, (void)red); BleCharacteristic greenCharacteristic("green", BleCharacteristicProperty::WRITE_WO_RSP, green, serviceUuid, onDataReceived, (void)green); BleCharacteristic blueCharacteristic("blue", BleCharacteristicProperty::WRITE_WO_RSP, blue, serviceUuid, onDataReceived, (void*)blue);

  // Add the characteristics BLE.addCharacteristic(redCharacteristic); BLE.addCharacteristic(greenCharacteristic); BLE.addCharacteristic(blueCharacteristic);

  // Advertising data BleAdvertisingData advData;

  // Add the RGB LED service advData.appendServiceUUID(rgbService);

  // Start advertising! BLE.advertise(&advData); }

  // loop() runs over and over again, as quickly as it can execute. void loop() {

  // Checks the publish flag, // Publishes to a variable called "red" "green" and "blue" if( m_publish ) {

  // Reset flag m_publish = false;

  // Publish to Mesh Mesh.publish("red", String::format("%d", m_led_level.red)); Mesh.publish("green", String::format("%d", m_led_level.green)); Mesh.publish("blue", String::format("%d", m_led_level.blue)); }

  }

Conclusion

In this tutorial you learned how to add Bluetooth to a Particle Mesh project. As you can imagine, the possibilities are endless. For instance you can add user/administrative apps into the experience. Now that's awesome. ?

You can expect more content like this in my upcoming book: The Ultimate Guide to Particle Mesh. Subscribe to my list for updates and insider content. Plus all early subscribers get a discount when it's released! Click here to sign up.

This post is originally from www.jaredwolff.com

In Part 1 we’ve learned the anatomy of a Protocol Buffer. In Part 2 we’ve learned how a Bluetooth Low Energy Service gets pieced together on the Nordic NRF52 SDK. This final post brings together all the elements in an end-to-end working example.

Let’s get going!

P.S. this post is lengthy. If you want something to download, click here for a a beautifully formatted PDF. (Added bonus, the PDF has all three parts of this series!)

Setting Everything Up

Go look at the Readme.md in each of the example repositories. (You will have to clone the repositories, sign up here to get the code).

I’ve made the setup for the firmware dead simple. For the javascript side, it’s a bit more hairy but’ doable! I’ll also include the instructions here as well:

Firmware Setup (For Mac)

1. Initialize the full repository (there are submodules!): git submodule update --init
2. Install protoc using Homebrew: brew install protobuf
3. Run make sdk. This will download your SDK files.
4. Run make tools_osx. This will download your ARMGCC toolchain (for Mac). For other environments see below.
5. Run make gen_key once (and only once)! This will set up your key for DFU.
6. Run make and this will build your bootloader and main app.

Note: You only have to do steps 1-5 once.

Javascript App Setup (For Mac)

Prerequisite: you will need Xcode command line tools. You can get those here.

1. Clone this repo to a place on your computer
2. Make sure you have nvm installed
3. Run nvm install v8.0.0
4. Run nvm install v10.15.3
5. Run nvm use v8.0.0
6. Run yarn (if you don’t have yarn npm install yarn -g)
7. Once installed, run nvm use v10.15.3
8. Then run node index.js to start the example

Using NVM helps mitigate a compile issue with the Bluetooth library. You mileage may vary on this one.

How the heck does this work?

In this project, the Protocol Buffer has two functions. The first as a “command” to the bluetooth device. Secondly, a “response” to that command from the device.

Our example javascript app command uses “This is” as the payload. With the power of some string operations, let's make a full sentence out of it!

The series of events looks something like this:

1. The test app connects and sends that data using our Bluetooth Low Energy service.
2. On the firmware decodes the message.
3. The firmware modifies the original data by adding “ cool.” Resulting in "This is cool"
4. The firmware encodes the payload and makes the data available for reading.
5. The app finally reads the characteristic, decodes and displays the result!

Seems complicated but there's some benefits to this:

1. In Protocol Buffers, data structures are well defined. This means that it has some great error checking abilities. If you're using any type of data structure you may have to code your own data validation.
2. Encoding and decoding is simple and straight forward. You can encode same data on different platforms and always get the same decoded result.

Want to get the example up and running? Seeing is believing after all. Let's do this.

Is This Thing On?

Once you're done with the setup (above), let's get this firmware programmed! Lucky for you it's only two quick steps!

1. Plug in your NRF52 DK board
2. Run make flash_all. (This compiles and flashes all the code for the project.)

Once flashed, the easiest way to know if things are working is when Led 1 is blinking. That means it’s advertising and ready for a connection.

Let’s make sure it’s advertising correctly though. You can grab a tool like NRF Connect for iOS or Android. Or, you can grab LightBlue. (Also available for iOS and Android)

Open up one of the app and scan for advertising devices. You’ll be looking for Nordic_Buttonless.

Now let’s connect and double check our connectable services & characteristics:

As you can see there are two services. One is Nordic’s DFU service. The other is our Protocol Buffer service!

You can compare PROTOBUF_UUID_BASE in ble_protobuf.h with the UUID of the “Unknown Service”. Nordic’s chips are Little Endian while the data here is Big Endian format. (i.e. you’ll have to reverse the bytes to see that they’re the same!)

You can even click in further to see the characteristics in NRF Connect. In the case of LightBlue, the characteristic UUIDs are already shown.

Using the Javascript App

So, once we’re up and advertising, it’s time to run the app.

Simply change to the ble-protobuf-js directory and run node index.js

If you've installed everything correctly, you should start seeing output like:

example started scanning peripheral with ID 06f9b62ec5334454875b9f53d2f3fa74 found with name: Nordic_Buttonles

It should then immediately connect and send data to the device. It should receive the response immediately and print it to the screen.

connected to Nordic_Buttonles Sent: This is Received: This is cool.

Bingo!

You’ve made it!

? Congrats if you made it this far through the tutorial. You should now be feeling confident enough to start playing with the software code. Maybe you’ll cook up something cool?

Here’s links to some resources that you may find handy.

• Protocol Buffer documentation
• NanoPB - (the implementation of Protocol Buffers we used for this project)
• Nordic SDK Documentation
• Again, here are the links to Part 1 and Part 2
• If you haven’t already, get all the code for this project

Conclusion

Protocol Buffers are quite versatile and convenient. Using them with Bluetooth Low Energy service is one way that you can take advantage. As the connected world of IoT continues to expand, I have no doubt that we'll be seeing more use cases in the future!

I hope this has inspired you to incorporate Protocol Buffers into your own project(s). Make sure you download the sample code and get started right now.

Has this tutorial been useful for you? Let me know what you think.

This post is originally from www.jaredwolff.com.

This is Part 2 of configuring your own Bluetooth Low Energy Service using a Nordic NRF52 series processor. If you haven’t seen Part 1 go back and check it out. I’ll be waiting right here..

If you’re with me thus far, high five. ?

Let’s jump in!

So far we’ve created an efficient cross platform data structure using Protocol Buffers. This Protocol Buffer in particular can be used to send these defined data structures a Bluetooth Low Energy Service. In this part, I’ll show you the inner workings of creating the service from scratch.

P.S. this post is lengthy. If you want something to download, click here for a a beautifully formatted PDF. (Added bonus, the PDF has all three parts of this series!)

Creating the Service

Dealing with Bluetooth Low Energy in general can seem overwhelming. As I discussed here, there’s a few moving parts that you need to keep in mind.

The best way to create a new service is to copy an already existing one! I’ve done this by:

1. Go to the sdk -> components -> ble -> ble_services -> ble_bas
2. Copy ble_bas.h to include/ble
3. Copy ble_bas.c to src/ble

I’ve then renamed them from ble_bas to ble_protobuf to be consistent. I’ve also done the same inside the files. (BAS is the battery level service used to report battery voltage or relative charge using a percentage)

I’ve also gone ahead and removed all the battery measurement functions as they will be replaced. This part of the process is fairly tedious and prone to error. If you’re new to the Nordic SDK, I highly recommend you download the example code for this post.

Adding a UUID

Normally, for a vendor defined service you’ll have to use your own UUID. There are certain ranges of UUIDs that are reserved for the Bluetooth SIG. Supposedly you can also reserve your own UUID if you’re a member. Here’s a handy post on Stack Overflow on the subject.

In our case, I’ve defined a UUID that I’ve used for other projects. If you go to ble_protobuf.h you can see the UUIDs for both the service and the characteristic:

// UUID for the Service & Char
#define PROTOBUF_UUID_BASE   {0x72, 0x09, 0x1a, 0xb3, 0x5f, 0xff, 0x4d, 0xf6, \
                               0x80, 0x62, 0x45, 0x8d, 0x00, 0x00, 0x00, 0x00}
#define PROTOBUF_UUID_SERVICE     0xf510
#define PROTOBUF_UUID_CONFIG_CHAR (PROTOBUF_UUID_SERVICE + 1)

Both PROTOBUF_UUID_BASE PROTOBUF_UUID_SERVICE are used in ble_protobuf_init The last one is used in command_char_add (I’ll describe that a bit more below).

You can go without defining a BASE ID but I highly recommend you go the extra mile. That way your application will be impervious to future Bluetooth protocol updates.

Creating the Characteristic

Nordic has a fairly straight forward way of initializing separate characteristics in each service. For each characteristic, there is a char_add function which then configures and add the characteristic to the service.

Configure your Characteristic withble_add_char_params_t

Nordic has put the configurations parameters for a BLE Characteristic into a logical (and helpful) struct. If you’re developing on a different platform you may find the same settings though all not in one place! (Or handled logically… ?)

Here’s the breakdown of the struct:

typedef struct
{
    uint16_t                    uuid;
    uint8_t                     uuid_type;
    uint16_t                    max_len;
    uint16_t                    init_len;
    uint8_t *                   p_init_value;
    bool                        is_var_len;
    ble_gatt_char_props_t       char_props;
    ble_gatt_char_ext_props_t   char_ext_props;
    bool                        is_defered_read;
    bool                        is_defered_write;
    security_req_t              read_access;
    security_req_t              write_access;
    security_req_t              cccd_write_access;
    bool                        is_value_user;
    ble_add_char_user_desc_t    *p_user_descr;
    ble_gatts_char_pf_t         *p_presentation_format;
} ble_add_char_params_t;

It’s here that you tell the BLE Stack about what type of characteristic this is. In this example I use a handful of parameters to define the Protobuf Command Characteristic.

uuid defines the address of how the characteristic will be accessed. If you’re defining your own service. max_len is the maximum length of data that you may send though the characteristic. That’s why it’s important to set max_size in your Protocol Buffer .options file for all variable length parameters. Once you compile your Protocol Buffers you’ll get a *_size variable much like the one defined in command.pb.h Here's a snippet of what it looks like below:

/* Maximum encoded size of messages (where known) */
#define event_size                               67

Thus when defining ble_add_char_params_t I set max_len to event_size:

add_char_params.uuid                      = PROTOBUF_UUID_CONFIG_CHAR;
add_char_params.max_len                   = event_size;
add_char_params.is_var_len                = true;

Along the same lines, because we’re using a string as one of the parameters in the Protocol Buffer, this data can be of variable size. is_var_len is handy to make sure that the right amount of bytes is sent and received. The decode function of the Protocol Buffers will fail if more data is fed in than necessary. (I learned this the hard way!)

char_props define the permissions for the characteristic. If you’re familiar with file system permissions on a computer, this will be second nature to you. In this example, read and write is what we’re looking for.

Finally, parameters ending in _access determine the security type used. In most cases SEC_OPEN or SEC_JUST_WORKSis more than sufficient. If you’re handling critical data (passwords, etc) you may have to implement a second layer of encryption or enable a higher level security mode.

If you’re looking on more info about Bluetooth Low Energy security, here’s a useful post on the subject.

Add. dat. char.

Once you’ve defined your params, it’s as easy as calling the characteristic_add function. This will associate this new characteristic with the related service. The first argument is the service handle, the second the configuration parameters and the third is a pointer to the handles for the characteristic. (See below)

uint32_t characteristic_add(uint16_t                   service_handle,
                            ble_add_char_params_t *    p_char_props,
                            ble_gatts_char_handles_t * p_char_handle)

Getting it Running

Setting everything up inside ble_protobuf.c is 90% of the battle. The final mile requires some bits being added to services_init in main.c

    ble_protobuf_init_t       protobuf_init = {0};

    protobuf_init.evt_handler          = ble_protobuf_evt_hanlder;
    protobuf_init.bl_rd_sec            = SEC_JUST_WORKS;
    protobuf_init.bl_cccd_wr_sec       = SEC_JUST_WORKS;
    protobuf_init.bl_wr_sec            = SEC_JUST_WORKS;

    err_code = ble_protobuf_init(&m_protobuf,&protobuf_init);
    APP_ERROR_CHECK(err_code);

The above allows events to be funneled back to the main context. That way your app becomes much more interactive with the core logic of your firmware code. In Nordic’s examples they’ve also brought the security parameters out so they can be defined in the main context as well.

Side note: m_protobuf is defined using a macro from ble_protobuf.h It not only creates a static instance of the service but it also defines the callback that is used for handling events.

/**@brief Macro for defining a ble_protobuf instance.
 *
 * @param   _name  Name of the instance.
 * @hideinitializer
 */
#define BLE_PROTOBUF_DEF(_name)                          \
    static ble_protobuf_t _name;                         \
    NRF_SDH_BLE_OBSERVER(_name ## _obs,             \
                         BLE_PROTOBUF_BLE_OBSERVER_PRIO, \
                         ble_protobuf_on_ble_evt,        \
                         &_name)

If you're making your own service, you'll have to update the function name for the event handler. If you need to tweak priorities you can define/update that as well.

What happens when this characteristic is written to?

ble_protobuf_on_ble_evt is the main way that events are handled within Bluetooth Low Energy services. We’re most concerned with the BLE_GATTS_EVT_WRITE event but you can trigger on any GATT event that tickles your fancy.

on_write is where the action happens. It takes the data that is written to the characteristic and decodes it according to event_fields It’s all put conveniently into a struct for additional processing, etc. If an error happens in decoding, pb_decode returns an error. Once modified, the data is encoded and made available for reading. Since reading Part 1, the calls to pb_decode and pb_encode should look very familiar!

Of course, you can have your firmware do whatever you want to. The Bluetooth Energy World is your oyster.

Final Notes

When adding new services to a Bluetooth Low Energy example, you may have to make some changes to the underlying code.

For example, sdk_config.h may need some changes. Particularly NRF_SDH_BLE_VS_UUID_COUNT needs to be increased depending how many service UUIDs are made available. For this project, I am also using the DFU service (as it should be a default for all connected projects!!)

Another important aspect is memory and flash management. The default .ld file that comes with the BLE DFU service may not be sufficient for another BLE Service. The only way you’ll know there’s not enough is when you compile and flash it to a NRF52 device. If the device boots up stating there’s not enough memory, you’ll have to make the suggested changes. The error will show up on the debug console where this message normally shows up:

<info> app: Setting vector table to bootloader: 0x00078000
<info> app: Setting vector table to main app: 0x00026000

Learn more about how to get the Debug Console set up in the example code here.

Conclusion

In this part I’ve shown you the inner workings of a custom Bluetooth Low Energy service using Protocol Buffers. In the last part, I’ll show you how to load the firmware, run the example javascript app and test our freshly developed Protocol Buffer!

This post is originally from www.jaredwolff.com

One of the most confusing things about Bluetooth Low Energy is how data is moved around. Depending on your application, your device state may be fairly complex. That means having an individual endpoint for every piece of data is suicide by Bluetooth.

So, what’s he solution?

Protocol Buffers.

A protocol buffer is a programatic way to encode/decode optimized structured data. They can be shared and manipulated across almost any platform. Nordic actually uses a variant of it for their DFU service.

There was a lot of buzz words in the first few sentences. Hopefully, by the end of this post you’ll understand exactly what I’m talking about.

In this tutorial, i'll include fully flushed out example code that you can clone and start using immediately. All you need is one of these:

So, how do you use this magical software?

Read on!

P.S. this post is lengthy. If you want something to download, click here for a a beautifully formatted PDF. (Added bonus, the PDF has all three parts of this series!)

Install

The first part of the process is to make sure you’ve installed all the correct utilities. Depending on what programming language will determine what you install and use. In this case I’ll outline the utilities that I have used for several projects in the past using C, Go and Javascript.

protoc is the most important utility you’ll have to install here. It's the Protobuf "compiler" which takes your .proto and .options files and turns them into static code.

1. For Mac, download the appropriate release here.
2. Unzip the folder
3. Run ./autogen.sh && ./configure && make in the folder
4. If you get an error autoreconf: failed to run aclocal: No such file or directory install autoconf using Homebrew:

brew install autoconf && brew install automake

Then, re-run step 3.

1. Then run:

make check
sudo make install
which protoc

Consider protoc the compiler for Protocol Buffers. It can either output raw files or libraries directly. That’s because it’s got Go support built in.

That raw data can also be used to generate static libraries for other languages. That usually requires an extra utility (or utilities). I describe the two that the Dondi Lib project used below.

2. nanopb is a python script used to create C libraries that encode/decode your structured data. It can be installed by navigating to the nanopb git repo and downloading the appropriate files. The most important pieces to include:

3. pb_encode.c, pb_decode.c and pb_common.c

4. /generator/nanopb_generator.py

5. And the /generator/nanopb/directory co-located with nanopb_generator.py

   nanopb is meant for deployment on embedded platforms. It's different from protoc-c (the regular C variant) because it is optimized for resource constrained systems like embedded processors. Buffers have finite sizes. There's no memory allocation! Depending on if there's bi-directional communication, you can only import and use the encoding functionality or decoding functionality.

6. pbjs uses the output from protoc to generate a static javascript library. This is powerful because you can then use it in any javascript application. The best way to install pbjs is by running:

      npm install -g protobufjs
   

I've simplified this step a bit in the example code. Get started by cloning the repos here.

Setting up the protocol buffer

Create a file called command.proto. You can make the contents of that file what's below:

syntax = "proto3";

message event {
  enum event_type {
    command = 0;
    response = 1;
  }
  event_type type = 1;
  string message = 2;
}

It may look foreign at first but once you take a deeper look, it’s not that much different than a standard C struct or hash table.

I'm using two types of data in this example: a string and enum as a type. There are actually a few more which you can read up at the documentation. When compiled, the equivalent c struct looks like:

/* Struct definitions */
typedef struct _event {
    event_event_type type;
    char message[64];
/* @@protoc_insertion_point(struct:event) */
} event;

Where event_event_type is

/* Enum definitions */
typedef enum _event_event_type {
    event_event_type_command = 0,
    event_event_type_response = 1
} event_event_type;

You can nest as many messages inside each other as your hearts content. Typically though, a message is as small as possible so data transmission is as efficient as possible. This is particularly important for resource constrained systems or LTE deployments where you're charged for every megabyte used. Note: when elements are not used or defined they are typically not included in the encoded Protocol Buffer payload.

Normally, when you create a generic message like this, there is no limit to the size of the string message. That option can be set in the .options file:

event.message    max_size:64

This way, the memory can be statically allocated in my microprocessor code at compile time. If the message size is greater than 64 bytes then it will get chopped off in the code (or you'll simply get an error during decode). It's up to you, the software engineer, to figure out the absolute maximum amount of bytes (or characters) that you may need for this type of data.

You can look at more of the nanopb related features at their documentation.

Generating the appropriate static libraries

In order to make this as easy as possible, I put all the following code into a Makefile. When you make a change to the Protocol Buffer, that every library for every language used gets generated.

If we want to generate a static Go file the command looks like:

protoc -I<directory with .proto> --go_out=<output directory> command.proto

If you've installed the nanopb plugin, you can do something similar to generate C code:

protoc -I<directory with .proto> -ocommand.pb command.proto
<path>/<to>/protogen/nanopb_generator.py -I<directory with .proto> command

The first file creates a generic "object" file. The second actually creates the static C library.

For javascript:

pbjs -t static-module -p<directory with .proto> command.proto > command.pb.js

You can test each of these commands with the .proto and .options file examples above. I also built this manual process into one command in the example repository. Get access here.

Encoding and Decoding

In the examples below, I show you how to use your freshly compiled static code! This is where the fun begins.

Encoding using Javascript

Here’s a typical flow that you can follow when using a statically generated javascript library. First, initialize the library.

// Import the config message
var protobuf  = require('./command.pb.js');

Then create an instance of event:

// setup command
var event = protobuf.event.create();
event.type = protobuf.event.event_type.command;
event.message = "This is";

Then, compile the payload. i.e. turn human readable JSON into nicely packed binary. See below.

// make sure it's valid
var err = protobuf.event.verify(event);
if( err != null ) {
   console.log("verify failed: " + err);
   return;
}

You'll get errors during this step if your object is malformed or if if you are missing required elements. I don't recommend using the required prefix when defining your .proto file. Any checks for required elements can be easily done in your application code.

Finally, the last step is to encode and turn it into raw bytes:

// encode into raw bytes
var payload = protobuf.event.encode(event).finish();

You can then use payload and send it over BLE, HTTP or whatever. If there's a communication protocol, you can send this buffer over it!

Decoding in C

Once the data is received it’s decoded on the embedded end. nanopb is confusing. But luckily I have some code here that will work for you:

// Setitng up protocol buffer data
event evt;

// Read in buffer
pb_istream_t istream = pb_istream_from_buffer((pb_byte_t *)data, data_len);

if (!pb_decode(&istream, event_fields, &evt)) {
   NRF_LOG_ERROR("Unable to decode: %s", PB_GET_ERROR(&istream));
   return;
}

// Validate code & type
if( evt.type != event_event_type_command ) {
   return;
}

First, you create an input stream based on the raw data and the size of the data.

Then, you use the pb_decode function. You point the first argument to the input stream. The second to the definition of our Protocol Buffer we’ve been working with. It's located in the command.pb.h file.

/* Defines for backwards compatibility with code written before nanopb-0.4.0 */
#define event_fields &event_msg

The last argument is a pointer to the struct to put the decoded data into. (In this case it's evt defined right before pb_istream_from_buffer above).

Encoding in C

Let's now say we're going to reply to the message that was just decoded above. So now we have to create data, encode it and send it back. Here's the process:

// Encode value
pb_byte_t output[event_size];

// Output buffer
pb_ostream_t ostream = pb_ostream_from_buffer(output,sizeof(output));

if (!pb_encode(&ostream, event_fields, &evt)) {
   NRF_LOG_ERROR("Unable to encode: %s", PB_GET_ERROR(&ostream));
   return;
}

First create a buffer that holds the maximum amount of bytes that your Protocol buffer takes up. This is also defined in your command.pb.h. In this case event_size is set to 67. Then, similarly to the decode command, you create a stream and connect it to your buffer. Then finally encode the data by pointing your evt struct along with the stream and event_fields.

As long as pb_encode returns without error, the encoded data has been written to output! The structure can be variable length so the best way to handle when sending it is to get the bytes_written from ostream:

NRF_LOG_INFO("bytes written %d",ostream.bytes_written);

Conclusion

Nice you made it! I hope you're starting to grasp the power of Protocol Buffers. Don't worry, it took me a little while to figure it all out. You too can be a Protocol Buffer master! ?

If you're not too thrilled with Protocol Buffers, there are other alternatives. I've used MessagePack with some success on previous products. It's straightforward and has tons of support for a majority of programming languages.

If you are interested how to roll this into a Bluetooth Low Energy project, stay tuned for Part Two. In Part two, I’ll show you how to set up a very simple Bluetooth Service and Characteristic that will be used to transfer our freshly encoded data to-and-fro.

Also, if you want to see all the code in action, you can download everything here.