Android development has also changed a lot in the last few years. Jetpack Compose is now the default UI toolkit, XML layouts are legacy, Kotlin is the only language the official templates use, and Google Play has tightened its requirements for new developers.

Older guides that start with findViewById or end with uploading an APK no longer match how things work.

This handbook walks through the whole path. You'll build a small but complete notes app with Jetpack Compose, Room, ViewModel, and Navigation 3, write a couple of tests, produce a signed release bundle, and then take it through the Google Play Console all the way to a production release.

Table of Contents

• Prerequisites

• What You Will Build

• How to Set Up Your Development Environment

• How to Create a New Compose Project

• How to Configure Dependencies with a Version Catalog

• How Jetpack Compose Thinks About UI

• How to Structure the App

• How to Store Data Locally with Room

• How to Expose Data with a Repository and Application Class

• How to Manage UI State with a ViewModel

• How to Build the Note List Screen

• How to Build the Note Editor Screen

• How to Add Navigation with Navigation 3

• How to Handle Theming and Edge-to-Edge Display

• How to Test Your Composables

• How to Prepare the App for Release

• How to Create an Upload Key and Sign Your App

• How to Build an Android App Bundle

• How to Create a Google Play Developer Account

• How to Create Your App in the Play Console

• How to Complete the App Content Declarations

• How to Set Up Your Store Listing

• How to Run Internal and Closed Testing

• How to Publish to Production

• How to Ship Updates After Launch

• Summary

Prerequisites

You should be comfortable with basic programming concepts and have at least read some Kotlin before. You don't need prior Android experience. Every Android-specific concept is explained as it comes up.

For tools, you need:

• A computer running macOS, Windows, or Linux with at least 16 GB of RAM (8 GB works, but the emulator will be slow)

• The latest stable version of Android Studio

• A physical Android phone (optional for development, but required later for Play Console account verification)

• A Google account and 25 USD for the one-time Google Play developer registration fee

What You Will Build

The sample app is called Quick Notes. It shows a list of notes sorted by the last time they were edited, and it lets you create a new note with a floating action button, tap a note to edit it, and delete notes. Everything is stored locally on the device in a SQLite database, so the app works offline and needs no backend.

A notes app sounds simple, but it touches every piece a real app needs: a list screen and a detail screen, navigation between them with a working back button, persistent storage, state that survives configuration changes such as screen rotation, and user input. Once you understand how these pieces fit together, you can swap the notes for anything else.

Here's the high level architecture you'll end up with:

+-------------------------------------------------------------+
|                         UI Layer                            |
|  MainActivity -> NavDisplay -> NoteListScreen               |
|                             -> NoteEditorScreen             |
|                  observes StateFlow, sends events           |
+------------------------------+------------------------------+
                               |
                               v
+-------------------------------------------------------------+
|                      NotesViewModel                         |
|      holds UI state, survives rotation, launches coroutines |
+------------------------------+------------------------------+
                               |
                               v
+-------------------------------------------------------------+
|                       Data Layer                            |
|   NoteRepository -> NoteDao -> NotesDatabase (Room/SQLite)  |
+-------------------------------------------------------------+

The diagram shows three layers stacked vertically, with arrows pointing down to show the direction of dependencies.

The UI layer at the top contains the activity and the two screens. It only talks to the ViewModel, never directly to the database.

The ViewModel in the middle owns the state that the screens display and survives events like rotation that would otherwise destroy the screen.

The data layer at the bottom wraps Room, which is a typed layer on top of SQLite. Data flows back up the stack as a Flow of notes, so when the database changes, the UI updates automatically.

This is the layered architecture that Google recommends in its official app architecture guide.

How to Set Up Your Development Environment

Download Android Studio from developer.android.com/studio and run the installer. On first launch, the setup wizard downloads the Android SDK, the platform tools (including adb), and a system image for the emulator. Accept the defaults unless you have a reason not to. Android Studio bundles its own JDK, so you don't need to install Java separately.

Once setup finishes, open the SDK Manager from Tools > SDK Manager and confirm that the latest stable Android platform is installed. At the time of writing, that means at least Android 16 (API level 36).

Google Play requires new apps and app updates to target a recent API level, and the requirement moves forward every year, usually at the end of August. Check the target API level requirements page before you start so you know which number to aim for.

Next, create an emulator from Tools > Device Manager. Pick a recent Pixel phone profile and the newest system image with Google Play services.

If you would rather test on a physical phone, enable Developer Options on the device by tapping Build number seven times in Settings > About phone, then turn on USB debugging (or Wireless debugging) in the Developer Options menu.

How to Create a New Compose Project

In Android Studio, choose File > New > New Project and select the Empty Activity template. This template is Compose-based. The similarly named "Empty Views Activity" uses the older XML layout system, so make sure you pick the right one.

Fill in the project details. The Name is what users see (Quick Notes). The Package name is the permanent, globally unique identifier for your app on Google Play, written in reverse domain format such as com.yourname.quicknotes. Choose it carefully, because you can't change it after you publish. Set Minimum SDK to API 24, which covers nearly every active Android device, and leave the build configuration language as Kotlin DSL.

Click Finish and wait for the first Gradle sync to complete. The project you get looks roughly like this:

QuickNotes/
├── app/
│   ├── build.gradle.kts
│   ├── proguard-rules.pro
│   └── src/
│       ├── main/
│       │   ├── AndroidManifest.xml
│       │   ├── java/com/yourname/quicknotes/
│       │   │   ├── MainActivity.kt
│       │   │   └── ui/theme/
│       │   └── res/
│       ├── test/
│       └── androidTest/
├── gradle/
│   └── libs.versions.toml
├── build.gradle.kts
└── settings.gradle.kts

The tree shows the important files in a fresh project.

The app folder is the single module that becomes your installable app, and its build.gradle.kts holds the Android configuration (SDK levels, version numbers, dependencies).

src/main contains production code, the AndroidManifest.xml that declares your app's components to the system, and the res folder for resources such as icons and strings.

The test folder is for unit tests that run on your computer, while androidTest is for tests that run on a device or emulator.

At the root, gradle/libs.versions.toml is the version catalog where all dependency versions live, and settings.gradle.kts lists the modules in the project. Kotlin files sit under a folder named java for historical reasons, which is normal.

Press the green Run button. After a short build, the emulator should show "Hello Android!" on screen. That confirms your toolchain works.

How to Configure Dependencies with a Version Catalog

Modern Android projects keep every library version in one file, gradle/libs.versions.toml, and refer to those libraries by alias from the build scripts.

Open the catalog and replace its contents with the following:

[versions]
agp = "9.0.0"
kotlin = "2.3.0"
ksp = "2.3.4"
composeBom = "2026.01.00"
activityCompose = "1.12.2"
lifecycle = "2.10.0"
navigation3 = "1.0.0"
room = "2.8.4"
serialization = "1.9.0"
junit = "4.13.2"
androidxJunit = "1.3.0"

[libraries]
androidx-activity-compose = { group = "androidx.activity", name = "activity-compose", version.ref = "activityCompose" }
androidx-compose-bom = { group = "androidx.compose", name = "compose-bom", version.ref = "composeBom" }
androidx-compose-ui = { group = "androidx.compose.ui", name = "ui" }
androidx-compose-ui-tooling = { group = "androidx.compose.ui", name = "ui-tooling" }
androidx-compose-ui-tooling-preview = { group = "androidx.compose.ui", name = "ui-tooling-preview" }
androidx-compose-ui-test-junit4 = { group = "androidx.compose.ui", name = "ui-test-junit4" }
androidx-compose-ui-test-manifest = { group = "androidx.compose.ui", name = "ui-test-manifest" }
androidx-compose-material3 = { group = "androidx.compose.material3", name = "material3" }
androidx-compose-material-icons-core = { group = "androidx.compose.material", name = "material-icons-core" }
androidx-lifecycle-viewmodel-compose = { group = "androidx.lifecycle", name = "lifecycle-viewmodel-compose", version.ref = "lifecycle" }
androidx-lifecycle-runtime-compose = { group = "androidx.lifecycle", name = "lifecycle-runtime-compose", version.ref = "lifecycle" }
androidx-navigation3-runtime = { group = "androidx.navigation3", name = "navigation3-runtime", version.ref = "navigation3" }
androidx-navigation3-ui = { group = "androidx.navigation3", name = "navigation3-ui", version.ref = "navigation3" }
androidx-room-runtime = { group = "androidx.room", name = "room-runtime", version.ref = "room" }
androidx-room-ktx = { group = "androidx.room", name = "room-ktx", version.ref = "room" }
androidx-room-compiler = { group = "androidx.room", name = "room-compiler", version.ref = "room" }
kotlinx-serialization-core = { group = "org.jetbrains.kotlinx", name = "kotlinx-serialization-core", version.ref = "serialization" }
junit = { group = "junit", name = "junit", version.ref = "junit" }
androidx-junit = { group = "androidx.test.ext", name = "junit", version.ref = "androidxJunit" }

[plugins]
android-application = { id = "com.android.application", version.ref = "agp" }
kotlin-compose = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }
kotlin-serialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }
ksp = { id = "com.google.devtools.ksp", version.ref = "ksp" }
room = { id = "androidx.room", version.ref = "room" }

The catalog has three sections: [versions] names each version number once. [libraries] maps a short alias to a Maven coordinate, and [plugins] does the same for Gradle plugins.

Gradle turns the dashes in each alias into dots, so androidx-room-runtime becomes libs.androidx.room.runtime in your build scripts. The Compose libraries have no version of their own because they get it from the Compose BOM (bill of materials), which pins a set of Compose libraries that are tested together. The Kotlin Compose compiler plugin shares its version with Kotlin itself, which has been the case since Kotlin 2.0.

KSP is the annotation processor Room uses to generate database code. The version numbers here were current when this article was written. Android Studio highlights outdated entries in the catalog, and you should accept its suggestions to move to the latest stable versions.

Now update the root build.gradle.kts so the plugins are available to the app module:

plugins {
    alias(libs.plugins.android.application) apply false
    alias(libs.plugins.kotlin.compose) apply false
    alias(libs.plugins.kotlin.serialization) apply false
    alias(libs.plugins.ksp) apply false
    alias(libs.plugins.room) apply false
}

This file declares each plugin with apply false, which puts the plugin on the build classpath without applying it to the root project. Each module then opts into the plugins it actually needs.

You might notice there's no org.jetbrains.kotlin.android plugin. Starting with Android Gradle Plugin 9, Kotlin support is built into the Android plugin, so a separate Kotlin Android plugin is no longer required. If you're working in an older project on AGP 8, you'll still see that plugin applied, and that's fine.

Then replace the contents of app/build.gradle.kts:

plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.compose)
    alias(libs.plugins.kotlin.serialization)
    alias(libs.plugins.ksp)
    alias(libs.plugins.room)
}

android {
    namespace = "com.yourname.quicknotes"
    compileSdk = 36

    defaultConfig {
        applicationId = "com.yourname.quicknotes"
        minSdk = 24
        targetSdk = 36
        versionCode = 1
        versionName = "1.0.0"
        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
    }

    buildTypes {
        release {
            isMinifyEnabled = true
            isShrinkResources = true
            proguardFiles(
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro"
            )
        }
    }

    buildFeatures {
        compose = true
    }
}

room {
    schemaDirectory("$projectDir/schemas")
}

dependencies {
    val composeBom = platform(libs.androidx.compose.bom)
    implementation(composeBom)
    androidTestImplementation(composeBom)

    implementation(libs.androidx.activity.compose)
    implementation(libs.androidx.compose.ui)
    implementation(libs.androidx.compose.ui.tooling.preview)
    implementation(libs.androidx.compose.material3)
    implementation(libs.androidx.compose.material.icons.core)
    implementation(libs.androidx.lifecycle.viewmodel.compose)
    implementation(libs.androidx.lifecycle.runtime.compose)
    implementation(libs.androidx.navigation3.runtime)
    implementation(libs.androidx.navigation3.ui)
    implementation(libs.androidx.room.runtime)
    implementation(libs.androidx.room.ktx)
    implementation(libs.kotlinx.serialization.core)
    ksp(libs.androidx.room.compiler)

    testImplementation(libs.junit)
    androidTestImplementation(libs.androidx.junit)
    androidTestImplementation(libs.androidx.compose.ui.test.junit4)
    debugImplementation(libs.androidx.compose.ui.tooling)
    debugImplementation(libs.androidx.compose.ui.test.manifest)
}

This is the most important configuration file in the project, so read it carefully.

The namespace is the package used for the generated R class, while applicationId is the identity of the app on devices and on Google Play. They usually match.

compileSdk is the API level your code is compiled against, and targetSdk tells Android which platform behaviors your app has been tested with. When you raise targetSdk, newer behaviors such as enforced edge-to-edge drawing switch on.

versionCode is an integer that must increase with every upload to Play, while versionName is the human-readable string users see.

The release block turns on R8, which shrinks, obfuscates, and optimizes your code, and isShrinkResources removes unused resources.

The room block tells the Room plugin where to write JSON snapshots of your database schema, which you'll need later when you write migrations.

In the dependencies, platform(libs.androidx.compose.bom) applies the BOM so the Compose libraries line up, and ksp(...) runs the Room compiler at build time. The debugImplementation lines include Compose preview tooling and a test manifest only in debug builds, so they never ship to users.

Click Sync Now in the banner at the top of the editor. If the sync succeeds, you're ready to write code.

How Jetpack Compose Thinks About UI

Before writing screens, it helps to understand the model Compose is built on, because it's different from the older View system.

In Compose, UI is a function of state. You write functions annotated with @Composable that describe what the screen should look like for the current data. You never reach into a view and call setText on it. Instead, when the data changes, Compose calls your function again with the new data and updates only the parts of the screen that actually changed. This re-running is called recomposition.

Here's the smallest useful example:

@Composable
fun Counter() {
    var count by remember { mutableIntStateOf(0) }

    Button(onClick = { count++ }) {
        Text("Clicked $count times")
    }
}

The Counter function declares a piece of state with mutableIntStateOf(0). Compose watches every read of that state. When the button's onClick lambda increments count, Compose knows that Counter read the old value, so it schedules Counter to run again, and the Text shows the new number.

The remember call is what keeps the value alive across recompositions. Without it, count would reset to zero every time the function ran.

The by keyword is Kotlin property delegation, which lets you read and write count like a regular variable instead of writing count.value.

remember survives recomposition but not configuration changes such as rotating the phone, because Android destroys and recreates the activity in that case. For simple values that must survive rotation, use rememberSaveable instead. For anything more substantial, such as data loaded from a database, keep the state in a ViewModel, which outlives the activity. You'll use both in this app.

The other core idea is state hoisting. A composable that owns its own state is hard to reuse and hard to test. A better pattern is to pass state in as parameters and pass events out as lambdas, so the composable only displays what it's given and reports what the user did. The caller decides where the state lives. You'll see this pattern in the list screen, where it makes testing straightforward.

How to Structure the App

Create the following packages under com.yourname.quicknotes by right-clicking the package in the Project panel and choosing New > Package:

com.yourname.quicknotes
├── data/
│   ├── Note.kt
│   ├── NoteDao.kt
│   ├── NotesDatabase.kt
│   └── NoteRepository.kt
├── ui/
│   ├── NotesViewModel.kt
│   ├── NoteListScreen.kt
│   ├── NoteEditorScreen.kt
│   └── theme/
├── navigation/
│   └── NavKeys.kt
├── MainActivity.kt
└── NotesApp.kt

The layout groups files by layer.

The data package holds everything related to storage: the Note entity, the DAO (data access object) that defines queries, the Room database class, and a repository that the rest of the app uses instead of talking to Room directly.

The ui package contains the ViewModel and the two screens, plus the theme files the template generated.

The navigation package holds the keys that identify each screen. MainActivity is the single activity that hosts all of the Compose UI, and NotesApp is a custom Application class used to create the database once for the whole app.

For a larger app, you would likely split these into separate Gradle modules, but packages are enough here.

How to Store Data Locally with Room

Room is the Jetpack persistence library. You describe tables as Kotlin classes and queries as annotated interface methods, and Room generates the SQLite code at compile time. Because queries are checked during the build, a typo in a column name becomes a compiler error instead of a crash on a user's phone.

Start with the entity in data/Note.kt:

package com.yourname.quicknotes.data

import androidx.room.Entity
import androidx.room.PrimaryKey

@Entity(tableName = "notes")
data class Note(
    @PrimaryKey(autoGenerate = true) val id: Long = 0,
    val title: String,
    val body: String,
    val updatedAt: Long = System.currentTimeMillis()
)

@Entity tells Room that this class maps to a table named notes, and each property becomes a column.

The id field is the primary key, and autoGenerate = true asks SQLite to assign a new ID when you insert a row whose ID is 0. That's why id defaults to 0: a new note doesn't have a real ID until it's saved.

The updatedAt property stores a timestamp in milliseconds and defaults to the current time whenever a Note object is created, which is how the app knows which notes were edited most recently.

Using a plain data class gives you equals, hashCode, and copy for free, which Compose relies on to decide whether a list item has changed.

Next, define the queries in data/NoteDao.kt:

package com.yourname.quicknotes.data

import androidx.room.Dao
import androidx.room.Delete
import androidx.room.Query
import androidx.room.Upsert
import kotlinx.coroutines.flow.Flow

@Dao
interface NoteDao {
    @Query("SELECT * FROM notes ORDER BY updatedAt DESC")
    fun observeAll(): Flow<List<Note>>

    @Query("SELECT * FROM notes WHERE id = :id")
    suspend fun getById(id: Long): Note?

    @Upsert
    suspend fun upsert(note: Note)

    @Delete
    suspend fun delete(note: Note)
}

A DAO is an interface whose implementation Room writes for you. The observeAll method returns a Flow<List<Note>> rather than a plain list. A Flow is a stream from Kotlin coroutines that emits a new value whenever the underlying data changes, so any time a note is inserted, updated, or deleted, Room automatically re-runs the query and emits the fresh list. This is what keeps the list screen in sync without any manual refresh logic.

The other methods are marked suspend, which means they must be called from a coroutine. Room runs them on a background thread, so database work never blocks the main thread and freezes the UI.

@Upsert inserts a row if its primary key doesn't exist and updates it if it does, which lets one method handle both creating and editing a note.

The :id syntax in the second query binds the method parameter to the SQL statement safely, with no string concatenation.

Now create the database in data/NotesDatabase.kt:

package com.yourname.quicknotes.data

import androidx.room.Database
import androidx.room.RoomDatabase

@Database(entities = [Note::class], version = 1, exportSchema = true)
abstract class NotesDatabase : RoomDatabase() {
    abstract fun noteDao(): NoteDao
}

The @Database annotation lists every entity in the database and a schema version number. Room generates a concrete subclass of this abstract class, including the implementation of noteDao().

The version field matters once your app is live. If you later add a column to Note, you must bump the version and provide a migration, or Room will refuse to open the existing database on users' devices.

exportSchema = true writes a JSON description of each schema version to the schemas folder you configured in Gradle. Commit that folder to version control, because Room uses those files to verify and auto-generate migrations.

How to Expose Data with a Repository and Application Class

The repository is a thin layer between the ViewModel and Room. In this app it mostly forwards calls, but it gives you one place to add caching, network sync, or validation later without touching the UI code. Create data/NoteRepository.kt:

package com.yourname.quicknotes.data

import kotlinx.coroutines.flow.Flow

class NoteRepository(private val noteDao: NoteDao) {

    fun observeNotes(): Flow<List<Note>> = noteDao.observeAll()

    suspend fun getNote(id: Long): Note? = noteDao.getById(id)

    suspend fun save(note: Note) = noteDao.upsert(note)

    suspend fun delete(note: Note) = noteDao.delete(note)
}

The repository takes a NoteDao in its constructor instead of creating one itself. This is dependency injection in its simplest form. Because the dependency is passed in, a test could hand the repository a fake DAO. The public methods use domain language (save, observeNotes) rather than database language (upsert, observeAll), which keeps Room details from leaking into the rest of the app.

The database should be created exactly once per app process, because opening SQLite is expensive and multiple instances can conflict. A common way to do that without a dependency injection framework is a custom Application subclass. Create NotesApp.kt in the root package:

package com.yourname.quicknotes

import android.app.Application
import androidx.room.Room
import com.yourname.quicknotes.data.NoteRepository
import com.yourname.quicknotes.data.NotesDatabase

class NotesApp : Application() {

    private val database: NotesDatabase by lazy {
        Room.databaseBuilder(this, NotesDatabase::class.java, "notes.db").build()
    }

    val repository: NoteRepository by lazy {
        NoteRepository(database.noteDao())
    }
}

Android creates one instance of the Application class before any activity starts, and keeps it for the lifetime of the process. That makes it a natural home for app-wide singletons.

The by lazy delegate defers creating the database until the first time repository is accessed, which keeps app startup fast.

Room.databaseBuilder takes a context, the database class, and a file name, and build() returns the generated implementation. For larger apps, Hilt or Koin can manage this wiring for you, but the manual approach shows exactly what those frameworks automate.

For Android to use this class, register it in AndroidManifest.xml by adding the android:name attribute to the <application> tag:

<application
    android:name=".NotesApp"
    android:allowBackup="true"
    android:icon="@mipmap/ic_launcher"
    android:label="@string/app_name"
    android:roundIcon="@mipmap/ic_launcher_round"
    android:supportsRtl="true"
    android:theme="@style/Theme.QuickNotes">

The only line you're adding is android:name=".NotesApp". The leading dot is shorthand for your app's namespace, so Android resolves it to com.yourname.quicknotes.NotesApp.

The other attributes came from the template: the launcher icon, the app label shown under the icon, right-to-left layout support, and the base theme used before Compose draws its first frame. If you forget the android:name attribute, Android uses the default Application class and your app crashes the first time it tries to cast it to NotesApp.

How to Manage UI State with a ViewModel

A ViewModel holds the state for a screen and survives configuration changes. When the user rotates the phone, the activity is destroyed and recreated, but the ViewModel stays in memory, so the list of notes doesn't need to be reloaded. Create ui/NotesViewModel.kt:

package com.yourname.quicknotes.ui

import androidx.lifecycle.ViewModel
import androidx.lifecycle.ViewModelProvider
import androidx.lifecycle.viewModelScope
import androidx.lifecycle.viewmodel.initializer
import androidx.lifecycle.viewmodel.viewModelFactory
import com.yourname.quicknotes.NotesApp
import com.yourname.quicknotes.data.Note
import com.yourname.quicknotes.data.NoteRepository
import kotlinx.coroutines.flow.SharingStarted
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.stateIn
import kotlinx.coroutines.launch

class NotesViewModel(private val repository: NoteRepository) : ViewModel() {

    val notes: StateFlow<List<Note>> = repository.observeNotes()
        .stateIn(
            scope = viewModelScope,
            started = SharingStarted.WhileSubscribed(5_000),
            initialValue = emptyList()
        )

    suspend fun getNote(id: Long): Note? = repository.getNote(id)

    fun saveNote(id: Long?, title: String, body: String) {
        viewModelScope.launch {
            repository.save(Note(id = id ?: 0, title = title.trim(), body = body.trim()))
        }
    }

    fun deleteNote(note: Note) {
        viewModelScope.launch {
            repository.delete(note)
        }
    }

    companion object {
        val Factory: ViewModelProvider.Factory = viewModelFactory {
            initializer {
                val app = this[ViewModelProvider.AndroidViewModelFactory.APPLICATION_KEY] as NotesApp
                NotesViewModel(app.repository)
            }
        }
    }
}

There are three ideas packed into this class.

The first is the notes property. repository.observeNotes() returns a cold Flow, which only does work while someone is collecting it. The stateIn operator converts it into a StateFlow, which always holds a current value (starting with an empty list) that the UI can read immediately. SharingStarted.WhileSubscribed(5_000) keeps the database query active while the UI is observing and for five seconds after it stops. That five second grace period means a quick rotation doesn't tear down and restart the query, while backgrounding the app for longer does release it.

The second idea is viewModelScope. Saving and deleting are suspend functions, so they need a coroutine. viewModelScope is a coroutine scope tied to the ViewModel's lifetime, and any work launched in it is cancelled automatically when the ViewModel is cleared.

In saveNote, a null ID means "this is a new note," so it becomes 0 and Room generates a fresh ID. A non-null ID updates the existing row. Because a new Note object is created on every save, updatedAt is refreshed to the current time.

The third idea is the Factory. Android creates ViewModels for you so it can keep them alive across rotations, which means you can't call the constructor directly.

A factory tells Android how to build the ViewModel when it needs one. The viewModelFactory and initializer builders read the Application instance out of the creation extras, cast it to NotesApp, and pass its repository into the constructor.

How to Build the Note List Screen

The list screen is split into two composables. A stateful wrapper connects to the ViewModel, and a stateless content composable does the actual drawing. Create ui/NoteListScreen.kt:

package com.yourname.quicknotes.ui

import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.PaddingValues
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.foundation.lazy.items
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Add
import androidx.compose.material.icons.filled.Delete
import androidx.compose.material3.Card
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.FloatingActionButton
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Scaffold
import androidx.compose.material3.Text
import androidx.compose.material3.TopAppBar
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.text.style.TextOverflow
import androidx.compose.ui.unit.dp
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import com.yourname.quicknotes.data.Note

@Composable
fun NoteListScreen(
    viewModel: NotesViewModel,
    onAddNote: () -> Unit,
    onOpenNote: (Long) -> Unit
) {
    val notes by viewModel.notes.collectAsStateWithLifecycle()

    NoteListContent(
        notes = notes,
        onAddNote = onAddNote,
        onOpenNote = onOpenNote,
        onDeleteNote = viewModel::deleteNote
    )
}

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun NoteListContent(
    notes: List<Note>,
    onAddNote: () -> Unit,
    onOpenNote: (Long) -> Unit,
    onDeleteNote: (Note) -> Unit
) {
    Scaffold(
        topBar = { TopAppBar(title = { Text("Quick Notes") }) },
        floatingActionButton = {
            FloatingActionButton(onClick = onAddNote) {
                Icon(Icons.Default.Add, contentDescription = "Add note")
            }
        }
    ) { innerPadding ->
        if (notes.isEmpty()) {
            Box(
                modifier = Modifier.fillMaxSize().padding(innerPadding),
                contentAlignment = Alignment.Center
            ) {
                Text("No notes yet", style = MaterialTheme.typography.bodyLarge)
            }
        } else {
            LazyColumn(
                contentPadding = PaddingValues(16.dp),
                verticalArrangement = Arrangement.spacedBy(12.dp),
                modifier = Modifier.fillMaxSize().padding(innerPadding)
            ) {
                items(notes, key = { it.id }) { note ->
                    NoteCard(
                        note = note,
                        onClick = { onOpenNote(note.id) },
                        onDelete = { onDeleteNote(note) }
                    )
                }
            }
        }
    }
}

@Composable
private fun NoteCard(note: Note, onClick: () -> Unit, onDelete: () -> Unit) {
    Card(modifier = Modifier.fillMaxWidth().clickable(onClick = onClick)) {
        Row(
            modifier = Modifier.padding(16.dp),
            verticalAlignment = Alignment.CenterVertically
        ) {
            Column(modifier = Modifier.weight(1f)) {
                Text(note.title, style = MaterialTheme.typography.titleMedium)
                if (note.body.isNotBlank()) {
                    Text(
                        note.body,
                        style = MaterialTheme.typography.bodyMedium,
                        maxLines = 2,
                        overflow = TextOverflow.Ellipsis
                    )
                }
            }
            IconButton(onClick = onDelete) {
                Icon(Icons.Default.Delete, contentDescription = "Delete ${note.title}")
            }
        }
    }
}

NoteListScreen is the only part that knows about the ViewModel. It calls collectAsStateWithLifecycle(), which turns the StateFlow into Compose state and, unlike the plain collectAsState(), stops collecting when the app moves to the background. That saves battery and avoids doing database work for a screen nobody can see. It then passes the plain list and some lambdas into NoteListContent.

The viewModel::deleteNote syntax is a function reference, a compact way of writing { note -> viewModel.deleteNote(note) }.

NoteListContent is stateless. It receives everything as parameters and reports clicks through lambdas, which is state hoisting in practice. Inside it, Scaffold is a Material 3 layout that provides slots for a top app bar and a floating action button and calculates innerPadding so your content doesn't end up behind those bars or behind the system status and navigation bars.

When the list is empty, the screen shows a centered message. Otherwise it uses LazyColumn, which only composes the rows that are currently visible, like RecyclerView in the old View system.

The key = { it.id } argument gives each row a stable identity, so when a note is deleted Compose knows exactly which row to remove instead of redrawing everything below it.

NoteCard draws one note. Modifier chains configure layout and behavior in order: fillMaxWidth() stretches the card across the screen and clickable makes the whole card respond to taps.

Inside the Row, Modifier.weight(1f) tells the text column to take all horizontal space left over after the delete button is measured. The contentDescription values on icons are read aloud by TalkBack, Android's screen reader. Including the note title in the delete button's description means a TalkBack user hears "Delete Groceries" instead of a row of identical "Delete" buttons.

How to Build the Note Editor Screen

The editor handles both new notes and existing ones. Create ui/NoteEditorScreen.kt:

package com.yourname.quicknotes.ui

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.imePadding
import androidx.compose.foundation.layout.padding
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.automirrored.filled.ArrowBack
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.Scaffold
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.material3.TopAppBar
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.saveable.rememberSaveable
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun NoteEditorScreen(
    noteId: Long?,
    viewModel: NotesViewModel,
    onDone: () -> Unit
) {
    var title by rememberSaveable { mutableStateOf("") }
    var body by rememberSaveable { mutableStateOf("") }
    var loaded by rememberSaveable { mutableStateOf(noteId == null) }

    LaunchedEffect(noteId) {
        if (noteId != null && !loaded) {
            viewModel.getNote(noteId)?.let {
                title = it.title
                body = it.body
            }
            loaded = true
        }
    }

    Scaffold(
        topBar = {
            TopAppBar(
                title = { Text(if (noteId == null) "New note" else "Edit note") },
                navigationIcon = {
                    IconButton(onClick = onDone) {
                        Icon(Icons.AutoMirrored.Filled.ArrowBack, contentDescription = "Back")
                    }
                },
                actions = {
                    TextButton(
                        onClick = {
                            viewModel.saveNote(noteId, title, body)
                            onDone()
                        },
                        enabled = title.isNotBlank()
                    ) {
                        Text("Save")
                    }
                }
            )
        }
    ) { innerPadding ->
        Column(
            modifier = Modifier
                .fillMaxSize()
                .padding(innerPadding)
                .imePadding()
                .padding(16.dp)
        ) {
            OutlinedTextField(
                value = title,
                onValueChange = { title = it },
                label = { Text("Title") },
                singleLine = true,
                modifier = Modifier.fillMaxWidth()
            )
            Spacer(Modifier.height(12.dp))
            OutlinedTextField(
                value = body,
                onValueChange = { body = it },
                label = { Text("Note") },
                modifier = Modifier.fillMaxWidth().weight(1f)
            )
        }
    }
}

The editor keeps the text the user is typing in local state with rememberSaveable, so a half-written note survives a rotation. The loaded flag tracks whether the existing note has already been read from the database. It starts as true for new notes (nothing to load) and false for existing ones.

LaunchedEffect(noteId) runs a coroutine when the composable first appears and again only if noteId changes. Inside it, the screen asks the ViewModel for the note and copies its title and body into the text fields.

Checking loaded before loading is important. Without that check, rotating the screen would run the effect again and overwrite whatever the user had typed with the saved version from the database.

OutlinedTextField is a Material 3 text input. Compose text fields are controlled components: the field shows whatever value you pass in, and when the user types, it calls onValueChange with the new text. If you forget to update title in that callback, the field appears frozen because Compose keeps redrawing the old value. The Save button is disabled while the title is blank, and pressing it saves through the ViewModel and calls onDone to go back.

imePadding() adds space at the bottom equal to the height of the on-screen keyboard, so the body field shrinks instead of hiding behind the keyboard. The back arrow uses the AutoMirrored icon set, which flips automatically in right-to-left languages such as Arabic and Hebrew.

How to Add Navigation with Navigation 3

Navigation 3 is the Compose-first navigation library from the Jetpack team. The earlier Navigation Compose library was adapted from a system designed for fragments and treated the back stack as something it owned internally.

Navigation 3 takes the opposite approach: the back stack is a plain list that you own, and navigating means adding or removing items from that list. The library observes the list and shows the screen for whatever key is on top.

First, define a key for each screen in navigation/NavKeys.kt:

package com.yourname.quicknotes.navigation

import androidx.navigation3.runtime.NavKey
import kotlinx.serialization.Serializable

@Serializable
data object NoteList : NavKey

@Serializable
data class NoteEditor(val noteId: Long? = null) : NavKey

Each destination is a type that implements NavKey. NoteList takes no arguments, so it's a data object, a singleton with a readable toString.

NoteEditor carries an optional note ID, where null means "create a new note." Arguments are typed properties instead of strings embedded in a URL route, so the compiler catches mistakes such as passing the wrong type.

The @Serializable annotation lets Navigation 3 save the back stack when Android kills your app in the background and restore it when the user comes back, which is why the serialization plugin was added earlier.

Now replace MainActivity.kt with the following:

package com.yourname.quicknotes

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.runtime.Composable
import androidx.lifecycle.viewmodel.compose.viewModel
import androidx.navigation3.runtime.entryProvider
import androidx.navigation3.runtime.rememberNavBackStack
import androidx.navigation3.ui.NavDisplay
import com.yourname.quicknotes.navigation.NoteEditor
import com.yourname.quicknotes.navigation.NoteList
import com.yourname.quicknotes.ui.NoteEditorScreen
import com.yourname.quicknotes.ui.NoteListScreen
import com.yourname.quicknotes.ui.NotesViewModel
import com.yourname.quicknotes.ui.theme.QuickNotesTheme

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()
        setContent {
            QuickNotesTheme {
                QuickNotesNavHost()
            }
        }
    }
}

@Composable
fun QuickNotesNavHost() {
    val backStack = rememberNavBackStack(NoteList)
    val notesViewModel: NotesViewModel = viewModel(factory = NotesViewModel.Factory)

    NavDisplay(
        backStack = backStack,
        onBack = { backStack.removeLastOrNull() },
        entryProvider = entryProvider {
            entry<NoteList> {
                NoteListScreen(
                    viewModel = notesViewModel,
                    onAddNote = { backStack.add(NoteEditor()) },
                    onOpenNote = { id -> backStack.add(NoteEditor(id)) }
                )
            }
            entry<NoteEditor> { key ->
                NoteEditorScreen(
                    noteId = key.noteId,
                    viewModel = notesViewModel,
                    onDone = { backStack.removeLastOrNull() }
                )
            }
        }
    )
}

MainActivity is now just a host. enableEdgeToEdge() lets the app draw behind the status bar and navigation bar (more on that in the next section), and setContent replaces the traditional XML layout with a Compose tree wrapped in the theme the template generated.

QuickNotesNavHost is where navigation happens. rememberNavBackStack(NoteList) creates a saveable back stack that starts with the list screen. The ViewModel is created once with the factory you wrote earlier and shared by both screens, since they work with the same notes.

NavDisplay renders the entry for the key at the top of the stack. The entryProvider block maps each key type to its composable with entry<T>. For NoteEditor, the lambda receives the key instance, so key.noteId gives you the typed argument directly.

Navigating forward is backStack.add(...) and going back is backStack.removeLastOrNull(). That's the whole API for basic navigation.

onBack is called when the user presses the system back button or makes the back gesture, and it removes the top entry. Navigation 3 also supports predictive back, the animation where the previous screen peeks in as the user swipes, without any extra code from you.

Run the app now. You should be able to add notes, see them appear in the list, tap one to edit it, delete notes, rotate the device without losing anything, and close and reopen the app with all notes still there.

How to Handle Theming and Edge-to-Edge Display

The template created a ui/theme package with Color.kt, Type.kt, and Theme.kt. The theme function looks roughly like this:

@Composable
fun QuickNotesTheme(
    darkTheme: Boolean = isSystemInDarkTheme(),
    dynamicColor: Boolean = true,
    content: @Composable () -> Unit
) {
    val colorScheme = when {
        dynamicColor && Build.VERSION.SDK_INT >= Build.VERSION_CODES.S -> {
            val context = LocalContext.current
            if (darkTheme) dynamicDarkColorScheme(context) else dynamicLightColorScheme(context)
        }
        darkTheme -> DarkColorScheme
        else -> LightColorScheme
    }

    MaterialTheme(
        colorScheme = colorScheme,
        typography = Typography,
        content = content
    )
}

MaterialTheme provides colors and typography to every Material 3 component below it, which is why calls such as MaterialTheme.typography.titleMedium in your screens work.

The when block picks a color scheme. On Android 12 (API 31, VERSION_CODES.S) and newer, dynamic color generates a palette from the user's wallpaper so your app matches the rest of their phone. On older versions, or if you set dynamicColor to false, it falls back to the fixed LightColorScheme and DarkColorScheme defined in Color.kt. isSystemInDarkTheme() follows the system dark mode setting.

If you want a consistent brand color everywhere, set dynamicColor = false and edit the colors in Color.kt. The Material Theme Builder can generate a full light and dark scheme from a single seed color.

Edge-to-edge means your app draws behind the system bars instead of inside a box between them. Apps that target Android 15 or higher are edge-to-edge by default, and starting with Android 16 the opt-out is gone.

The enableEdgeToEdge() call in MainActivity makes the behavior consistent on older Android versions too and sets the system bar icons to the correct light or dark color. Because both screens use Scaffold and apply its innerPadding, the content already avoids the bars.

When you build screens without Scaffold, use modifiers such as Modifier.safeDrawingPadding() or Modifier.systemBarsPadding() to keep text and buttons out from under the status bar and gesture area.

How to Test Your Composables

Because NoteListContent is stateless, you can test it without a database or ViewModel by passing in a fake list. Create app/src/androidTest/java/com/yourname/quicknotes/NoteListContentTest.kt:

package com.yourname.quicknotes

import androidx.compose.ui.test.assertIsDisplayed
import androidx.compose.ui.test.junit4.createComposeRule
import androidx.compose.ui.test.onNodeWithContentDescription
import androidx.compose.ui.test.onNodeWithText
import androidx.compose.ui.test.performClick
import com.yourname.quicknotes.data.Note
import com.yourname.quicknotes.ui.NoteListContent
import org.junit.Assert.assertEquals
import org.junit.Rule
import org.junit.Test

class NoteListContentTest {

    @get:Rule
    val composeRule = createComposeRule()

    @Test
    fun showsEmptyMessageWhenThereAreNoNotes() {
        composeRule.setContent {
            NoteListContent(notes = emptyList(), onAddNote = {}, onOpenNote = {}, onDeleteNote = {})
        }

        composeRule.onNodeWithText("No notes yet").assertIsDisplayed()
    }

    @Test
    fun tappingANoteReportsItsId() {
        var openedId: Long? = null
        val notes = listOf(Note(id = 42, title = "Groceries", body = "Milk, eggs"))

        composeRule.setContent {
            NoteListContent(
                notes = notes,
                onAddNote = {},
                onOpenNote = { openedId = it },
                onDeleteNote = {}
            )
        }

        composeRule.onNodeWithText("Groceries").performClick()
        assertEquals(42L, openedId)
    }

    @Test
    fun deleteButtonIsLabelledForScreenReaders() {
        val notes = listOf(Note(id = 1, title = "Groceries", body = ""))

        composeRule.setContent {
            NoteListContent(notes = notes, onAddNote = {}, onOpenNote = {}, onDeleteNote = {})
        }

        composeRule.onNodeWithContentDescription("Delete Groceries").assertIsDisplayed()
    }
}

createComposeRule() sets up an empty activity where setContent can render any composable in isolation. Compose tests find elements through the semantics tree, the same structure accessibility services read. onNodeWithText finds a node by its visible text and onNodeWithContentDescription finds one by its accessibility label.

The first test confirms the empty state appears when the list is empty. The second test passes a lambda that records the ID it receives, taps the note, and asserts that the screen reported the correct ID. The third test checks that the delete button has a meaningful label, which doubles as an accessibility check. None of these tests touch Room or the ViewModel, which is the practical payoff of hoisting state out of NoteListContent.

Run the tests by right-clicking the file and choosing Run 'NoteListContentTest', or from the terminal:

./gradlew connectedDebugAndroidTest

This Gradle task builds a debug version of the app and a separate test APK, installs both on the connected emulator or phone, runs every test in androidTest, and writes an HTML report to app/build/reports/androidTests/connected/. Instrumented tests need a running device. For logic that doesn't depend on Android, such as validation rules or formatting helpers, put unit tests in the test folder and run them with ./gradlew testDebugUnitTest, which runs on your computer in a few seconds.

How to Prepare the App for Release

A debug build is fine for development, but there are several things to take care of before anyone else installs your app.

Replace the Default App Icon

The template ships with the generic green Android icon. Right-click the res folder and choose New > Image Asset. Image Asset Studio generates an adaptive icon, which has a separate foreground and background layer so launchers can mask it into circles, squircles, or other shapes.

Keep the important part of your artwork inside the central safe zone shown in the preview, because the edges get cropped on some launchers. Also provide a monochrome layer. Android 13 and newer use it for themed icons, where the launcher tints every icon to match the wallpaper, and an app without one looks out of place on those phones.

Move Hardcoded Strings into Resources

The screens in this article use hardcoded strings like "Quick Notes" and "No notes yet" to keep the code readable. In a real app, you'd want to move them into res/values/strings.xml and read them with stringResource(R.string.no_notes).

That is what makes translation possible, since Android picks the right strings.xml for the user's language automatically. Android Studio flags hardcoded strings with a lint warning and can extract them for you with the Extract string resource quick fix.

Check the Release Build with R8

You enabled isMinifyEnabled in the release build type, which turns on R8. R8 removes unused code, shortens class and method names, and optimizes what remains. That typically makes an app noticeably smaller and faster, but it can break code that relies on reflection, because R8 can't see that a class is used if nothing references it directly.

Room, Compose, and kotlinx.serialization ship their own keep rules, so this app needs no extra configuration. If you add libraries that use reflection, check their documentation for rules to add to proguard-rules.pro.

The way to catch R8 problems is to actually run a release build before uploading it. Select the release variant from Build > Select Build Variant (it will use a debug signing key until you set up release signing in the next section), install it, and click through every screen. A crash that only appears in release builds is almost always a missing keep rule.

Remove Unnecessary Permissions

Open your merged manifest (the Merged Manifest tab at the bottom of AndroidManifest.xml) and look at the permissions listed. Libraries can add permissions you never asked for, and every permission you declare has to be justified in Play Console declarations. Quick Notes stores everything locally, so it shouldn't need any permissions at all, not even INTERNET. Fewer permissions also make the Data safety form in Play Console simpler to fill out.

How to Create an Upload Key and Sign Your App

Every Android app must be cryptographically signed before it can be installed. Google Play uses a two-key system called Play App Signing. You sign your uploads with an upload key that you create and keep. Google verifies the upload, strips your signature, and re-signs the app with an app signing key that Google stores in its own secure infrastructure. Users only ever see the app signing key.

The benefit of this split is recovery. If you lose your upload key or it leaks, you can ask Google to reset it from Play Console, and your users keep receiving updates. Before Play App Signing existed, losing your only signing key meant you could never update your app again.

Play App Signing is mandatory for new apps, and it's also what makes Android App Bundles possible, since Google needs the signing key to generate optimized APKs for each device.

Create an upload key from the terminal with keytool, which comes with the JDK bundled in Android Studio:

keytool -genkeypair -v \
  -keystore ~/keys/quicknotes-upload.jks \
  -alias upload \
  -keyalg RSA -keysize 2048 \
  -validity 10000

This command creates a Java keystore file at ~/keys/quicknotes-upload.jks containing one key pair with the alias upload. -keyalg RSA -keysize 2048 sets the key type and strength Google Play expects, and -validity 10000 makes the key valid for roughly 27 years. Google Play requires keys to be valid until at least October 2033.

The tool prompts for a keystore password and asks for your name and organization, which are stored in the certificate. If keytool isn't on your path, Android Studio's Build > Generate Signed App Bundle or APK wizard can create the same key through a dialog.

Store the keystore somewhere outside your project folder and back it up to a password manager or encrypted storage. Never commit it to Git.

Next, create a keystore.properties file in your project root to hold the signing details:

storeFile=/Users/yourname/keys/quicknotes-upload.jks
storePassword=your-keystore-password
keyAlias=upload
keyPassword=your-key-password

This file maps the four values Gradle needs to sign a build: the path to the keystore, the keystore password, the alias of the key inside it, and the password for that key. Keeping them in a separate file lets you share the project without sharing secrets. Add keystore.properties and *.jks to your .gitignore right away.

Then load the file in app/build.gradle.kts and create a release signing configuration:

import java.util.Properties

val keystorePropertiesFile = rootProject.file("keystore.properties")
val keystoreProperties = Properties().apply {
    if (keystorePropertiesFile.exists()) {
        keystorePropertiesFile.inputStream().use { load(it) }
    }
}

android {
    // namespace, compileSdk, defaultConfig as before

    signingConfigs {
        if (keystorePropertiesFile.exists()) {
            create("release") {
                storeFile = file(keystoreProperties.getProperty("storeFile"))
                storePassword = keystoreProperties.getProperty("storePassword")
                keyAlias = keystoreProperties.getProperty("keyAlias")
                keyPassword = keystoreProperties.getProperty("keyPassword")
            }
        }
    }

    buildTypes {
        release {
            isMinifyEnabled = true
            isShrinkResources = true
            proguardFiles(
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro"
            )
            signingConfig = signingConfigs.findByName("release")
        }
    }
}

The import must go at the very top of the file, above the plugins block. The script reads keystore.properties into a Properties object if the file exists.

Inside signingConfigs, it creates a configuration named release from those values, but only when the file is present. That guard matters because a teammate cloning the repository, or a CI server running tests, won't have your keystore, and the build should still work for debug tasks.

The release build type then uses findByName("release"), which returns null instead of failing when the config doesn't exist. In a CI pipeline, you would typically read these values from environment variables or a secrets manager instead of a file.

How to Build an Android App Bundle

Google Play doesn't accept APKs for new apps. You upload an Android App Bundle (AAB) instead. A bundle contains all of your compiled code and resources for every screen density, CPU architecture, and language. When a user installs the app, Google Play generates an APK containing only what that specific device needs. A phone with an English locale and a high density screen doesn't download Japanese strings or low density images, so the download is smaller.

Build the bundle from the terminal:

./gradlew bundleRelease

This task compiles the release variant, runs R8, signs the result with your upload key, and writes the bundle to app/build/outputs/bundle/release/app-release.aab. You can also use Build > Generate Signed App Bundle or APK in Android Studio, which does the same thing through a wizard. If the build fails with a signing error, double-check the path and passwords in keystore.properties.

Before uploading, increase versionCode for every new build you send to Play. The first upload can use 1, the next must be 2 or higher, and so on. Play rejects any bundle whose versionCode it has already seen, even on a different testing track. versionName can be anything, but semantic versions such as 1.0.0, 1.0.1, and 1.1.0 are easy for users and for you to follow.

How to Create a Google Play Developer Account

Go to play.google.com/console and sign in with the Google account you want to own the developer account. Consider creating a dedicated account for this rather than using your personal Gmail, since transferring ownership later is awkward.

You'll be asked to choose between a personal account and an organization account. A personal account is for individuals. An organization account is for registered businesses and requires a D-U-N-S number, a free business identifier from Dun and Bradstreet that can take a week or more to obtain.

The choice affects more than paperwork. New personal accounts must complete a closed testing period before they can publish to production (covered below), while organization accounts are exempt from that requirement. Your developer name and, for organizations and monetized personal accounts, your address are shown publicly on your store listing.

Pay the one-time 25 USD registration fee, then complete identity verification. Google asks for a legal name and address matching a government ID, verifies your contact email and phone number, and for personal accounts asks you to confirm that you have access to a physical Android device by installing the Play Console app and signing in. Verification usually takes a few days. You can't publish until it's complete, so start this step early, even before your app is finished.

Identity verification is becoming more important across the Android ecosystem. Google has begun rolling out developer verification for all apps installed on certified Android devices, including those distributed outside Google Play, starting with a handful of countries in late 2026. If you distribute through Play and have completed Play Console verification, you're already covered, but it's one more reason to make sure your account details are accurate.

How to Create Your App in the Play Console

Once your account is verified, click Create app on the Play Console home page. Enter the app name as it should appear on Google Play (up to 30 characters), select the default language, choose App rather than Game, and choose Free or Paid.

Be careful here. You can change a paid app to free later, but a free app can never become paid. If you want to charge money, use in-app purchases or subscriptions instead. Accept the Developer Program Policies and US export law declarations and click Create app.

You land on the app dashboard, which shows a checklist of tasks grouped into sections. Play Console walks you through them in a sensible order, but the next two sections cover the parts that confuse people most.

How to Complete the App Content Declarations

Under Policy and programs > App content (also linked from the dashboard checklist), Google asks a series of questions about your app. Every app must complete all of them before it can be released to any track, including internal testing.

The Privacy policy requires a public URL to a page describing what data your app collects and how it's used. This is required even if your app collects nothing. For Quick Notes, a short page stating that notes are stored only on the device and no data is collected or shared is enough. You can host it with GitHub Pages, Google Sites, or your own website, but it must be a working public web page, not a PDF or a Google Doc that requires sign-in.

App access asks whether parts of the app require login. If they do, you must provide test credentials so reviewers can reach every screen. Quick Notes has no login, so select that all functionality is available without special access.

Ads asks whether your app contains ads, including ads from SDKs you didn't write yourself. Answer honestly, because apps with ads get a "Contains ads" label on the store listing and reviewers check.

Content rating is an IARC questionnaire about violence, sexual content, language, controlled substances, user interaction, and similar topics. Your answers produce age ratings for regions around the world (ESRB in North America, PEGI in Europe, and so on). A notes app with no user-generated sharing will receive the lowest rating everywhere.

Target audience and content asks which age groups your app is designed for. If you include children under 13, your app falls under the Families policy, which adds requirements around ads, data collection, and SDKs. For a general purpose utility, choose 18 and over or a range starting at 13, unless children really are your audience.

Data safety is the most detailed form. It produces the "Data safety" section on your store listing and asks whether your app collects or shares each type of user data, such as location, contacts, personal info, and app activity, and for what purpose. The trap is that you're responsible for data collected by every library in your app, not only your own code. Analytics, crash reporting, and ad SDKs all collect data and must be declared.

Most major SDKs publish a page explaining exactly what to declare. Quick Notes uses no such libraries and makes no network calls, so the honest answer is that no data is collected or shared.

The remaining declarations (news apps, government apps, financial features, health apps, and others) are yes or no questions. For a notes app, the answer to each is no.

How to Set Up Your Store Listing

The store listing, under Grow users > Store presence > Main store listing, is what people see before they install. It needs the following text and graphics.

The left column lists each required asset and the right column lists Google's current limits.

The short description appears directly under your app name in search results, so treat it as your one-line pitch and put your most important keyword in it. The full description is where you explain features in plain language. Google Play indexes it for search, but stuffing it with keywords violates the metadata policy and can get your listing rejected.

The 512 px icon is separate from the launcher icon inside the app, though it should look the same. Google applies the rounded mask itself, so upload a full square without pre-rounded corners or drop shadows. The feature graphic appears at the top of your listing in some layouts and when your app is promoted.

Screenshots are the biggest factor in whether someone installs. Capture them from the emulator using the camera button in the emulator toolbar, and consider adding short captions that explain what each screen does. If you want your app to show up well on tablets and Chromebooks, Play Console has separate slots for tablet screenshots, and providing them improves your listing on those devices.

Also fill in the Store settings page with an app category (Productivity fits Quick Notes), tags, and a contact email address. The contact email is shown publicly on the listing.

How to Run Internal and Closed Testing

Google Play has several release tracks. Internal testing is for up to 100 testers you add by email, and builds are usually available within minutes with minimal review. Closed testing is for a larger group you control, either by email list or Google Group. Open testing lets anyone join from the store listing. Production is the public release.

Start with internal testing. Go to Test and release > Testing > Internal testing, create an email list of testers (you can include yourself), and click Create new release. The first time, Play Console asks you to confirm Play App Signing. Accept the default, which lets Google generate and protect the app signing key. Then upload your app-release.aab, enter release notes, and roll out the release.

Share the opt-in link from the Testers tab with your testers. They accept the invitation in a browser and can then install the app from Google Play like any other app. Installing through Play, instead of sideloading, proves the bundle works end to end with Play App Signing.

If you created a personal developer account, you can't publish to production right away. Personal accounts created after November 13, 2023 must run a closed test with at least 12 testers who have stayed opted in for the last 14 days continuously. Google introduced this rule to cut down on low-quality and abandoned apps, and it's the step that catches the most first-time developers by surprise.

Set this up under Test and release > Testing > Closed testing. Create a track, add testers through an email list or a Google Group, and upload a release (you can promote the same build from internal testing).

Recruit testers early. Friends, family, coworkers, and developer communities are the usual sources. The 12 testers must actually opt in through the link, and the count is of testers who remain opted in, so if someone leaves on day 10, your clock is affected. Plan for more than 12 to give yourself a buffer.

Use the 14 days productively. Ask testers to send feedback, watch for crashes in Monitor and improve > Android vitals, and push updated builds as you fix problems. Each update needs a higher versionCode. When Google reviews your production access request, it looks at whether you used the test to improve the app, not only whether time passed.

When the 14 days are up, the dashboard shows an Apply for production button. The application asks how you recruited testers, what feedback you received, what you changed as a result, and whether the app is ready for release. Answer specifically. Vague answers like "testers liked it" are a common reason for rejection. Approval typically takes up to a week.

How to Publish to Production

Once you have production access, go to Test and release > Production and click Create new release. You can upload a new bundle or promote one from a testing track. Add release notes in the "What's new" field. Users see these on the store listing and in the update notification.

Before rolling out, choose which countries and regions to make the app available in, under the Countries / regions tab of the Production page. Then review the release summary. Play Console shows any errors that block the release (such as an incomplete declaration) and warnings that do not (such as missing translations). Fix the errors, read the warnings, and click Send for review.

Every new app and every update goes through review. For a brand new app, the first review can take up to seven days and occasionally longer. Later updates usually take a day or two. If the app is rejected, Play Console and your developer email explain which policy was violated. Fix the issue, increment the versionCode, and resubmit.

By default, approved releases go live as soon as they pass review. If you want to control the launch date, turn on Managed publishing in the Publishing overview page. Approved changes then wait until you click Publish, which is useful when you're coordinating with a blog post or a marketing date.

How to Ship Updates After Launch

Getting your app live is the start of maintenance, not the end of the project. Three habits make updates go smoothly.

The first is staged rollouts. When you release an update to production, Play Console lets you choose a percentage of users to receive it, such as 10 percent. Watch crash and ANR (App Not Responding) rates in Android vitals for a day or two, then increase the percentage. If something goes wrong, you can halt the rollout, and the remaining users never get the broken version.

Google uses Android vitals thresholds to decide whether to show warnings on your listing or reduce its visibility, so catching problems at 10 percent matters.

The second is keeping your target SDK current. Google Play raises the minimum targetSdk for updates every year. If your app falls behind, you can no longer publish updates, and after a grace period new users on recent Android versions may not be able to find it.

Raising targetSdk isn't just changing a number. Read the behavior changes page for each new Android version and test your app against them. A good routine is to install the Android beta on a test device or emulator each spring so the August deadline is never a surprise.

The third is planning for database changes. When you add a column to Note or create a new entity, increment the version in @Database and give Room a migration. For simple changes, such as adding a column with a default value, Room can generate the migration if you declare autoMigrations = [AutoMigration(from = 1, to = 2)] in the annotation, using the schema JSON files you exported. Skipping this step causes a crash for every existing user the moment they open the updated app, and it's one of the most common causes of one-star reviews after an update.

Summary

In this handbook, you built a complete native Android app with the tools Google currently recommends.

Jetpack Compose describes the UI as functions of state, and the state hoisting pattern keeps screens such as NoteListContent simple to test. Room provides compile-time checked storage that streams updates through a Flow, and a ViewModel exposes that data as a StateFlow that survives rotation. Navigation 3 treats the back stack as an ordinary list you own, so navigating forward and back are just add and removeLastOrNull.

On the release side, you configured R8 to shrink the app, created an upload key and stored it safely outside the project, and built a signed Android App Bundle. Play App Signing means Google holds the final signing key, so losing your upload key is recoverable instead of fatal.

Publishing to Google Play takes more than an upload. You verified your developer identity, filled in the privacy policy, content rating, and Data safety declarations honestly (including data collected by third party libraries), built a store listing, and, for a personal account, ran a 14 day closed test with at least 12 testers before applying for production access. Planning for that testing window from the start is the biggest thing you can do to avoid a delayed launch.

From here, good next steps are adding a dependency injection framework such as Hilt as the app grows, syncing notes to a backend, adding a second language through strings.xml, and setting up a CI pipeline that runs your tests and builds a signed bundle on every tagged release. The full flow you followed in this handbook stays the same no matter how large the app becomes.

These bugs are hard to track down because the crash often happens far away from the line that caused it, sometimes minutes later, inside the garbage collector.

The Java Native Interface gives C and C++ code a way to call into the JVM and work with Java objects. Native code never gets a raw pointer to a Java object. It gets a reference, and each kind of reference comes with its own rules about how long it stays valid, which threads can use it, and who's responsible for freeing it. Once those rules are clear, most JNI crashes become easy to prevent and easy to diagnose.

This article explains how local, global, and weak global references work, walks through the most common mistakes with broken and fixed code for each, and finishes with tools and patterns (CheckJNI and RAII wrappers) that catch these problems before they reach production.

The examples use C++ and Android conventions, but the reference rules come from the JNI specification and apply to any JVM.

Table of Contents

• Prerequisites

• How JNI References Work

• Local References

• Pitfall 1: Leaking Local References in a Loop

• Pitfall 2: Caching a Local Reference in a Static Variable

• Global References

• Pitfall 3: Leaking Global References

• Weak Global References

• Pitfall 4: Using a Weak Global Reference Directly

• Pitfall 5: Sharing JNIEnv Across Threads

• Pitfall 6: Calling FindClass from a Native Thread

• Pitfall 7: Ignoring Pending Exceptions

• Pitfall 8: Comparing References with the Equality Operator

• How to Catch Reference Bugs with CheckJNI

• How to Manage References Safely with RAII

• Reference Types Compared

• Summary

Prerequisites

You should be comfortable reading C++ and Java, and you should have written or at least read a basic JNI function (one declared with extern "C" JNIEXPORT and called from a Java native method).

Familiarity with the Android NDK helps for the Android specific parts, but it's not required to follow the core ideas.

How JNI References Work

A Java object lives on the managed heap, and the garbage collector is free to move it whenever it compacts memory.

If native code held a raw pointer to that object, the pointer would silently go stale after the next compaction. JNI avoids this by handing native code an opaque handle instead. Types like jobject, jclass, jstring, and jobjectArray are all handles of this kind.

 Native code                 JVM reference tables             Managed heap
 +-------------+            +----------------------+         +------------+
 | jobject h   + -------->  | slot 17 : ptr        + ------> |  User obj  |
 +-------------+            +----------------------+         +------------+
                              (GC updates the ptr
                               when the object moves)

The diagram above shows the indirection that makes JNI references safe. Native code holds a handle (h), which points at a slot in a reference table owned by the JVM. That slot holds the real address of the object on the managed heap.

When the garbage collector moves the object, it updates the pointer stored in the slot, and the handle in native code stays valid. The slot also acts as a GC root, which means that as long as the slot exists, the object it points to can't be collected.

Every rule about references comes down to one question: when does that slot get freed?

JNI has three kinds of references, and they differ in exactly that respect. A local reference's slot is freed automatically when the native method returns. A global reference's slot lives until native code explicitly deletes it. A weak global reference also lives until deleted, but it doesn't keep the object alive, so the object behind it can disappear at any time.

Local References

Almost every JNI function that returns a Java object returns a local reference. FindClass, NewStringUTF, GetObjectArrayElement, CallObjectMethod, and GetObjectClass all do this. Arguments passed into a native method (including thiz or the jclass for static methods) are local references too.

A local reference is valid only within the native method call that created it, and only on the thread that created it. When the native method returns to Java, the JVM frees every local reference created during that call in one step. This is convenient for short functions, and it's the reason most JNI code never calls DeleteLocalRef at all.

The convenience has limits. The local reference table has a fixed capacity per call frame. The JNI specification only guarantees room for 16 local references, and you must call EnsureLocalCapacity if you need more.

In practice, JVMs give you much more than that. Older Android versions capped the table at 512 entries, and exceeding it aborted the process with local reference table overflow (max=512). Newer versions of ART raised the limit considerably, but any code that creates local references in an unbounded loop will still eventually run out.

Pitfall 1: Leaking Local References in a Loop

The most common local reference bug is a loop that creates a new reference on every iteration and never releases it.

extern "C" JNIEXPORT void JNICALL
Java_com_example_NameProcessor_processNames(JNIEnv* env, jobject thiz,
                                            jobjectArray names) {
  jsize count = env->GetArrayLength(names);
  for (jsize i = 0; i < count; i++) {
    jstring name = static_cast<jstring>(env->GetObjectArrayElement(names, i));
    const char* utf = env->GetStringUTFChars(name, nullptr);
    if (utf == nullptr) return;
    LogName(utf);
    env->ReleaseStringUTFChars(name, utf);
  }
}

This function iterates over a Java String[] and logs each entry. Each call to GetObjectArrayElement creates a new local reference and stores it in the table.

The code correctly releases the UTF-8 buffer with ReleaseStringUTFChars, but that only frees the character data. It does nothing for the jstring reference itself.

With 10 names this works fine. With 100,000 names, the table fills up and the process aborts. The bug is especially easy to miss because unit tests usually pass small arrays.

The direct fix is to delete each reference once it's no longer needed.

for (jsize i = 0; i < count; i++) {
  jstring name = static_cast<jstring>(env->GetObjectArrayElement(names, i));
  const char* utf = env->GetStringUTFChars(name, nullptr);
  if (utf == nullptr) {
    env->DeleteLocalRef(name);
    return;
  }
  LogName(utf);
  env->ReleaseStringUTFChars(name, utf);
  env->DeleteLocalRef(name);
}

The loop now calls DeleteLocalRef at the end of every iteration and on the early return path, so the table never holds more than one reference from this loop at a time.

The early return matters: GetStringUTFChars returns nullptr when it fails to allocate memory, and in that case it also leaves an OutOfMemoryError pending, so returning to Java right away is the correct response.

When an iteration creates several references (a class, a method result, a string), deleting each one by hand becomes tedious and error prone. PushLocalFrame and PopLocalFrame handle that case.

for (jsize i = 0; i < count; i++) {
  if (env->PushLocalFrame(8) != 0) return;
  jobject user = env->GetObjectArrayElement(users, i);
  jstring name = static_cast<jstring>(env->CallObjectMethod(user, gGetName));
  jstring email = static_cast<jstring>(env->CallObjectMethod(user, gGetEmail));
  SaveUser(env, name, email);
  env->PopLocalFrame(nullptr);
}

PushLocalFrame(8) opens a new scope in the local reference table with room for at least 8 references. Every local reference created after that point belongs to the new frame. PopLocalFrame(nullptr) frees all of them at once, so user, name, and email are released together at the end of each iteration.

If PushLocalFrame returns a nonzero value, the JVM couldn't allocate the frame and an OutOfMemoryError is pending, so the function returns immediately.

If you need one reference to survive the frame, pass it to PopLocalFrame instead of nullptr, and the function returns a new local reference to that object in the outer frame.

Pitfall 2: Caching a Local Reference in a Static Variable

Looking up classes and method IDs is relatively slow, so native libraries often cache them. The mistake is caching the class as a local reference.

static jclass gUserClass;
static jmethodID gGetName;

JNIEXPORT jint JNI_OnLoad(JavaVM* vm, void* reserved) {
  JNIEnv* env = nullptr;
  if (vm->GetEnv(reinterpret_cast<void**>(&env), JNI_VERSION_1_6) != JNI_OK) {
    return JNI_ERR;
  }
  gUserClass = env->FindClass("com/example/User");  // Bug: local reference
  gGetName = env->GetMethodID(gUserClass, "getName", "()Ljava/lang/String;");
  return JNI_VERSION_1_6;
}

JNI_OnLoad runs once when the library is loaded, and this version stores the result of FindClass in a static variable for later use. The problem is that FindClass returns a local reference, and that reference is freed as soon as JNI_OnLoad returns. Every later use of gUserClass goes through a slot that has already been released and may have been reused for a completely different object.

The frustrating part is that this code often appears to work. On some JVMs a stale handle still happens to point at the right class for a while. On ART with CheckJNI enabled, the process aborts with an error along the lines of accessed stale local reference. Without CheckJNI, you get random crashes or calls that land on the wrong object.

The fix is to promote the class to a global reference before storing it.

jclass localClass = env->FindClass("com/example/User");
if (localClass == nullptr) return JNI_ERR;
gUserClass = static_cast<jclass>(env->NewGlobalRef(localClass));
env->DeleteLocalRef(localClass);
if (gUserClass == nullptr) return JNI_ERR;

gGetName = env->GetMethodID(gUserClass, "getName", "()Ljava/lang/String;");
if (gGetName == nullptr) return JNI_ERR;

NewGlobalRef creates a second reference to the same class, one that survives after JNI_OnLoad returns. The original local reference is no longer needed, so the code deletes it right away. Every call is checked for nullptr, because FindClass and GetMethodID return nullptr and leave a pending exception when the class or method doesn't exist (for example, after an obfuscation tool renames it).

The jmethodID doesn't need the same treatment. Method IDs and field IDs aren't object references, so they're not tracked in any reference table. They stay valid as long as the class they belong to is loaded. Holding a global reference to the class guarantees it won't be unloaded, which is one more reason to cache the class globally alongside its IDs.

Global References

A global reference is created explicitly with NewGlobalRef and stays valid until native code calls DeleteGlobalRef. It can be used from any thread, and it keeps the referenced object alive for its entire lifetime. That makes it the right tool for anything native code needs to keep across calls: cached classes, callback objects, or a Java object that owns a native resource.

The cost is that the JVM will never free a global reference on its own. The garbage collector treats it as a root, so the object and everything reachable from it stays in memory until the reference is deleted.

Global references also live in a table with a fixed size. On Android, that limit is 51,200 entries, and exceeding it aborts the process with global reference table overflow.

Pitfall 3: Leaking Global References

Global reference leaks usually come from code that creates a new global reference each time something is registered, without releasing the previous one.

static jobject gListener;

extern "C" JNIEXPORT void JNICALL
Java_com_example_Sensor_setListener(JNIEnv* env, jobject thiz, jobject listener) {
  gListener = env->NewGlobalRef(listener);
}

Every call to setListener creates a new global reference and overwrites the old handle stored in gListener. The old reference is still in the table, but nothing points to it anymore, so it can never be deleted. Each leaked reference also pins a listener object, and a listener is often an inner class that holds a reference to an entire Activity or Fragment. The result is a memory leak that grows with every screen rotation, and eventually a crash when the table overflows.

A corrected version releases the previous reference and gives Java a way to clear the listener.

static std::mutex gListenerMutex;
static jobject gListener = nullptr;

extern "C" JNIEXPORT void JNICALL
Java_com_example_Sensor_setListener(JNIEnv* env, jobject thiz, jobject listener) {
  std::lock_guard<std::mutex> lock(gListenerMutex);
  if (gListener != nullptr) {
    env->DeleteGlobalRef(gListener);
    gListener = nullptr;
  }
  if (listener != nullptr) {
    gListener = env->NewGlobalRef(listener);
  }
}

This version deletes any existing global reference before creating a new one, so at most one listener reference exists at any time. Passing null from Java clears the listener entirely, which gives the Java side a clean way to release it in onDestroy or close(). The mutex protects gListener because the listener might be read from a native worker thread while Java is replacing it on the main thread. Without the lock, the worker could read a handle that was deleted a moment earlier.

A good habit is to pair every NewGlobalRef with a clearly identified place where the matching DeleteGlobalRef happens. If you can't point to that place, the reference will probably leak.

Weak Global References

A weak global reference, created with NewWeakGlobalRef, works like a global reference in that it survives across calls and can be used from any thread. The difference is that it doesn't keep the object alive. If nothing else in Java refers to the object, the garbage collector can collect it, and the weak reference then refers to null.

Weak references are useful when native code wants to call back into a Java object without controlling that object's lifetime. A native audio engine that notifies a UI component is a typical example. The engine shouldn't keep the UI alive after the user has left the screen, but while the UI exists, the engine should be able to reach it.

Pitfall 4: Using a Weak Global Reference Directly

The mistake with weak references is using them as if they were strong ones.

static jweak gCallback;

void NotifyProgress(JNIEnv* env, jint percent) {
  if (!env->IsSameObject(gCallback, nullptr)) {
    env->CallVoidMethod(gCallback, gOnProgress, percent);  // Bug: race with GC
  }
}

The code checks whether the object behind gCallback has been collected, and if not, calls a method on it. The check and the call are two separate steps, and the garbage collector can run between them. If it does, CallVoidMethod receives a reference to an object that no longer exists. This is a textbook time-of-check to time-of-use race, and it will only show up under memory pressure.

The safe approach is to promote the weak reference to a local reference first.

void NotifyProgress(JNIEnv* env, jint percent) {
  jobject callback = env->NewLocalRef(gCallback);
  if (callback == nullptr) return;
  env->CallVoidMethod(callback, gOnProgress, percent);
  env->DeleteLocalRef(callback);
}

NewLocalRef either returns nullptr (the object has been collected) or returns a strong local reference. Once the code holds that local reference, the garbage collector can't collect the object until the reference is deleted, so the call is safe.

NewLocalRef was added in JNI 1.2 and is available on every modern JVM and on all versions of Android. When the weak reference itself is no longer needed, free it with DeleteWeakGlobalRef, not DeleteGlobalRef.

Pitfall 5: Sharing JNIEnv Across Threads

The JNIEnv* pointer passed into every native method is tied to the current thread. It points to per-thread state such as the local reference table and the pending exception. Storing it in a global and using it from another thread corrupts that state.

static JNIEnv* gEnv;  // Bug: JNIEnv is per thread

extern "C" JNIEXPORT void JNICALL
Java_com_example_Downloader_start(JNIEnv* env, jobject thiz) {
  gEnv = env;
  std::thread([] {
    DownloadFile();
    gEnv->CallStaticVoidMethod(gDownloaderClass, gOnComplete);
  }).detach();
}

The native method saves its JNIEnv* and then starts a worker thread that uses it after the download completes. By that point, the saved pointer belongs to a different thread (the one that called start), and that thread may be running other JNI code at the same moment. On ART with CheckJNI, this fails immediately with a message saying the JNIEnv was used on the wrong thread. Without CheckJNI, it causes unpredictable corruption.

The correct pattern is to cache the JavaVM*, which is shared across all threads, and have each thread attach itself to obtain its own JNIEnv*.

static JavaVM* gVm;

JNIEXPORT jint JNI_OnLoad(JavaVM* vm, void* reserved) {
  gVm = vm;
  // Cache classes and method IDs here.
  return JNI_VERSION_1_6;
}

void WorkerThread() {
  JNIEnv* env = nullptr;
  if (gVm->AttachCurrentThread(&env, nullptr) != JNI_OK) return;

  DownloadFile();
  env->CallStaticVoidMethod(gDownloaderClass, gOnComplete);
  if (env->ExceptionCheck()) env->ExceptionClear();

  gVm->DetachCurrentThread();
}

JNI_OnLoad stores the JavaVM*, which stays valid for the lifetime of the process. The worker thread calls AttachCurrentThread to register itself with the JVM and receive a JNIEnv* of its own, then calls DetachCurrentThread before it exits. The Android NDK declares AttachCurrentThread as taking a JNIEnv**, while the desktop JDK header takes a void**, so desktop code needs a reinterpret_cast<void**>(&env).

Detaching isn't optional. Local references created on an attached native thread are never freed automatically, because there's no native method return to trigger the cleanup. They're only freed on detach.

On Android, a native thread that exits while still attached causes ART to abort the process. If a thread is attached for its entire life, a common approach is to register a pthread_key_create destructor that calls DetachCurrentThread when the thread exits, so no code path can forget it.

Also note that gDownloaderClass must be a global reference, for the reasons covered in Pitfall 2. Local references can't cross threads any more than JNIEnv* can.

Pitfall 6: Calling FindClass from a Native Thread

A related surprise shows up when a newly attached native thread calls FindClass for one of the app's own classes.

void WorkerThread() {
  JNIEnv* env = nullptr;
  gVm->AttachCurrentThread(&env, nullptr);
  jclass cls = env->FindClass("com/example/Downloader");  // Returns nullptr
  // ...
  gVm->DetachCurrentThread();
}

When FindClass is called from inside a native method, the JVM uses the class loader of the Java class that declared that method, so application classes resolve correctly.

A thread created in native code and attached with AttachCurrentThread has no Java frames on its stack. In that case, the JVM falls back to the system class loader, which only knows about framework classes. The lookup fails, FindClass returns nullptr, and a ClassNotFoundException is left pending. Code that doesn't check the return value then crashes on the next call that uses cls.

The standard solution is to look up every class you need in JNI_OnLoad (which runs with the application's class loader), store each one as a global reference, and never call FindClass from native threads. If a class has to be resolved dynamically, cache a global reference to the application's ClassLoader object during JNI_OnLoad and call its loadClass method from the worker thread instead.

Pitfall 7: Ignoring Pending Exceptions

When a JNI call fails or when Java code invoked from native code throws, the exception doesn't unwind the native stack. It's recorded as pending, and the native function keeps running. Continuing to call most JNI functions while an exception is pending is undefined behavior.

jstring name = static_cast<jstring>(env->CallObjectMethod(user, gGetName));
const char* utf = env->GetStringUTFChars(name, nullptr);  // Bug if getName threw

If getName() throws, CallObjectMethod returns nullptr and leaves the exception pending. The next line passes that nullptr into GetStringUTFChars while an exception is still pending, which breaks two rules at once. With CheckJNI, ART aborts with a message such as JNI GetStringUTFChars called with pending exception. Without it, the process usually crashes with a null dereference.

jstring name = static_cast<jstring>(env->CallObjectMethod(user, gGetName));
if (env->ExceptionCheck()) {
  return nullptr;
}
const char* utf = env->GetStringUTFChars(name, nullptr);
if (utf == nullptr) {
  return nullptr;
}

After every call that can throw, the fixed code checks ExceptionCheck() and returns immediately if an exception is pending. Returning from a native method with a pending exception is allowed and useful: the exception is rethrown in Java as soon as control returns there, so the Java caller sees it as a normal exception from the native method.

If native code wants to handle the failure itself instead, it calls ExceptionClear() before making any further JNI calls. A small set of functions, such as DeleteLocalRef, DeleteGlobalRef, and the Release functions, are explicitly allowed while an exception is pending, so cleanup can still run before returning.

Pitfall 8: Comparing References with the Equality Operator

Because references are handles and not object addresses, two different handles can refer to the same Java object.

if (listener == gListener) {  // Bug: compares handles, not objects
  RemoveListener();
}

In this comparison, listener is a local reference passed into the current call and gListener is a global reference created earlier. Even if both refer to the same Java object, they occupy different slots in different tables, so the handles are different values and the comparison is false. The listener is never removed.

if (env->IsSameObject(listener, gListener)) {
  RemoveListener();
}

IsSameObject asks the JVM whether both handles resolve to the same object, which is the Java == semantics you actually want. Passing nullptr as the second argument is also the standard way to check whether a weak global reference has been cleared, although as Pitfall 4 showed, NewLocalRef is safer when you intend to use the object afterward.

How to Catch Reference Bugs with CheckJNI

Most of the bugs in this article either work by accident or crash somewhere unrelated to the real mistake. CheckJNI is an extended validation mode that makes them fail loudly and immediately, with a message pointing at the bad call.

On Android, CheckJNI is enabled automatically for apps built with android:debuggable="true" and on emulators. To force it on for all apps on a physical device with a user build, run the following command and then restart the app.

adb shell setprop debug.checkjni 1

This sets a system property that tells ART to enable CheckJNI for every app process started afterward. It doesn't affect processes that are already running, which is why the app needs a restart.

With it enabled, ART validates every JNI call: it rejects stale local references, references used on the wrong thread, calls made with a pending exception, JNIEnv* pointers used from the wrong thread, mismatched Release calls, and invalid method IDs. When a check fails, ART prints JNI DETECTED ERROR IN APPLICATION in logcat along with a description of the problem and a native stack trace, then aborts.

On a desktop JVM, pass the -Xcheck:jni flag instead.

java -Xcheck:jni -Djava.library.path=build/libs -jar app.jar

This runs the application with HotSpot's JNI checking enabled and loads native libraries from build/libs. HotSpot prints warnings for many of the same problems, such as calls made with a pending exception or invalid references. Its checks are generally less strict than ART's, so an app that runs cleanly under -Xcheck:jni on the desktop can still fail CheckJNI on Android. Running tests with CheckJNI enabled on both platforms, including tests that pass large arrays and run work on native threads, catches most reference bugs well before release.

How to Manage References Safely with RAII

Manual DeleteLocalRef and DeleteGlobalRef calls are easy to forget, especially on early return paths. C++ lets you tie the lifetime of a reference to a scope, the same way std::unique_ptr manages heap memory.

template <typename T>
class ScopedLocalRef {
 public:
  ScopedLocalRef(JNIEnv* env, T ref) : env_(env), ref_(ref) {}
  ~ScopedLocalRef() {
    if (ref_ != nullptr) env_->DeleteLocalRef(ref_);
  }
  ScopedLocalRef(const ScopedLocalRef&) = delete;
  ScopedLocalRef& operator=(const ScopedLocalRef&) = delete;

  T get() const { return ref_; }

 private:
  JNIEnv* env_;
  T ref_;
};

ScopedLocalRef takes ownership of a local reference and deletes it in its destructor, so the reference is released no matter how the enclosing scope exits (normal completion, an early return, or a C++ exception). The copy constructor and copy assignment are deleted because two wrappers holding the same handle would both try to delete it. The get() method returns the raw handle for passing into JNI functions.

With this wrapper, the loop from Pitfall 1 becomes shorter and can't leak.

for (jsize i = 0; i < count; i++) {
  ScopedLocalRef<jstring> name(
      env, static_cast<jstring>(env->GetObjectArrayElement(names, i)));
  const char* utf = env->GetStringUTFChars(name.get(), nullptr);
  if (utf == nullptr) return;
  LogName(utf);
  env->ReleaseStringUTFChars(name.get(), utf);
}

Each iteration constructs a ScopedLocalRef for the array element, and the destructor runs at the end of the iteration or on the early return. There's no explicit DeleteLocalRef call anywhere, and adding another return path later can't introduce a leak.

A global reference wrapper follows the same idea, with one important difference: the destructor might run on a thread other than the one that created the reference, so it shouldn't store a JNIEnv*. Instead, it stores the JavaVM* and obtains the current thread's environment when it needs to delete the reference.

class ScopedGlobalRef {
 public:
  ScopedGlobalRef(JNIEnv* env, jobject obj)
      : ref_(obj ? env->NewGlobalRef(obj) : nullptr) {
    env->GetJavaVM(&vm_);
  }
  ~ScopedGlobalRef() {
    JNIEnv* env = nullptr;
    if (ref_ != nullptr &&
        vm_->GetEnv(reinterpret_cast<void**>(&env), JNI_VERSION_1_6) == JNI_OK) {
      env->DeleteGlobalRef(ref_);
    }
  }
  ScopedGlobalRef(const ScopedGlobalRef&) = delete;
  ScopedGlobalRef& operator=(const ScopedGlobalRef&) = delete;

  jobject get() const { return ref_; }

 private:
  JavaVM* vm_ = nullptr;
  jobject ref_;
};

The constructor creates a global reference from any local or global reference it receives and records the JavaVM*. The destructor calls GetEnv to get the JNIEnv* for whatever thread it happens to run on, and deletes the reference only if that thread is attached to the JVM.

If the destructor runs on an unattached thread, this simple version leaks the reference rather than crashing. A production version would either attach temporarily or log the leak so it gets noticed. Android's platform code uses the same pattern in its own ScopedLocalRef helper, and libraries such as fbjni provide complete, tested versions of both wrappers if you prefer not to write your own.

Reference Types Compared

The table summarizes the three reference types. The "Valid until" row describes when the handle stops being usable, and "Freed automatically" describes whether you can rely on the JVM to clean it up.

The main takeaway is that local references are the only kind the JVM cleans up for you, and that convenience is exactly why they can't be stored or shared. Global references can be stored and shared, but each one is a permanent GC root until you delete it. Weak global references can also be stored and shared without pinning the object, but you must promote them to a local reference before every use.

Summary

Every JNI reference is a handle to a slot in a JVM-managed table, and each reference type is defined by when that slot is freed. Local references disappear when the native method returns and belong to a single thread. Global references survive until you delete them and can be used anywhere. Weak global references survive until you delete them but don't keep the object alive.

Most JNI crashes follow directly from breaking one of those rules. Creating local references in a loop without releasing them overflows the local table, which DeleteLocalRef or PushLocalFrame and PopLocalFrame prevent. Storing a local reference for later use leaves you with a stale handle, which promoting it with NewGlobalRef fixes. Creating global references without deleting them leaks memory and eventually overflows the global table. Using a weak reference without first promoting it with NewLocalRef races with the garbage collector.

The threading rules matter just as much. A JNIEnv* belongs to one thread, so cache the JavaVM* and attach each native thread before using JNI, then detach it before the thread exits. Resolve application classes in JNI_OnLoad, because native threads can't find them later. Check for pending exceptions after every call that can throw, and compare references with IsSameObject rather than ==.

Finally, let tools enforce these rules for you. Run your tests with CheckJNI on Android and -Xcheck:jni on the desktop so that reference mistakes fail at the call that caused them, and use RAII wrappers so that releasing a reference happens automatically instead of depending on every code path remembering to do it.

Most wake lock bugs aren't caused by a misunderstanding of the API itself. They come from ordinary control flow problems: an exception thrown between acquire() and release(), an early return, a callback that never fires, or a reference count that drifts out of balance.

These bugs are hard to spot in code review and invisible during normal testing, because the device is usually plugged in and awake anyway.

This article explains what a wake lock actually does at the system level, walks through the most common ways apps leak them, and shows concrete patterns and tools for preventing and detecting leaks. It also covers the modern APIs that remove the need for manual wake locks in most cases.

Table of Contents

• Prerequisites

• What Happens When an Android Device Sleeps

• What a Wake Lock Does

• The Types of Wake Locks

• How to Acquire and Release a Wake Lock

• How Reference Counting Works

• Common Ways Apps Leak Wake Locks

• Patterns That Prevent Leaks

• When You Don't Need a Wake Lock at All

• How to Detect Wake Lock Leaks

• How to Test Wake Lock Behavior

• Wake Locks Below the Framework

• Summary

Prerequisites

You should be comfortable writing Android apps in Kotlin and know the basics of services, broadcast receivers, and coroutines.

You'll also need adb installed and a physical device for the debugging section. Emulators don't model power states in a realistic way, so some of the commands later in the article produce misleading results on them.

What Happens When an Android Device Sleeps

When the screen turns off and nothing else needs the CPU, Android puts the application processor into a low power suspend state. In this state, the CPU stops executing instructions, most of RAM is kept in self refresh, and only a few hardware blocks (the modem, the real time clock, sensor hubs, and a handful of interrupt controllers) stay alive. The device looks idle but is ready to wake up quickly when an interrupt arrives.

Android uses a mechanism called autosleep. The kernel tries to suspend the system as soon as there's no reason to stay awake. Anything that needs the CPU to keep running has to say so explicitly by holding a wakeup source (the kernel term for what Android calls a wake lock). As long as at least one wakeup source is active, the kernel refuses to suspend.

 Screen off
     |
     v
 Any active wakeup sources? == yes ==> CPU stays awake
     |
     no
     |
     v
 Kernel suspends CPU
     |
     v
 Interrupt (alarm, network packet, button press)
     |
     v
 CPU resumes, driver or framework takes a wake lock to handle the event

The above diagram shows the decision the kernel makes repeatedly while the screen is off. If any wakeup source is held, the CPU keeps running. If none are held, the system suspends until a hardware interrupt arrives. When the device resumes, whatever code handles the interrupt usually grabs a short wake lock so it can finish its work before the kernel tries to suspend again.

The important detail is that staying awake is opt in. Your code doesn't get CPU time while the screen is off unless something is holding a wake lock on its behalf.

What a Wake Lock Does

An app level wake lock is a request to PowerManagerService, a system service running inside system_server. When your app calls acquire(), the call goes over Binder to that service, which records the request along with your UID, a tag string, and the lock type. PowerManagerService aggregates all app requests and holds a single kernel wakeup source on behalf of all of them. When the last app level lock is released, it drops the kernel wakeup source and the device is free to suspend.

This design has two consequences worth understanding. First, the system knows exactly which app holds each lock and for how long, which is how battery statistics and Play Console vitals can blame your app.

Second, PowerManagerService links each lock to your process through a Binder death notification. If your process dies, the system releases its locks automatically. A leak is therefore bounded by the lifetime of your process, but processes that run foreground services or are kept alive by the system can live for many hours.

The Types of Wake Locks

The PowerManager class defines several lock levels. Most of them are deprecated, and in practice only one matters for app developers.

The first column is the constant you pass to newWakeLock(), and the next two describe what the lock keeps powered. The screen-related levels were deprecated because apps kept them held after the user left, leaving the display on and the battery draining.

The replacement for keeping the screen on is the FLAG_KEEP_SCREEN_ON window flag (or android:keepScreenOn in a layout), which the window manager ties to the visibility of your window, so it can't leak. The proximity lock is a special case for in-call screens. For everything else, "wake lock" in modern Android means PARTIAL_WAKE_LOCK, and the rest of this article focuses on it.

How to Acquire and Release a Wake Lock

Using a wake lock requires the WAKE_LOCK permission in your manifest. It's a normal permission, so it's granted at install time without a prompt.

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

This line declares that the app may hold wake locks. Without it, acquire() throws a SecurityException. Because the permission is granted silently, users have no idea your app uses wake locks until they look at battery usage, which is one more reason to be careful with them.

Here's the most basic usage.

val powerManager = context.getSystemService(PowerManager::class.java)
val wakeLock = powerManager.newWakeLock(
    PowerManager.PARTIAL_WAKE_LOCK,
    "myapp:upload"
)

wakeLock.acquire(10 * 60 * 1000L) // 10 minutes
uploadPendingFiles()
wakeLock.release()

The code gets the PowerManager system service and creates a WakeLock object with the partial level and a tag. Creating the object does nothing by itself. The CPU is only kept awake between acquire() and release().

The tag "myapp:upload" shows up in dumpsys, Battery Historian, and Play Console, so it should identify both your app and the specific job.

The app:component format is the convention Google recommends, and it saves real time during debugging. The argument to acquire() is a timeout in milliseconds. If the lock is still held after 10 minutes, the system releases it for you.

This snippet looks correct but has a real bug: if uploadPendingFiles() throws, release() never runs. The timeout limits the damage to 10 minutes, but that's still 10 minutes of battery drain for every failure. The next sections explain how to fix this and what other traps exist.

How Reference Counting Works

Wake locks are reference counted by default. Each call to acquire() increments an internal counter, each call to release() decrements it, and the lock is only dropped when the counter reaches zero.

wakeLock.acquire(60_000L)  // count = 1, lock held
wakeLock.acquire(60_000L)  // count = 2
wakeLock.release()         // count = 1, still held
wakeLock.release()         // count = 0, lock released
wakeLock.release()         // throws RuntimeException: WakeLock under-locked

The first two calls push the count to two. The first release only brings it back to one, so the lock stays held even though the code "released" it.

The lock is actually dropped on the second release. A third release, with nothing left to release, throws RuntimeException with the message "WakeLock under-locked". This is a crash in production, which is why some developers wrap release() in a try block or check isHeld first.

Reference counting is useful when several independent pieces of code share a single WakeLock object. It becomes a problem when the number of acquires and releases doesn't match, for example when a function is called twice but its completion callback fires only once.

You can turn reference counting off with setReferenceCounted(false), after which any single release() drops the lock no matter how many times it was acquired. That's often the simpler model when one component owns the lock.

Common Ways Apps Leak Wake Locks

Wake lock leaks almost always fall into a small number of patterns. Recognizing them makes code review far more effective.

Exceptions and Early Returns

The basic example above is the most common leak. Any code path that exits the function between acquire() and release() without running the release is a leak. That includes thrown exceptions, return statements added later by someone who didn't notice the lock, and break or continue inside loops.

fun syncContacts() {
    wakeLock.acquire(5 * 60 * 1000L)
    val account = accountStore.current() ?: return
    api.pushContacts(account)
    wakeLock.release()
}

This function leaks the lock whenever there's no current account, because the early return skips the release. It also leaks when pushContacts() throws a network exception. Both paths look harmless in isolation. The timeout keeps the leak from being permanent, but every failed sync still costs 5 minutes of awake time.

Asynchronous Work That Outlives the Caller

Wake locks are often acquired in one place and released in a callback somewhere else. If the callback never runs, the lock is never released.

fun startDownload(url: String) {
    wakeLock.acquire()
    downloader.enqueue(url, object : Callback {
        override fun onComplete() {
            wakeLock.release()
        }
        override fun onError(e: Throwable) {
            log("download failed", e)
        }
    })
}

Two mistakes are here. The error callback forgets to release the lock, so every failed download leaks it. And the lock is acquired with no timeout at all, so the leak lasts until the process dies.

There is a third, less obvious risk: if downloader is ever cancelled or drops the request without calling either callback, the lock also leaks. Any design where the release depends on a third party calling you back needs a timeout as a safety net.

Unbalanced Reference Counts

When a shared, reference counted lock is acquired more times than it's released, it stays held even though every code path appears to release it.

class LocationTracker(private val wakeLock: PowerManager.WakeLock) {
    fun onStart() {
        wakeLock.acquire(30 * 60 * 1000L)
        startUpdates()
    }

    fun onStop() {
        stopUpdates()
        wakeLock.release()
    }
}

This class looks balanced. The problem appears when onStart() is called twice (for example after a configuration change or a duplicate intent) but onStop() is called once. The count ends at one, and the lock stays held until its timeout expires. Turning off reference counting, or guarding the acquire with if (!wakeLock.isHeld), fixes this particular bug.

Broadcast Receivers That Start Background Work

The system holds a wake lock for you while onReceive() runs. As soon as onReceive() returns, that lock is released, and the process may be treated as idle.

A common mistake is to acquire a separate wake lock in onReceive(), start a thread, and release the lock from the thread. If the process is killed or the thread hangs, the release never happens.

The older WakefulBroadcastReceiver helper was built for this pattern and is now deprecated because of these problems. The modern alternatives are covered later in this article.

Holding a Lock Across Unbounded Operations

Network requests without timeouts, waiting on a CountDownLatch without a deadline, and blocking reads from a Bluetooth socket are all operations that can hang forever. If a wake lock is held around one of them, the lock hangs too. The code technically releases the lock in every path, but the release is never reached because the operation never finishes.

Patterns That Prevent Leaks

The fixes for these leaks come down to a few habits that are easy to apply consistently.

Always Use a Timeout

Every call to acquire() should pass a timeout. Android Lint enforces this with the WakelockTimeout check, which flags calls to acquire() with no arguments.

Pick a timeout that's comfortably longer than the work should ever take, but short enough that a leak is survivable. For a sync job that normally finishes in 20 seconds, a few minutes is reasonable. An hour is not.

Release in a Finally Block

Structured release is the single most effective fix. In Kotlin, a small extension function makes it hard to get wrong.

inline fun <T> PowerManager.WakeLock.withLock(
    timeoutMs: Long,
    block: () -> T
): T {
    acquire(timeoutMs)
    try {
        return block()
    } finally {
        if (isHeld) release()
    }
}

The function acquires the lock with a mandatory timeout, runs the caller's block, and releases the lock in a finally clause. Because of finally, the release runs on normal completion, on early return from the block, and when an exception propagates.

The isHeld check matters because the timeout may have already released the lock if the block ran long. Without the check, the release() call would throw "WakeLock under-locked" and replace whatever exception the block originally threw. Marking the function inline lets callers use return from the enclosing function inside the block, and the finally clause still runs.

With the helper in place, the contact sync function from earlier becomes safe.

fun syncContacts() = wakeLock.withLock(timeoutMs = 5 * 60 * 1000L) {
    val account = accountStore.current() ?: return
    api.pushContacts(account)
}

The early return and any exception from pushContacts() now both pass through the finally block in withLock, so the lock is released on every path. The call site is also shorter, and a reviewer can confirm correctness at a glance without tracing every branch.

Scope Locks to Coroutines Carefully

The same pattern works inside a coroutine, because cancellation in Kotlin is delivered as a CancellationException and finally blocks run when a coroutine is cancelled.

suspend fun uploadAll(files: List<File>) {
    wakeLock.acquire(10 * 60 * 1000L)
    try {
        withTimeout(9 * 60 * 1000L) {
            files.forEach { api.upload(it) }
        }
    } finally {
        if (wakeLock.isHeld) wakeLock.release()
    }
}

The lock is acquired before the work starts and released in finally, which runs on completion, on failure, and on cancellation of the enclosing scope. withTimeout puts a hard deadline on the uploads themselves, set slightly shorter than the wake lock timeout so the coroutine gives up before the system forcibly drops the lock. This addresses the unbounded operation problem described earlier.

One caveat: the inline helper from the previous section can also be used here, since inline lambdas can call suspend functions when invoked from a suspend context.

Give Each Job Its Own Lock

Sharing one WakeLock object across unrelated features makes reference counts hard to reason about and makes battery stats useless, because every feature reports the same tag. Creating a separate lock with a descriptive tag per job costs almost nothing and makes leaks far easier to attribute.

If you do share a lock, disable reference counting or make sure a single owner manages it.

Attribute Work Correctly

If your code acquires a wake lock on behalf of another app or UID (common in system services and SDKs), call setWorkSource() so the battery cost is charged to the right party. Apps rarely need this, but platform and OEM engineers should know it exists.

When You Don't Need a Wake Lock at All

The best way to avoid leaking a wake lock is to not hold one. Most background work on modern Android should use a higher level API that manages wake locks internally.

The left column describes what the app is trying to do, and the right column names the API that covers it. The common thread is that each of these APIs takes a wake lock on your behalf and releases it when your work finishes or times out.

WorkManager and JobScheduler hold a wake lock for the duration of doWork() or onStartJob() and enforce execution limits. goAsync() extends the system's broadcast wake lock for roughly 10 seconds while you finish up. FLAG_KEEP_SCREEN_ON is tied to window visibility and disappears when the user leaves.

Here's a WorkManager worker that replaces the upload example.

class UploadWorker(
    context: Context,
    params: WorkerParameters
) : CoroutineWorker(context, params) {

    override suspend fun doWork(): Result {
        return try {
            uploadPendingFiles()
            Result.success()
        } catch (e: IOException) {
            Result.retry()
        }
    }
}

CoroutineWorker runs doWork() while JobScheduler holds a wake lock for it. When doWork() returns, the wake lock is released, whether the result is success, failure, or retry. If the work runs too long, the system stops it and cancels the coroutine. There's no acquire() or release() in the code, so there's nothing to leak. Returning Result.retry() on an I/O failure lets WorkManager schedule another attempt with backoff instead of the app keeping the CPU awake while it retries in a loop.

Manual wake locks still have a place. Media players, VoIP stacks, and apps that stream data from a connected device over Bluetooth often need to keep the CPU running while a foreground service is active. In those cases, the service is the lifecycle owner, and the wake lock should be acquired in onCreate() or when playback starts, and released in the matching stop path and in onDestroy().

It also helps to know that Doze mode limits what a wake lock can do. When a device enters Doze, the system ignores partial wake locks held by apps that aren't on the battery optimization allowlist. That's not a license to leak, since the lock is still counted during maintenance windows and while the device is active, but it explains why a wake lock alone doesn't guarantee your code keeps running overnight.

How to Detect Wake Lock Leaks

Leaks rarely show up during development because the device is plugged in, the screen is on, and something else is keeping it awake. You need to look for them deliberately.

Check Currently Held Locks with dumpsys power

The quickest check is to ask PowerManagerService what it's holding right now.

adb shell dumpsys power | grep -A 20 "Wake Locks:"

This command dumps the full state of the power manager and filters it to the wake lock section. The output lists every app level wake lock currently held, one per line.

Wake Locks: size=2
  PARTIAL_WAKE_LOCK              'myapp:upload' ACQ=-14m32s110ms (uid=10245 pid=8123)
  PARTIAL_WAKE_LOCK              'AudioMix' ACQ=-3s204ms (uid=1041 ws=WorkSource{10112})

Each line shows the lock level, the tag, how long ago it was acquired (ACQ), and the owning UID and process.

In this example, myapp:upload has been held for over 14 minutes, which is a strong hint of a leak if uploads normally take seconds. The second entry is held by the audio server on behalf of another app, as shown by its work source. Turn the screen off, wait a minute, and run this command again. Any lock from your app that is still present with a growing ACQ time deserves investigation.

Measure Totals with batterystats

dumpsys power shows the current moment. To see how much wake lock time accumulated over a period, use battery statistics.

adb shell dumpsys batterystats --reset
# unplug, use the device normally or leave it idle for a while
adb shell dumpsys batterystats com.example.myapp | grep -i "wake lock"

The first command clears the collected statistics so the measurement starts fresh. After running the device on battery for a while (at least an hour gives useful numbers), the second command prints statistics for your package, filtered to wake lock lines.

You'll see each tag along with its total held time and how many times it was acquired. A tag with a large total time and a small acquire count usually means a lock was held for a long stretch and not released promptly.

For a visual timeline, capture a bug report with adb bugreport and load it into Battery Historian, or record a Perfetto trace with the android.power data source enabled. Both show wake locks as bars on a timeline next to screen state, network activity, and CPU frequency, which makes it easy to see a lock that stays held long after the related activity stopped.

Watch Android Vitals in Play Console

Google Play tracks excessive partial wake lock usage as an Android vitals metric. A user session counts as excessive when the app holds non-exempt partial wake locks for a long cumulative period (the current definition is 2 or more hours within a 24 hour window) while in the background. Wake locks held by some system managed work, such as audio playback or certain job types, are exempt.

Play has made this a core vital, which means apps that exceed the bad behavior threshold can have reduced visibility in the store and may show a warning on their listing. The exact thresholds and exemptions change over time, so check the current Android vitals documentation, but the practical takeaway is stable: leaked wake locks are now a store ranking problem, not just a battery complaint.

Enable Lint Checks

Android Lint includes two relevant checks. Wakelock flags code paths where a lock is acquired but may not be released, and WakelockTimeout flags acquires without a timeout. Both are enabled by default as warnings. Raising them to errors in your lint.xml or Gradle configuration stops new leaks from being merged.

android {
    lint {
        error += listOf("Wakelock", "WakelockTimeout")
    }
}

This Gradle block promotes both checks from warnings to errors, so the build fails when either pattern appears. Lint is static and can't follow every asynchronous path, so it won't catch the callback leak shown earlier, but it catches the simple cases cheaply.

How to Test Wake Lock Behavior

Wake lock handling is easy to cover with unit tests using Robolectric, which provides a shadow implementation of PowerManager.

@RunWith(RobolectricTestRunner::class)
class ContactSyncTest {

    @Test
    fun releasesWakeLockWhenSyncFails() {
        val context = ApplicationProvider.getApplicationContext<Context>()
        val syncer = ContactSyncer(context, api = FailingApi())

        runCatching { syncer.syncContacts() }

        val lock = ShadowPowerManager.getLatestWakeLock()
        assertThat(lock).isNotNull()
        assertThat(lock.isHeld).isFalse()
    }
}

The test creates the component under test with a fake API that always throws. It runs the sync and ignores the exception, then asks Robolectric for the most recently created wake lock.

The two assertions check that a lock was actually used and that it's no longer held after the failure. Tests like this are cheap to write for every error path, and they catch exactly the exception and early return leaks that are hardest to see in review. Injecting the WakeLock (or a small wrapper interface around it) into your classes makes this even easier, because you can then use a plain fake without Robolectric.

Wake Locks Below the Framework

If you work on platform code, HALs, or native daemons, you deal with wake locks one layer lower. Native code can call acquire_wake_lock() and release_wake_lock() from libpower, and on current Android versions these go through the SystemSuspend service, which owns the interface to the kernel's /sys/power/wake_lock file.

The AIDL interface of SystemSuspend returns an IWakeLock object from acquireWakeLock(). The lock is held as long as that object is alive and is released when the last reference is dropped, which gives native code the same scoped lifetime as the Kotlin finally pattern.

The kernel exposes the full list of wakeup sources (including those held by drivers, not just the one held by PowerManagerService) under /sys/class/wakeup/ on recent kernels, or /sys/kernel/debug/wakeup_sources on older ones with debugfs. Reading either requires elevated privileges. When dumpsys power shows no app wake locks but the device still refuses to suspend, a driver or native daemon holding a kernel wakeup source is usually the cause, and these files show which one.

Summary

A wake lock tells the system that some code needs the CPU to stay awake even though the screen is off. App level wake locks are managed by PowerManagerService, which tracks every lock by UID and tag and holds a single kernel wakeup source for all of them. Because staying awake is opt in, a lock that's never released keeps the device from suspending and drains the battery until it times out or the process dies.

Most leaks come from ordinary control flow: exceptions and early returns that skip release(), error callbacks that forget to release, reference counts that drift out of balance, and locks held around operations that never finish.

The fixes are equally ordinary. Always pass a timeout, release in a finally block (ideally through a small helper like withLock), give each job its own tagged lock, and put deadlines on the work inside the lock.

In most cases, the better choice is to avoid manual wake locks entirely. WorkManager, JobScheduler, goAsync(), foreground services, and FLAG_KEEP_SCREEN_ON all manage the lock for you and release it when the work ends. When you do need one, verify it with dumpsys power, batterystats, Perfetto or Battery Historian, Lint, and unit tests that cover the failure paths.

With Play now treating excessive wake locks as a core vital, catching these leaks before release matters for both your users' batteries and your app's visibility in the store.

This guide teaches you how to do that properly and completely in Flutter.

Bluetooth on mobile is notoriously fiddly. Permissions differ between Android and iOS and even between Android versions. The connection lifecycle has more states than people expect, the BLE data model of services and characteristics confuses newcomers, and byte-level encoding trips up almost everyone the first time.

The flutter_blue_plus package hides most of the platform-specific pain while still giving you full control over scanning, connecting, and exchanging data.

This is a handbook by design. It covers the theory of how BLE actually works, complete platform configuration for Android and iOS, scanning and advertisement parsing, connecting and MTU negotiation, service discovery, reading and writing, notifications and descriptors, pairing and bonding, background operation, error handling, a production-ready service architecture with state management, testing and debugging, and performance.

Also, every code snippet is explained line by line so you can adapt it to your own hardware.

Table of Contents

• Prerequisites

• Bluetooth Classic vs Bluetooth Low Energy

• The BLE Data Model: GATT, Services, and Characteristics

• Roles, Advertising, and the Connection Lifecycle

• Choosing a Flutter Bluetooth Package

• Setting Up the Project

• Configuring Android Permissions

• Configuring iOS Permissions and Background Modes

• Checking Bluetooth Adapter State

• Requesting Runtime Permissions

• Scanning for Devices

• Parsing Advertisement Data

• Connecting to a Device

• Negotiating the MTU

• Discovering Services and Characteristics

• Understanding Characteristic Properties

• Reading Data from a Characteristic

• Writing Data to a Characteristic

• Subscribing to Notifications and Indications

• Working with Descriptors

• Encoding and Decoding Byte Data

• Pairing, Bonding, and Encryption

• Reading Signal Strength and Setting Connection Priority

• Handling Disconnection and Reconnection

• Running Bluetooth in the Background

• Error Handling

• A Production BLE Service Architecture

• Building the UI

• Testing and Debugging

• Performance and Battery Optimization

• Common Pitfalls

• Summary

Prerequisites

You should have the Flutter SDK installed (version 3.0 or later) and be comfortable with Dart, StatefulWidget, Future, and the Stream API, since almost everything in BLE is stream-based.

You also need a physical Android or iOS device, because BLE doesn't work on emulators or simulators as they have no Bluetooth radio.

Finally, you need a BLE peripheral to talk to. A cheap heart rate strap, a BLE development board like the Nordic nRF52 or an ESP32, or even a second phone running a BLE peripheral simulator app will work.

You'll want to install the free nRF Connect app on a spare phone as well, because it's the single most useful debugging tool for BLE work.

Bluetooth Classic vs Bluetooth Low Energy

Bluetooth comes in two incompatible flavors, and confusing them is the first mistake many developers make.

Bluetooth Classic (also called BR/EDR, for Basic Rate / Enhanced Data Rate) is the older, higher-bandwidth protocol used for streaming audio to headphones, file transfer, and serial-port emulation.

Bluetooth Low Energy, introduced with Bluetooth 4.0, is a completely separate protocol optimized for tiny bursts of data and extremely low power draw. A BLE coin-cell sensor can run for months or years on a single battery, which is impossible with Classic.

The two protocols don't talk to each other. A Classic-only device can't be reached with BLE APIs and vice versa, although many modern chips are dual-mode and support both.

The flutter_blue_plus package handles Bluetooth Low Energy only. If you need Bluetooth Classic, for example to build a serial (SPP) connection to an Arduino over the classic profile, you need a different package such as flutter_bluetooth_serial.

Everything in this article is about BLE, which is what the overwhelming majority of modern IoT and wearable devices use.

The practical difference for you as a developer is the data model. Classic gives you a stream, similar to a socket. BLE gives you a small structured database that you read and write field by field. That structural difference shapes the entire API, so it's worth understanding before writing any code.

The BLE Data Model: GATT, Services, and Characteristics

BLE data is organized by GATT, the Generic Attribute Profile. GATT sits on top of a lower layer called ATT (the Attribute Protocol), but you rarely touch ATT directly. What matters is that a peripheral exposes a hierarchical database, and your phone reads and writes entries in it.

Peripheral (e.g. heart rate monitor)
└── Service: Heart Rate (UUID 0x180D)
    ├── Characteristic: Heart Rate Measurement (0x2A37)  [notify]
    │   └── Descriptor: Client Characteristic Config (0x2902)
    ├── Characteristic: Body Sensor Location (0x2A38)    [read]
    └── Characteristic: Heart Rate Control Point (0x2A39) [write]
└── Service: Battery (0x180F)
    └── Characteristic: Battery Level (0x2A19)            [read, notify]

The diagram above shows the GATT tree for a typical peripheral. At the top level a device exposes one or more services, each identified by a UUID and grouping related functionality, such as the Heart Rate service and the Battery service.

Inside each service are characteristics, which are the actual data endpoints you interact with. Each characteristic has a UUID and a set of properties in square brackets that declare which operations it supports.

Some characteristics also contain descriptors, which are metadata attached to a characteristic. The most important descriptor is the Client Characteristic Configuration Descriptor (CCCD, UUID 0x2902), which acts as the on/off switch for notifications.

When you write BLE code, you navigate this exact tree: discover services, find the characteristic you want, then read, write, or subscribe to it.

UUIDs come in two sizes. Standard functionality defined by the Bluetooth SIG uses short 16-bit UUIDs written as four hex digits, like 0x180D for Heart Rate. These are shorthand for a full 128-bit UUID that follows a fixed pattern.

Custom devices that implement their own functionality use full 128-bit UUIDs, written as a long string like 6e400001-b5a3-f393-e0a9-e50e24dcca9e, which is the Nordic UART service used by countless hobbyist projects. When you build your own hardware, you generate random 128-bit UUIDs for your services and characteristics so they don't clash with anyone else's.

Roles, Advertising, and the Connection Lifecycle

BLE defines two pairs of roles that are easy to mix up. The first pair describes the connection: the central is the device that scans and initiates connections, which is your phone, and the peripheral is the device that advertises and accepts connections, which is your sensor or wearable.

The second pair describes data flow within a connection: the GATT client requests data (usually the central) and the GATT server holds the data (usually the peripheral).

In this article, your Flutter app is the central and GATT client, and the hardware is the peripheral and GATT server. This is the typical arrangement, though roles can be reversed and a device can play both.

Before any connection exists, a peripheral broadcasts advertising packets. An advertising packet is a small payload, at most 31 bytes in the legacy format, that announces the device's presence and can include its name, the service UUIDs it offers, manufacturer-specific data, and a transmit power level. Your central scans by listening for these packets. This is why scanning returns not just a device but an entire advertisement full of useful metadata you can inspect before ever connecting.

Once you decide to connect, the two devices negotiate a connection and agree on parameters like the connection interval, which is how often they exchange packets. A short interval means lower latency but higher power draw, while a long interval saves battery but adds delay.

After connecting, the central performs service discovery to learn the peripheral's GATT tree, and only then can it read, write, and subscribe. When either side goes out of range or chooses to disconnect, the link drops, all the discovered service objects become invalid, and you must reconnect and rediscover to continue.

Understanding this lifecycle (advertise, scan, connect, discover, communicate, and disconnect) is the mental model behind every function you'll write.

Choosing a Flutter Bluetooth Package

Several packages exist for BLE in Flutter, and picking the right one saves grief. This article uses flutter_blue_plus, which is the actively maintained community successor to the original flutter_blue package that's now abandoned. It supports Android, iOS, and macOS, has a clean stream-based API, and covers the full central workflow including MTU negotiation, bonding, and connection priority.

The main alternative is flutter_reactive_ble from Philips, which is also solid and takes a more reactive, operation-based approach where you compose streams for each action. It's a reasonable choice, especially if your team already thinks in reactive terms.

Another option is universal_ble, which adds web and Windows/Linux support and presents a unified API. It's useful if you target desktop or browser.

For Bluetooth Classic rather than BLE, you need flutter_bluetooth_serial instead, since none of the BLE packages handle the classic SPP profile.

For most projects that target Android and iOS and act as a central connecting to peripherals, flutter_blue_plus is the pragmatic default because of its maturity, documentation, and large community. The concepts in this article transfer directly to the other packages even where the exact method names differ, since they all model the same underlying BLE stack.

Setting Up the Project

Create a new Flutter project and add the packages you need. The first is flutter_blue_plus for BLE itself, and the second is permission_handler for requesting runtime permissions cleanly on Android.

flutter create ble_demo
cd ble_demo
flutter pub add flutter_blue_plus
flutter pub add permission_handler

These commands scaffold a fresh project and then add both dependencies to your pubspec.yaml and run flutter pub get automatically. Using flutter pub add instead of editing pubspec.yaml by hand ensures you get a compatible recent version and avoids indentation mistakes in the YAML file. After running these, open pubspec.yaml and confirm both packages appear under dependencies with reasonable version constraints.

You import the library with a single line wherever you use it, and it exposes everything through the top-level FlutterBluePlus class plus the BluetoothDevice, BluetoothService, and BluetoothCharacteristic types.

import 'dart:async';
import 'dart:io' show Platform;
import 'package:flutter_blue_plus/flutter_blue_plus.dart';

This import block brings in three things you'll use throughout. The dart:async import gives you StreamSubscription and Future, which every BLE operation relies on. The dart:io import provides Platform, which you use to branch between Android-specific and iOS-specific behavior, and the show Platform clause keeps the import narrow. The final line imports the plugin itself. Keeping these at the top of every BLE-related file avoids the confusing errors that appear when a type like BluetoothDevice isn't in scope.

Configuring Android Permissions

Android is the harder platform because Bluetooth permissions changed significantly in Android 12 (API level 31).

On Android 11 and earlier, BLE scanning required location permission, because scanning for nearby devices could in theory reveal the user's location. On Android 12 and above, there are dedicated Bluetooth permissions instead, and you can opt out of the location requirement. You must declare all of them so your app works across the full range of devices your users have.

Open android/app/src/main/AndroidManifest.xml and add the following inside the <manifest> tag, above the <application> tag:

<uses-permission android:name="android.permission.BLUETOOTH_SCAN"
    android:usesPermissionFlags="neverForLocation" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />

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

<uses-feature android:name="android.hardware.bluetooth_le"
    android:required="true" />

The first three permissions cover Android 12 and later. BLUETOOTH_SCAN allows your app to discover nearby devices, and the neverForLocation flag tells the system you aren't using BLE to infer the user's physical location. This lets you skip requesting location permission entirely on modern devices.

BLUETOOTH_CONNECT is required to connect and exchange data with a device. BLUETOOTH_ADVERTISE is only needed if your app acts as a peripheral and advertises, so you can omit it for a pure central app.

The next three permissions handle Android 11 and earlier: BLUETOOTH and BLUETOOTH_ADMIN were the classic permissions, and ACCESS_FINE_LOCATION was mandatory for scanning on those versions. The maxSdkVersion="30" attribute makes each of these apply only up to Android 11 so newer devices don't ask for location unnecessarily. The final uses-feature line declares that your app needs BLE hardware, and setting required="true" prevents the Play Store from offering the app to devices without it.

One subtlety: if you set neverForLocation but your app actually does use BLE to derive location (for example beacon-based indoor positioning), you must remove that flag and request location permission, otherwise Android strips location-bearing results from your scans. For the common case of talking to a known device, keep the flag.

You also need to set the minimum SDK version. Open android/app/build.gradle and confirm minSdkVersion is at least 21, because the BLE APIs require it.

android {
    defaultConfig {
        minSdkVersion 21
        targetSdkVersion 34
    }
}

This block sets the floor and ceiling of Android versions your app supports. minSdkVersion 21 corresponds to Android 5.0, which is the earliest version with usable BLE support in flutter_blue_plus. Setting targetSdkVersion 34 tells the system your app is tested against modern Android behavior, which is required for Play Store submission and ensures the Android 12 permission model applies to your app rather than the legacy location-based one.

Configuring iOS Permissions and Background Modes

iOS is simpler for permissions but stricter about App Store review. There are no runtime permission grants to code, but you must declare a usage description string, or the app crashes the instant it touches Bluetooth. Open ios/Runner/Info.plist and add the following keys inside the top-level <dict>.

<key>NSBluetoothAlwaysUsageDescription</key>
<string>This app uses Bluetooth to connect to and communicate with your devices.</string>
<key>NSBluetoothPeripheralUsageDescription</key>
<string>This app uses Bluetooth to connect to and communicate with your devices.</string>

Both keys provide the text iOS shows in the system permission dialog the first time your app uses Bluetooth. NSBluetoothAlwaysUsageDescription is the modern key used on iOS 13 and later, and NSBluetoothPeripheralUsageDescription covers older versions.

Write a description that clearly explains why you need Bluetooth and names the benefit to the user, because Apple rejects apps with vague or missing justifications during review. iOS presents the actual permission prompt automatically the first time you scan, so you don't call permission_handler on this platform.

If your app needs to keep using Bluetooth while backgrounded, for example to keep receiving heart rate notifications while the screen is off, you must also declare background modes. Add this to the same Info.plist:

<key>UIBackgroundModes</key>
<array>
    <string>bluetooth-central</string>
</array>

This array enables the bluetooth-central background mode, which permits your app to continue scanning for and communicating with peripherals after the user switches away. Without it, iOS suspends your Bluetooth activity when the app leaves the foreground.

Only declare this if you genuinely need background operation, because Apple scrutinizes background modes during review and rejects apps that request them without a clear justification. If your app also acts as a peripheral in the background, add bluetooth-peripheral as a second array entry.

Checking Bluetooth Adapter State

Before scanning, confirm that Bluetooth is actually supported and turned on. flutter_blue_plus exposes the adapter state as a stream, so you can react to the user toggling Bluetooth in system settings while your app runs.

Future<void> initBluetooth() async {
  if (await FlutterBluePlus.isSupported == false) {
    print('Bluetooth is not supported on this device');
    return;
  }

  FlutterBluePlus.adapterState.listen((BluetoothAdapterState state) {
    print('Adapter state: $state');
    if (state == BluetoothAdapterState.on) {
      // Ready to scan
    } else if (state == BluetoothAdapterState.off) {
      // Prompt the user to enable Bluetooth
    }
  });

  if (Platform.isAndroid) {
    await FlutterBluePlus.turnOn();
  }
}

This function first checks FlutterBluePlus.isSupported, which returns false on devices without Bluetooth hardware so you can fail gracefully rather than crash. It then subscribes to FlutterBluePlus.adapterState, a stream that emits a new BluetoothAdapterState every time the radio changes, so your app stays in sync even if the user disables Bluetooth mid-session.

The value BluetoothAdapterState.on means you are clear to scan, while off means you should prompt the user. On Android only, FlutterBluePlus.turnOn() asks the system to enable Bluetooth by showing the standard enable dialog. This call throws on iOS, where Apple provides no API to programmatically enable Bluetooth, so it's guarded behind the platform check and you must direct iOS users to Settings manually.

You can also read the current state once without subscribing, which is handy at a decision point rather than for continuous monitoring.

BluetoothAdapterState current = FlutterBluePlus.adapterStateNow;
if (current != BluetoothAdapterState.on) {
  print('Bluetooth is not ready, current state: $current');
  return;
}

This reads FlutterBluePlus.adapterStateNow, a synchronous snapshot of the adapter state at the moment you call it, and bails out if the radio isn't on. Use this style of check immediately before starting a scan or connection to avoid firing an operation that's guaranteed to fail.

Use the stream from the previous snippet for ongoing UI that needs to reflect the radio state, and use this one-shot getter for a quick gate inside a workflow.

Requesting Runtime Permissions

On Android 6.0 and later, declaring permissions in the manifest isn't enough. You must also request the dangerous ones at runtime, and the exact set depends on the Android version.

The permission_handler package makes this straightforward and abstracts away most of the version differences.

import 'package:permission_handler/permission_handler.dart';

Future<bool> requestBlePermissions() async {
  if (!Platform.isAndroid) {
    return true;
  }

  final statuses = await [
    Permission.bluetoothScan,
    Permission.bluetoothConnect,
    Permission.location,
  ].request();

  final granted = statuses.values.every((status) => status.isGranted);

  if (!granted) {
    final permanentlyDenied = statuses.values.any(
      (status) => status.isPermanentlyDenied,
    );
    if (permanentlyDenied) {
      await openAppSettings();
    }
  }

  return granted;
}

This function returns true immediately on iOS, because the operating system handles Bluetooth consent through the Info.plist description without any code from you.

On Android, it requests three permissions in a single system dialog by passing them as a list to .request(). bluetoothScan and bluetoothConnect map to the Android 12 permissions, while location covers older devices that still tie scanning to location. The plugin no-ops the ones that don't apply to the running OS version. The call returns a map of each permission to its resulting PermissionStatus, and .every() confirms that all of them were granted.

If any permission is permanently denied, meaning the user checked "don't ask again", the code opens the app's settings page with openAppSettings() so the user can grant it manually, because at that point the system will no longer show the prompt. Call this function once before your first scan and abort if it returns false.

Scanning for Devices

With permissions handled, you can search for nearby peripherals. Scanning returns a stream of scan results, each representing one advertising device along with its signal strength and advertised data.

final List<ScanResult> _scanResults = [];
StreamSubscription<List<ScanResult>>? _scanSubscription;

Future<void> startScan() async {
  _scanResults.clear();

  _scanSubscription = FlutterBluePlus.onScanResults.listen(
    (results) {
      for (ScanResult r in results) {
        print('${r.device.remoteId}: "${r.advertisementData.advName}" '
            'rssi: ${r.rssi}');
      }
      _scanResults
        ..clear()
        ..addAll(results);
    },
    onError: (e) => print('Scan error: $e'),
  );

  FlutterBluePlus.cancelWhenScanComplete(_scanSubscription!);

  await FlutterBluePlus.startScan(
    timeout: const Duration(seconds: 15),
    androidUsesFineLocation: false,
  );
}

Future<void> stopScan() async {
  await FlutterBluePlus.stopScan();
  await _scanSubscription?.cancel();
}

The startScan function first clears results from any previous run, then subscribes to FlutterBluePlus.onScanResults, which emits the current list of discovered devices every time a new advertisement arrives.

Inside the listener, each ScanResult gives you the device's remoteId (a stable identifier), the advertised name via advertisementData.advName, and rssi (the signal strength in dBm, where values closer to zero mean a stronger signal, so -40 is strong and -95 is weak).

The onError callback catches scan failures such as permissions being revoked mid-scan. FlutterBluePlus.cancelWhenScanComplete ties the subscription's lifetime to the scan so it cleans itself up when the timeout fires. The scan itself is started by FlutterBluePlus.startScan, where timeout stops scanning automatically after 15 seconds to save battery, and androidUsesFineLocation: false matches the neverForLocation flag you set in the manifest. The stopScan function stops the radio early and cancels the subscription so you don't leak a listener.

If you only care about a specific type of device, filter the scan so the operating system ignores everything else. This is more efficient and more reliable than scanning for everything and filtering in Dart, and it works far better in crowded RF environments.

await FlutterBluePlus.startScan(
  withServices: [Guid('180D')],
  withNames: ['MySensor'],
  withKeywords: ['Sensor'],
  timeout: const Duration(seconds: 15),
);

This call restricts the scan several ways at once. withServices keeps only peripherals that advertise the given service UUID, here 180D for Heart Rate, with the Guid class wrapping the UUID string. withNames matches devices whose advertised name exactly equals one of the listed strings, and withKeywords matches devices whose name contains a substring.

Filtering at the platform level means your results stream only contains relevant devices, which cuts noise dramatically in places where dozens of Bluetooth devices are advertising. You can combine these filters, and a device must satisfy all of the specified ones to appear.

To know whether a scan is currently running, listen to the scanning state, which is useful for toggling a button between "Scan" and "Stop" in the UI.

FlutterBluePlus.isScanning.listen((scanning) {
  print('Scanning: $scanning');
});

This subscribes to FlutterBluePlus.isScanning, a stream of booleans that emits true when a scan starts and false when it stops, whether it stopped because of the timeout or an explicit stopScan() call. Binding your scan button's label and icon to this stream keeps the UI honest, since it reflects the actual radio state rather than what you last told it to do.

Parsing Advertisement Data

The advertisement attached to each scan result carries more than a name and RSSI. It often includes the primary use case data before you even connect, and reading it correctly lets you identify and filter devices precisely.

void inspectAdvertisement(ScanResult r) {
  final adv = r.advertisementData;

  print('Name: ${adv.advName}');
  print('Connectable: ${adv.connectable}');
  print('Tx power: ${adv.txPowerLevel}');
  print('Service UUIDs: ${adv.serviceUuids}');

  adv.manufacturerData.forEach((companyId, bytes) {
    print('Manufacturer $companyId: $bytes');
  });

  adv.serviceData.forEach((uuid, bytes) {
    print('Service data $uuid: $bytes');
  });
}

This function pulls apart the advertisementData object. advName is the advertised local name, which is often empty because many peripherals omit it to save the limited 31-byte advertising budget. connectable tells you whether the device accepts connections at all, since beacons frequently advertise without being connectable.

txPowerLevel is the calibrated transmit power the device claims, which you can compare against rssi to roughly estimate distance. serviceUuids lists the services the device advertises, which is useful for identifying its type. manufacturerData is a map from a company identifier to raw bytes, which is how devices like Apple's iBeacon or custom hardware pack proprietary data into the advertisement. You decode those bytes per the vendor's format. serviceData similarly maps a service UUID to bytes, commonly used by sensors to broadcast a reading without requiring a connection at all.

Reading these fields lets you recognize and triage devices before spending the time and battery to connect.

Connecting to a Device

Once you have picked a device, you connect to it. Connection can fail or drop, so always wrap it in error handling and listen to the connection state before you initiate the connection.

Future<void> connectToDevice(BluetoothDevice device) async {
  final subscription = device.connectionState.listen((state) {
    print('Connection state: $state');
    if (state == BluetoothConnectionState.disconnected) {
      print('Disconnected, reason code: ${device.disconnectReason?.code}, '
          'description: ${device.disconnectReason?.description}');
    }
  });

  device.cancelWhenDisconnected(subscription, delayed: true, next: true);

  try {
    await device.connect(
      timeout: const Duration(seconds: 15),
      autoConnect: false,
      mtu: null,
    );
    print('Connected to ${device.platformName}');
  } catch (e) {
    print('Connection failed: $e');
  }
}

This function first subscribes to the device's connectionState stream so you always know whether you're connected or disconnected, and it logs both the numeric code and human-readable description from device.disconnectReason when a drop happens. This is invaluable for diagnosing why a peripheral went away.

device.cancelWhenDisconnected ties that subscription to the connection so it cleans up appropriately, with delayed: true keeping it alive long enough to catch the final disconnect event.

The connection itself happens in a try/catch: timeout gives up after 15 seconds if the device doesn't respond, autoConnect: false tells the system to connect immediately rather than lazily waiting for the device to reappear, and passing mtu: null skips automatic MTU negotiation so you can control it yourself later. If the connection throws, the catch reports the failure instead of crashing. Set up the state listener before calling connect, otherwise you can miss the first transition.

Always stop scanning before you connect. Scanning and connecting at the same time strains the radio on many Android devices and causes intermittent connection failures. Call stopScan() first, then connect. You can also check whether you're already connected with device.isConnected, which returns a boolean synchronously, to avoid redundant connect calls.

When you're done with a device, disconnect cleanly to free the connection slot, since phones support only a limited number of simultaneous BLE connections.

Future<void> disconnectFromDevice(BluetoothDevice device) async {
  await device.disconnect();
  print('Disconnected from ${device.platformName}');
}

This calls device.disconnect, which tears down the GATT connection and releases the resources associated with it. Awaiting the call ensures the disconnect completes before you continue, which matters if you plan to immediately reconnect or connect to a different device.

Failing to disconnect properly is a common cause of the "maximum connections reached" errors that appear after your app has been running for a while, because orphaned connections pile up.

Negotiating the MTU

The MTU (Maximum Transmission Unit) is the largest amount of data that fits in a single BLE packet. By default it is 23 bytes, of which 3 are protocol overhead, leaving only 20 bytes of usable payload per read or write. For anything larger you request a bigger MTU right after connecting.

Future<void> negotiateMtu(BluetoothDevice device) async {
  if (Platform.isAndroid) {
    int mtu = await device.requestMtu(512);
    print('MTU negotiated to: $mtu');
  } else {
    int mtu = await device.mtu.first;
    print('iOS negotiated MTU automatically: $mtu');
  }
}

On Android, device.requestMtu(512) asks the peripheral for a 512-byte MTU, which is the maximum the BLE spec allows, and returns the value both sides actually agreed on, since the peripheral may grant less. Larger payloads then travel in one operation instead of being split into 20-byte chunks, which improves throughput significantly.

On iOS there's no manual request because Apple negotiates the MTU automatically at connection time, so the code just reads the current value from the device.mtu stream with .first. Always compute your maximum safe payload as the negotiated MTU minus 3 bytes of ATT overhead, and never assume the peripheral honored your full request.

You can also subscribe to the MTU stream to react whenever it changes, which some stacks do partway through a connection.

device.mtu.listen((mtu) {
  print('Current MTU: $mtu, usable payload: ${mtu - 3} bytes');
});

This listens to device.mtu, a stream that emits the current MTU and re-emits whenever it changes during the connection's life. The listener computes the usable payload as mtu - 3 to account for the fixed ATT header. Binding your chunking logic to this stream rather than to a value you cached once means your writes stay correct even if the MTU changes after your initial negotiation.

Discovering Services and Characteristics

A connection alone gives you nothing. You must discover the peripheral's services to gain access to its characteristics. This step maps out the GATT tree and must be repeated after every reconnection, because the old objects become invalid.

Future<BluetoothCharacteristic?> discoverServices(
  BluetoothDevice device,
  Guid serviceUuid,
  Guid characteristicUuid,
) async {
  List<BluetoothService> services = await device.discoverServices();

  for (BluetoothService service in services) {
    print('Service: ${service.uuid}');
    for (BluetoothCharacteristic c in service.characteristics) {
      print('  Characteristic: ${c.uuid} '
          '(read: ${c.properties.read}, '
          'write: ${c.properties.write}, '
          'notify: ${c.properties.notify})');
    }
  }

  for (BluetoothService service in services) {
    if (service.uuid == serviceUuid) {
      for (BluetoothCharacteristic c in service.characteristics) {
        if (c.uuid == characteristicUuid) {
          return c;
        }
      }
    }
  }
  return null;
}

This function calls device.discoverServices, which asks the peripheral for its full GATT tree and returns the list once discovery finishes.

The first pair of loops prints every service and characteristic with its properties, which is exactly what you want during development to learn a device's layout. The second pair of loops searches for the specific service and characteristic you passed in by comparing UUIDs, returning the matching BluetoothCharacteristic or null if it is absent.

Returning the characteristic object lets the caller cache it and reuse it for subsequent reads, writes, and subscriptions rather than searching the tree every time. Run discovery once right after connecting, cache the handles you need, and rediscover after any reconnection.

Understanding Characteristic Properties

Every characteristic advertises which operations it supports through its properties object, and attempting an unsupported operation throws. Checking properties first is the difference between a robust app and one that crashes on unexpected hardware.

void printProperties(BluetoothCharacteristic c) {
  final p = c.properties;
  print('read: ${p.read}');
  print('write: ${p.write}');
  print('writeWithoutResponse: ${p.writeWithoutResponse}');
  print('notify: ${p.notify}');
  print('indicate: ${p.indicate}');
  print('broadcast: ${p.broadcast}');
  print('authenticatedSignedWrites: ${p.authenticatedSignedWrites}');
}

This function dumps the full set of property flags. read means you can pull the value on demand. write is a write that the peripheral acknowledges, and writeWithoutResponse is a faster fire-and-forget write with no acknowledgment.

notify and indicate both mean the peripheral pushes updates to you, with the difference that indicate requires the central to acknowledge each update while notify does not, making indicate more reliable but slower.

broadcast means the value can be included in advertising packets. authenticatedSignedWrites means the characteristic accepts signed writes that require bonding.

Reading these flags before acting lets you pick the correct method and skip operations the device doesn't support, which is essential when your app talks to hardware from multiple vendors that implement the same logical feature with different property sets.

Reading Data from a Characteristic

Reading pulls the current value of a characteristic on demand. The value always comes back as a list of bytes, and it's your job to interpret those bytes according to the peripheral's specification.

Future<List<int>> readCharacteristic(BluetoothCharacteristic c) async {
  if (!c.properties.read) {
    print('This characteristic is not readable');
    return [];
  }

  List<int> value = await c.read();
  print('Raw bytes: $value');
  return value;
}

The function first guards against reading a characteristic that doesn't support it by checking c.properties.read, returning an empty list if the operation isn't allowed. It then calls c.read, which returns a List<int> where each element is a byte from 0 to 255.

Because BLE has no concept of data types at the transport level, you receive raw bytes and must decode them yourself according to the device's data sheet. We'll cover this topic in detail in the encoding section below. Returning the raw bytes lets the caller decide how to interpret them. Always confirm the read property first, because reading an unreadable characteristic throws a FlutterBluePlusException.

Writing Data to a Characteristic

Writing sends bytes to the peripheral, which is how you send commands, change settings, or push data to custom hardware.

There are two write modes, and choosing the right one matters for reliability and speed.

Future<void> writeCharacteristic(
  BluetoothCharacteristic c,
  List<int> data,
) async {
  if (c.properties.write) {
    await c.write(data, withoutResponse: false);
    print('Write with response complete');
  } else if (c.properties.writeWithoutResponse) {
    await c.write(data, withoutResponse: true);
    print('Write without response complete');
  } else {
    print('This characteristic is not writable');
  }
}

This function inspects the properties to decide how to write. If the characteristic supports write, it uses a write with response by passing withoutResponse: false, which means the peripheral acknowledges receipt and the await completes only after confirmation. This is reliable but slower because it waits for a round trip.

If the characteristic instead supports writeWithoutResponse, it sends the data fire-and-forget with withoutResponse: true, which is faster and ideal for high-throughput streaming but gives no delivery guarantee.

If neither property is present, the characteristic isn't writable and the function reports so. The data argument is a List<int> of bytes, so to send a two-byte command you might pass [0x01, 0xFF].

When you need to send more data than the MTU allows, split it into chunks sized to the negotiated MTU minus overhead and write them in sequence.

Future<void> writeLongData(
  BluetoothCharacteristic c,
  List<int> data,
  int mtu,
) async {
  final chunkSize = mtu - 3;
  for (var i = 0; i < data.length; i += chunkSize) {
    final end = (i + chunkSize < data.length) ? i + chunkSize : data.length;
    final chunk = data.sublist(i, end);
    await c.write(chunk, withoutResponse: false);
  }
  print('Sent ${data.length} bytes in chunks of $chunkSize');
}

This function breaks a large payload into MTU-sized pieces. It computes chunkSize as the negotiated MTU minus 3 bytes of ATT overhead, then walks the data in steps of that size.

For each step it calculates the end index, guarding against running past the end of the list, slices out the chunk with sublist, and writes it. Using write-with-response here (withoutResponse: false) serializes the chunks safely, because each write waits for acknowledgment before the next begins, which prevents overrunning the peripheral's buffer.

If your peripheral defines its own reassembly protocol, follow that instead, since some devices expect a length header or sequence numbers in each chunk.

Subscribing to Notifications and Indications

Notifications are the reason BLE is efficient. Instead of polling a characteristic repeatedly, you subscribe once and the peripheral pushes new values to you as they change. This is how continuous data like heart rate, temperature, or accelerometer readings arrives with minimal power cost.

StreamSubscription<List<int>>? _valueSubscription;

Future<void> subscribe(BluetoothCharacteristic c) async {
  if (!c.properties.notify && !c.properties.indicate) {
    print('This characteristic does not support notifications');
    return;
  }

  _valueSubscription = c.onValueReceived.listen((value) {
    print('Update received: $value');
  });

  c.device.cancelWhenDisconnected(_valueSubscription!);

  await c.setNotifyValue(true);
}

Future<void> unsubscribe(BluetoothCharacteristic c) async {
  await c.setNotifyValue(false);
  await _valueSubscription?.cancel();
}

The subscribe function first confirms that the characteristic supports either notify or indicate, the two flavors of server-initiated updates. It then listens to c.onValueReceived, a stream that emits a new byte list every time the peripheral sends an update, and ties that subscription to the connection with cancelWhenDisconnected so it stops cleanly on disconnect. Finally it calls setNotifyValue(true), which under the hood writes to the CCCD descriptor (UUID 0x2902) to tell the peripheral to start pushing data. The plugin automatically picks indicate over notify when only indicate is supported.

The order matters: set up the listener before enabling notifications so you don't miss the first update. The unsubscribe function reverses this by calling setNotifyValue(false) to tell the peripheral to stop and cancelling the Dart subscription to free resources. Always unsubscribe when you no longer need the data, because leaving notifications on drains both devices' batteries.

Working with Descriptors

Descriptors are metadata attached to a characteristic. The plugin handles the notification descriptor for you when you call setNotifyValue, but some devices expose custom descriptors you need to read or write directly, such as a user-readable description or a valid-range definition.

Future<void> exploreDescriptors(BluetoothCharacteristic c) async {
  for (BluetoothDescriptor d in c.descriptors) {
    print('Descriptor: ${d.uuid}');
    List<int> value = await d.read();
    print('  Value: $value');
  }
}

Future<void> writeDescriptor(BluetoothDescriptor d, List<int> data) async {
  await d.write(data);
  print('Descriptor written');
}

The exploreDescriptors function iterates over c.descriptors, the list of descriptors discovered alongside the characteristic, and reads each one's value with d.read, which returns bytes just like a characteristic read.

The writeDescriptor function sends bytes to a descriptor with d.write. Most apps never touch descriptors directly because setNotifyValue manages the important one, but if your hardware documents a custom descriptor, for example the Characteristic User Description (0x2901) that holds a human-readable label, this is how you access it.

Treat descriptor values as raw bytes and decode them per the specification, exactly as you would a characteristic.

Encoding and Decoding Byte Data

BLE transmits raw bytes with no type information, so encoding and decoding is where most real bugs hide. You must know the byte layout of each characteristic from its specification, including the size of each field, whether integers are signed, and the byte order (endianness).

The most common order in BLE is little-endian, meaning the least significant byte comes first, but always verify against the device documentation.

import 'dart:typed_data';

int readUint8(List<int> bytes, int offset) => bytes[offset];

int readUint16LE(List<int> bytes, int offset) {
  return bytes[offset] | (bytes[offset + 1] << 8);
}

int readUint32LE(List<int> bytes, int offset) {
  return bytes[offset] |
      (bytes[offset + 1] << 8) |
      (bytes[offset + 2] << 16) |
      (bytes[offset + 3] << 24);
}

int readInt16LE(List<int> bytes, int offset) {
  final data = ByteData.sublistView(Uint8List.fromList(bytes));
  return data.getInt16(offset, Endian.little);
}

double readFloat32LE(List<int> bytes, int offset) {
  final data = ByteData.sublistView(Uint8List.fromList(bytes));
  return data.getFloat32(offset, Endian.little);
}

These helpers cover the field types you meet most often. readUint8 simply returns a single byte as an unsigned integer. readUint16LE combines two bytes into a 16-bit unsigned value by placing the low byte first and shifting the high byte left by 8 bits, joined with a bitwise OR. readUint32LE extends the same idea to four bytes with shifts of 8, 16, and 24.

For signed values and floats, manual bit twiddling is error-prone, so readInt16LE and readFloat32LE wrap the bytes in a ByteData view and use its getInt16 and getFloat32 methods with Endian.little, which correctly handle sign extension and IEEE 754 float decoding. Using ByteData is the recommended approach for anything beyond simple unsigned integers, because it is both correct and readable.

Encoding data to send follows the reverse pattern, and ByteData is again the cleanest tool.

List<int> encodeCommand(int commandId, int value) {
  final data = ByteData(5);
  data.setUint8(0, commandId);
  data.setUint32(1, value, Endian.little);
  return data.buffer.asUint8List();
}

This function builds a five-byte command packet. It allocates a ByteData buffer of five bytes, writes the command identifier as a single byte at offset 0 with setUint8, then writes a 32-bit value in little-endian order starting at offset 1 with setUint32. Finally it converts the buffer to a Uint8List with buffer.asUint8List(), which is the List<int> type that characteristic.write expects.

Building packets with ByteData keeps offsets explicit and endianness correct, which prevents the subtle off-by-one and byte-swap bugs that plague hand-assembled byte lists.

To decode a real-world example, here's how you parse a heart rate measurement, which uses a flags byte to signal its own format.

int parseHeartRate(List<int> bytes) {
  final flags = bytes[0];
  final is16Bit = (flags & 0x01) != 0;
  if (is16Bit) {
    return readUint16LE(bytes, 1);
  } else {
    return readUint8(bytes, 1);
  }
}

This function implements the standard Heart Rate Measurement format. The first byte is a flags field, and its lowest bit indicates whether the heart rate value that follows is 8-bit or 16-bit, which the code extracts with a bitwise AND against 0x01. If the bit is set, the value is a two-byte little-endian integer read from offset 1. Otherwise it's a single byte at offset 1.

This flags-then-payload pattern is extremely common in standardized BLE characteristics, so recognizing it saves time. It also shows why you can't decode BLE data without the specification: the same characteristic changes its own layout depending on a flag.

Pairing, Bonding, and Encryption

Some characteristics require an encrypted connection, and accessing them triggers pairing. Pairing is the process where the two devices exchange keys, and bonding is when they save those keys so future connections are encrypted automatically without pairing again.

Many secured devices work this way, and understanding the flow prevents confusing "insufficient authentication" errors.

Future<void> bondDevice(BluetoothDevice device) async {
  if (Platform.isAndroid) {
    print('Current bond state: ${await device.bondState.first}');
    await device.createBond();
    print('Bond created');
  }
}

Future<void> removeBondIfNeeded(BluetoothDevice device) async {
  if (Platform.isAndroid) {
    await device.removeBond();
    print('Bond removed');
  }
}

On Android, device.createBond() explicitly initiates pairing and bonding, which shows the system pairing dialog and, on success, stores the keys so the device is remembered. Reading device.bondState.first tells you the current state (none, bonding, or bonded) before you act. device.removeBond() deletes a stored bond, which is useful during development when a stale bond causes connection problems, or when a user wants to forget a device.

These APIs are Android-only in the plugin because iOS handles bonding transparently: on iOS, pairing is triggered automatically the first time you access an encrypted characteristic, and the system manages the keys with no code from you.

In practice, the cleanest cross-platform approach is often to let bonding happen implicitly by simply reading or writing a secured characteristic and letting each OS present its own pairing prompt, reserving createBond for cases where you must bond up front.

A subtle but important point: on Android, bonding sometimes needs to happen before service discovery for encrypted services to appear, while on other devices it happens on demand. If secured characteristics are missing from your discovery results, try bonding first and rediscovering.

Because bonding behavior varies so much across manufacturers, test it specifically on your target hardware rather than assuming one flow works everywhere.

Reading Signal Strength and Setting Connection Priority

After connecting, you can still read the live signal strength and tune the connection's power profile. These help with proximity features and with balancing throughput against battery life.

Future<void> readLiveRssi(BluetoothDevice device) async {
  int rssi = await device.readRssi();
  print('Live RSSI: $rssi dBm');
}

Future<void> setHighThroughput(BluetoothDevice device) async {
  if (Platform.isAndroid) {
    await device.requestConnectionPriority(
      connectionPriorityRequest: ConnectionPriority.high,
    );
    print('Requested high connection priority');
  }
}

The readLiveRssi function calls device.readRssi, which returns the current signal strength of the active connection in dBm, distinct from the RSSI in a scan result because it reflects the live link rather than an advertisement. Polling this lets you build proximity features like "hold your phone closer".

The setHighThroughput function calls device.requestConnectionPriority with ConnectionPriority.high, which asks Android to shorten the connection interval so packets exchange more frequently, raising throughput at the cost of battery. The other options are balanced for normal use and lowPower for infrequent updates that maximize battery life.

This tuning is Android-only, since iOS manages the connection interval itself based on the peripheral's advertised preferences. Use high priority temporarily during a large transfer, then drop back to balanced to avoid draining both devices.

Handling Disconnection and Reconnection

Bluetooth connections are inherently unstable. Devices go out of range, batteries die, and radios get interrupted. A production app must handle disconnection gracefully and reconnect intelligently rather than assuming the link stays alive.

int _retryCount = 0;
const int _maxRetries = 5;

void setupAutoReconnect(BluetoothDevice device) {
  device.connectionState.listen((state) async {
    if (state == BluetoothConnectionState.connected) {
      _retryCount = 0;
      await device.discoverServices();
    } else if (state == BluetoothConnectionState.disconnected) {
      print('Disconnected: ${device.disconnectReason?.description}');
      await _attemptReconnect(device);
    }
  });
}

Future<void> _attemptReconnect(BluetoothDevice device) async {
  while (_retryCount < _maxRetries && !device.isConnected) {
    _retryCount++;
    final backoff = Duration(seconds: 1 << _retryCount);
    print('Reconnect attempt $_retryCount in ${backoff.inSeconds}s');
    await Future.delayed(backoff);
    try {
      await device.connect(timeout: const Duration(seconds: 15));
      print('Reconnected');
      return;
    } catch (e) {
      print('Reconnect failed: $e');
    }
  }
  if (!device.isConnected) {
    print('Giving up after $_maxRetries attempts');
  }
}

The setupAutoReconnect function subscribes to the connection state and reacts to both transitions. On connected, it resets the retry counter and rediscovers services, which is mandatory because the previous service objects become invalid after any disconnect. On disconnected, it logs the reason and calls the reconnect routine.

The _attemptReconnect function implements exponential backoff: it retries up to _maxRetries times, and each attempt waits longer than the last, computed as 1 << _retryCount seconds, which yields 2, 4, 8, 16, and 32 seconds. Backoff matters because hammering a device that just disappeared wastes battery and rarely succeeds, whereas spacing out attempts gives the device time to come back into range.

Each attempt is wrapped in a try/catch so a failure schedules the next retry instead of throwing, and the loop exits once the device reconnects or the retry budget is exhausted.

On Android you can alternatively pass autoConnect: true to connect, which offloads reconnection to the OS and lets the system reconnect in the background whenever the device reappears, at the cost of a slower initial connection.

Running Bluetooth in the Background

Keeping BLE alive when your app is backgrounded requires platform-specific work. iOS handles it through the background mode you declared earlier, while Android needs a foreground service so the OS doesn't kill your Bluetooth activity.

On iOS, once you've added the bluetooth-central background mode to Info.plist, the system automatically keeps your connections alive and delivers notifications to your app even when it's suspended, waking it briefly to process each update.

There's nothing more to write on the Dart side, though you should be aware that iOS throttles background scanning heavily: background scans can't use certain filters, run at a slower duty cycle, and require you to specify service UUIDs, so a filterless background scan finds nothing on iOS.

On Android, you must run a foreground service with a persistent notification so the system treats your Bluetooth work as user-visible and doesn't suspend it under Doze mode. You can do this with a package like flutter_foreground_task, configured with the connected-device service type.

import 'package:flutter_foreground_task/flutter_foreground_task.dart';

Future<void> startBleForegroundService() async {
  FlutterForegroundTask.init(
    androidNotificationOptions: AndroidNotificationOptions(
      channelId: 'ble_service',
      channelName: 'BLE Connection',
      channelDescription: 'Maintains the Bluetooth connection',
    ),
    iosNotificationOptions: const IOSNotificationOptions(),
    foregroundTaskOptions: ForegroundTaskOptions(
      eventAction: ForegroundTaskEventAction.repeat(5000),
      autoRunOnBoot: false,
      allowWakeLock: true,
    ),
  );

  await FlutterForegroundTask.startService(
    notificationTitle: 'BLE Active',
    notificationText: 'Connected to your device',
  );
}

This function initializes and starts a foreground service. The androidNotificationOptions define the persistent notification channel Android requires, including an ID, a visible name, and a description that appear in the system notification settings.

The foregroundTaskOptions control the service behavior: eventAction.repeat(5000) schedules a periodic callback every 5 seconds so you can perform maintenance work, autoRunOnBoot: false keeps the service from starting itself after a reboot, and allowWakeLock: true prevents the CPU from sleeping so your BLE callbacks fire reliably.

Calling startService shows the notification and promotes your app to foreground priority, which is what keeps the connection alive. You must also declare FOREGROUND_SERVICE and FOREGROUND_SERVICE_CONNECTED_DEVICE permissions in the manifest and set the service type to connectedDevice, because on Android 14 and above the OS enforces that the service type matches the actual work.

Stop the service with FlutterForegroundTask.stopService() when the connection is no longer needed, since a lingering notification annoys users.

Error Handling

BLE operations fail in many ways, and the plugin surfaces failures as a FlutterBluePlusException with a code you can inspect. Catching and interpreting these turns cryptic crashes into recoverable states.

Future<List<int>> safeRead(BluetoothCharacteristic c) async {
  try {
    return await c.read();
  } on FlutterBluePlusException catch (e) {
    print('BLE error: function=${e.function}, code=${e.code}, '
        'description=${e.description}');
    if (e.code == 6) {
      print('Device is disconnected');
    }
    return [];
  } on PlatformException catch (e) {
    print('Platform error: ${e.message}');
    return [];
  } catch (e) {
    print('Unexpected error: $e');
    return [];
  }
}

This function wraps a characteristic read in layered error handling. The first catch handles FlutterBluePlusException, the plugin's own exception type, which exposes function (the operation that failed), code (a numeric error code from the underlying platform), and description (a readable message). Checking specific codes, such as code 6 indicating the device disconnected, lets you branch to appropriate recovery.

The second catch handles PlatformException, which can arise from the platform channel itself, and the final generic catch is a safety net for anything unforeseen. Returning an empty list from every branch keeps the caller simple, though in a real app you might rethrow a typed error or update UI state instead.

The core lesson is that every BLE call can throw, so wrap reads, writes, connects, and subscribes in try/catch rather than letting an exception tear down your widget tree.

A Production BLE Service Architecture

Scattering BLE calls across widgets becomes unmaintainable quickly. A better structure isolates all Bluetooth logic in a single service class that exposes streams of state, which your UI and state management layer consume. This keeps widgets ignorant of BLE details and makes the logic testable.

enum BleConnectionStatus { disconnected, scanning, connecting, connected }

class BleService {
  BluetoothDevice? _device;
  BluetoothCharacteristic? _dataCharacteristic;

  final _statusController =
      StreamController<BleConnectionStatus>.broadcast();
  final _dataController = StreamController<List<int>>.broadcast();

  Stream<BleConnectionStatus> get status => _statusController.stream;
  Stream<List<int>> get data => _dataController.stream;

  final Guid serviceUuid = Guid('180D');
  final Guid characteristicUuid = Guid('2A37');

  Future<void> scanAndConnect() async {
    _statusController.add(BleConnectionStatus.scanning);

    await FlutterBluePlus.startScan(
      withServices: [serviceUuid],
      timeout: const Duration(seconds: 15),
    );

    final results = await FlutterBluePlus.onScanResults.first;
    if (results.isEmpty) {
      _statusController.add(BleConnectionStatus.disconnected);
      return;
    }

    await FlutterBluePlus.stopScan();
    await _connect(results.first.device);
  }

  Future<void> _connect(BluetoothDevice device) async {
    _device = device;
    _statusController.add(BleConnectionStatus.connecting);

    device.connectionState.listen((state) {
      if (state == BluetoothConnectionState.connected) {
        _statusController.add(BleConnectionStatus.connected);
      } else if (state == BluetoothConnectionState.disconnected) {
        _statusController.add(BleConnectionStatus.disconnected);
      }
    });

    await device.connect(timeout: const Duration(seconds: 15));
    await _setupCharacteristic();
  }

  Future<void> _setupCharacteristic() async {
    final services = await _device!.discoverServices();
    for (final service in services) {
      if (service.uuid == serviceUuid) {
        for (final c in service.characteristics) {
          if (c.uuid == characteristicUuid) {
            _dataCharacteristic = c;
            c.onValueReceived.listen(_dataController.add);
            await c.setNotifyValue(true);
          }
        }
      }
    }
  }

  Future<void> send(List<int> bytes) async {
    await _dataCharacteristic?.write(bytes);
  }

  Future<void> dispose() async {
    await _device?.disconnect();
    await _statusController.close();
    await _dataController.close();
  }
}

This service encapsulates the entire BLE workflow behind a small interface. It defines a BleConnectionStatus enum for a clean, UI-friendly view of the connection, and exposes two broadcast streams: status for lifecycle changes and data for incoming characteristic values, with broadcast controllers so multiple listeners can subscribe.

The scanAndConnect method drives the happy path: it publishes a scanning status, starts a filtered scan, waits for the first batch of results, stops scanning, and connects to the first match, publishing a disconnected status if nothing was found.

The private _connect method wires up a connection-state listener that maps BLE states onto the enum, then connects and sets up the characteristic. The _setupCharacteristic method discovers services, locates the target characteristic, forwards its onValueReceived stream into the service's data controller, and enables notifications. The send method writes bytes to the cached characteristic, and dispose disconnects and closes the controllers so nothing leaks.

By funneling everything through streams of a simple enum and byte lists, the UI never touches a BluetoothDevice directly, which makes the widgets trivial and the whole thing far easier to reason about and swap out.

Building the UI

With the service in place, the UI becomes a thin layer that reacts to streams. Here's a scanner and status screen that consumes the service.

import 'package:flutter/material.dart';

class BleHomePage extends StatefulWidget {
  final BleService service;
  const BleHomePage({super.key, required this.service});

  @override
  State<BleHomePage> createState() => _BleHomePageState();
}

class _BleHomePageState extends State<BleHomePage> {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('BLE Demo')),
      body: Column(
        children: [
          StreamBuilder<BleConnectionStatus>(
            stream: widget.service.status,
            initialData: BleConnectionStatus.disconnected,
            builder: (context, snapshot) {
              return ListTile(
                leading: const Icon(Icons.bluetooth),
                title: Text('Status: ${snapshot.data?.name}'),
              );
            },
          ),
          Expanded(
            child: StreamBuilder<List<int>>(
              stream: widget.service.data,
              builder: (context, snapshot) {
                if (!snapshot.hasData) {
                  return const Center(child: Text('No data yet'));
                }
                final hr = snapshot.data!.length > 1 ? snapshot.data![1] : 0;
                return Center(
                  child: Text('$hr bpm',
                      style: const TextStyle(fontSize: 48)),
                );
              },
            ),
          ),
        ],
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: widget.service.scanAndConnect,
        child: const Icon(Icons.search),
      ),
    );
  }
}

This widget takes a BleService and binds its UI entirely to the service's streams. The first StreamBuilder listens to the status stream and renders the current connection state as a list tile, with initialData so the tile shows something before the first event arrives.

The second StreamBuilder, wrapped in Expanded, listens to the data stream and displays the incoming value; it interprets byte index 1 of the heart rate payload as the reading and shows it in large text, falling back to a placeholder when no data has arrived yet.

The floating action button simply calls service.scanAndConnect, so the entire interactive surface is one method call. Because the widget holds no BLE objects and no connection logic, it's easy to test with a fake service that pushes canned values into the same streams, and swapping the underlying BLE package wouldn't touch this file at all.

For a larger app, wrap the service in a Provider, Riverpod provider, or Bloc so it is injected rather than passed manually.

Testing and Debugging

BLE is hard to test because it depends on physical hardware and radio conditions, but a few practices make it manageable.

The most valuable tool is the nRF Connect app from Nordic Semiconductor, available for free on both Android and iOS. It lets you scan, connect, and browse the full GATT tree of any peripheral, read and write characteristics by hand, and log every packet.

Before writing a single line of Dart against a new device, connect to it with nRF Connect and note the exact service and characteristic UUIDs, their properties, and the byte format of each value. This removes guesswork and tells you whether a problem is in your code or the hardware.

For unit testing your own logic, isolate the pure functions. The byte encoding and decoding helpers from earlier are ordinary Dart with no plugin dependency, so you can test them directly without any device.

import 'package:flutter_test/flutter_test.dart';

void main() {
  test('readUint16LE decodes little-endian correctly', () {
    expect(readUint16LE([0x34, 0x12], 0), equals(0x1234));
  });

  test('parseHeartRate handles 8-bit format', () {
    expect(parseHeartRate([0x00, 72]), equals(72));
  });

  test('parseHeartRate handles 16-bit format', () {
    expect(parseHeartRate([0x01, 0x2C, 0x01]), equals(300));
  });
}

These tests exercise the decoding logic without any Bluetooth hardware. The first confirms that readUint16LE correctly assembles the bytes 0x34, 0x12 into 0x1234, verifying the little-endian byte order. The second and third test parseHeartRate with both formats its flags byte selects: an 8-bit value of 72 and a 16-bit value of 300 encoded as 0x2C, 0x01.

Because you designed the service to keep BLE side effects separate from data interpretation, all the tricky parsing logic is covered by fast, deterministic tests that run in CI.

For the BLE calls themselves, the practical approach is manual testing on real hardware combined with an abstraction like the BleService interface, which you can replace with a fake implementation in widget tests that pushes scripted values into the same streams the UI consumes.

When debugging live connections, enable the plugin's verbose logging to see every operation and its result.

FlutterBluePlus.setLogLevel(LogLevel.verbose, color: true);

This sets the plugin's log level to verbose, which prints every scan result, connection event, read, write, and notification to the console, with color: true making the output easier to scan visually.

Turning this on while chasing a connection or data bug shows exactly where the sequence breaks, for example whether a write was even attempted or whether service discovery returned the characteristic you expected. Set it back to LogLevel.none or LogLevel.error before shipping, since verbose logging is noisy and can leak details about the connected device.

Performance and Battery Optimization

BLE is designed for low power, but careless code undoes that. The single biggest drain is scanning, so never scan continuously. Always pass a timeout to startScan, filter by service UUID so the radio wakes your app less often, and stop scanning the moment you have found your device. Leaving a scan running in the background is the fastest way to earn one-star reviews about battery life.

The connection interval is the next lever. A short interval gives snappy, high-throughput communication but keeps both radios busy, while a long interval sips power at the cost of latency. Use requestConnectionPriority(ConnectionPriority.high) only during bursts like firmware updates or large transfers, and drop back to balanced or lowPower for idle monitoring. Match the interval to the actual data rate your app needs rather than always demanding high throughput.

Batch your operations. Every read, write, and notification costs a radio wakeup, so combining several small values into one larger characteristic, or reading a block once instead of many fields separately, saves power and time. Where the peripheral supports it, prefer notifications over polling, because a notification only transmits when data actually changes whereas polling burns energy asking "anything new?" over and over.

Finally, disconnect when you are done rather than holding an idle connection open, since maintaining a link consumes power even when no data flows, and phones cap the number of concurrent connections. Releasing one frees a slot for the next.

Common Pitfalls

The single most common mistake is testing on an emulator. Neither the Android emulator nor the iOS simulator has a Bluetooth radio, so nothing will ever appear in your scan. Always test on physical hardware, and ideally test on both an old and a new Android device to catch the permission differences between Android 11 and Android 12, since a bug that only appears on one generation is easy to miss otherwise.

The second frequent issue is forgetting that scan results often have empty names. Many peripherals don't include their name in the advertising packet to save the limited 31-byte budget, so relying on advName for identification fails. Filter by service UUID or match on the stable remoteId instead, and treat the name as a nice-to-have for display only.

A third trap is ignoring the connection lifecycle. Developers connect once, run their reads, and assume the link stays up. It will not. Always subscribe to connectionState, handle disconnects, and rediscover services after every reconnection because the old service and characteristic objects become stale and their reads silently fail or throw.

Related to this, remember to cancel your stream subscriptions when they're no longer needed, otherwise you leak listeners every time a widget rebuilds, which eventually causes duplicate handling of every notification.

A fourth pitfall is the MTU. If your writes silently truncate at 20 bytes, you forgot to negotiate a larger MTU or you exceeded the negotiated size. Keep payloads within the negotiated MTU minus 3 bytes of overhead, and remember MTU negotiation is Android-only in the API since iOS handles it automatically.

A fifth is byte-order confusion: assuming big-endian when the device uses little-endian, or reading a signed value as unsigned, produces plausible but wrong numbers. This is why you should always verify the format against the specification and cover your parsers with unit tests.

Finally, don't scan and connect simultaneously on Android, because it causes intermittent connection failures that are maddening to reproduce. Stop the scan first, then connect.

Summary

Bluetooth Low Energy in Flutter comes down to a predictable sequence that mirrors how BLE itself works: configure permissions for each platform, confirm the adapter is on, scan for peripherals and inspect their advertisements, connect to the one you want, negotiate an MTU if you need large payloads, discover services and characteristics, then read, write, or subscribe as the characteristic properties allow.

The flutter_blue_plus package models each of these steps directly through streams. Once you internalize the GATT hierarchy of services, characteristics, and descriptors, the API stops feeling mysterious and starts feeling like a thin wrapper over a well-defined protocol.

The parts that trip people up are almost never the happy path. They're the platform permission differences between Android versions, the empty device names, the unstable connections that require reconnection with backoff, the byte-level encoding that demands the device specification, and the MTU limits that silently truncate data. Handle those deliberately, isolate all of it behind a service class that exposes clean streams, and cover your parsing logic with unit tests, and your BLE app will feel solid rather than flaky.

From here, the natural next steps depend on your goal. If you're building against standard devices like heart rate monitors, thermometers, or glucose meters, look up the official Bluetooth SIG GATT specifications, because they define the exact UUIDs and byte layouts you need.

If you're building custom hardware, generate your own 128-bit UUIDs and document the byte format of every characteristic so your firmware and app agree.

For robustness, add proper state management with Provider or Riverpod, implement background operation only if you truly need it, and lean on nRF Connect to verify the hardware before blaming your code.

With the foundation in this article, you can talk to almost any BLE peripheral from a Flutter app and ship something reliable.

Gabeldorsche is Google's attempt to fix that at the architectural level, not with another patch on top of the old code but with a ground-up rewrite of the stack internals.

This article explains what Gabeldorsche actually is, how its architecture is put together, and how the pieces fit at the implementation level.

We'll walk through the OS abstraction, the module system, the threading and queue model, the HCI layer, the packet parsing generator, the ACL data path, L2CAP, security, the neighbor and storage modules, the shim and facade layers, the build system, and the testing infrastructure, with real code patterns for each.

The scope here is the internal architecture of the stack, not the public Android Bluetooth APIs your app calls. If you've ever wondered what happens between BluetoothDevice.createBond() and the actual radio, this is that layer, and this article goes deep into it.

Table of Contents

• Prerequisites

• What Gabeldorsche Is and Why It Exists

• A Short History and the Migration Strategy

• The Layered Architecture

• The OS Abstraction Layer

• The Module System

• The Stack Bootstrap

• The Queue Abstraction

• The HCI Layer

• The Packet Definition Language

• The ACL Manager and Connection Management

• The Round Robin Scheduler and the ACL Data Path

• L2CAP and the Data Pipeline

• Security and Pairing

• GATT and ATT

• The Neighbor and Storage Modules

• The Shim and Facade Layers

• Build System Integration

• Logging, Metrics, and dumpsys

• Testing with Cert Tests and RootCanal

• Floss: Gabeldorsche Beyond Android

• Summary

Prerequisites

You should be comfortable with modern C++ (C++17 idioms like lambdas, std::unique_ptr, move semantics, and template basics), and you should have a rough mental model of the Bluetooth protocol stack (HCI, L2CAP, ATT, GATT, the difference between Classic and Low Energy).

Familiarity with event-driven and message-passing concurrency helps a great deal, because Gabeldorsche leans on it hard. Some exposure to epoll or a reactor-style event loop will make the OS layer feel familiar.

You don't need to have hacked on AOSP before, but knowing that AOSP is enormous and slow to build will emotionally prepare you.

What Gabeldorsche Is and Why It Exists

Gabeldorsche, usually abbreviated as GD, is the rearchitected core of the Android Bluetooth stack. The name is a running Google tradition of picking place names in the Bavarian Alps region as codenames. And yes, nearly everyone mispronounces it, which is arguably part of the charm.

In the source tree it lives under the Bluetooth module at packages/modules/Bluetooth/system/gd/, having graduated from its original home at system/bt/gd/ when Bluetooth became an updatable Mainline module.

The stack it replaces is usually called Fluoride, and before that BlueDroid. That older code worked, in the sense that a bridge held up by hope also works.

It was built around a large web of global state, callback chains that were difficult to reason about, and threading that varied by subsystem. When something went wrong, reproducing it was a coin flip, and unit testing individual layers in isolation ranged from painful to impossible. Bluetooth bugs became famous for being non-deterministic, and non-deterministic bugs are the ones that survive to production and then to angry reviews.

Gabeldorsche was designed around a small number of firm opinions. Every layer should be a self-contained module with explicit dependencies. Concurrency should be message passing on well-defined threads instead of shared locks scattered through the code. Packet parsing should be generated from a formal specification rather than hand-written byte arithmetic, because hand-written byte arithmetic is where security bugs go to be born. Every layer should be testable in isolation against a virtual controller, so continuous integration can catch regressions before your earbuds do. And the whole thing should be portable enough to run somewhere other than Android, which turned out to matter more than anyone expected.

A Short History and the Migration Strategy

Gabeldorsche was announced publicly around 2019 and 2020 as a multi-year effort, and it was never going to land as a single commit. You can't atomically swap the Bluetooth stack on a billion devices, so the rollout was designed to be gradual, reversible, and boring, which are three excellent adjectives for infrastructure work.

The migration proceeded one layer at a time from the bottom up. The HCI layer moved to GD first, because it sits closest to the controller and has the cleanest boundary. Then the ACL and connection management layers, then L2CAP, then security, and so on upward.

Each layer was gated behind a flag so that a device could run the new GD implementation of one layer while still using the legacy implementation of the layers above and below it. This is why the shim layer, discussed later, exists at all.

The flags themselves lived as system properties and later as aconfig flags, and they let the team ship a GD layer to a small population, watch the crash and connection metrics, and roll it back instantly if something regressed.

Because each layer was independently toggleable, a regression could be bisected to a single layer by flipping flags rather than by staring at stack traces. This unglamorous flag discipline is a large part of why the rewrite reached production without a catastrophe, and it's worth studying even if you never touch Bluetooth.

The Layered Architecture

Gabeldorsche is organized as a stack of layers, each one a module that depends on the layers beneath it. The following diagram shows the major layers from the radio hardware at the bottom to the Android framework at the top.

        +------------------------------------------+
        |     Android Framework (Java / AIDL)      |
        +------------------------------------------+
        |     BTIF / BTA (legacy profile logic)    |
        +------------------------------------------+
        |     Shim layer (GD <~> legacy bridge)    |
        +------------------------------------------+
        |  GATT | Security | L2CAP | Neighbor      | 
        +------------------------------------------+
        |  AclManager | Controller | HciLayer      |   
        +------------------------------------------+
        |     hci_hal (HAL: AIDL / HIDL interface) |
        +------------------------------------------+
        |     Bluetooth Controller (radio chip)    |
        +------------------------------------------+

The diagram reads bottom to top as a dependency ladder. The controller chip speaks HCI over a physical transport. The hci_hal layer wraps the Android hardware abstraction interface so the rest of the stack doesn't care whether the transport is UART, USB, or a virtual socket.

Above it, the HCI layer manages command flow control and demultiplexes events, the Controller module caches the chip's capabilities, and AclManager owns connections.

The upper layers implement L2CAP channels, security, neighbor operations like inquiry and page scan, and the GATT database. The shim layer is a temporary bridge that lets the new GD modules coexist with the older BTIF and BTA profile code during migration. At the very top sits the Android framework that applications talk to.

The important structural point is that each layer only reaches downward through explicit interfaces, never sideways into another layer's internals.

The OS Abstraction Layer

Before any Bluetooth logic exists, Gabeldorsche defines its own small operating system abstraction in the os/ directory. This is the foundation everything else stands on, and it exists so the stack can run unchanged on Android, Linux, and inside tests.

The following table lists the core primitives and what each one is responsible for:

This table maps each OS primitive to its one job. Thread and Reactor are the execution substrate: a thread is a reactor plus a real kernel thread wrapped around it. Handler is how other code schedules work onto a thread without touching its internals. Alarm and RepeatingAlarm add time to the model. Queue and EnqueueBuffer are the data-movement primitives that connect producers to consumers.

Everything above this layer is built out of exactly these pieces, which is why understanding them pays off across the entire codebase.

A Thread in GD isn't just a raw kernel thread. It owns a Reactor, which is an epoll-based event loop. Instead of blocking on a socket read, you register a file descriptor with the reactor and hand it a callback to run when the descriptor becomes readable.

The thread spins the reactor loop, and all work on that thread happens as reactions to events. Threads can be created at normal or real-time priority, and the stack uses a higher priority for the threads on the data path so that audio doesn't stutter when the system is busy. This is the same idea as libevent or the Node.js event loop, just wearing a Bluetooth badge.

The Reactor is worth understanding because it's the beating heart of every thread. It holds an epoll file descriptor and a set of registered reactables, each pairing a file descriptor with an on-read and an optional on-write callback.

The loop calls epoll_wait, and for each ready descriptor it invokes the registered callback. One subtle detail is unregistration safety: a callback might ask to unregister its own reactable while the reactor is mid-dispatch, so the reactor tracks the currently executing reactable and defers its destruction, which prevents a use-after-free that would otherwise be trivial to trigger. The reactor also uses an internal control file descriptor so another thread can wake it up to stop cleanly.

A Handler is the mechanism for getting work onto a specific thread. You post a closure to a handler, and the closure runs on that handler's thread. Internally, a handler owns a queue of closures plus an eventfd registered with the reactor, so posting work writes to the eventfd, which wakes the reactor, which drains the closure queue.

This is how the entire stack avoids locks: instead of two threads grabbing a mutex to touch shared state, one thread posts a message to the other thread's handler, and the state is only ever touched by its owning thread.

// Get the module's handler and post work onto its thread.
os::Handler* handler = GetHandler();

handler->Post(common::BindOnce(
    [](int connection_handle) {
      // This lambda runs on the handler's thread, not the caller's.
      LOG_INFO("Tearing down connection %d", connection_handle);
    },
    connection_handle));

This snippet shows the central concurrency pattern of the stack. GetHandler() returns the handler associated with the current module, which is bound to a specific thread. common::BindOnce packages a callable together with its arguments into a one-shot closure, similar to std::bind but move-aware and single-use, which matters because many Bluetooth payloads are move-only buffers. handler->Post writes to the handler's eventfd and enqueues that closure to run on the handler's thread. The consequence is that the lambda body executes serially on one thread, so it can read and write that module's state without any mutex.

If you internalize one thing about Gabeldorsche, make it this: work travels to the data's thread, the data does not travel to the work.

For time-based work, there's Alarm and RepeatingAlarm. An alarm schedules a closure to run on a handler after a delay, and it's built on top of the same reactor using a timerfd, so timers are just another readable file descriptor in the loop rather than a separate timer thread.

// Fire a one-shot timeout on this module's handler thread.
alarm_ = std::make_unique<os::Alarm>(GetHandler());

alarm_->Schedule(
    common::BindOnce(&MyModule::OnConnectionTimeout, common::Unretained(this)),
    std::chrono::milliseconds(5000));

The alarm here is constructed against the module's handler, which ties its callback to the correct thread. Schedule takes a closure and a duration, arms a timerfd for that duration, and when it fires the reactor runs OnConnectionTimeout on the handler thread.

common::Unretained(this) tells the binder to keep a raw pointer to the object without extending its lifetime, which is safe here precisely because the alarm and the object live on the same thread and are torn down in a known order.

That last point matters. Unretained is a promise you're making to the compiler, and if you break it, the crash will be memorable and probably remote.

The Module System

Every functional layer in Gabeldorsche is a Module. A module has a lifecycle, a set of dependencies, and its own handler thread affinity. The ModuleRegistry is responsible for starting modules in dependency order and stopping them in reverse. This turns the old tangle of initialization ordering into something a computer can figure out on its own, which is a healthier arrangement than a comment that says "do not reorder these calls."

A module subclasses Module, declares a static ModuleFactory, and implements a small set of methods. The most important ones are ListDependencies, Start, and Stop.

class ExampleModule : public bluetooth::Module {
 public:
  static const ModuleFactory Factory;

 protected:
  void ListDependencies(ModuleList* list) const override {
    list->add<hci::HciLayer>();
    list->add<hci::Controller>();
  }

  void Start() override {
    hci_layer_ = GetDependency<hci::HciLayer>();
    controller_ = GetDependency<hci::Controller>();
    // Module is now ready to do work on GetHandler().
  }

  void Stop() override {
    // Release references; the registry stops dependencies after this.
    hci_layer_ = nullptr;
    controller_ = nullptr;
  }

  std::string ToString() const override { return "ExampleModule"; }

 private:
  hci::HciLayer* hci_layer_ = nullptr;
  hci::Controller* controller_ = nullptr;
};

const ModuleFactory ExampleModule::Factory =
    ModuleFactory([]() { return new ExampleModule(); });

This class demonstrates the full contract of a module.

ListDependencies declares, at construction time, which other modules this one needs, by adding their types to the ModuleList. The registry reads these declarations across all modules and computes a start order so that HciLayer and Controller are running before ExampleModule::Start is ever called.

Inside Start, GetDependency<T>() looks up the already-running instance of each dependency by its factory and returns it as a raw pointer, which the module caches because the registry guarantees the dependency outlives it. Stop runs during shutdown before the dependencies are stopped, giving the module a chance to release references and cancel outstanding work.

ToString gives the module a name for logging and dumpsys. The static Factory is a small object holding a lambda that constructs the module, and it is the handle the registry uses both to instantiate the module and to identify it in the dependency graph. There's no global initialization order to get wrong, because you never write the order at all.

The registry itself is what glues this together at boot, and it also assigns each module its handler.

ModuleList modules;
modules.add<ExampleModule>();

// The registry topologically sorts and starts everything.
ModuleRegistry registry;
registry.Start(&modules, thread);

// ... stack runs ...

registry.StopAll();

Here the application declares the top-level modules it wants and hands them to the registry along with the thread the modules will run on.

Start walks the dependency graph, starts each module exactly once in topological order, injects dependencies, and gives each module a Handler bound to the supplied thread.

StopAll reverses the process, calling Stop in the exact reverse of the start order so no module is ever torn down before something that depends on it.

Because dependencies are explicit data rather than imperative code, the same machinery powers a TestModuleRegistry that lets a test start a single real module on top of fake dependencies.

That test variant is the quiet superpower of this design. Because a module only ever reaches its dependencies through GetDependency<T>(), a test can register a fake HciLayer before starting the real module under test, and the module can't tell the difference.

TestModuleRegistry test_registry;
test_registry.InjectTestModule(&HciLayer::Factory, fake_hci_layer_);
test_registry.Start<ExampleModule>(&test_registry.GetTestModuleList());

// Drive the fake HCI layer, assert on what ExampleModule does in response.

In this test setup, InjectTestModule pre-registers a fake implementation against the real HciLayer factory key, so any module that depends on HciLayer transparently receives the fake. Start<ExampleModule> then brings up the real module under test on top of it. The test can now feed events into the fake HCI layer and assert on the commands ExampleModule sends, all on a controlled thread, with no hardware and no other layers involved.

This is unit testing in the honest sense of the word, where the unit is genuinely isolated, which was close to impossible in the previous stack.

The Stack Bootstrap

Something has to construct the registry, pick the thread, add the top-level modules, and bring the whole thing to life. That something is the Stack object. It's the single entry point that owns the ModuleRegistry and the main thread, and it's what the shim layer talks to when Android decides Bluetooth should turn on.

The bootstrap does three things in order. It creates a Thread at the appropriate priority for the stack to run on. It builds a ModuleList containing the top-level modules for the current configuration, which pulls in all of their transitive dependencies automatically. Then it starts the registry against that thread and blocks until every module has finished starting, so that by the time the call returns the stack is fully operational.

Shutdown is the mirror image: stop the registry, which stops every module in reverse dependency order, then join the thread.

Concentrating this in one object means there's exactly one place that knows how the stack comes up and goes down, instead of the historical situation where startup was an emergent property of many files being included in the right order and hoping.

The Queue Abstraction

Modules that produce and consume a stream of packets don't call each other directly. They connect through a Queue, which is a reactive, bounded, single-producer single-consumer channel built on the reactor. This is how ACL data, for example, flows between L2CAP and the HCI layer without either side blocking or sharing a lock.

The queue exposes two half-interfaces, one for each end. The producer side implements enqueue by registering a callback that the queue invokes when there's room. The consumer side registers a callback that the queue invokes when data is available. Nobody ever busy-waits, and nobody blocks on a full or empty queue.

// Producer side: register to be asked for the next packet.
queue_end_->RegisterEnqueue(
    handler_,
    common::Bind(&MyModule::OnQueueReadyToSend, common::Unretained(this)));

std::unique_ptr<packet::BasePacketBuilder> MyModule::OnQueueReadyToSend() {
  if (pending_packets_.empty()) {
    queue_end_->UnregisterEnqueue();  // Nothing to send; stop being asked.
    return nullptr;
  }
  auto packet = std::move(pending_packets_.front());
  pending_packets_.pop();
  return packet;
}

This is the enqueue half of the pattern and it's inverted from what most people expect. You don't push data into the queue. Instead you call RegisterEnqueue with a callback, and when the queue has capacity it calls your callback asking for the next item.

Your callback returns one packet builder, or returns nullptr after calling UnregisterEnqueue when you have nothing left to send. This inversion is deliberate: it means backpressure is automatic. If the downstream consumer is slow and the queue fills up, your callback simply stops being called, and packets pile up in your own buffer where you can see them and account for them, rather than in some hidden kernel buffer where they turn into latency you can't explain.

The dequeue half mirrors this exactly.

// Consumer side: register to be told when a packet arrives.
queue_end_->RegisterDequeue(
    handler_,
    common::Bind(&MyModule::OnPacketReceived, common::Unretained(this)));

void MyModule::OnPacketReceived() {
  auto packet = queue_end_->TryDequeue();
  if (packet == nullptr) {
    return;
  }
  // Process the received packet on handler_'s thread.
}

On the consuming side, RegisterDequeue hands the queue a callback bound to a handler. When a packet becomes available, the queue posts that callback to the handler thread, and inside it you call TryDequeue to retrieve the packet. The TryDequeue can still return nullptr if the item was already taken, so you check. The same thread-affinity rule applies: the callback runs on handler_'s thread, so packet processing is serial and lock-free.

Under the hood the two ends coordinate through a small reactive semaphore built on an eventfd, which is what lets one thread's producer safely signal another thread's consumer. When you have many items to push, EnqueueBuffer wraps this whole dance so you can add items and let the buffer drive the registration for you, which is what most call sites actually use.

The HCI Layer

The Host Controller Interface is the protocol between the host stack and the controller chip. In Gabeldorsche the HciLayer module owns the command channel and enforces the one rule that trips up every naïve implementation: the controller tells you how many commands it can accept at once through a credit count. If you send more than it has credits for, things break in ways that are miserable to trace.

You don't write HCI bytes directly. You build a typed command packet, hand it to the HCI layer, and provide a callback for the eventual response. The layer handles flow control, matching responses to the commands that triggered them, and routing unsolicited events to subscribers.

hci_layer_->EnqueueCommand(
    hci::ResetBuilder::Create(),
    GetHandler()->BindOnceOn(this, &MyModule::OnResetComplete));

void MyModule::OnResetComplete(hci::CommandCompleteView view) {
  auto reset_view = hci::ResetCompleteView::Create(view);
  ASSERT(reset_view.IsValid());
  if (reset_view.GetStatus() != hci::ErrorCode::SUCCESS) {
    LOG_ERROR("Reset failed");
  }
}

This sends the HCI Reset command and handles its completion. hci::ResetBuilder::Create() builds a typed, validated command packet, so you physically can't send a malformed Reset.

EnqueueCommand places the command in the layer's internal command queue, which only releases a command to the controller when a credit is available and holds the rest until the controller returns credits in its responses. The second argument is a callback bound to your handler with BindOnceOn, so the completion runs on your thread.

Commands come in two flavors, those answered by a Command Complete event and those answered by a Command Status event, and the layer has EnqueueCommand overloads that route each to the right callback type.

When the response arrives you receive a generic view, narrow it to the specific ResetCompleteView, and check IsValid() before reading fields. That validity check isn't ceremony. It's the parser telling you whether the bytes actually match the structure you expect.

The HCI layer also splits its outputs into distinct streams instead of one overloaded callback. Command responses go to the callback you supplied with the command. Unsolicited events like a remote device connecting are delivered to whichever module registered a handler for that specific event code. LE meta-events, subevents of the single LE Meta Event opcode, are demultiplexed to their own subscribers. And the layer exposes narrower sub-interfaces, such as a security interface and an LE advertising interface, so that a module only sees the slice of HCI it actually cares about rather than the entire firehose.

This separation keeps request-response logic away from spontaneous-event logic, which in the old stack were frequently the same function trying to do three jobs at once.

Sitting beside HciLayer is the Controller module, whose job is to interrogate the chip once at startup and cache the answers. It issues the read-local-version, read-local-supported-commands, read-buffer-size, and LE feature commands, then exposes the results through simple getters.

This matters because the rest of the stack constantly needs to know things like the ACL buffer size and how many packets the controller can hold, and asking once and caching is far better than asking the chip repeatedly. When a higher layer wants to know whether a feature is supported, it asks the Controller, not the hardware.

The Packet Definition Language

Here's the feature that quietly does the most good. In the old stack, parsing a packet meant reading bytes at hand-computed offsets, shifting and masking by hand, and hoping every author got the endianness and bounds checking right. They didn't always get it right, and malformed Bluetooth packets are a classic remote attack surface, the kind that ends up with a catchy name and a logo.

Gabeldorsche replaces all of that with a Packet Definition Language, or PDL. You describe the wire format once in a .pdl file, and a generator called bluetooth_packetgen emits C++ parser and builder classes from it.

A PDL file starts by declaring endianness and then defines enums, structs, and packets. The following table summarizes the field constructs you'll see most often:

This table covers the vocabulary of a PDL file. Scalar and enum fields describe individual values with exact bit widths, so a 3-bit field is genuinely 3 bits and the generator packs it accordingly. The array forms describe repeated data, either variable or fixed length.

The _size_ and _count_ fields are the clever part: they let the format describe a length prefix once, and the generator wires up the arithmetic so that the builder computes the length on serialize and the view validates it on parse.

The _payload_ marker is how packet inheritance carries a child's body inside a parent. And _fixed_ and _reserved_ encode constants and mandatory zeroes so no human has to remember them.

Everything here is declarative, and the generator turns it into code that can't forget a bounds check.

A concrete definition looks like a struct description with explicit widths and constraints, where child packets constrain fields of their parents.

little_endian_packets

enum OpCode : 16 {
  RESET = 0x0C03,
  READ_LOCAL_NAME = 0x0C14,
}

packet Command {
  op_code : OpCode,
  _size_(payload) : 8,
  _payload_,
}

packet Reset : Command (op_code = RESET) {
}

packet ReadLocalNameComplete : CommandComplete (command_op_code = READ_LOCAL_NAME) {
  status : ErrorCode,
  local_name : 8[248],
}

This defines an opcode enum, a generic Command parent, and two concrete packets. The Command packet carries an op_code, a one-byte size of its payload, and the payload itself, which is the generic shape every command shares. Reset inherits from Command and fixes op_code to RESET, so the generated builder always emits the correct opcode and the generated view can recognize a Reset by matching that constraint. ReadLocalNameComplete inherits from CommandComplete and adds a status enum field plus local_name written as 8[248], meaning 248 elements of 8 bits each, which is exactly how the Bluetooth specification defines the local name field.

The constraints in parentheses are what let generated code route a raw buffer to the correct view type based on the opcode it carries, without a hand-written switch statement anywhere.

From that definition, the generator produces two kinds of classes per packet. A Builder serializes structured data into bytes, and a View parses bytes into structured, bounds-checked accessors.

// Building: structured data becomes validated bytes.
auto builder = hci::ResetBuilder::Create();
std::vector<uint8_t> bytes;
BitInserter it(bytes);
builder->Serialize(it);   // writes op_code, computed size, payload

// Parsing: bytes become a validated, typed view.
auto command_view = hci::CommandView::Create(
    PacketView<kLittleEndian>(std::make_shared<std::vector<uint8_t>>(bytes)));
auto name_view = hci::ReadLocalNameCompleteView::Create(command_view);

if (name_view.IsValid()) {
  std::array<uint8_t, 248> name = name_view.GetLocalName();
}

The building side shows that a builder knows the exact layout: Serialize walks the fields in order through a BitInserter, writing the fixed opcode, computing and writing the payload size, and emitting the payload, so you never touch an offset.

The parsing side is lazy and layered. A PacketView<kLittleEndian> wraps a shared byte buffer without copying it, a generic CommandView interprets the common command header, and the specific ReadLocalNameCompleteView narrows it further.

The critical method is IsValid(), which the generated code implements to verify that the buffer is long enough for every field and that all constraints hold before you read anything. Only after that check do you call GetLocalName() to pull out the parsed field as a typed array.

Because the parser is generated from the same specification for every packet, a whole category of off-by-one and out-of-bounds bugs simply can't be written by hand anymore. There's even a Python binding, generated from the same PDL, so the test suite parses and builds packets with byte-for-byte identical logic to the production stack.

The ACL Manager and Connection Management

Above the raw HCI layer sits the AclManager, the module responsible for asynchronous connection-oriented links, which is what carries actual user data once devices are connected. It manages both Classic and Low Energy connections, and it presents connections as objects with their own callback interfaces rather than as integer handles floating around global tables waiting to be misused. Internally it splits into a classic implementation and an LE implementation that share the round-robin data scheduler described in the next section.

When you request a connection, you register a callback that fires when the connection succeeds or fails, and on success you receive a connection object that owns the queue for that link.

// Register interest in Classic connection events, then connect.
acl_manager_->RegisterCallbacks(this, GetHandler());
acl_manager_->CreateConnection(remote_address);

void MyModule::OnConnectSuccess(
    std::unique_ptr<hci::acl_manager::ClassicAclConnection> connection) {
  uint16_t handle = connection->GetHandle();
  // The connection object owns the data queue for this link.
  connection->GetAclQueueEnd()->RegisterDequeue(
      GetHandler(),
      common::Bind(&MyModule::OnAclData, common::Unretained(this)));
  connections_[handle] = std::move(connection);
}

This shows the connection lifecycle from the consumer's point of view. RegisterCallbacks subscribes your module to connection events on your handler thread, and CreateConnection kicks off the HCI dance to page and connect to the remote address.

When it succeeds, OnConnectSuccess receives a ClassicAclConnection owned by a unique_ptr, which means ownership is explicit and the link is torn down deterministically when the object is destroyed. The connection carries its own data queue, accessed through GetAclQueueEnd(), and you register a dequeue callback on it using the exact same queue pattern from earlier.

Finally you move the connection into your own map keyed by handle. There's no ambiguity about who owns the link, which was a genuine source of use-after-free bugs in the previous design.

The LE side adds one wrinkle that deserves a mention: privacy. LE devices rotate their advertising address using a Resolvable Private Address so that trackers can't follow a device by its MAC.

Gabeldorsche has an LeAddressManager that owns the local address rotation and the controller's resolving list, coordinating when the address may change so that it doesn't rotate in the middle of an operation that depends on address stability. This is fiddly, timing-sensitive work, and concentrating it in one component rather than spreading address logic across the LE code is exactly the kind of decision the whole architecture is built to make easy.

The Round Robin Scheduler and the ACL Data Path

The controller has a finite number of ACL buffers, and every connection competes for them. If one busy connection is allowed to consume every buffer, the other connections starve, which on a phone means your file transfer strangles your audio.

Gabeldorsche solves this with a RoundRobinScheduler that sits between the per-connection queues and the single shared link to the controller.

The scheduler tracks how many buffer credits the controller has, dequeues one packet at a time from each connection in rotation, fragments it to the controller's ACL packet size, and sends it downward, decrementing the credit count.

When the controller reports that it has transmitted packets and freed buffers, through the number-of-completed-packets event, the scheduler adds those credits back and resumes sending.

Because it visits connections in round-robin order rather than draining one before touching the next, bandwidth is shared fairly across links without any connection needing to know the others exist. The fragmentation happens here too, so upper layers get to think in whole L2CAP frames while the scheduler quietly chops them into controller-sized bites and reassembles credits on the way back. This one component is the difference between "my earbuds and my file sync coexist" and "pick one."

L2CAP and the Data Pipeline

L2CAP, the Logical Link Control and Adaptation Protocol, multiplexes the single ACL link into many logical channels and handles segmentation and reassembly of larger service data units.

Gabeldorsche implements Classic and LE variants as separate modules, L2capClassicModule and L2capLeModule, sharing common machinery underneath. It distinguishes fixed channels, which are always present for duties like signalling, from dynamic channels, which are opened on demand for a specific service.

A service registers itself by protocol or service multiplexer, and when a remote device opens a channel to it, the service receives a channel object that, unsurprisingly by now, owns a queue.

// Register a dynamic L2CAP service on a PSM.
dynamic_channel_manager_->RegisterService(
    kMyPsm,
    security_policy,
    GetHandler()->BindOnceOn(this, &MyModule::OnServiceRegistered),
    GetHandler()->BindOn(this, &MyModule::OnConnectionOpen));

void MyModule::OnConnectionOpen(
    std::unique_ptr<l2cap::classic::DynamicChannel> channel) {
  channel->RegisterOnCloseCallback(/* ... */);
  channel->GetQueueUpEnd()->RegisterDequeue(/* ... */);
}

Here a service is registered against a Protocol Service Multiplexer value, the L2CAP equivalent of a port number. RegisterService takes the PSM, a security policy describing what level of pairing and encryption the channel requires, a one-shot callback confirming registration, and a repeating callback that fires each time a remote peer opens a channel. When a channel opens, OnConnectionOpen receives a DynamicChannel owned by a unique_ptr, and you wire up a close callback and a dequeue on its queue.

The security policy being a parameter of registration, rather than something checked ad hoc later, means a channel physically can't be opened at a lower security level than the service demanded. Security as a property of the type, not a runtime afterthought, is a recurring design choice in this stack.

Underneath that friendly channel object is a genuine data pipeline, and it's worth picturing how a byte travels through it.

outgoing SDU
    -> per-channel Segmenter (splits SDU into PDUs, applies mode)
    -> channel Scheduler (picks which channel sends next, by priority)
    -> Fragmenter (splits PDUs to ACL buffer size)
    -> AclManager queue -> RoundRobinScheduler -> controller

incoming from controller
    -> Reassembler (rebuilds PDUs from ACL fragments)
    -> per-channel Recombiner (rebuilds SDUs from PDUs)
    -> channel queue up-end -> upper layer

This diagram traces the two directions of L2CAP data flow. On the way out, a service data unit from an upper layer enters the channel's Segmenter, which breaks it into protocol data units and applies the channel's transmission mode, such as Basic Mode or Enhanced Retransmission Mode with its acknowledgements and retransmits.

A per-link Scheduler then decides which channel gets to transmit next based on channel priority, so a latency-sensitive channel can be favored. The Fragmenter cuts those PDUs down to the controller's ACL buffer size, and they hand off to the AclManager queue and the round-robin scheduler from the previous section.

On the way in, the process runs in reverse: a Reassembler stitches ACL fragments back into PDUs, a per-channel Recombiner rebuilds the original SDUs, and the finished SDU is delivered to the channel's queue up-end where the upper layer reads it.

Each stage is a small, testable component with a single responsibility, which is why L2CAP, historically one of the buggiest layers, becomes tractable.

Security and Pairing

The SecurityModule centralizes pairing, bonding, and encryption for both transports. Classic pairing runs its procedures over the link, while the LE Security Manager Protocol runs over a fixed L2CAP channel dedicated to SMP.

The module drives the state machines for the various association models, including numeric comparison, passkey entry, out-of-band, and just works. It surfaces user interaction through a callback interface so the framework can display the pairing dialog and report back what the user chose.

The design goal is that no other module implements its own crypto or pairing logic. When L2CAP needs a channel encrypted before it will carry data, it doesn't reach into key storage or start an encryption procedure itself. It asks the security module through an enforcement interface, waits for the result on its handler, and only then opens the channel to upper layers.

This is the same principle as the rest of the stack, applied to the most sensitive state: one module owns the pairing state machines and the keys, and everyone else sends it messages. Concentrating cryptographic decisions in one audited place is considerably safer than the historical situation, where security-relevant checks were sprinkled across many files and occasionally forgotten in exactly one of them, which is all it takes.

GATT and ATT

At the top of the LE protocol stack sit the Attribute Protocol, ATT, and the Generic Attribute Profile, GATT, which is the request-response database that nearly every LE product actually uses.

ATT defines the wire operations, reads, writes, notifications, and indications against numbered attribute handles, and it runs over its own fixed L2CAP channel. GATT organizes those attributes into services and characteristics, the abstraction that a heart-rate monitor or a pair of earbuds presents to the phone.

In Gabeldorsche this is layered cleanly on everything below it. ATT is a client of the fixed-channel L2CAP interface, so it receives its channel through the same mechanism as any other fixed channel and moves packets through the same queue pattern. Its packets are defined in PDL like everything else, so an ATT read request and its response are generated builders and views with the same validity guarantees as an HCI command.

GATT builds its service and characteristic database on top of ATT and exposes registration and notification interfaces to the profiles above.

The payoff of the architecture shows up here in a subtle way: because GATT is just another set of modules speaking through queues and typed packets, it can be tested against a virtual peer over RootCanal without any of the layers below it being real hardware.

The Neighbor and Storage Modules

Two supporting module groups round out the picture. The neighbor modules handle discovery and identification of other devices, and the storage module handles persistence.

Discovery isn't one operation but several, and Gabeldorsche models each as a focused component under the neighbor umbrella. Inquiry handles Classic device discovery and its scan modes. Page and page-scan handle becoming connectable and connecting. Name resolution fetches a remote device's human-readable name.

Keeping these as distinct components with narrow interfaces, rather than one large discovery blob, means each can be reasoned about and tested on its own. It also it means a bug in name resolution can't accidentally corrupt inquiry state because they don't share mutable state.

The storage module is responsible for remembering things across reboots, chiefly bonded devices and their keys, along with adapter and device properties. It presents an in-memory model of devices and their properties and persists that model to a configuration file, batching writes so that a burst of property changes does not thrash the disk.

Because persistence lives behind a module interface, the rest of the stack reads and writes device properties through method calls rather than parsing a config file directly. The on-disk format can change without every layer needing to know. Losing your paired devices on every reboot would be a memorable kind of bad, so this module earns its keep quietly.

The Shim and Facade Layers

You can't rewrite an entire Bluetooth stack in one commit and ship it. Gabeldorsche was rolled out incrementally, one layer at a time, which means for a long stretch the new GD modules had to coexist with the old Fluoride profile code.

The shim/ layer is the diplomatic bridge that makes this possible. It exposes the old C-style interfaces that BTIF and BTA expect, and translates those calls into the new module method calls underneath, hopping onto the GD stack thread as it crosses the boundary. Individual layers were gated behind flags so that a given layer could run on GD in one build and on legacy code in another, which made it possible to bisect regressions to a specific layer by toggling flags rather than by archaeology.

The facade/ layer serves a different purpose entirely. Each GD module can expose a gRPC service, called a facade, that lets an external process drive the module directly. This is the seam that the test framework plugs into. Instead of testing through the entire Android framework, a test can start a single module, connect to its facade over gRPC, and issue commands straight at the layer under test while observing its event stream.

service HciLayerFacade {
  rpc SendCommand(Command) returns (google.protobuf.Empty) {}
  rpc StreamEvents(google.protobuf.Empty) returns (stream Event) {}
}

This is a sketch of what a module facade looks like in protobuf. It defines a gRPC service with a unary method to send a command into the module and a server-streaming method that pushes every event the module emits back to the caller. Because it's gRPC, the client driving the test can be written in any language, and the project chose Python for readability and speed of writing tests.

The facade turns each internal layer into something you can poke at from outside the process without building the entire operating system around it. This is the difference between a testable design and a design that merely has the word testable in its design doc.

Build System Integration

None of this would be pleasant without build tooling that treats the packet generator as a first-class citizen. Gabeldorsche builds with Soong, the AOSP build system whose files are named Android.bp, and the PDL generator is wired in as a custom rule so that .pdl files are compiled to C++ headers automatically as part of the build graph.

The mechanism is a generated-sources rule. A build rule names the bluetooth_packetgen tool, points it at the .pdl inputs, and declares the .h outputs. Any C++ library that lists those generated headers as sources gets them built on demand and rebuilt whenever a .pdl file changes.

The practical effect is that a developer edits a packet definition, rebuilds, and the new typed builders and views simply exist, both in the C++ target and, through a parallel rule, in the Python bindings used by tests. There's no checked-in generated code to fall out of sync and no manual codegen step to forget before sending a change for review. The same source of truth feeds production C++ and test Python, and the build system guarantees they never drift.

Logging, Metrics, and dumpsys

A stack you can't see into is a stack you can't debug, and Bluetooth debugging often happens after the fact from a bug report.

Gabeldorsche invests accordingly. It logs through the standard Android logging macros with per-module tags, so a log line tells you which layer produced it. It also maintains structured metrics that feed the platform's statistics pipeline for aggregate health monitoring across the fleet.

The most useful debugging affordance is dumpsys integration. Modules can implement a dump method, and the registry can walk the running modules and ask each to serialize its current state, which lands in the Bluetooth section of a bug report.

Because every module knows how to describe itself, a bug report captures a coherent snapshot of the whole stack, connection tables, channel states, controller capabilities, without a human needing to instrument anything at the moment of failure.

This is the difference between "please reproduce it while I watch" and "send me the bug report you already have." For a component as timing-dependent as Bluetooth, that difference is often the entire investigation.

Testing with Cert Tests and RootCanal

The payoff for all this modularity is the test infrastructure, and it has two standout pieces. The first is the certification test suite, usually called Cert tests, written in Python and driving modules through their gRPC facades. The second is RootCanal, a virtual Bluetooth controller.

RootCanal deserves special attention. It's a software implementation of a Bluetooth controller that speaks HCI. But instead of a radio, it has a simulated physical layer.

You can connect multiple stacks to a single RootCanal instance, and it models them being in radio range of each other, delivering one stack's advertisements and connection requests to another. This means an entire pairing and data-transfer scenario between two devices can run in continuous integration on a Linux machine with no Bluetooth hardware present at all. The flakiness of real radios, radio interference, timing jitter, a colleague walking past with a microwave, which made the old test story hopeless, is removed by construction.

A Cert test wires these together: it starts the stack under test and a second reference stack, connects both to RootCanal, and asserts on the packets that cross between them.

class HciTest(GdBaseTestClass):

    def test_local_hci_cmd_and_event(self):
        # Send an HCI command through the DUT's facade.
        self.dut.hci.SendCommand(
            hci_facade.Command(payload=bytes(ResetBuilder().Serialize())))

        # Assert the expected completion event comes back.
        assertThat(self.dut.hci.get_event_stream()).emits(
            HciMatchers.CommandComplete(OpCode.RESET))

This test exercises the HCI layer end to end without any hardware. self.dut is the device under test, a real GD stack instance running behind its gRPC facade. SendCommand serializes a ResetBuilder, built by the Python bindings generated from the same PDL as the C++ code, and pushes it into the stack's HCI facade. The test then takes the stack's event stream and asserts that it emits a command-complete event for the Reset opcode, using a matcher that waits for the event to arrive rather than checking once and giving up on a race.

The whole scenario runs deterministically in CI. When this test passes, you know the HCI command path works. When it fails, it fails the same way every time, which is the single most valuable property a test can have.

Floss: Gabeldorsche Beyond Android

Because the GD stack was built on its own OS abstraction rather than baked into Android internals, it turned out to be portable. Floss, which stands for Fluoride Linux OS Stack, is the project that runs the Gabeldorsche core as the Bluetooth stack for desktop Linux and ChromeOS. It reuses the same modules, the same packet library, and the same testing infrastructure, and exposes them to the Linux world through a D-Bus interface instead of Android AIDL.

This is a real vindication of the architecture. The same connection management, HCI flow control, round-robin scheduling, and PDL-generated parsers that keep your phone's earbuds connected also run on a laptop, because none of that logic was ever coupled to Android in the first place.

The parts that differ between platforms are pushed to the edges, the transport that talks to the chip at the bottom and the interface that talks to the OS at the top, while the large protocol middle is shared.

An architecture that ports cleanly to an entirely different operating system is one that had genuinely clean seams, not just aspirational comments claiming it did.

Summary

Gabeldorsche is what happens when a team decides that the way to fix a decade of flaky Bluetooth is to fix the architecture rather than the symptoms.

The whole design rests on a few consistent ideas repeated at every layer. Work is organized into modules with explicit, declared dependencies that a registry starts in the right order and tears down in reverse. Concurrency is message passing to a thread that owns its data, built on a reactor and handlers, so the stack barely uses locks and the ones it does use are rare and deliberate.

Data moves between layers through reactive queues that provide backpressure for free, a round-robin scheduler shares controller buffers fairly across connections so audio and bulk transfer coexist, and L2CAP is a pipeline of small single-purpose stages rather than one monolith. Packets are parsed by code generated from a formal specification, which erases an entire family of memory-safety bugs and keeps the C++ and Python paths byte-for-byte identical. Connections and channels are owned objects with clear lifetimes rather than integer handles in global tables, and security is a property attached to types and registrations rather than a runtime check someone might forget.

The testing story is the part that makes the rest believable. Every layer exposes a gRPC facade, the build system regenerates packet code on every change, dumpsys captures a full state snapshot into every bug report, and RootCanal provides a virtual controller so full multi-device scenarios run deterministically in continuous integration without any radios. Tests that fail the same way every time are worth more than a stack that occasionally works, and that principle drove the whole rewrite.

If you want to explore further, the code lives in AOSP under the Bluetooth Mainline module, and the same core now runs on Linux desktops through Floss. Read a .pdl file, then read its generated header, then follow one ACL packet from L2CAP down through the round-robin scheduler to the HCI layer, and the philosophy of the whole project becomes clear in an afternoon. It's a stack that was designed to be understood, which, for Bluetooth, still feels like a small miracle.

This handbook teaches you how to build Bluetooth applications on Zephyr from the ground up. You'll start with the fundamentals of BLE (what GAP, GATT, services, and characteristics actually mean), then move into writing real Zephyr firmware: advertising a device, creating custom services, handling connections, reading sensor data over BLE, and building a complete BLE peripheral that a phone can talk to.

Every concept comes with working code, and every code block comes with an explanation of what it does and why it matters.

This is a long, detailed guide. Bluetooth has a lot of moving parts, and most tutorials gloss over the pieces that trip people up in real projects.

This one does not. Work through it sequentially, build the code as you go, and by the end you'll have the knowledge to build production BLE devices on Zephyr.

Table of Contents

• Prerequisites

• What Is Zephyr OS (And Why Use It for Bluetooth)?

• Bluetooth Low Energy Fundamentals

• The GAP Layer: Advertising and Connections

• The GATT Layer: Services and Characteristics

• Setting Up Your Zephyr Development Environment

• Your First BLE Application: A Simple Beacon

• Building a BLE Peripheral with a Custom Service

• Handling Connections and Connection Callbacks

• Adding Write Support: Receiving Data from a Phone

• Notifications: Pushing Data to a Connected Device

• Building a Complete BLE Sensor Node

• Pairing and Security

• Implementing a Standard BLE Profile (Heart Rate)

• Building a BLE Central

• MTU Negotiation and Data Throughput

• PHY Selection for Range and Speed

• Firmware Updates Over BLE

• Bluetooth Mesh on Zephyr

• LE Audio: The Next Generation of Bluetooth Audio

• Debugging Bluetooth Applications

• Power Optimization for BLE Devices

• Zephyr Bluetooth vs Other Stacks

• Where to Go from Here

• Summary

Prerequisites

To follow along with this tutorial, you should be comfortable reading and writing C code. Pointers, structs, function pointers, and callbacks should not be foreign concepts. You need a command-line terminal and basic familiarity with building C projects. Prior Bluetooth experience isn't required. This article explains BLE concepts from scratch.

For hardware, a Nordic Semiconductor nRF52840 DK is the ideal board for following along. Nordic's chips have the best-supported Bluetooth stack in Zephyr, and the nRF52840 DK is affordable (around $40), widely available, and includes an onboard debugger.

If you have a different Zephyr-supported board with Bluetooth (nRF52832 DK, nRF5340 DK, or any board with a BLE-capable radio), that works too.

For testing the BLE side, you'll need a phone with a BLE scanner app (nRF Connect for Mobile is excellent and free on both iOS and Android).

You'll also need a computer running Linux (Ubuntu 22.04 or newer), macOS, or Windows with WSL2.

What Is Zephyr OS (And Why Use It for Bluetooth)?

Zephyr OS is a small, open-source, real-time operating system built for resource-constrained embedded devices. It's hosted by the Linux Foundation, licensed under Apache 2.0, and runs on microcontrollers with as little as 8 KB of RAM. It supports over 600 boards across ARM, RISC-V, x86, Xtensa, and other architectures.

But this article is about Bluetooth, so here's why Zephyr matters specifically for BLE development.

Zephyr includes a full, Bluetooth SIG-qualified BLE stack. That means the stack has been through the official Bluetooth qualification process and meets the specification requirements. You aren't building on a hobby implementation. You're building on a stack that has passed conformance testing.

The stack covers both the host (GAP, GATT, SMP, L2CAP, ATT) and the controller (Link Layer, HCI). For supported radios (primarily Nordic nRF series), Zephyr provides its own open-source controller implementation. This means the entire Bluetooth stack, from your application code down to the radio registers, is open source. No binary blobs. No closed-source libraries. You can read, debug, and modify every line.

Nordic Semiconductor, the company whose chips dominate the BLE market, built their nRF Connect SDK on top of Zephyr. When Nordic's own engineers write BLE firmware, they use Zephyr. That's a strong endorsement.

The Zephyr Bluetooth stack supports Bluetooth 5.x features (2M PHY, Coded PHY for long range, Extended Advertising), Bluetooth Mesh (relay, proxy, friend, and low-power nodes), LE Audio (the newest Bluetooth audio standard with LC3 codec, broadcast, and hearing aid support), Direction Finding (Angle of Arrival and Angle of Departure for indoor positioning), and all the standard BLE profiles and services you need for product development.

In short: if you're building a BLE product these days, Zephyr is one of the best platforms available. Google uses it in Chromebooks, Nordic uses it for their entire SDK, and hundreds of companies ship products built on it.

Bluetooth Low Energy Fundamentals

Before you write any code, you need a mental model of how BLE works. Skip this section if you already know BLE well. Read it carefully if you don't, because everything that follows builds on these concepts.

BLE is not the same as "classic" Bluetooth (the kind used for audio streaming to speakers before LE Audio). Classic Bluetooth (BR/EDR) is designed for continuous, high-throughput data streaming. BLE is designed for intermittent, low-power communication.

A BLE sensor might wake up once per minute, send 20 bytes of data, and go back to sleep. That interaction consumes microwatts of energy. This fundamental design difference is why BLE devices can run on a coin cell battery for years.

BLE communication is organized into two main layers that you interact with as a developer: GAP and GATT.

GAP (Generic Access Profile) controls how devices discover each other and establish connections. Think of GAP as the "meeting people at a party" layer.

A device can be in one of several GAP roles. A peripheral (also called an advertiser) broadcasts small packets of data at regular intervals, announcing its presence and basic information. A central (also called a scanner) listens for these broadcasts and can initiate a connection. Your phone is typically a central. A sensor, earbud, or smartwatch is typically a peripheral.

GATT (Generic Attribute Profile) controls how data is exchanged after two devices are connected. Think of GATT as the "having a conversation" layer.

GATT defines a hierarchical data structure. At the top level, a device exposes one or more services. A service groups related data together.

For example, a heart rate monitor might have a Heart Rate Service. Inside each service are one or more characteristics. A characteristic is a single data point with a value and metadata. The Heart Rate Service might have a Heart Rate Measurement characteristic (the actual BPM value) and a Body Sensor Location characteristic (where the sensor is worn).

Each characteristic has properties that define what you can do with it. A characteristic can be readable (a central can request its value), writable (a central can set its value), notifiable (the peripheral can push updates to the central without being asked), or indicatable (like notify but with acknowledgment). A characteristic can have multiple properties.

Every service and characteristic is identified by a UUID. The Bluetooth SIG defines standard 16-bit UUIDs for common services and characteristics (Heart Rate is 0x180D, Battery Service is 0x180F, and so on). For custom functionality, you define your own 128-bit UUIDs.

Here's a concrete mental model. Imagine a temperature sensor device:

Device: "My Temp Sensor"
  |
  +-- Environmental Sensing Service (UUID: 0x181A)
  |     |
  |     +-- Temperature characteristic (UUID: 0x2A6E)
  |     |     Properties: Read, Notify
  |     |     Value: 23.5 (degrees C)
  |     |
  |     +-- Humidity characteristic (UUID: 0x2A6F)
  |           Properties: Read, Notify
  |           Value: 65.2 (percent)
  |
  +-- Battery Service (UUID: 0x180F)
        |
        +-- Battery Level characteristic (UUID: 0x2A19)
              Properties: Read, Notify
              Value: 87 (percent)

This diagram shows a device with two services and three characteristics. A connected phone could read the temperature, subscribe to humidity notifications, and check the battery level. The services and characteristics are the API of your BLE device.

Designing them well is like designing a good REST API: think about what data your device exposes and how clients will interact with it.

One more concept: advertising data. When a peripheral advertises, it broadcasts small packets (up to 31 bytes in legacy advertising, larger with Extended Advertising). These packets contain structured data like the device name, supported services, manufacturer-specific data, and flags. The advertising data is what a scanner sees before making a connection. It is your device's "business card."

The GAP Layer: Advertising and Connections

GAP is the first layer you interact with when building a BLE device. Your peripheral needs to advertise its presence before anything else can happen.

Advertising works like this: the peripheral's radio wakes up at regular intervals (the "advertising interval"), transmits a short packet on one of three advertising channels (channels 37, 38, and 39), and goes back to sleep. A central scanning those channels picks up the packet and learns about the device.

The advertising interval is a tradeoff: shorter intervals (like 20 ms) make the device easier to discover but consume more power. Longer intervals (like 1000 ms) save power but make discovery slower. For most applications, 100 to 500 ms is a reasonable range.

An advertising packet contains structured fields called AD (Advertising Data) structures. Each AD structure has a length byte, a type byte, and data bytes. Common types include flags (indicating discoverability and BR/EDR support), complete or shortened local name, list of service UUIDs, TX power level, and manufacturer-specific data.

The total payload is limited to 31 bytes for legacy advertising (Bluetooth 4.x), so you can't fit much. You often have to choose between including the device name or the service UUID, because both might not fit.

Bluetooth 5.0 introduced Extended Advertising, which allows advertising payloads up to 254 bytes per fragment (chained into even larger payloads), advertising on all 40 BLE channels (not just the three advertising channels), and multiple simultaneous advertising sets. Zephyr supports Extended Advertising when the hardware and controller support it.

When a central decides to connect, it sends a connection request to the peripheral. The two devices negotiate connection parameters: the connection interval (how often they communicate, typically 7.5 ms to 4 seconds), the peripheral latency (how many connection events the peripheral can skip to save power), and the supervision timeout (how long to wait before considering the connection lost).

These parameters affect both data throughput and power consumption. A short connection interval gives you fast data transfer but costs more power. A high peripheral latency saves power but adds latency to data exchange.

The GATT Layer: Services and Characteristics

Once a connection is established, GATT takes over. The connected devices exchange data through the service/characteristic hierarchy described earlier.

On the peripheral side, you define the GATT database: the list of services and characteristics your device exposes. On the central side, you perform service discovery: querying the peripheral for its available services and characteristics.

Each characteristic in the GATT database has several components. The value is the actual data (a byte array). The properties define permitted operations: Read (0x02), Write Without Response (0x04), Write (0x08), Notify (0x10), and Indicate (0x20) are the most common. The permissions are security requirements: whether reading/writing requires encryption, authentication, or authorization.

For notifications and indications, the characteristic has a Client Characteristic Configuration Descriptor (CCCD). This is a special 2-byte value that the central writes to enable or disable notifications/indications. When the central writes 0x0001 to the CCCD, notifications are enabled. When it writes 0x0000, they're disabled. Zephyr handles the CCCD automatically when you define a characteristic with the notify property.

The GATT operations flow like this.

• For a read: the central sends a read request, the peripheral responds with the characteristic value.

• For a write: the central sends a write request with the new value, the peripheral updates the value and sends a response.

• For a notification: the peripheral sends the value to the central without the central asking. The central must have previously enabled notifications on that characteristic.

This request/response model means that BLE isn't a streaming protocol. It's a message-passing protocol. If you need to send continuous sensor data, you use notifications at a fixed interval. If you need to configure the device, you write to a characteristic. This shapes how you design your BLE application.

Setting Up Your Zephyr Development Environment

This section walks through a complete environment setup. If you already have a Zephyr environment, skip to the next section.

Install system dependencies (Ubuntu):

sudo apt update
sudo apt install --no-install-recommends git cmake ninja-build gperf \
  ccache dfu-util device-tree-compiler wget python3-dev python3-pip \
  python3-setuptools python3-tk python3-wheel xz-utils file \
  make gcc gcc-multilib g++-multilib libsdl2-dev libmagic1

These packages provide the compiler toolchain, build systems, and utilities that Zephyr's build process requires.

The devicetree compiler (device-tree-compiler) is particularly important for Zephyr because it processes the hardware description files that tell the build system about your board's peripherals and pin assignments.

Install west, the Zephyr command-line tool:

pip3 install west

West manages the multi-repository workspace that Zephyr uses, and provides commands for building, flashing, and debugging firmware. It's the single tool you interact with most.

Initialize and update the workspace:

west init ~/zephyrproject
cd ~/zephyrproject
west update

The west init command creates a workspace and clones the main Zephyr repository. The west update command then fetches all module dependencies: vendor HALs (the low-level chip support packages), cryptography libraries, the Bluetooth controller code, and other components. This downloads several gigabytes, so it takes a while.

Install Python requirements:

pip3 install -r ~/zephyrproject/zephyr/scripts/requirements.txt

This installs the Python packages that Zephyr's build scripts and west extensions depend on, including the devicetree processing tools, the Kconfig frontend, and various code generation utilities. The requirements file pins specific versions to ensure build reproducibility.

Install the Zephyr SDK (provides cross-compilation toolchains for all supported architectures):

cd ~
wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.16.8/zephyr-sdk-0.16.8_linux-x86_64.tar.xz
tar xvf zephyr-sdk-0.16.8_linux-x86_64.tar.xz
cd zephyr-sdk-0.16.8
./setup.sh

The SDK includes GCC-based toolchains for ARM, RISC-V, x86, Xtensa, and more. The setup.sh script registers them with CMake. Check the Zephyr releases page for the latest SDK version number, as it may have been updated since this handbook was written.

Set environment variables (add these to your ~/.bashrc or ~/.zshrc):

export ZEPHYR_BASE=~/zephyrproject/zephyr
source ~/zephyrproject/zephyr/zephyr-env.sh

The ZEPHYR_BASE variable tells the build system where the Zephyr source tree lives. The zephyr-env.sh script sets up additional paths. With both configured, you can build for any supported board from any directory.

Your First BLE Application: A Simple Beacon

We'll start with the simplest possible BLE application: a device that advertises but does nothing else. No connections, no services, no data exchange. Just a beacon broadcasting its existence.

Create the project structure:

mkdir -p ~/my_ble_apps/beacon/src

This creates the standard Zephyr application directory layout. Every Zephyr application lives in its own directory with a src/ subdirectory for C source files. The project root holds the build configuration files.

Create ~/my_ble_apps/beacon/CMakeLists.txt:

cmake_minimum_required(VERSION 3.20.0)
find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
project(ble_beacon)
target_sources(app PRIVATE src/main.c)

The find_package(Zephyr) line loads the entire Zephyr build system. The target_sources line adds your source file to the build target named app, which is the standard target name for Zephyr applications.

Create ~/my_ble_apps/beacon/prj.conf:

CONFIG_BT=y
CONFIG_BT_BROADCASTER=y

Two configuration lines: CONFIG_BT=y enables the Bluetooth subsystem, pulling in the host stack, HCI layer, and (on supported boards) the controller. CONFIG_BT_BROADCASTER=y enables the broadcaster role, which is the minimal role for a device that only advertises. You don't need the peripheral role yet because this beacon doesn't accept connections.

Create ~/my_ble_apps/beacon/src/main.c:

#include <zephyr/kernel.h>
#include <zephyr/bluetooth/bluetooth.h>

static const struct bt_data ad[] = {
    BT_DATA_BYTES(BT_DATA_FLAGS, BT_LE_AD_GENERAL | BT_LE_AD_NO_BREDR),
    BT_DATA_BYTES(BT_DATA_NAME_COMPLETE,
                  'M', 'y', 'B', 'e', 'a', 'c', 'o', 'n'),
};

int main(void)
{
    int err;

    printk("Starting BLE Beacon\n");

    err = bt_enable(NULL);
    if (err) {
        printk("Bluetooth init failed (err %d)\n", err);
        return 0;
    }

    printk("Bluetooth initialized\n");

    err = bt_le_adv_start(BT_LE_ADV_NCONN, ad, ARRAY_SIZE(ad), NULL, 0);
    if (err) {
        printk("Advertising failed to start (err %d)\n", err);
        return 0;
    }

    printk("Beacon is advertising\n");

    return 0;
}

Let's walk through this code piece by piece.

The ad array defines the advertising data. It contains two AD structures.

The first is the Flags field, which is mandatory in BLE advertising. BT_LE_AD_GENERAL means the device is in General Discoverable mode (visible to all scanners). BT_LE_AD_NO_BREDR indicates that the device doesn't support classic Bluetooth (BR/EDR), only BLE.

The second AD structure is the complete local name, spelled out character by character. The BT_DATA_BYTES macro packs these into the correct AD structure format.

The bt_enable(NULL) call initializes the entire Bluetooth subsystem. This sets up the HCI transport, initializes the controller (if using an onboard radio), and prepares the host stack. The NULL argument means this is a synchronous call: it blocks until initialization is complete. You could pass a callback function to make it asynchronous.

The bt_le_adv_start call begins advertising. The first argument, BT_LE_ADV_NCONN, specifies non-connectable advertising. This means scanners can see the beacon but cannot connect to it. The ad array and its size (ARRAY_SIZE(ad)) provide the advertising data. The last two arguments (NULL, 0) are for scan response data, which is additional data sent when a scanner actively scans (sends a scan request). You aren't using scan response data in this simple example.

After main() returns, the Zephyr main thread terminates, but the system keeps running. The Bluetooth subsystem continues advertising in the background, driven by the controller and the Bluetooth host thread.

Build and flash:

cd ~/zephyrproject
west build -b nrf52840dk/nrf52840 ~/my_ble_apps/beacon
west flash

The west build command compiles the application for the nRF52840 DK, producing an ELF binary and a HEX file in the build/ directory. The west flash command programs that binary onto the board via the onboard J-Link debugger, automatically detecting the connected board and using the correct programming protocol.

Open the nRF Connect app on your phone, start scanning, and you should see "MyBeacon" appear in the list of discovered devices. That's your firmware, running on your board, advertising over BLE.

Building a BLE Peripheral with a Custom Service

A beacon that broadcasts is useful for some applications (iBeacon, Eddystone, asset tracking). But most BLE devices need to be connectable and expose data through GATT services. Now you'll build a peripheral with a custom service.

You'll create a "LED Service" that lets a phone control an LED on your board and read a button state. This is a classic BLE demo that teaches you the patterns you'll use in every BLE project.

Create the project:

mkdir -p ~/my_ble_apps/led_service/src

Same project layout as the beacon: a root directory for build configuration and a src/ directory for source code. This separation keeps build artifacts isolated from your source files.

Create ~/my_ble_apps/led_service/prj.conf:

CONFIG_BT=y
CONFIG_BT_PERIPHERAL=y
CONFIG_BT_DEVICE_NAME="Zephyr LED"
CONFIG_BT_DEVICE_APPEARANCE=0
CONFIG_GPIO=y
CONFIG_BT_GATT_DYNAMIC_DB=y

CONFIG_BT_PERIPHERAL=y enables the peripheral role, which includes the broadcaster role plus the ability to accept connections. CONFIG_BT_DEVICE_NAME sets the default device name used in advertising and the GAP Device Name characteristic. CONFIG_GPIO=y enables the GPIO driver so you can control the LED and read the button.

Create ~/my_ble_apps/led_service/CMakeLists.txt:

cmake_minimum_required(VERSION 3.20.0)
find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
project(ble_led_service)
target_sources(app PRIVATE src/main.c)

This is the same CMake boilerplate from the beacon project. The only change is the project name (ble_led_service). The find_package(Zephyr) call loads the full Zephyr build system, and target_sources registers your application source file.

Create ~/my_ble_apps/led_service/src/main.c:

#include <zephyr/kernel.h>
#include <zephyr/bluetooth/bluetooth.h>
#include <zephyr/bluetooth/gatt.h>
#include <zephyr/bluetooth/uuid.h>
#include <zephyr/drivers/gpio.h>

/* Custom service UUID: 00001234-0000-1000-8000-00805f9b34fb */
#define BT_UUID_LED_SERVICE_VAL \
    BT_UUID_128_ENCODE(0x00001234, 0x0000, 0x1000, 0x8000, 0x00805f9b34fb)
#define BT_UUID_LED_SERVICE BT_UUID_DECLARE_128(BT_UUID_LED_SERVICE_VAL)

/* LED characteristic UUID */
#define BT_UUID_LED_CHAR_VAL \
    BT_UUID_128_ENCODE(0x00001235, 0x0000, 0x1000, 0x8000, 0x00805f9b34fb)
#define BT_UUID_LED_CHAR BT_UUID_DECLARE_128(BT_UUID_LED_CHAR_VAL)

/* Button characteristic UUID */
#define BT_UUID_BUTTON_CHAR_VAL \
    BT_UUID_128_ENCODE(0x00001236, 0x0000, 0x1000, 0x8000, 0x00805f9b34fb)
#define BT_UUID_BUTTON_CHAR BT_UUID_DECLARE_128(BT_UUID_BUTTON_CHAR_VAL)

#define LED0_NODE DT_ALIAS(led0)
#define SW0_NODE  DT_ALIAS(sw0)

static const struct gpio_dt_spec led = GPIO_DT_SPEC_GET(LED0_NODE, gpios);
static const struct gpio_dt_spec button = GPIO_DT_SPEC_GET(SW0_NODE, gpios);

static uint8_t led_state;
static uint8_t button_state;

static ssize_t read_led(struct bt_conn *conn,
                        const struct bt_gatt_attr *attr,
                        void *buf, uint16_t len, uint16_t offset)
{
    return bt_gatt_attr_read(conn, attr, buf, len, offset,
                             &led_state, sizeof(led_state));
}

static ssize_t write_led(struct bt_conn *conn,
                         const struct bt_gatt_attr *attr,
                         const void *buf, uint16_t len,
                         uint16_t offset, uint8_t flags)
{
    if (len != 1) {
        return BT_GATT_ERR(BT_ATT_ERR_INVALID_ATTRIBUTE_LEN);
    }

    led_state = *((const uint8_t *)buf);
    gpio_pin_set_dt(&led, led_state ? 1 : 0);

    printk("LED %s\n", led_state ? "ON" : "OFF");

    return len;
}

static ssize_t read_button(struct bt_conn *conn,
                           const struct bt_gatt_attr *attr,
                           void *buf, uint16_t len, uint16_t offset)
{
    button_state = gpio_pin_get_dt(&button);
    return bt_gatt_attr_read(conn, attr, buf, len, offset,
                             &button_state, sizeof(button_state));
}

BT_GATT_SERVICE_DEFINE(led_service,
    BT_GATT_PRIMARY_SERVICE(BT_UUID_LED_SERVICE),

    BT_GATT_CHARACTERISTIC(BT_UUID_LED_CHAR,
        BT_GATT_CHRC_READ | BT_GATT_CHRC_WRITE,
        BT_GATT_PERM_READ | BT_GATT_PERM_WRITE,
        read_led, write_led, NULL),

    BT_GATT_CHARACTERISTIC(BT_UUID_BUTTON_CHAR,
        BT_GATT_CHRC_READ,
        BT_GATT_PERM_READ,
        read_button, NULL, NULL),
);

static const struct bt_data ad[] = {
    BT_DATA_BYTES(BT_DATA_FLAGS, BT_LE_AD_GENERAL | BT_LE_AD_NO_BREDR),
    BT_DATA(BT_DATA_NAME_COMPLETE, CONFIG_BT_DEVICE_NAME,
            sizeof(CONFIG_BT_DEVICE_NAME) - 1),
};

static const struct bt_data sd[] = {
    BT_DATA_BYTES(BT_DATA_UUID128_ALL, BT_UUID_LED_SERVICE_VAL),
};

int main(void)
{
    int err;

    if (!gpio_is_ready_dt(&led) || !gpio_is_ready_dt(&button)) {
        printk("GPIO devices not ready\n");
        return 0;
    }

    gpio_pin_configure_dt(&led, GPIO_OUTPUT_INACTIVE);
    gpio_pin_configure_dt(&button, GPIO_INPUT);

    err = bt_enable(NULL);
    if (err) {
        printk("Bluetooth init failed (err %d)\n", err);
        return 0;
    }

    printk("Bluetooth initialized\n");

    err = bt_le_adv_start(BT_LE_ADV_CONN, ad, ARRAY_SIZE(ad),
                          sd, ARRAY_SIZE(sd));
    if (err) {
        printk("Advertising failed to start (err %d)\n", err);
        return 0;
    }

    printk("Advertising as '%s'\n", CONFIG_BT_DEVICE_NAME);

    return 0;
}

This is a substantial piece of code, so let's go through it section by section.

The UUID definitions at the top create custom 128-bit UUIDs for the service and its two characteristics. When you build a custom BLE device, you generate your own UUIDs rather than using the standard Bluetooth SIG UUIDs (unless you're implementing a standard profile like Heart Rate).

In production, you would generate random 128-bit UUIDs using a tool like uuidgen. The UUIDs here are simple for readability. The BT_UUID_128_ENCODE macro formats the UUID in the byte order that the Bluetooth stack expects. BT_UUID_DECLARE_128 creates a struct bt_uuid_128 from the encoded value.

The led and button GPIO specs use the devicetree aliases led0 and sw0, which most Zephyr boards define. The GPIO_DT_SPEC_GET macro pulls the pin number, GPIO controller, and flags directly from the devicetree, keeping the code portable across boards.

The read_led callback is called when a connected central reads the LED characteristic. It uses bt_gatt_attr_read, a helper function that handles offset and length correctly (GATT reads can be partial if the value is larger than the MTU). The function returns the current LED state as a single byte.

The write_led callback is called when a central writes to the LED characteristic. It validates that exactly one byte was written, updates the led_state variable, and calls gpio_pin_set_dt to physically toggle the LED. It returns the number of bytes consumed (len), or a GATT error if the length was wrong. The BT_GATT_ERR macro wraps an ATT error code into the return value that the stack expects.

The read_button callback reads the current physical button state at the moment of the read request. It calls gpio_pin_get_dt to sample the pin, stores the result, and returns it.

The BT_GATT_SERVICE_DEFINE macro is where the GATT database is constructed at compile time. The first argument names the service variable. BT_GATT_PRIMARY_SERVICE declares a primary service with the custom UUID. Each BT_GATT_CHARACTERISTIC declaration takes the characteristic UUID, the properties (Read + Write for the LED, Read-only for the button), the permissions (who can read/write), the read callback, the write callback, and a pointer to user data (NULL in both cases here).

The ad array contains the advertising data: flags and the device name. The sd array contains the scan response data: the 128-bit service UUID.

Splitting data between advertising and scan response is common because the 31-byte advertising packet limit is tight. The service UUID alone is 16 bytes, which would leave little room for other data in the main advertising packet. By putting the UUID in the scan response, you keep the advertising packet small and include the UUID only when a scanner explicitly requests it.

The bt_le_adv_start call uses BT_LE_ADV_CONN instead of BT_LE_ADV_NCONN. This makes the advertising connectable: scanners can now establish a connection to your device. The sd and ARRAY_SIZE(sd) arguments provide the scan response data that was NULL in the beacon example.

Build, flash, and test:

cd ~/zephyrproject
west build -b nrf52840dk/nrf52840 ~/my_ble_apps/led_service
west flash

The build command compiles the application with the full Bluetooth stack, GPIO drivers, and GATT database linked into a single binary. The flash command programs it onto the board. Because CONFIG_BT_PERIPHERAL is enabled, the binary is significantly larger than the beacon (the connectable advertising, GATT server, and ATT protocol layers are all included).

Open nRF Connect on your phone, scan, and find "Zephyr LED." Tap Connect. After connecting, you'll see the GATT services. Find the custom service (UUID starting with 00001234). You'll see two characteristics. Read the button characteristic to see the button state. Write 0x01 to the LED characteristic to turn on the LED, and 0x00 to turn it off. You just controlled hardware over Bluetooth from your phone.

Handling Connections and Connection Callbacks

In a real application, you need to know when devices connect and disconnect. Maybe you want to stop advertising when a device connects (to save power), restart advertising when it disconnects (to allow reconnection), or update a status LED to indicate connection state.

Zephyr provides connection callbacks through a registration mechanism:

#include <zephyr/bluetooth/conn.h>

static void connected(struct bt_conn *conn, uint8_t err)
{
    if (err) {
        printk("Connection failed (err %u)\n", err);
        return;
    }

    char addr[BT_ADDR_LE_STR_LEN];
    bt_addr_le_to_str(bt_conn_get_dst(conn), addr, sizeof(addr));
    printk("Connected: %s\n", addr);
}

static void disconnected(struct bt_conn *conn, uint8_t reason)
{
    char addr[BT_ADDR_LE_STR_LEN];
    bt_addr_le_to_str(bt_conn_get_dst(conn), addr, sizeof(addr));
    printk("Disconnected: %s (reason %u)\n", addr, reason);

    /* Restart advertising after disconnect */
    bt_le_adv_start(BT_LE_ADV_CONN, ad, ARRAY_SIZE(ad),
                    sd, ARRAY_SIZE(sd));
}

BT_CONN_CB_DEFINE(conn_callbacks) = {
    .connected = connected,
    .disconnected = disconnected,
};

The BT_CONN_CB_DEFINE macro statically registers a set of connection callbacks. The .connected callback fires when a connection is established. The err parameter indicates whether the connection was successful (0 means success). The .disconnected callback fires when a connection ends. The reason parameter is an HCI disconnect reason code (0x13 is "Remote User Terminated Connection," which is the normal disconnect).

In the connected callback, the code retrieves the remote device's Bluetooth address using bt_conn_get_dst and converts it to a printable string. This is useful for logging and debugging.

In the disconnected callback, the code restarts advertising. By default, Zephyr stops advertising when a connection is established (because the radio is now used for the connection). When the connection drops, you typically want to start advertising again so the device can be rediscovered.

The bt_conn pointer represents the connection. You can use it to query connection parameters, request parameter updates, initiate pairing, or disconnect programmatically. Hold a reference to it (using bt_conn_ref) if you need to use it outside the callback. Release the reference (using bt_conn_unref) when you're done.

Adding Write Support: Receiving Data from a Phone

The LED service already has a write characteristic, but let's look more closely at the write callback pattern and how to handle more complex data.

Consider a scenario where the phone sends a configuration struct to the device:

struct device_config {
    uint8_t mode;
    uint16_t interval_ms;
    uint8_t threshold;
} __packed;

static struct device_config current_config = {
    .mode = 0,
    .interval_ms = 1000,
    .threshold = 50,
};

static ssize_t write_config(struct bt_conn *conn,
                            const struct bt_gatt_attr *attr,
                            const void *buf, uint16_t len,
                            uint16_t offset, uint8_t flags)
{
    if (offset != 0) {
        return BT_GATT_ERR(BT_ATT_ERR_INVALID_OFFSET);
    }

    if (len != sizeof(struct device_config)) {
        return BT_GATT_ERR(BT_ATT_ERR_INVALID_ATTRIBUTE_LEN);
    }

    memcpy(&current_config, buf, len);

    printk("Config updated: mode=%u, interval=%u ms, threshold=%u\n",
           current_config.mode,
           current_config.interval_ms,
           current_config.threshold);

    return len;
}

static ssize_t read_config(struct bt_conn *conn,
                           const struct bt_gatt_attr *attr,
                           void *buf, uint16_t len, uint16_t offset)
{
    return bt_gatt_attr_read(conn, attr, buf, len, offset,
                             &current_config, sizeof(current_config));
}

The __packed attribute on the struct ensures that there is no padding between fields, so the byte layout matches what the phone sends. Without __packed, the compiler might insert padding bytes between mode and interval_ms for alignment, and the data wouldn't match.

The write callback validates two things. First, it checks that the offset is zero (no partial writes for this simple case). Second, it checks that the length matches the expected struct size. If either check fails, it returns a GATT error code that the central receives as a write response error.

Validating input is critical in BLE applications because the central is sending raw bytes over the air. Malformed data should be rejected, not blindly accepted.

The memcpy copies the validated data into the configuration struct. In a real application, you would likely apply the new configuration to your device's behavior (change a sensor polling interval, switch operating modes, and so on).

The flags parameter in the write callback indicates whether this is a Write With Response (the central expects an acknowledgment) or Write Without Response (fire-and-forget). You can check flags & BT_GATT_WRITE_FLAG_CMD to distinguish the two. For configuration data, you typically want Write With Response so the central knows the write succeeded.

Notifications: Pushing Data to a Connected Device

Reading and writing work for on-demand data. But many BLE applications need the peripheral to push data to the central proactively. A heart rate monitor doesn't wait for the phone to ask for the heart rate every second. It pushes the value via notifications.

Here's how to add notification support to a characteristic:

static uint8_t sensor_value;
static bool notifications_enabled;

static void sensor_ccc_changed(const struct bt_gatt_attr *attr, uint16_t value)
{
    notifications_enabled = (value == BT_GATT_CCC_NOTIFY);
    printk("Notifications %s\n", notifications_enabled ? "enabled" : "disabled");
}

static ssize_t read_sensor(struct bt_conn *conn,
                           const struct bt_gatt_attr *attr,
                           void *buf, uint16_t len, uint16_t offset)
{
    return bt_gatt_attr_read(conn, attr, buf, len, offset,
                             &sensor_value, sizeof(sensor_value));
}

BT_GATT_SERVICE_DEFINE(sensor_service,
    BT_GATT_PRIMARY_SERVICE(BT_UUID_LED_SERVICE),

    BT_GATT_CHARACTERISTIC(BT_UUID_LED_CHAR,
        BT_GATT_CHRC_READ | BT_GATT_CHRC_NOTIFY,
        BT_GATT_PERM_READ,
        read_sensor, NULL, &sensor_value),

    BT_GATT_CCC(sensor_ccc_changed, BT_GATT_PERM_READ | BT_GATT_PERM_WRITE),
);

The characteristic now has BT_GATT_CHRC_NOTIFY in its properties, which tells connected centrals that this characteristic supports notifications.

The BT_GATT_CCC macro adds the Client Characteristic Configuration Descriptor (CCCD). The sensor_ccc_changed callback is called when a central enables or disables notifications by writing to the CCCD. The value parameter will be BT_GATT_CCC_NOTIFY (0x0001) when notifications are enabled and 0 when disabled.

To actually send a notification:

void send_sensor_notification(void)
{
    if (!notifications_enabled) {
        return;
    }

    sensor_value = read_actual_sensor();

    int err = bt_gatt_notify(NULL, &sensor_service.attrs[1],
                             &sensor_value, sizeof(sensor_value));
    if (err) {
        printk("Notify failed (err %d)\n", err);
    }
}

The bt_gatt_notify function sends a notification to all connected centrals that have enabled notifications on this characteristic.

The first argument is NULL to notify all connections (you can pass a specific bt_conn pointer to notify only one). The second argument is a pointer to the characteristic attribute in the GATT table. The &sensor_service.attrs[1] points to the first characteristic value attribute (index 0 is the service declaration, index 1 is the characteristic declaration, and the value follows). The third and fourth arguments are the data and its length.

A common pattern is to call this function from a timer or a work queue at a regular interval:

void sensor_work_handler(struct k_work *work)
{
    send_sensor_notification();
}

K_WORK_DELAYABLE_DEFINE(sensor_work, sensor_work_handler);

/* In main(), after Bluetooth is initialized and advertising: */
k_work_schedule(&sensor_work, K_SECONDS(1));

/* In the work handler, reschedule for periodic execution: */
void sensor_work_handler(struct k_work *work)
{
    send_sensor_notification();
    k_work_schedule(&sensor_work, K_SECONDS(1));
}

This approach uses a delayable work item that reschedules itself every second. Each time it fires, it reads the sensor value and sends a notification (if notifications are enabled). The work item runs on the system work queue thread, not in interrupt context, so it's safe to call bt_gatt_notify and other Bluetooth APIs.

Building a Complete BLE Sensor Node

Now we'll tie everything together into a complete application. This is a BLE environmental sensor that reads temperature (simulated), exposes it through a custom GATT service with read and notify support, handles connections and disconnections, and manages advertising.

Create ~/my_ble_apps/sensor_node/src/main.c:

#include <zephyr/kernel.h>
#include <zephyr/bluetooth/bluetooth.h>
#include <zephyr/bluetooth/gatt.h>
#include <zephyr/bluetooth/uuid.h>
#include <zephyr/bluetooth/conn.h>
#include <zephyr/drivers/gpio.h>

/* UUIDs */
#define BT_UUID_ENV_SERVICE_VAL \
    BT_UUID_128_ENCODE(0xaabbccdd, 0x0000, 0x1000, 0x8000, 0x00805f9b34fb)
#define BT_UUID_ENV_SERVICE BT_UUID_DECLARE_128(BT_UUID_ENV_SERVICE_VAL)

#define BT_UUID_TEMP_CHAR_VAL \
    BT_UUID_128_ENCODE(0xaabbccdd, 0x0001, 0x1000, 0x8000, 0x00805f9b34fb)
#define BT_UUID_TEMP_CHAR BT_UUID_DECLARE_128(BT_UUID_TEMP_CHAR_VAL)

#define BT_UUID_INTERVAL_CHAR_VAL \
    BT_UUID_128_ENCODE(0xaabbccdd, 0x0002, 0x1000, 0x8000, 0x00805f9b34fb)
#define BT_UUID_INTERVAL_CHAR BT_UUID_DECLARE_128(BT_UUID_INTERVAL_CHAR_VAL)

/* LED for connection status */
#define LED0_NODE DT_ALIAS(led0)
static const struct gpio_dt_spec status_led = GPIO_DT_SPEC_GET(LED0_NODE, gpios);

/* Sensor state */
static int16_t temperature_value = 2250;
static uint16_t notify_interval_ms = 1000;
static bool temp_notifications_enabled;
static struct bt_conn *current_conn;

/* Forward declaration */
static void sensor_work_handler(struct k_work *work);
K_WORK_DELAYABLE_DEFINE(sensor_work, sensor_work_handler);

static int16_t simulate_temperature(void)
{
    static int16_t base = 2250;
    base += (k_uptime_get_32() % 11) - 5;
    if (base > 3500) base = 3500;
    if (base < 1000) base = 1000;
    return base;
}

/* GATT callbacks */
static ssize_t read_temperature(struct bt_conn *conn,
                                const struct bt_gatt_attr *attr,
                                void *buf, uint16_t len, uint16_t offset)
{
    temperature_value = simulate_temperature();
    return bt_gatt_attr_read(conn, attr, buf, len, offset,
                             &temperature_value, sizeof(temperature_value));
}

static void temp_ccc_changed(const struct bt_gatt_attr *attr, uint16_t value)
{
    temp_notifications_enabled = (value == BT_GATT_CCC_NOTIFY);
    printk("Temperature notifications %s\n",
           temp_notifications_enabled ? "enabled" : "disabled");

    if (temp_notifications_enabled) {
        k_work_schedule(&sensor_work, K_MSEC(notify_interval_ms));
    } else {
        k_work_cancel_delayable(&sensor_work);
    }
}

static ssize_t read_interval(struct bt_conn *conn,
                             const struct bt_gatt_attr *attr,
                             void *buf, uint16_t len, uint16_t offset)
{
    return bt_gatt_attr_read(conn, attr, buf, len, offset,
                             &notify_interval_ms, sizeof(notify_interval_ms));
}

static ssize_t write_interval(struct bt_conn *conn,
                              const struct bt_gatt_attr *attr,
                              const void *buf, uint16_t len,
                              uint16_t offset, uint8_t flags)
{
    if (len != sizeof(uint16_t)) {
        return BT_GATT_ERR(BT_ATT_ERR_INVALID_ATTRIBUTE_LEN);
    }

    uint16_t new_interval = *((const uint16_t *)buf);

    if (new_interval < 100 || new_interval > 60000) {
        return BT_GATT_ERR(BT_ATT_ERR_VALUE_NOT_ALLOWED);
    }

    notify_interval_ms = new_interval;
    printk("Notification interval changed to %u ms\n", notify_interval_ms);

    if (temp_notifications_enabled) {
        k_work_cancel_delayable(&sensor_work);
        k_work_schedule(&sensor_work, K_MSEC(notify_interval_ms));
    }

    return len;
}

/* GATT service definition */
BT_GATT_SERVICE_DEFINE(env_service,
    BT_GATT_PRIMARY_SERVICE(BT_UUID_ENV_SERVICE),

    BT_GATT_CHARACTERISTIC(BT_UUID_TEMP_CHAR,
        BT_GATT_CHRC_READ | BT_GATT_CHRC_NOTIFY,
        BT_GATT_PERM_READ,
        read_temperature, NULL, NULL),
    BT_GATT_CCC(temp_ccc_changed,
        BT_GATT_PERM_READ | BT_GATT_PERM_WRITE),

    BT_GATT_CHARACTERISTIC(BT_UUID_INTERVAL_CHAR,
        BT_GATT_CHRC_READ | BT_GATT_CHRC_WRITE,
        BT_GATT_PERM_READ | BT_GATT_PERM_WRITE,
        read_interval, write_interval, NULL),
);

/* Notification sender */
static void sensor_work_handler(struct k_work *work)
{
    temperature_value = simulate_temperature();

    if (temp_notifications_enabled) {
        int err = bt_gatt_notify(NULL, &env_service.attrs[2],
                                 &temperature_value,
                                 sizeof(temperature_value));
        if (err && err != -ENOTCONN) {
            printk("Notify error: %d\n", err);
        }

        k_work_schedule(&sensor_work, K_MSEC(notify_interval_ms));
    }
}

/* Advertising data */
static const struct bt_data ad[] = {
    BT_DATA_BYTES(BT_DATA_FLAGS, BT_LE_AD_GENERAL | BT_LE_AD_NO_BREDR),
    BT_DATA(BT_DATA_NAME_COMPLETE, CONFIG_BT_DEVICE_NAME,
            sizeof(CONFIG_BT_DEVICE_NAME) - 1),
};

static const struct bt_data sd[] = {
    BT_DATA_BYTES(BT_DATA_UUID128_ALL, BT_UUID_ENV_SERVICE_VAL),
};

/* Connection callbacks */
static void connected(struct bt_conn *conn, uint8_t err)
{
    if (err) {
        printk("Connection failed (err %u)\n", err);
        return;
    }

    current_conn = bt_conn_ref(conn);
    gpio_pin_set_dt(&status_led, 1);

    char addr[BT_ADDR_LE_STR_LEN];
    bt_addr_le_to_str(bt_conn_get_dst(conn), addr, sizeof(addr));
    printk("Connected: %s\n", addr);
}

static void disconnected(struct bt_conn *conn, uint8_t reason)
{
    char addr[BT_ADDR_LE_STR_LEN];
    bt_addr_le_to_str(bt_conn_get_dst(conn), addr, sizeof(addr));
    printk("Disconnected: %s (reason %u)\n", addr, reason);

    if (current_conn) {
        bt_conn_unref(current_conn);
        current_conn = NULL;
    }

    temp_notifications_enabled = false;
    k_work_cancel_delayable(&sensor_work);
    gpio_pin_set_dt(&status_led, 0);

    bt_le_adv_start(BT_LE_ADV_CONN, ad, ARRAY_SIZE(ad), sd, ARRAY_SIZE(sd));
}

BT_CONN_CB_DEFINE(conn_callbacks) = {
    .connected = connected,
    .disconnected = disconnected,
};

int main(void)
{
    int err;

    if (!gpio_is_ready_dt(&status_led)) {
        printk("LED not ready\n");
        return 0;
    }
    gpio_pin_configure_dt(&status_led, GPIO_OUTPUT_INACTIVE);

    err = bt_enable(NULL);
    if (err) {
        printk("Bluetooth init failed (err %d)\n", err);
        return 0;
    }

    printk("Bluetooth initialized\n");

    err = bt_le_adv_start(BT_LE_ADV_CONN, ad, ARRAY_SIZE(ad),
                          sd, ARRAY_SIZE(sd));
    if (err) {
        printk("Advertising failed (err %d)\n", err);
        return 0;
    }

    printk("Environmental sensor ready. Advertising as '%s'\n",
           CONFIG_BT_DEVICE_NAME);

    return 0;
}

The prj.conf for this application:

CONFIG_BT=y
CONFIG_BT_PERIPHERAL=y
CONFIG_BT_DEVICE_NAME="Zephyr Sensor"
CONFIG_BT_GATT_DYNAMIC_DB=y
CONFIG_GPIO=y
CONFIG_SYSTEM_WORKQUEUE_STACK_SIZE=2048

This application demonstrates the full lifecycle of a BLE sensor device, so study the design carefully.

The service exposes two characteristics. The temperature characteristic supports read and notify. When a central reads it, it gets the latest simulated temperature. When the central enables notifications, the device starts pushing temperature updates at a configurable interval.

The interval characteristic lets the central read and write the notification interval, bounded between 100 ms and 60000 ms. The validation in write_interval rejects values outside this range with BT_ATT_ERR_VALUE_NOT_ALLOWED, which the central receives as an error response.

Temperature values are stored as int16_t in hundredths of a degree Celsius (2250 = 22.50 degrees C). This fixed-point representation avoids floating-point math, which is expensive on microcontrollers without an FPU, and gives you 0.01 degree resolution in a 2-byte value.

The connection callbacks manage the full connection lifecycle. On connect, the code takes a reference to the connection object (bt_conn_ref) and turns on the status LED. On disconnect, it releases the reference (bt_conn_unref), cancels any pending notification work, turns off the LED, and restarts advertising.

The reference counting is important because the bt_conn pointer is only valid while you hold a reference. Using it after the reference is released leads to undefined behavior.

The notification work item reschedules itself at the configured interval, creating a periodic loop. When notifications are disabled (either explicitly by the central or implicitly by disconnection), the work is cancelled. This prevents wasted CPU cycles (and battery) when nobody is listening.

Pairing and Security

Production BLE devices almost always need security. Without pairing, any device within radio range can connect and interact with your GATT services. Pairing establishes an encrypted link and optionally authenticates the devices to each other.

BLE supports several pairing methods. "Just Works" provides encryption but no authentication. It protects against passive eavesdropping but not against active man-in-the-middle attacks. "Passkey Entry" requires the user to enter a 6-digit code, providing authentication. "Numeric Comparison" displays a number on both devices and the user confirms they match. "Out of Band (OOB)" uses an external channel (like NFC) to exchange pairing information.

Enable security in your prj.conf:

CONFIG_BT_SMP=y
CONFIG_BT_SETTINGS=y
CONFIG_FLASH=y
CONFIG_FLASH_MAP=y
CONFIG_NVS=y
CONFIG_SETTINGS=y

CONFIG_BT_SMP=y enables the Security Manager Protocol, which handles pairing. The Settings, Flash, and NVS options enable persistent storage so that bonding information (the keys exchanged during pairing) survives reboots. Without persistent storage, the device would need to re-pair after every power cycle, which is a terrible user experience.

To require encryption on a characteristic, change its permissions:

BT_GATT_CHARACTERISTIC(BT_UUID_TEMP_CHAR,
    BT_GATT_CHRC_READ | BT_GATT_CHRC_NOTIFY,
    BT_GATT_PERM_READ_ENCRYPT,
    read_temperature, NULL, NULL),

BT_GATT_PERM_READ_ENCRYPT means the characteristic can only be read over an encrypted connection. If a central tries to read it without pairing first, the stack automatically triggers pairing. You can also use BT_GATT_PERM_READ_AUTHEN to require authenticated pairing (Passkey or Numeric Comparison, not Just Works).

Register authentication callbacks to handle passkey display or input:

static void auth_passkey_display(struct bt_conn *conn, unsigned int passkey)
{
    char addr[BT_ADDR_LE_STR_LEN];
    bt_addr_le_to_str(bt_conn_get_dst(conn), addr, sizeof(addr));
    printk("Passkey for %s: %06u\n", addr, passkey);
}

static void auth_cancel(struct bt_conn *conn)
{
    char addr[BT_ADDR_LE_STR_LEN];
    bt_addr_le_to_str(bt_conn_get_dst(conn), addr, sizeof(addr));
    printk("Pairing cancelled: %s\n", addr);
}

static struct bt_conn_auth_cb auth_callbacks = {
    .passkey_display = auth_passkey_display,
    .cancel = auth_cancel,
};

/* In main(), after bt_enable(): */
bt_conn_auth_cb_register(&auth_callbacks);

The passkey_display callback fires when the stack generates a passkey that the user needs to enter on the central (phone). On a device with a display, you would show the passkey on screen. On a device without a display (like a sensor), you might print it to a serial console during development or use Just Works pairing in production.

The bt_conn_auth_cb_register function registers these callbacks with the stack. Only one set of callbacks can be active at a time.

Implementing a Standard BLE Profile (Heart Rate)

The examples so far have used custom 128-bit UUIDs. In production, many BLE devices implement standard profiles defined by the Bluetooth SIG. Standard profiles use 16-bit UUIDs, which consume less advertising space and allow generic apps (like nRF Connect) to automatically parse and display the data in a human-readable format. The Heart Rate Profile is one of the most common and illustrates how standard profiles work in Zephyr.

The Heart Rate Service (UUID 0x180D) contains a Heart Rate Measurement characteristic (UUID 0x2A37) that uses notifications to push heart rate data. The measurement characteristic has a specific byte format defined by the Bluetooth SIG: the first byte is a flags field, and the remaining bytes contain the heart rate value and optional fields like energy expended and RR-interval.

#include <zephyr/kernel.h>
#include <zephyr/bluetooth/bluetooth.h>
#include <zephyr/bluetooth/gatt.h>
#include <zephyr/bluetooth/uuid.h>
#include <zephyr/bluetooth/conn.h>

static uint8_t heart_rate_bpm = 72;
static bool hr_notifications_enabled;

static void hr_ccc_changed(const struct bt_gatt_attr *attr, uint16_t value)
{
    hr_notifications_enabled = (value == BT_GATT_CCC_NOTIFY);
}

static ssize_t read_body_sensor_location(struct bt_conn *conn,
                                         const struct bt_gatt_attr *attr,
                                         void *buf, uint16_t len,
                                         uint16_t offset)
{
    uint8_t location = 0x01; /* Chest */
    return bt_gatt_attr_read(conn, attr, buf, len, offset,
                             &location, sizeof(location));
}

BT_GATT_SERVICE_DEFINE(hr_service,
    BT_GATT_PRIMARY_SERVICE(BT_UUID_HRS),

    BT_GATT_CHARACTERISTIC(BT_UUID_HRS_MEASUREMENT,
        BT_GATT_CHRC_NOTIFY,
        BT_GATT_PERM_NONE,
        NULL, NULL, NULL),
    BT_GATT_CCC(hr_ccc_changed,
        BT_GATT_PERM_READ | BT_GATT_PERM_WRITE),

    BT_GATT_CHARACTERISTIC(BT_UUID_HRS_BODY_SENSOR,
        BT_GATT_CHRC_READ,
        BT_GATT_PERM_READ,
        read_body_sensor_location, NULL, NULL),
);

static void send_heart_rate(void)
{
    if (!hr_notifications_enabled) {
        return;
    }

    uint8_t hr_data[2];
    hr_data[0] = 0x00; /* Flags: uint8 format, no extra fields */
    hr_data[1] = heart_rate_bpm;

    bt_gatt_notify(NULL, &hr_service.attrs[1], hr_data, sizeof(hr_data));
}

This code uses Zephyr's predefined UUID macros (BT_UUID_HRS, BT_UUID_HRS_MEASUREMENT, BT_UUID_HRS_BODY_SENSOR) instead of custom 128-bit UUIDs. Zephyr defines macros for all standard Bluetooth SIG services and characteristics in zephyr/bluetooth/uuid.h. Using these standard UUIDs means that any BLE heart rate app on a phone can automatically discover, connect, and display data from your device without custom app development.

The Heart Rate Measurement characteristic has BT_GATT_PERM_NONE for permissions because it's notify-only. No read or write access is permitted: the data flows exclusively through notifications.

The first byte of the notification payload (hr_data[0]) is a flags field defined by the SIG specification. A value of 0x00 means the heart rate is in uint8 format (values 0 to 255 BPM) with no optional fields present. Setting bit 0 would switch to uint16 format for heart rates above 255. Setting other bits would indicate the presence of energy expended or RR-interval data.

The Body Sensor Location characteristic is a simple read-only value. The value 0x01 means "Chest." Other defined values include 0x00 (Other), 0x02 (Wrist), 0x03 (Finger), 0x04 (Hand), 0x05 (Ear Lobe), and 0x06 (Foot).

The prj.conf for a standard profile application doesn't need any special configuration beyond the basic Bluetooth peripheral setup:

CONFIG_BT=y
CONFIG_BT_PERIPHERAL=y
CONFIG_BT_DEVICE_NAME="Zephyr HR"

The standard UUIDs are always available when CONFIG_BT=y is set. No additional Kconfig options are needed to use SIG-defined service and characteristic UUIDs.

The advertising data for a standard profile device typically includes the 16-bit service UUID in the advertising packet, which allows phones to filter scans by service type:

static const struct bt_data ad[] = {
    BT_DATA_BYTES(BT_DATA_FLAGS, BT_LE_AD_GENERAL | BT_LE_AD_NO_BREDR),
    BT_DATA_BYTES(BT_DATA_UUID16_ALL, BT_UUID_16_ENCODE(0x180D)),
    BT_DATA(BT_DATA_NAME_COMPLETE, CONFIG_BT_DEVICE_NAME,
            sizeof(CONFIG_BT_DEVICE_NAME) - 1),
};

The BT_DATA_UUID16_ALL type advertises the complete list of 16-bit service UUIDs. The BT_UUID_16_ENCODE(0x180D) macro encodes the Heart Rate Service UUID in little-endian byte order. A 16-bit UUID takes only 2 bytes in the advertising packet (compared to 16 bytes for a 128-bit UUID), leaving much more room for other advertising data. This is a significant advantage of using standard profiles.

Building a BLE Central

Every example so far has built a peripheral (a device that advertises and accepts connections). The other side of a BLE connection is the central: a device that scans for peripherals, initiates connections, and reads/writes characteristics. Gateways, hubs, and data collectors are typically centrals.

Building a central on Zephyr requires a second board, but understanding the central role is essential for building complete BLE systems.

The prj.conf for a central application:

CONFIG_BT=y
CONFIG_BT_CENTRAL=y
CONFIG_BT_GATT_CLIENT=y
CONFIG_BT_SCAN=y
CONFIG_BT_DEVICE_NAME="Zephyr Central"

CONFIG_BT_CENTRAL=y enables the central role (scanning and connection initiation). CONFIG_BT_GATT_CLIENT=y enables the GATT client APIs for service discovery, reading, writing, and subscribing. CONFIG_BT_SCAN=y enables the scan module, which provides a higher-level scanning API with filtering.

A BLE central starts by scanning for peripherals:

#include <zephyr/kernel.h>
#include <zephyr/bluetooth/bluetooth.h>
#include <zephyr/bluetooth/conn.h>
#include <zephyr/bluetooth/gatt.h>
#include <zephyr/bluetooth/uuid.h>

static struct bt_conn *default_conn;

static void device_found(const bt_addr_le_t *addr, int8_t rssi,
                          uint8_t type, struct net_buf_simple *ad)
{
    char addr_str[BT_ADDR_LE_STR_LEN];
    bt_addr_le_to_str(addr, addr_str, sizeof(addr_str));

    if (rssi < -70) {
        return; /* Skip distant devices */
    }

    printk("Found device: %s (RSSI %d)\n", addr_str, rssi);

    /* Stop scanning before connecting */
    bt_le_scan_stop();

    int err = bt_conn_le_create(addr, BT_CONN_LE_CREATE_CONN,
                                BT_LE_CONN_PARAM_DEFAULT,
                                &default_conn);
    if (err) {
        printk("Connection failed (err %d)\n", err);
        bt_le_scan_start(BT_LE_SCAN_ACTIVE, device_found);
    }
}

int main(void)
{
    int err;

    err = bt_enable(NULL);
    if (err) {
        printk("Bluetooth init failed (err %d)\n", err);
        return 0;
    }

    printk("Starting BLE scan...\n");

    err = bt_le_scan_start(BT_LE_SCAN_ACTIVE, device_found);
    if (err) {
        printk("Scan failed (err %d)\n", err);
        return 0;
    }

    return 0;
}

The bt_le_scan_start function begins scanning for BLE advertisements. The first argument, BT_LE_SCAN_ACTIVE, enables active scanning, which means the scanner sends scan request packets to advertisers to get their scan response data (passive scanning only listens). The second argument is a callback function that's called for every advertising packet received.

The device_found callback receives the advertiser's address, RSSI (signal strength in dBm), advertising type, and the raw advertising data.

In this example, the code filters by RSSI to ignore distant devices, then attempts to connect to the first device it finds. The bt_le_scan_stop call is necessary before initiating a connection because the radio can't scan and connect simultaneously.

The bt_conn_le_create function initiates a connection. It takes the target address, creation parameters (which control the scan window used during connection establishment), connection parameters (interval, latency, timeout), and a pointer to store the connection reference. BT_LE_CONN_PARAM_DEFAULT uses the default connection parameters, which are suitable for most applications.

In a real application, you would filter the scan results more carefully, typically by checking the advertised service UUIDs or device name. After connecting, you would perform GATT service discovery and then read/write/subscribe to characteristics:

static uint8_t discover_func(struct bt_conn *conn,
                              const struct bt_gatt_attr *attr,
                              struct bt_gatt_discover_params *params)
{
    if (!attr) {
        printk("Discovery complete\n");
        return BT_GATT_ITER_STOP;
    }

    char uuid_str[BT_UUID_STR_LEN];
    bt_uuid_to_str(params->uuid, uuid_str, sizeof(uuid_str));
    printk("Discovered attribute: handle %u, UUID %s\n",
           attr->handle, uuid_str);

    return BT_GATT_ITER_CONTINUE;
}

static struct bt_gatt_discover_params discover_params;

static void start_discovery(struct bt_conn *conn)
{
    discover_params.uuid = NULL; /* Discover all services */
    discover_params.func = discover_func;
    discover_params.start_handle = BT_ATT_FIRST_ATTRIBUTE_HANDLE;
    discover_params.end_handle = BT_ATT_LAST_ATTRIBUTE_HANDLE;
    discover_params.type = BT_GATT_DISCOVER_PRIMARY;

    int err = bt_gatt_discover(conn, &discover_params);
    if (err) {
        printk("Discovery failed (err %d)\n", err);
    }
}

The bt_gatt_discover function initiates GATT service discovery on the connected peripheral. The discover_params structure controls what to discover: setting uuid to NULL discovers all primary services. Setting type to BT_GATT_DISCOVER_PRIMARY discovers primary services. You can also set it to BT_GATT_DISCOVER_CHARACTERISTIC to discover characteristics within a service, or BT_GATT_DISCOVER_DESCRIPTOR to discover descriptors within a characteristic.

The discovery callback (discover_func) is called once for each discovered attribute and once more with attr set to NULL when discovery is complete. Returning BT_GATT_ITER_CONTINUE tells the stack to continue discovering. Returning BT_GATT_ITER_STOP stops discovery early.

After discovering the services and characteristics, you read a characteristic value using bt_gatt_read and subscribe to notifications using bt_gatt_subscribe. The subscribe function takes a bt_gatt_subscribe_params structure that specifies the characteristic handle, a notification callback function, and the CCC value to write (BT_GATT_CCC_NOTIFY).

MTU Negotiation and Data Throughput

The default BLE ATT MTU (Maximum Transmission Unit) is 23 bytes. Subtract 3 bytes of ATT protocol overhead, and you're left with 20 bytes of actual payload per GATT operation. For a single temperature reading, 20 bytes is plenty. For transferring a firmware image or a large sensor data buffer, 20 bytes per operation is painfully slow.

MTU negotiation allows two connected devices to agree on a larger MTU, up to 517 bytes (the BLE maximum). A larger MTU means more data per packet, fewer round-trips, and higher throughput. On an nRF52840 with 2M PHY, the difference between a 23-byte MTU and a 247-byte MTU can be 5x to 10x throughput improvement.

Enable a larger MTU in your prj.conf:

CONFIG_BT_L2CAP_TX_MTU=247
CONFIG_BT_BUF_ACL_RX_SIZE=251
CONFIG_BT_BUF_ACL_TX_SIZE=251
CONFIG_BT_CTLR_DATA_LENGTH_MAX=251

CONFIG_BT_L2CAP_TX_MTU=247 sets the maximum ATT MTU that the device will request during negotiation. The value 247 is commonly used because it aligns with the maximum single-packet data length (251 bytes at the Link Layer minus 4 bytes of L2CAP header).

CONFIG_BT_BUF_ACL_RX_SIZE and CONFIG_BT_BUF_ACL_TX_SIZE set the ACL buffer sizes to accommodate the larger packets. CONFIG_BT_CTLR_DATA_LENGTH_MAX enables Data Length Extension (DLE) at the controller level, allowing the Link Layer to send longer packets instead of fragmenting them into 27-byte chunks.

MTU negotiation happens automatically after a connection is established. The Zephyr stack initiates an MTU exchange on connection if the configured MTU is larger than the default. You can also trigger it explicitly:

static void exchange_func(struct bt_conn *conn, uint8_t att_err,
                           struct bt_gatt_exchange_params *params)
{
    if (att_err) {
        printk("MTU exchange failed (err %u)\n", att_err);
        return;
    }

    uint16_t mtu = bt_gatt_get_mtu(conn);
    printk("MTU exchanged: %u bytes\n", mtu);
}

static struct bt_gatt_exchange_params exchange_params = {
    .func = exchange_func,
};

static void connected(struct bt_conn *conn, uint8_t err)
{
    if (err) {
        return;
    }

    bt_gatt_exchange_mtu(conn, &exchange_params);
}

The bt_gatt_exchange_mtu function sends an MTU exchange request to the remote device. The callback receives the result. After a successful exchange, bt_gatt_get_mtu returns the negotiated MTU, which is the minimum of both devices' supported MTU values. The effective payload per notification or write operation is the negotiated MTU minus 3 bytes of ATT header.

When sending large amounts of data over notifications, the effective throughput depends on three factors: the MTU (larger means fewer packets), the connection interval (shorter means more transmission opportunities), and the PHY (2M PHY doubles the raw data rate compared to 1M PHY).

With a 247-byte MTU, a 7.5 ms connection interval, and 2M PHY, you can achieve throughput in the range of 800 kbps to 1400 kbps, depending on the specific controller and radio conditions.

One practical consideration: iOS and Android handle MTU negotiation differently. Android allows you to request a specific MTU via the app layer, while iOS automatically negotiates the maximum supported MTU (typically 185 or 251 bytes depending on the iOS version) without app intervention. Your firmware should always handle whatever MTU is negotiated, rather than assuming a specific value.

PHY Selection for Range and Speed

Bluetooth 5.0 introduced two new PHY (Physical Layer) options beyond the original 1M PHY. Selecting the right PHY trades off range, throughput, and power consumption.

1M PHY is the default and the only PHY available in Bluetooth 4.x. It transmits at 1 megabit per second with standard range. Every BLE device supports 1M PHY.

2M PHY doubles the data rate to 2 megabits per second. Each packet takes half as long to transmit, which means the radio is active for less time. This improves both throughput (more data per unit time) and power consumption (shorter radio on-time). The tradeoff is slightly reduced range compared to 1M PHY because the receiver has less time to integrate each bit. Use 2M PHY when the central and peripheral are close together (within a few meters) and throughput matters.

Coded PHY uses forward error correction to extend range significantly, approximately 2x to 4x compared to 1M PHY. It achieves this by transmitting each bit with redundant coding (S=2 for 2x range, S=8 for 4x range). The cost is reduced throughput: Coded PHY S=8 has an effective data rate of 125 kbps, which is 8x slower than 1M PHY. Use Coded PHY for applications that need long range (outdoor asset tracking, building-wide sensor networks) and can tolerate low data rates.

Enable PHY support in prj.conf:

CONFIG_BT_USER_PHY_UPDATE=y
CONFIG_BT_CTLR_PHY_2M=y
CONFIG_BT_CTLR_PHY_CODED=y

CONFIG_BT_USER_PHY_UPDATE=y enables the application to request PHY updates after a connection is established. CONFIG_BT_CTLR_PHY_2M and CONFIG_BT_CTLR_PHY_CODED enable support for the respective PHYs in the controller.

Request a PHY update after connection:

static void connected(struct bt_conn *conn, uint8_t err)
{
    if (err) {
        return;
    }

    /* Request 2M PHY for higher throughput */
    struct bt_conn_le_phy_param phy_param = {
        .options = BT_CONN_LE_PHY_OPT_NONE,
        .pref_tx_phy = BT_GAP_LE_PHY_2M,
        .pref_rx_phy = BT_GAP_LE_PHY_2M,
    };

    int phy_err = bt_conn_le_phy_update(conn, &phy_param);
    if (phy_err) {
        printk("PHY update request failed (err %d)\n", phy_err);
    }
}

The bt_conn_le_phy_update function sends a PHY update request to the remote device. The pref_tx_phy and pref_rx_phy fields indicate the preferred PHY for transmitting and receiving data, respectively. The remote device may accept or suggest an alternative. Both devices must support the requested PHY for the update to succeed.

To monitor PHY changes, register a callback:

static void phy_updated(struct bt_conn *conn,
                         struct bt_conn_le_phy_info *param)
{
    printk("PHY updated: TX PHY %u, RX PHY %u\n",
           param->tx_phy, param->rx_phy);
}

BT_CONN_CB_DEFINE(conn_callbacks) = {
    .connected = connected,
    .disconnected = disconnected,
    .le_phy_updated = phy_updated,
};

The le_phy_updated callback fires whenever the PHY changes on a connection. The tx_phy and rx_phy fields report the active PHY for each direction. A value of 1 means 1M PHY, 2 means 2M PHY, and 4 means Coded PHY. The TX and RX PHYs can be different (asymmetric PHY), though most applications use the same PHY in both directions.

For Coded PHY with S=8 encoding (maximum range), set the options field:

struct bt_conn_le_phy_param phy_param = {
    .options = BT_CONN_LE_PHY_OPT_CODED_S8,
    .pref_tx_phy = BT_GAP_LE_PHY_CODED,
    .pref_rx_phy = BT_GAP_LE_PHY_CODED,
};

The BT_CONN_LE_PHY_OPT_CODED_S8 option selects S=8 coding, which provides the maximum range extension at the cost of the lowest throughput. Omitting this option (or using BT_CONN_LE_PHY_OPT_CODED_S2) selects S=2 coding, which provides moderate range extension with better throughput.

Firmware Updates Over BLE

Deploying firmware updates to devices in the field is a critical capability for any production BLE product. Users shouldn't need to connect a USB cable or visit a service center to get bug fixes and new features.

Zephyr supports Device Firmware Update (DFU) over BLE through integration with MCUboot, a secure open-source bootloader.

The DFU architecture has two components. MCUboot is a bootloader that runs before your application. It manages two firmware slots: the active slot (running firmware) and the upgrade slot (new firmware waiting to be applied). When new firmware is written to the upgrade slot, MCUboot verifies its cryptographic signature, swaps the slots, and boots the new firmware. If the new firmware fails to confirm itself (mark itself as valid), MCUboot automatically rolls back to the previous version on the next reboot.

The BLE transport for DFU uses the SMP (Simple Management Protocol) over a GATT service. The mcumgr library implements SMP, and Zephyr includes a BLE SMP transport that exposes an SMP GATT service. A phone app (like nRF Connect or mcumgr CLI) connects to this service and uploads the new firmware image in chunks.

Enable DFU in your prj.conf:

CONFIG_BOOTLOADER_MCUBOOT=y
CONFIG_MCUMGR=y
CONFIG_MCUMGR_TRANSPORT_BT=y
CONFIG_MCUMGR_GRP_IMG=y
CONFIG_MCUMGR_GRP_OS=y
CONFIG_IMG_MANAGER=y
CONFIG_STREAM_FLASH=y
CONFIG_FLASH_MAP=y
CONFIG_FLASH=y

CONFIG_BOOTLOADER_MCUBOOT=y tells the build system that this application runs under MCUboot, which changes the linker script and image format. CONFIG_MCUMGR=y enables the mcumgr management library. CONFIG_MCUMGR_TRANSPORT_BT=y enables the BLE SMP transport, which creates a GATT service that the phone connects to for uploading firmware. CONFIG_MCUMGR_GRP_IMG=y enables the image management command group (upload, confirm, erase). CONFIG_MCUMGR_GRP_OS=y enables the OS management group (reset, echo).

Register the BLE SMP transport in your application:

#include <zephyr/mgmt/mcumgr/transport/smp_bt.h>

int main(void)
{
    int err;

    err = bt_enable(NULL);
    if (err) {
        printk("Bluetooth init failed (err %d)\n", err);
        return 0;
    }

    /* Start SMP BLE transport for DFU */
    smp_bt_register();

    /* Start advertising (include SMP service UUID) */
    bt_le_adv_start(BT_LE_ADV_CONN, ad, ARRAY_SIZE(ad), NULL, 0);

    printk("DFU-capable device ready\n");
    return 0;
}

The smp_bt_register() call registers the SMP GATT service with the Bluetooth stack. After this, any BLE central that connects can discover the SMP service and upload firmware using the mcumgr protocol.

Building with MCUboot requires flashing the bootloader first. MCUboot is built separately and programmed into the boot partition of flash:

west build -b nrf52840dk/nrf52840 bootloader/mcuboot/boot/zephyr \
    -d build_mcuboot
west flash -d build_mcuboot

west build -b nrf52840dk/nrf52840 my_dfu_app
west flash

The first two commands build and flash MCUboot. The second two commands build and flash your application. MCUboot occupies the first portion of flash and boots your application from the primary slot.

To perform a DFU, you build a new version of your application, which produces a zephyr.signed.bin file in the build directory. Upload that file to the device using the nRF Connect mobile app (which has built-in DFU support) or the mcumgr command-line tool. The upload happens over the BLE SMP connection. After the upload completes, the device reboots, MCUboot verifies the new image, and swaps it into the active slot.

MCUboot supports several security features that are important for production. Image signing ensures that only firmware signed with your private key can be installed. Image encryption prevents reverse-engineering of firmware images during transfer. Rollback protection reverts to the previous firmware if the new version does not boot successfully. These features require additional configuration but are essential for any product that accepts over-the-air updates.

Bluetooth Mesh on Zephyr

BLE point-to-point connections work well for devices that communicate directly with a phone or gateway. But they break down when you need to control hundreds of light bulbs in a building. You can't connect to each one individually. Bluetooth Mesh solves this.

Bluetooth Mesh is a many-to-many networking standard that runs on top of BLE. Devices in a mesh network relay messages to each other, extending the range far beyond a single BLE connection. A command to turn on the lights can originate from one device, bounce through multiple relay nodes, and reach every light bulb in the building.

Zephyr includes a complete Bluetooth Mesh implementation. Here's the conceptual architecture.

Mesh devices have roles. A relay node forwards messages from other devices, extending the network range. A proxy node bridges between GATT-connected devices (phones) and the mesh network, so a phone without mesh support can control mesh devices through a proxy. A friend node stores messages for nearby low-power nodes that spend most of their time sleeping. A low-power node periodically wakes up and asks its friend for any stored messages.

Mesh communication uses a publish/subscribe model. Devices publish messages to addresses, and devices subscribed to those addresses receive them. A light switch publishes "turn on" to a group address. All light bulbs subscribed to that group address turn on.

Data in mesh is organized using models. A model defines a set of messages that a device can send and receive. The Bluetooth SIG defines standard models for common use cases: Generic OnOff (on/off switches and lights), Generic Level (dimmers), Sensor (sensor data), and Lighting (color temperature, lightness, hue). You can also define custom models.

Here's a minimal mesh node configuration in prj.conf:

CONFIG_BT=y
CONFIG_BT_MESH=y
CONFIG_BT_MESH_RELAY=y
CONFIG_BT_MESH_PB_ADV=y
CONFIG_BT_MESH_PB_GATT=y
CONFIG_BT_MESH_GATT_PROXY=y
CONFIG_BT_MESH_CFG_CLI=y
CONFIG_BT_MESH_HEALTH_SRV=y

CONFIG_BT_MESH=y enables the mesh stack. CONFIG_BT_MESH_RELAY=y makes this node relay messages for other nodes. CONFIG_BT_MESH_PB_ADV=y and CONFIG_BT_MESH_PB_GATT=y enable provisioning (the process of adding a device to the mesh network) over both advertising and GATT connections. CONFIG_BT_MESH_GATT_PROXY=y enables the proxy role for phone connectivity.

A full mesh application involves defining your composition data (what models your device supports), implementing model handlers, and setting up provisioning. The Zephyr samples directory (samples/bluetooth/mesh/) contains several complete examples including a light bulb, a light switch, and a sensor server that demonstrate the full pattern.

LE Audio: The Next Generation of Bluetooth Audio

LE Audio is the most significant addition to the Bluetooth specification in years. It replaces the Classic Bluetooth audio profile (A2DP) with a new system built entirely on BLE. Zephyr's implementation of LE Audio is one of the most complete available in any open-source stack.

The core of LE Audio is the LC3 (Low Complexity Communication Codec). LC3 provides better audio quality than the SBC codec used in classic Bluetooth audio, at half the bitrate. This means better sound quality and lower power consumption.

LE Audio introduces two communication modes. Connected Isochronous Streams (CIS) are point-to-point audio connections, similar to classic Bluetooth audio but more efficient. CIS is used for phone-to-earbud connections, hearing aids, and other paired audio scenarios.

Broadcast Isochronous Streams (BIS) are one-to-many broadcasts. A single source can broadcast audio to an unlimited number of receivers. This is the technology behind Auracast, which envisions public venues broadcasting audio that any compatible device can tune into (think: silent TVs in airports, hearing assistance in theaters, multi-language broadcasts in conference halls).

Zephyr implements the full LE Audio profile stack: BAP (Basic Audio Profile), PACS (Published Audio Capabilities), ASCS (Audio Stream Control), VCP (Volume Control), MCP (Media Control), CCP (Call Control), TMAP (Telephony and Media Audio Profile), and CAP (Common Audio Profile).

The prj.conf for an LE Audio project includes:

CONFIG_BT=y
CONFIG_BT_AUDIO=y
CONFIG_BT_BAP_UNICAST_SERVER=y
CONFIG_BT_PACS=y
CONFIG_BT_ASCS=y
CONFIG_BT_ISO=y
CONFIG_BT_PAC_SNK=y
CONFIG_BT_PAC_SRC=y

LE Audio development is considerably more complex than basic BLE peripheral development. It involves managing isochronous channels, configuring codec parameters, handling audio data streams, and implementing the various profile layers. The Zephyr samples in samples/bluetooth/bap_unicast_server and samples/bluetooth/bap_broadcast_source are the best starting points.

If you're building hearing aids, earbuds, or any audio device, LE Audio on Zephyr is worth serious investment. The open-source stack gives you full visibility into the implementation, and Nordic's nRF5340 and nRF54 series chips provide the hardware support needed.

Debugging Bluetooth Applications

BLE applications are harder to debug than regular embedded applications because the radio communication is invisible. You can't set a breakpoint in the air. Here are the tools and techniques that make BLE debugging manageable.

Zephyr's logging subsystem is your first line of defense. Enable detailed Bluetooth logging in prj.conf:

CONFIG_LOG=y
CONFIG_BT_DEBUG_LOG=y
CONFIG_BT_LOG_LEVEL_DBG=4

CONFIG_LOG=y enables the logging framework. CONFIG_BT_DEBUG_LOG=y and CONFIG_BT_LOG_LEVEL_DBG=4 enable debug-level logging for the Bluetooth stack.

This produces verbose output showing every HCI command, advertising event, connection event, GATT operation, and error. The output goes to the console (typically UART). It's extremely verbose, so only enable it during active debugging.

The Zephyr shell provides an interactive command line for Bluetooth operations:

CONFIG_SHELL=y
CONFIG_BT_SHELL=y

With these enabled, you get shell commands like bt init, bt advertise on, bt connect, bt gatt discover, and bt gatt read that let you control and inspect the Bluetooth stack interactively over the serial console. This is invaluable for testing because you can manually trigger operations and see the results without modifying firmware.

nRF Connect for Mobile (iOS/Android) is an essential companion tool. Beyond scanning and connecting, it displays all GATT services and characteristics, lets you read/write/subscribe to characteristics, shows raw advertising data, and logs BLE events with timestamps. Use it to verify that your device is advertising correctly, that your GATT database looks right, and that reads/writes/notifications work as expected.

Bluetooth sniffers capture the actual radio packets. The nRF52840 DK can be used as a sniffer with Nordic's nRF Sniffer for Bluetooth LE firmware. Combined with Wireshark (which has BLE protocol dissectors), you can inspect every packet on the wire: advertising PDUs, connection events, GATT requests/responses, and pairing exchanges. This is the ultimate debugging tool when something at the protocol level isn't working.

Common debugging patterns. If advertising isn't visible, check that the advertising data doesn't exceed 31 bytes (for legacy advertising) and that the flags field is present.

If connections drop immediately, check that CONFIG_BT_PERIPHERAL is enabled (not just CONFIG_BT_BROADCASTER). If GATT reads return zero-length data, verify that your read callback returns the correct value from bt_gatt_attr_read. If notifications don't arrive, confirm that the central has written 0x0001 to the CCCD. If pairing fails, ensure CONFIG_BT_SMP=y is set and the authentication callbacks are registered.

Power Optimization for BLE Devices

A BLE device that drains its battery in a week is a failed product. Power optimization isn't an afterthought – it's a core design constraint. Zephyr provides the tools, but you have to use them correctly.

The biggest power consumer in a BLE device is the radio. Every advertising event, connection event, and scan window activates the radio transmitter or receiver for milliseconds at a time, consuming milliamps of current. Reducing radio usage is the primary lever for extending battery life.

For advertising, increase the advertising interval. An interval of 1000 ms uses roughly 5x less power than an interval of 200 ms. If fast discovery isn't critical, use an even longer interval.

You can also use a two-phase approach: advertise at a fast interval (100 ms) for the first 30 seconds after power-on, then switch to a slow interval (1000 ms) for the steady state. Zephyr's advertising API supports changing parameters while advertising.

For connected devices, use the peripheral latency parameter. A peripheral latency of 4 means the peripheral can skip 4 connection events before it must respond. If the connection interval is 50 ms and the peripheral latency is 4, the peripheral only wakes up every 250 ms instead of every 50 ms. Request a longer connection interval from the central when high-throughput isn't needed:

static struct bt_le_conn_param conn_params = {
    .interval_min = 80,   /* 100 ms (units of 1.25 ms) */
    .interval_max = 160,  /* 200 ms */
    .latency = 4,
    .timeout = 400,       /* 4 seconds (units of 10 ms) */
};

/* After connection is established: */
bt_conn_le_param_update(conn, &conn_params);

The bt_conn_le_param_update function sends a connection parameter update request to the central. The central may accept or reject the request. Most centrals (phones) accept reasonable parameter ranges.

Enable Zephyr's system power management:

CONFIG_PM=y
CONFIG_PM_DEVICE=y

With power management enabled, the kernel puts the processor into a low-power state whenever no threads are ready to run.

On an nRF52840, the idle current drops from roughly 3 mA (active) to about 1.5 microamps (System OFF with RAM retention). The difference is enormous. The Zephyr power management policy automatically selects the deepest sleep state that the system can enter given the next scheduled wake-up event.

Disable unused peripherals in your devicetree overlay. Every enabled peripheral (UART, SPI, I2C) consumes power even when idle. If you don't need UART in production (you used it only for development logging), disable it:

&uart0 {
    status = "disabled";
};

Measure your actual current consumption. Tools like the Nordic Power Profiler Kit II show real-time current draw at microamp resolution. Zephyr's CONFIG_THREAD_ANALYZER helps you right-size thread stacks (over-allocated stacks waste RAM, which means more RAM needs to be powered).

The goal for a well-optimized BLE sensor is single-digit microamp average current, which translates to years of operation on a coin cell battery. Zephyr makes this achievable, but it requires attention to every layer: radio scheduling, peripheral management, clock configuration, and application design.

Zephyr Bluetooth vs Other Stacks

When choosing a Bluetooth stack, you have options. Here is how Zephyr compares.

1. Zephyr vs. Nordic SoftDevice

Nordic's SoftDevice was their proprietary BLE stack before they moved to Zephyr. SoftDevice was a pre-compiled binary blob: you couldn't read or modify the stack code. Nordic's nRF Connect SDK (built on Zephyr) replaces SoftDevice with Zephyr's open-source stack. If you're starting a new Nordic project, use Zephyr. SoftDevice is legacy.

Zephyr vs. NimBLE (Apache Mynewt)

NimBLE is a lightweight, open-source BLE host stack originally from the Apache Mynewt project (also usable standalone and ported to ESP-IDF). NimBLE is smaller than Zephyr's stack and may be a better fit for extremely RAM-constrained devices. Zephyr's stack is more feature-complete (LE Audio, Mesh, Direction Finding) and has broader industry adoption. For new products, Zephyr is the stronger choice unless you are severely RAM-constrained.

Zephyr vs. ESP-IDF Bluetooth

Espressif's ESP-IDF includes a Bluetooth stack (Bluedroid or NimBLE) for ESP32 chips. If you're exclusively using ESP32 hardware, ESP-IDF is a valid choice. Zephyr supports ESP32 and gives you portability to other hardware, a unified build system, and a more comprehensive BLE feature set. If you might ever need to switch chips, Zephyr's portability is a significant advantage.

Zephyr vs. vendor SDKs with proprietary stacks

Many chip vendors provide their own BLE SDKs with closed-source stacks. These work well but lock you into that vendor's ecosystem. Zephyr gives you portability, open source, and the collective effort of a large community. The trade-off is a steeper learning curve.

For a product that needs to ship on a timeline with one known chip, a vendor SDK might be faster to start with. For a product line that spans multiple chips or that values long-term maintainability, Zephyr wins.

Where to Go from Here

We've covered a lot of ground in this handbook. You should now understand BLE fundamentals, GAP advertising, GATT services, connections, notifications, pairing, Mesh, LE Audio, debugging, and power optimization. You've written code for every major concept. Here's how to continue.

Explore the Zephyr Bluetooth samples directory (zephyr/samples/bluetooth/). It contains over 30 Bluetooth-specific examples. The peripheral_hr sample implements a complete Heart Rate profile. The central sample shows how to build a scanning/connecting central role. The mesh/ subdirectory has light switch, light bulb, and sensor examples for Mesh development. The bap_* samples demonstrate LE Audio.

Read the Zephyr Bluetooth documentation at docs.zephyrproject.org/latest/connectivity/bluetooth/. The API reference covers every function, macro, and configuration option. The Bluetooth architecture documentation explains how the host, controller, and HCI layers interact.

Get an nRF Connect SDK setup if you are using Nordic hardware. The nRF Connect SDK adds Nordic-specific features on top of Zephyr, including their Bluetooth libraries, proprietary wireless protocols (ESB, Gazell), and cellular modem support. It uses the same Zephyr kernel and build system.

Build something real. A BLE remote control for your desk lamp. A sensor that reports room temperature and humidity to your phone. A custom keyboard with BLE connectivity. A pet tracker.

The best way to solidify this knowledge is to encounter and solve real problems on real hardware. Every BLE product has its quirks (connection parameter negotiation with iOS vs Android, handling reconnection after bond loss, managing MTU size for efficient data transfer), and you learn those quirks by building.

The BLE ecosystem is enormous and growing. Zephyr gives you a production-quality, open-source foundation to build on, with a community and corporate backing that ensures it will be actively developed for years to come. You now have the knowledge to start building on it.

Summary

This handbook covered the full spectrum of Bluetooth development on Zephyr OS, from foundational concepts to production-ready features.

The BLE fundamentals section established the mental model that everything else builds on: GAP controls discovery and connections, GATT defines how data is structured and exchanged, services and characteristics form the API of your device, and UUIDs identify every component. These concepts are not Zephyr-specific – they apply to any BLE stack.

On the Zephyr side, you built progressively more complex applications. The beacon demonstrated the minimal BLE setup: initialize the stack and start advertising. The LED service introduced GATT with read and write characteristics, showing how to control hardware from a phone. The notification examples added real-time data push, and the complete sensor node tied together advertising, GATT, connection management, and periodic data delivery into a single cohesive application.

Each of these patterns (advertising data construction, GATT callback signatures, CCC handling, connection reference management) will appear in every BLE project you build.

The standard Heart Rate profile showed how SIG-defined 16-bit UUIDs integrate with Zephyr's predefined UUID macros, enabling interoperability with generic BLE apps.

The central role example demonstrated the other side of BLE: scanning, connecting, and discovering services on remote devices. MTU negotiation and PHY selection are the two primary levers for optimizing data throughput and range after a connection is established, and both require coordinated configuration in Kconfig and runtime API calls.

The DFU section addressed the production requirement of field-updatable firmware, integrating MCUboot with SMP over BLE.

Beyond point-to-point connections, Bluetooth Mesh extends BLE into many-to-many networks for building automation and large-scale IoT deployments, while LE Audio represents the next generation of wireless audio with the LC3 codec and broadcast capabilities. Pairing and security protect production devices from unauthorized access. Power optimization, debugging tooling, and stack comparison round out the practical knowledge needed to ship a real product.

The code patterns and Kconfig options presented here form the toolkit for building any BLE device on Zephyr, from a simple beacon to a complex multi-protocol gateway.

This handbook walks through SCons from first principles. You'll install it, build a multi-file C++ project with a static library, set up cross-compilation for an embedded target (Qualcomm's QuRT real-time operating system), and learn the internals that make SCons different from Make and CMake.

By the end, you'll have a working build system you can adapt to your own projects.

The full example code is self-contained. You can type it out, run it, and see real output at every step.

Table of Contents

• Prerequisites

• What is SCons and Why Does it Exist

• How SCons Compares to Make, CMake, and Meson

• A Side-by-Side Look at Make Versus SCons

• Installing SCons

• Core Concepts You Need Before Writing a Build File

• The Three Environments in SCons

• Construction Variables Reference

• Your First SConstruct File

• Building a Multi-File C++ Project Step by Step

• Detailed Walkthrough of Every File in the Project

• Running the Build and Understanding the Output

• What Happens During an Incremental Build

• Cross-Compiling for QuRT (Qualcomm Real-Time OS)

• Writing QuRT-Specific Application Code

• Building Both Native and QuRT From One SConstruct

• How SCons Detects Dependencies and Decides What to Rebuild

• Writing a Custom Scanner

• The Shared Build Cache

• Working with Shared Libraries

• Adding Command-Line Options with AddOption

• Configure Checks for Portability

• Custom Builders for Non-Standard File Types

• Aliases, Default Targets, and Install Rules

• Platform-Specific Configuration

• Customizing Build Output

• How to Debug SCons Build Files

• The SCons Command-Line Reference

• Common Mistakes and How to Avoid Them

• Summary

Prerequisites

You need Python 3.7 or newer installed on your system. You also need a C++ compiler (GCC, Clang, or MSVC). Familiarity with basic C/C++ compilation (what a compiler and linker do) is assumed. Prior experience with Make or any build system is helpful but not required.

For the QuRT cross-compilation sections, you need the Qualcomm Hexagon SDK installed on your machine. Those sections are self-contained, so you can skip them if you're only interested in native builds.

What is SCons and Why Does it Exist?

SCons is an open-source, cross-platform software construction tool written entirely in Python. Steven Knight created it in 2001 after his design won the Software Carpentry SC Build competition in August 2000.

The competition asked participants to design a better build tool, and Knight's "ScCons" entry beat out the alternatives. The name was later shortened to "SCons" after the project separated from Software Carpentry.

Knight's design drew heavily from Cons, a Perl-based build tool created by Bob Sidebotham in the late 1990s. Cons introduced several ideas that were radical at the time: content-based change detection (using MD5 hashes instead of timestamps), automatic dependency scanning for C/C++ headers, and a single global dependency graph that eliminated the problems with recursive Make.

SCons took all of these ideas and reimplemented them in Python, adding a proper configuration API, cross-platform support, and extensibility through Python's object model.

The project is currently maintained by William Deegan and Gary Oberbrunner, and it's released under the MIT license. The current stable version is 4.10.x. Development happens on GitHub, and the community communicates through a Discord server, IRC (#scons on Libera.Chat), and mailing lists.

How SCons Works

The central idea behind SCons is straightforward: build files should be written in a real programming language, not a domain-specific language with quirky syntax rules.

An SConstruct file is a Python script. You have access to loops, conditionals, functions, classes, and every Python library on your system. There are no special syntax rules to memorize, no tab-sensitivity bugs, and no distinction between spaces and tabs that silently breaks your build. If you can write Python, you can write SCons build files.

SCons also differs from Make in how it determines what needs to be rebuilt. Make compares file timestamps. If you run touch main.c, Make will recompile it even though nothing actually changed.

SCons computes a content hash (MD5 by default) of every source file. If the content hasn't changed, SCons skips the rebuild. This eliminates an entire class of unnecessary recompilations. It also means you never need to run make clean because you are unsure whether the build state is consistent. SCons' build state is always correct, because it tracks content, not time.

Several large projects have used SCons in production. The Godot game engine uses SCons as its build system. MongoDB used SCons for years. PlatformIO, the embedded development ecosystem, uses SCons as its core build engine. National Instruments has used it for projects with over 5,000 source files. NSIS (the Nullsoft Scriptable Install System) and several aerospace projects (including the Aerosonde UAV) have also relied on SCons.

How SCons Compares to Make, CMake, and Meson

Understanding where SCons fits relative to other build tools helps you decide when to reach for it.

SCons versus Make

Make uses a custom DSL that is notoriously finicky. Tabs matter (a space where a tab should be silently does nothing). Variable expansion rules are complex and have multiple flavors (=, :=, ?=, +=). Dependency detection for C/C++ headers requires manual setup or external tools like makedepend or compiler-generated .d files.

Recursive Make (the standard pattern for multi-directory projects) can miss cross-directory dependencies entirely, a problem documented in Peter Miller's famous 1997 paper "Recursive Make Considered Harmful."

SCons solves all of these problems. It scans C/C++ source files automatically, builds a single global dependency graph across all directories in a single pass, and uses content hashing instead of timestamps.

The tradeoff is startup speed. SCons must read every build file and construct the full dependency graph before building anything, which adds overhead that Make doesn't have. On small to medium projects (up to a few thousand source files), this overhead is negligible. On very large projects (tens of thousands of files), it can add several seconds to every invocation.

SCons versus CMake

CMake is not a build tool. It's a meta-build system that generates Makefiles, Ninja files, or Visual Studio project files. You write CMakeLists.txt, run cmake to generate the native build files, then run make or ninja to actually build.

SCons builds directly. There is no generation step. CMake has a much larger ecosystem, better IDE integration (it can generate Xcode projects, Visual Studio solutions, and CLion configurations), and a huge library of find_package modules for locating third-party libraries like Boost, OpenSSL, and Qt. SCons has nothing comparable.

Where SCons wins is in simplicity and debuggability. Your build files are Python. You can print() variables, set breakpoints with pdb, use list comprehensions, and call any Python function. CMake's custom language is harder to debug, has surprising scoping rules, and requires learning a distinct syntax that's not used anywhere else.

SCons versus Meson

Meson is a newer build tool that generates Ninja files for fast parallel builds. It uses a custom DSL that is intentionally not Turing-complete. You can't write loops over source files or call arbitrary external programs during the configuration phase. This sounds limiting, but it prevents an entire class of build file bugs (like accidentally depending on host state that doesn't exist on other developers' machines).

Meson is faster than SCons on large projects because Ninja, its backend, is extremely optimized for incremental builds. Meson also has better built-in support for cross-compilation through a dedicated "cross file" format.

SCons gives you more flexibility through Python, but Meson's opinionated approach catches more mistakes at configuration time and produces faster builds.

The short version: use SCons when you want the full power of Python in your build files, when you need content-based rebuild detection, when you're working on a project that already uses it, or when you're doing embedded work where the build system needs to handle unusual toolchains and file types.

Use CMake when IDE integration and ecosystem size matter most. Use Meson when build speed on large projects is the primary concern.

A Side-by-Side Look at Make Versus SCons

Seeing the same build expressed in both Make and SCons makes the differences concrete. Consider a simple project with two C files and a header.

The Makefile looks like this:

CC = gcc
CFLAGS = -Wall -O2
OBJECTS = main.o utils.o

myapp: $(OBJECTS)
	\((CC) \)(CFLAGS) -o \(@ \)^

main.o: main.c utils.h
	\((CC) \)(CFLAGS) -c $<

utils.o: utils.c utils.h
	\((CC) \)(CFLAGS) -c $<

clean:
	rm -f myapp $(OBJECTS)

This Makefile has 13 lines and requires you to manually list every header dependency. If you add a new header file and forget to update the Makefile, your build will succeed but produce incorrect output. The indented lines must use literal tab characters, not spaces. The \(@, \)^, and $< automatic variables are cryptic until you memorize them.

The equivalent SConstruct file looks like this:

env = Environment(CCFLAGS=['-Wall', '-O2'])
env.Program('myapp', ['main.c', 'utils.c'])

Two lines. SCons detects the header dependency on utils.h automatically by scanning the #include directives in the source files. There's no clean target because scons -c handles cleanup. There are no tab sensitivity issues because this is Python.

The Makefile approach has one advantage: it starts faster on large projects because it doesn't need to scan every source file for includes.

On a two-file project, this difference is unmeasurable. On a 10,000-file project, the SCons overhead might add 2 to 5 seconds. Whether that tradeoff matters depends on your project size and your tolerance for manual dependency management.

Installing SCons

The simplest installation method is pip, since SCons is a pure Python package with no compiled dependencies.

pip install scons

This installs the scons command globally (or in your active virtual environment). The package name on PyPI is SCons. On some systems, you may need to use pip3 instead of pip to target Python 3.

You can also install through system package managers:

# Debian / Ubuntu
sudo apt install scons

# Fedora
sudo dnf install scons

# macOS with Homebrew
brew install scons

# Arch Linux
sudo pacman -S scons

# Conda
conda install -c conda-forge scons

The pip install line pulls the SCons package from PyPI and places the scons executable on your PATH. System package managers do the same thing but integrate with your OS's package database. Either approach works. The pip method tends to give you the latest version, while system packages may lag behind by one or two releases.

Verify the installation by checking the version.

scons --version

You should see output showing the SCons version number and the Python version it's running under. If the command isn't found, make sure your Python scripts directory is on your PATH. On Linux, this is typically ~/.local/bin for user installs. On macOS with Homebrew Python, it's usually /usr/local/bin or /opt/homebrew/bin.

Core Concepts You Need Before Writing a Build File

SCons organizes builds around five core concepts. Understanding them before you write any code saves confusion later.

The SConstruct Build File

This is the top-level build file. When you run scons in a directory, it looks for a file named SConstruct (capital S, capital C, no file extension). SCons also accepts the alternative names Sconstruct and sconstruct, but the capitalized version is the convention.

This file is a Python script. It defines what to build and how. There is exactly one SConstruct per project, and it lives in the project root.

SConscript Build Files

These are subsidiary build files for subdirectories. The top-level SConstruct calls SConscript('src/SConscript') to pull in build definitions from the src directory.

All file paths inside an SConscript are relative to that SConscript's location, not the project root. The # character at the start of a path means "relative to the SConstruct directory," which is useful for referencing shared include directories from any SConscript at any depth.

For example, #include always refers to the include directory at the project root, regardless of which subdirectory's SConscript uses it.

Construction Environment

This is a Python object (created with Environment()) that holds all the configuration for a build: which compiler to use, what flags to pass, where to find headers, what libraries to link. You can create multiple environments for different build configurations (debug vs. release, or native vs. cross-compiled).

Every environment has a set of construction variables (like CC, CCFLAGS, CPPPATH, LIBS) and a set of builders (like Program, Library, Object). When you modify an environment with env.Append() or env.Replace(), you change the configuration for all subsequent builder calls on that environment. To isolate changes, clone the environment first with env.Clone().

Builder Methods

These are methods on the Environment object that know how to produce specific types of output.

• env.Program() compiles and links an executable.

• env.StaticLibrary() creates a static library (.a on Linux, .lib on Windows).

• env.SharedLibrary() creates a shared library (.so on Linux, .dylib on macOS, .dll on Windows).

• env.Object() compiles a single source file to an object file.

• env.Command() runs an arbitrary shell command.

Every builder returns a list of Node objects representing the files it will produce. You can define your own builders for file types that SCons doesn't know about, such as protocol buffer definitions, shader files, or firmware images.

Nodes

These are SCons' internal representation of files and directories. When you call env.Object('main.cpp'), you get back a Node object, not a string. You can pass Node objects to other builders, concatenate them with the + operator, and use them anywhere SCons expects a file reference.

Working with Nodes instead of raw strings makes your build files portable across platforms because SCons handles platform-specific file extensions and path separators internally.

You can also create Nodes explicitly: File('foo.c') creates a file Node, Dir('src') creates a directory Node, and Entry('ambiguous') creates a Node whose type (file or directory) SCons determines later.

The Three Environments in SCons

SCons distinguishes three types of environments, and confusing them is a common source of bugs. Understanding the distinction upfront prevents a category of hard-to-diagnose build failures.

The External Environment is your shell's environment, accessible through os.environ in Python. It contains variables like PATH, HOME, PKG_CONFIG_PATH, and anything else you have set in your .bashrc or .zshrc.

SCons doesn't automatically import this environment. This is deliberate. If SCons inherited your shell environment, your build would depend on whatever happened to be set in each developer's shell, making builds non-reproducible. A build that works on your machine but fails on a colleague's machine because they have a different PATH is exactly the kind of problem SCons tries to prevent.

The Construction Environment is the Environment() object you create in your SConstruct file. It holds construction variables that control how SCons invokes tools.

• CC specifies the C compiler.

• CXX specifies the C++ compiler.

• CCFLAGS holds flags for both C and C++ compilation.

• CPPPATH lists header search directories.

• LIBS lists libraries to link.

• LIBPATH lists library search directories.

These variables don't come from your shell. SCons populates them with platform-appropriate defaults (for example, CC defaults to gcc on Linux and cl on Windows with MSVC).

The Execution Environment is a dictionary stored at env['ENV'] inside the construction environment. This is the environment that gets passed to child processes (compilers, linkers, archivers) when SCons runs them.

By default, it contains a minimal PATH sufficient to find the compiler. If your build tools need additional environment variables (for example, a cross-compiler that reads HEXAGON_SDK_ROOT), you must add them to env['ENV'] explicitly.

When a build fails because a tool is "not found," the problem is almost always that the tool is on your shell's PATH (external environment) but not on the execution environment's PATH (env['ENV']['PATH']). The fix is to pass it through:

import os
env = Environment()
env['ENV']['PATH'] = os.environ['PATH']

This line copies your shell's PATH into the execution environment so child processes can find the same tools you can find in your terminal.

A broader approach is env = Environment(ENV=os.environ.copy()), which copies everything, but this reduces reproducibility because your build now depends on every variable in your shell.

Construction Variables Reference

SCons has dozens of construction variables. The ones you'll use most frequently for C/C++ projects are worth knowing by name.

CC is the C compiler command. Defaults to the platform's default C compiler (gcc on Linux, clang on macOS, cl on Windows with MSVC). Override it to use a different compiler or a cross-compiler.

CXX is the C++ compiler command. Same defaults as CC but for C++.

CCFLAGS holds flags passed to both the C and C++ compilers during compilation. Use this for warnings (-Wall), optimization (-O2), and other flags that apply regardless of language.

CFLAGS holds flags passed only to the C compiler. Use this for C-specific flags like -std=c11.

CXXFLAGS holds flags passed only to the C++ compiler. Use this for C++-specific flags like -std=c++17.

CPPPATH is a list of directories to search for header files. SCons translates each entry into a -I flag. The # prefix means relative to the SConstruct directory.

CPPDEFINES is a list of preprocessor definitions. env.Append(CPPDEFINES=['DEBUG', ('VERSION', '2')]) translates to -DDEBUG -DVERSION=2. Using CPPDEFINES instead of adding -D flags to CCFLAGS is preferred because SCons tracks them as structured data and can compare them correctly for rebuild decisions.

LIBS is a list of libraries to link against. LIBS=['pthread', 'm'] translates to -lpthread -lm. You can also pass Node objects returned by StaticLibrary or SharedLibrary builders.

LIBPATH is a list of directories to search for libraries. Translates to -L flags.

LINKFLAGS holds flags passed to the linker. Use this for linker-specific options like -nostdlib, -Wl,--gc-sections, or -static.

AR is the static library archiver command. Defaults to ar on POSIX systems.

LINK is the linker command. Defaults to the C or C++ compiler (which invokes the linker internally).

PROGSUFFIX is the suffix for executable files. Empty on POSIX, .exe on Windows. You rarely need to set this, as SCons detects it from the platform.

All of these variables can be set in the Environment() constructor, modified with env.Append(), env.Prepend(), or env.Replace(), or overridden per-builder-call by passing them as keyword arguments.

Your First SConstruct File

Create a directory for experimentation and put a single C file in it.

// hello.c
#include <stdio.h>

int main() {
    printf("Hello from SCons!\n");
    return 0;
}

This is a minimal C program that prints a message and exits. Nothing complicated. It exists solely to give SCons something to build.

Now create an SConstruct file in the same directory.

Program('hello.c')

This single line is a complete SConstruct file. Program is a default builder that's available without creating an explicit Environment. Behind the scenes, SCons creates a default environment with platform-appropriate compiler settings and uses it for this Program call. It tells SCons to compile hello.c and link it into an executable.

Run the build.

scons

SCons prints output showing the compilation and linking commands it executes. On Linux with GCC, you'll see something like gcc -o hello.o -c hello.c followed by gcc -o hello hello.o. The resulting executable is named hello (on Linux/macOS) or hello.exe (on Windows). SCons derives the output name from the source file name by stripping the extension.

Run scons again without changing anything. SCons prints scons: 'hello' is up to date. and does nothing. It read the content hash of hello.c, compared it to the stored hash from the previous build, and determined that no rebuild was necessary. This is the content-based rebuild detection in action.

Now run touch hello.c and then scons again. SCons still does nothing. The content of hello.c didn't change, so the hash is identical. Make would have recompiled here. SCons does not.

For a slightly more realistic example, create an explicit environment with custom flags.

env = Environment(
    CC='gcc',
    CCFLAGS=['-Wall', '-Wextra', '-O2'],
)
env.Program('hello', 'hello.c')

This version creates a construction environment, sets the compiler to gcc explicitly, enables extra warnings with -Wextra, and optimizes with -O2. The Program call now takes two arguments: the target name 'hello' and the source file 'hello.c'. When you provide both, you control the output name directly.

You can add multiple programs in the same SConstruct:

env = Environment(CCFLAGS=['-Wall', '-O2'])
env.Program('hello', 'hello.c')
env.Program('goodbye', 'goodbye.c')

Running scons builds both executables. Running scons hello builds only the first one. SCons accepts target names on the command line to build selectively.

Building a Multi-File C++ Project Step by Step

A single-file example is useful for verifying your installation, but real projects have multiple source files, libraries, and header directories. This section builds a complete project with all of those elements.

The project structure looks like this:

myproject/
    SConstruct
    include/
        config.h
    lib/
        SConscript
        mathutils.h
        mathutils.cpp
        stringutils.h
        stringutils.cpp
    src/
        SConscript
        main.cpp
        app.h
        app.cpp

This diagram shows a project with three directories beneath the root. The include directory holds a shared configuration header that defines version constants. The lib directory contains two utility modules (math and string operations) that get compiled into a static library called libmyutils.a. The src directory holds the main application code that depends on the library.

Each directory with compilable source files has its own SConscript file. The top-level SConstruct orchestrates everything.

The build system compiles the library first, then the application, and places all build artifacts in a separate build directory to keep the source tree clean. This separation means you can delete the entire build directory and rebuild from scratch without touching any source files.

Create the project directory and all subdirectories first.

mkdir -p myproject/include myproject/lib myproject/src
cd myproject

These commands create the full directory tree. The -p flag on mkdir creates parent directories as needed and does not error if they already exist.

Now create each file. Start with the shared configuration header.

// include/config.h
#ifndef CONFIG_H
#define CONFIG_H
#define APP_VERSION "1.0.0"
#define APP_NAME "SCons Demo"
#endif

This header defines version and name constants that the application code will reference. The include guards (#ifndef / #define / #endif) prevent double-inclusion, which is standard practice in C/C++ headers. Because this header is in the include directory, any source file that wants to use it must have include on its header search path. The SConstruct file handles this through the CPPPATH variable.

Next, the math utility library:

// lib/mathutils.h
#ifndef MATHUTILS_H
#define MATHUTILS_H

int factorial(int n);
double circle_area(double radius);

#endif

// lib/mathutils.cpp
#include "mathutils.h"
#include <cmath>

int factorial(int n) {
    if (n <= 1) return 1;
    return n * factorial(n - 1);
}

double circle_area(double radius) {
    return M_PI * radius * radius;
}

The mathutils module provides two functions: a recursive factorial calculation and a circle area computation. The header declares the function signatures so that other translation units can call them. The implementation file defines the function bodies. The cmath include brings in M_PI, the mathematical constant for pi.

When SCons processes mathutils.cpp, it scans the #include directives and discovers that mathutils.cpp depends on both mathutils.h and the system header cmath. If you later modify mathutils.h, SCons knows to recompile mathutils.cpp without any manual dependency declaration.

Now the string utility:

// lib/stringutils.h
#ifndef STRINGUTILS_H
#define STRINGUTILS_H
#include <string>

std::string to_upper(const std::string& s);

#endif

// lib/stringutils.cpp
#include "stringutils.h"
#include <algorithm>
#include <cctype>

std::string to_upper(const std::string& s) {
    std::string result = s;
    std::transform(result.begin(), result.end(),
                   result.begin(), ::toupper);
    return result;
}

The stringutils module has a single function that converts a string to uppercase using the standard library's transform algorithm. The ::toupper passed as the transformation function is the C locale version from <cctype>. Together with mathutils, these two modules form a small utility library that the application will link against.

Now the application layer:

// src/app.h
#ifndef APP_H
#define APP_H

void run_app();

#endif

// src/app.cpp
#include "app.h"
#include "config.h"
#include "mathutils.h"
#include "stringutils.h"
#include <iostream>

void run_app() {
    std::cout << "Application: " << APP_NAME << std::endl;
    std::cout << "Version: " << APP_VERSION << std::endl;
    std::cout << "5! = " << factorial(5) << std::endl;
    std::cout << "Circle area (r=3): " << circle_area(3.0) << std::endl;
    std::cout << to_upper("hello scons") << std::endl;
}

// src/main.cpp
#include "app.h"

int main() {
    run_app();
    return 0;
}

The app.cpp file includes headers from all three directories: config.h from include, mathutils.h and stringutils.h from lib, and its own app.h.

This cross-directory dependency pattern is common in real projects and is precisely the scenario where Make's manual dependency tracking becomes error-prone. SCons handles it automatically. The main.cpp file is deliberately thin, delegating all work to run_app(). This pattern (a thin main that calls into application logic) makes the code easier to test because you can link app.cpp against a test harness without pulling in main.

Now the build files. Start with the top-level SConstruct:

# SConstruct
import os

env = Environment(
    CPPPATH=['#include', '#lib'],
    CCFLAGS=['-Wall', '-std=c++17'],
)

debug = ARGUMENTS.get('debug', '0')
if debug == '1':
    env.Append(CCFLAGS=['-g', '-O0', '-DDEBUG'])
    variant = 'build/debug'
else:
    env.Append(CCFLAGS=['-O2', '-DNDEBUG'])
    variant = 'build/release'

Export('env')

lib = SConscript('lib/SConscript',
                 variant_dir=variant + '/lib',
                 duplicate=0)

SConscript('src/SConscript',
           variant_dir=variant + '/src',
           duplicate=0,
           exports={'mylib': lib})

This SConstruct file is the control center of the build. The next section walks through every line in detail.

The library's SConscript file:

# lib/SConscript
Import('env')

lib = env.StaticLibrary('myutils', [
    'mathutils.cpp',
    'stringutils.cpp',
])

Return('lib')

This file imports the shared environment, compiles both library source files into a static library named libmyutils.a (on Linux) or myutils.lib (on Windows), and returns the resulting Node to the caller.

The source file paths mathutils.cpp and stringutils.cpp are relative to this SConscript file's directory, which is lib/. You don't need to write lib/mathutils.cpp because SCons already knows the context.

The application's SConscript file:

# src/SConscript
Import('env')
Import('mylib')

app = env.Program(
    target='myapp',
    source=['main.cpp', 'app.cpp'],
    LIBS=[mylib, 'm'],
    LIBPATH=['#build/release/lib', '#build/debug/lib'],
)

Return('app')

This file imports both the shared environment and the library Node. It compiles the application sources and links them against the myutils library and the math library (-lm). The LIBPATH tells the linker where to find libmyutils.a.

Both the debug and release library paths are listed so the linker finds the library regardless of which build variant is active.

Detailed Walkthrough of Every File in the Project

This section explains the SConstruct and SConscript files line by line. Understanding each line is the difference between cargo-culting a build system and being able to modify it confidently.

The SConstruct File

import os

Standard Python import. You might need os.environ later to pass shell environment variables into the build, os.path.join to construct portable file paths, or os.path.exists to check for optional toolchains. Even if you don't use it immediately, having it available is common practice in SConstruct files.

env = Environment(
    CPPPATH=['#include', '#lib'],
    CCFLAGS=['-Wall', '-std=c++17'],
)

Environment() creates a construction environment. This is the central configuration object that holds everything SCons needs to compile and link your code. CPPPATH sets the header search path. The # prefix means "relative to the directory containing SConstruct." So #include resolves to myproject/include and #lib resolves to myproject/lib, regardless of which SConscript file uses this environment.

When SCons invokes the compiler, it translates CPPPATH entries into -I flags automatically: -Iinclude -Ilib. CCFLAGS holds compiler flags passed to both the C and C++ compilers. -Wall enables all standard warnings. -std=c++17 selects the C++17 standard. Note that -std=c++17 is a language standard flag, so it could also go in CXXFLAGS (C++ only), but placing it in CCFLAGS is harmless here because this project has no C files.

debug = ARGUMENTS.get('debug', '0')
if debug == '1':
    env.Append(CCFLAGS=['-g', '-O0', '-DDEBUG'])
    variant = 'build/debug'
else:
    env.Append(CCFLAGS=['-O2', '-DNDEBUG'])
    variant = 'build/release'

ARGUMENTS is a global dictionary that SCons populates from command-line key=value pairs. Running scons debug=1 sets ARGUMENTS['debug'] to the string '1'. The get method provides a default of '0' when the key is absent, so running scons without arguments builds in release mode.

Depending on the value, the code appends debug flags (-g for debug symbols so GDB can show source lines, -O0 for no optimization so variable values are not optimized away, and -DDEBUG to define a preprocessor macro your code can check with #ifdef DEBUG) or release flags (-O2 for optimization and -DNDEBUG to disable assert() statements).

The variant variable determines the output directory for build artifacts. env.Append() adds to an existing variable without overwriting what is already there. If CCFLAGS already contains ['-Wall', '-std=c++17'], appending ['-g', '-O0', '-DDEBUG'] produces ['-Wall', '-std=c++17', '-g', '-O0', '-DDEBUG'].

Export('env')

Export makes the env variable available to SConscript files that call Import('env'). This is SCons' mechanism for sharing data between build files. It works through a global namespace managed by SCons, not through Python's module import system. You can export any Python object: environments, strings, lists, dictionaries, or Node objects. Multiple variables can be exported at once: Export('env', 'version', 'platform').

lib = SConscript('lib/SConscript',
                 variant_dir=variant + '/lib',
                 duplicate=0)

SConscript() reads and executes a subsidiary build file. The first argument is the path to the SConscript file relative to the SConstruct. The variant_dir parameter redirects all build output from lib/ into the variant directory (for example, build/release/lib). This keeps compiled object files and libraries out of your source tree. duplicate=0 tells SCons not to copy (or symlink) source files into the variant directory.

Without this flag, SCons creates copies of your source files inside build/release/lib so that the build tool sees sources and outputs in the same directory. This duplication is rarely necessary and can be confusing because you end up with two copies of every source file. Setting duplicate=0 tells SCons to reference the original source files in place. The return value of SConscript() is whatever the subsidiary file passes to Return(). In this case, it's the Node object representing the built static library.

SConscript('src/SConscript',
           variant_dir=variant + '/src',
           duplicate=0,
           exports={'mylib': lib})

This second SConscript call reads the application's build file. The exports parameter is different from the global Export() function. It passes the library Node (returned from the library SConscript) into the application SConscript under the name mylib.

This is a scoped export: only this specific SConscript call receives mylib. The application SConscript retrieves it with Import('mylib'). This is how the application build file knows about the library without hardcoding paths to .a files.

The Library SConscript

Import('env')

Import retrieves a variable from SCons' global export namespace. This pulls in the environment that the SConstruct file exported with Export('env'). After this line, env refers to the same Environment object created in SConstruct. Any modifications you make to env here will affect it everywhere. If you need local modifications, use env.Clone() first.

lib = env.StaticLibrary('myutils', [
    'mathutils.cpp',
    'stringutils.cpp',
])

env.StaticLibrary() is a builder that compiles the listed source files into object files and then archives them into a static library using ar.

The first argument is the library name. SCons automatically adds the platform-appropriate prefix and suffix: libmyutils.a on Linux/macOS, myutils.lib on Windows. You never need to hard-code these. The source file paths are relative to this SConscript file's directory (which is lib/).

SCons also automatically scans these .cpp files for #include directives to establish implicit dependencies on header files. If mathutils.cpp includes mathutils.h, that dependency is tracked without any action from you.

Return('lib')

Return sends the library Node back to the calling SConscript() function in SConstruct. The string 'lib' is the name of the local variable to return, not a file path. This is similar to a Python return statement, but it works across SCons' build file execution model. You can return multiple values: Return('lib', 'headers').

The Application SConscript

Import('env')
Import('mylib')

Two imports: the shared construction environment (from the global Export) and the library Node (from the scoped exports parameter of the SConscript() call in the SConstruct file). These are separate Import calls, but you can also write Import('env', 'mylib') on a single line.

app = env.Program(
    target='myapp',
    source=['main.cpp', 'app.cpp'],
    LIBS=[mylib, 'm'],
    LIBPATH=['#build/release/lib', '#build/debug/lib'],
)

env.Program() compiles source files and links them into an executable. target is the output executable name (SCons adds .exe on Windows automatically). source lists the C++ files to compile. The order of source files doesn't matter for the final result, but convention is to list main.cpp first.

LIBS specifies libraries to link against. Passing the mylib Node directly (instead of a string like 'myutils') is the correct approach because SCons then knows the exact file dependency and will rebuild the executable if the library changes.

The 'm' string links the system math library (-lm on the command line), needed because mathutils.cpp uses functions from <cmath>. LIBPATH tells the linker where to search for libraries, translated to -L flags. Both debug and release paths are listed so the correct one is found regardless of build type.

These keyword arguments (LIBS, LIBPATH) override the environment's values for this specific builder call only. They don't modify the shared env.

Return('app')

Returns the application Node to the caller. The SConstruct doesn't use this return value in the current example, but returning it is good practice because it allows future extensions. You might later add env.Install('/usr/local/bin', app) in the SConstruct, or create an env.Alias('run', app, './build/release/src/myapp') to define a scons run command.

Running the Build and Understanding the Output

With all files in place, run the build from the project root.

scons

SCons produces output like this (on Linux with GCC):

scons: Reading SConscript files ...
scons: done reading SConscript files.
scons: Building targets ...
g++ -o build/release/lib/mathutils.o -c -Wall -std=c++17 -O2 -DNDEBUG -Iinclude -Ilib lib/mathutils.cpp
g++ -o build/release/lib/stringutils.o -c -Wall -std=c++17 -O2 -DNDEBUG -Iinclude -Ilib lib/stringutils.cpp
ar rc build/release/lib/libmyutils.a build/release/lib/mathutils.o build/release/lib/stringutils.o
ranlib build/release/lib/libmyutils.a
g++ -o build/release/src/main.o -c -Wall -std=c++17 -O2 -DNDEBUG -Iinclude -Ilib src/main.cpp
g++ -o build/release/src/app.o -c -Wall -std=c++17 -O2 -DNDEBUG -Iinclude -Ilib src/app.cpp
g++ -o build/release/src/myapp build/release/src/main.o build/release/src/app.o -Lbuild/release/lib -Lbuild/debug/lib build/release/lib/libmyutils.a -lm
scons: done building targets.

The first two lines show SCons reading all SConstruct and SConscript files. During this phase, it constructs the complete dependency graph in memory. No compilation happens yet.

The "Building targets" section shows the actual commands executed. Each g++ call includes the -I flags derived from CPPPATH (note -Iinclude -Ilib), the flags from CCFLAGS (-Wall -std=c++17 -O2 -DNDEBUG), and the -c flag for compilation (producing an object file, not linking).

The ar rc command creates the static library archive, and ranlib generates the archive index so the linker can find symbols efficiently.

The final g++ line links everything together, with -L flags from LIBPATH pointing the linker to the library directories, the explicit library file path, and -lm for the system math library.

Run the resulting executable:

./build/release/src/myapp

The output is:

Application: SCons Demo
Version: 1.0.0
5! = 120
Circle area (r=3): 28.2743
HELLO SCONS

Each line corresponds to a function call in run_app(). The version and name come from config.h. The factorial and circle area come from mathutils. The uppercase string comes from stringutils. All libraries linked correctly and all header paths resolved.

Now build the debug version:

scons debug=1

This creates a parallel set of build artifacts under build/debug/. The release build artifacts under build/release/ remain untouched.

You can switch between debug and release builds without triggering a full recompile of the other variant. Each variant has its own .o files, .a library, and executable. The directory structure under build/debug/ mirrors build/release/.

What Happens During an Incremental Build

Understanding what SCons does on the second and subsequent builds helps you trust the system and diagnose unexpected rebuilds.

Run scons again after a successful build. The output is:

scons: Reading SConscript files ...
scons: done reading SConscript files.
scons: Building targets ...
scons: `.' is up to date.
scons: done building targets.

SCons still reads every SConscript file and constructs the full dependency graph. It then walks the graph and checks every node.

For each source file, it computes the content hash and compares it to the hash stored in .sconsign.dblite. For each target file, it checks whether the source hashes, compiler command, and flags match the values from the previous build. Everything matches, so nothing is rebuilt.

Now modify lib/mathutils.h by adding a new function declaration:

// Add this line to mathutils.h
int fibonacci(int n);

Run scons again. SCons recompiles mathutils.cpp (because it includes mathutils.h, which changed), recompiles app.cpp (because it also includes mathutils.h), re-archives the static library (because mathutils.o changed), and re-links the executable (because both the library and app.o changed).

It doesn't recompile stringutils.cpp (it doesn't include mathutils.h) or main.cpp (it only includes app.h, which didn't change).

This is the dependency graph at work. SCons knows the complete chain: mathutils.h changed, so every file that directly or transitively depends on it gets rebuilt. Files that don't depend on it are untouched. You didn't need to specify any of these dependencies manually.

Now add a comment to stringutils.cpp without changing any actual code:

// This is just a comment
#include "stringutils.h"

Run scons. SCons recompiles stringutils.cpp because its content hash changed (comments are part of the content).

But here's where SCons gets clever: after recompiling, it computes the hash of the new stringutils.o. If the compiler produced an identical object file (which it often does for comment-only changes because comments don't affect the compiled output), SCons doesn't re-archive the library or re-link the executable.

This "short-circuiting" behavior prevents unnecessary downstream rebuilds. Make can't do this because it only looks at timestamps, not content.

Cross-Compiling for QuRT (Qualcomm Real-Time OS)

One of SCons' strengths is that setting up cross-compilation does not require a separate toolchain file format (like CMake's toolchain files). You configure everything in Python, using the same Environment API you already know.

What is QuRT

QuRT is Qualcomm's proprietary real-time operating system that runs on the Hexagon DSP (Digital Signal Processor) found in Snapdragon processors. The Hexagon DSP is a separate processor core on the Snapdragon SoC (System on Chip), distinct from the ARM application cores that run Android or Linux.

While the ARM cores handle the user interface and general application logic, the Hexagon DSP handles computationally intensive, latency-sensitive tasks: audio processing, sensor fusion, camera image processing, and machine learning inference.

QuRT provides the threading, memory management, and interrupt handling layer on the Hexagon DSP. It's a microkernel RTOS with hard real-time guarantees: interrupt latencies are bounded and predictable, which is essential for applications like audio where a missed deadline produces an audible glitch. QuRT supports POSIX-like threading (with qurt_thread_create instead of pthread_create), mutexes, semaphores, signals, and memory-mapped I/O.

Building code for QuRT requires the Hexagon SDK, which includes the Hexagon compiler (hexagon-clang and hexagon-clang++), linker, assembler, archiver, and QuRT-specific system headers and libraries. The SDK also includes a simulator (hexagon-sim) that can run Hexagon binaries on your development machine for testing without physical hardware.

The Hexagon SDK Directory Structure

The Hexagon SDK follows a specific layout that you need to know to configure your build system. A typical installation looks like this:

$HEXAGON_SDK_ROOT/
    tools/
        HEXAGON_Tools/
            8.8.06/
                Tools/
                    bin/
                        hexagon-clang
                        hexagon-clang++
                        hexagon-ar
                        hexagon-ranlib
                        hexagon-as
                        hexagon-sim
                    include/
                    lib/
    rtos/
        qurt/
            computev66/
                include/
                    qurt.h
                    qurt_thread.h
                    qurt_mutex.h
                    posix/
                lib/
                    libqurt.a
            computev73/
                include/
                lib/
    libs/
        common/

The tools/HEXAGON_Tools directory contains the compiler toolchain. The version number (like 8.8.06) corresponds to the Hexagon Tools release. The rtos/qurt directory contains the QuRT kernel headers and prebuilt libraries, organized by architecture variant. computev66 targets the Hexagon V66 architecture (found in older Snapdragon chips), while computev73 targets the V73 (found in newer ones like Snapdragon 8 Gen 2). Each variant has its own include and lib directories because the kernel is compiled differently for each architecture version.

The Cross-Compilation SConstruct

The following SConstruct file configures a cross-compilation environment for QuRT. It assumes the Hexagon SDK is installed and the HEXAGON_SDK_ROOT environment variable points to it.

# SConstruct for QuRT / Hexagon cross-compilation
import os
import sys

hexagon_sdk = os.environ.get('HEXAGON_SDK_ROOT',
                              '/opt/hexagon/sdk')
if not os.path.isdir(hexagon_sdk):
    print('Error: HEXAGON_SDK_ROOT not set or directory does not exist')
    print('Set it with: export HEXAGON_SDK_ROOT=/path/to/hexagon/sdk')
    Exit(1)

hexagon_tools = os.path.join(hexagon_sdk, 'tools', 'HEXAGON_Tools')
hexagon_ver = os.environ.get('HEXAGON_TOOLS_VER', '8.8.06')
tool_base = os.path.join(hexagon_tools, hexagon_ver, 'Tools')
tool_bin = os.path.join(tool_base, 'bin')

hexagon_arch = ARGUMENTS.get('arch', 'v73')
qurt_root = os.path.join(hexagon_sdk, 'rtos', 'qurt')
qurt_variant = 'compute' + hexagon_arch
qurt_inc = os.path.join(qurt_root, qurt_variant, 'include')
qurt_lib = os.path.join(qurt_root, qurt_variant, 'lib')

env = Environment(
    CC=os.path.join(tool_bin, 'hexagon-clang'),
    CXX=os.path.join(tool_bin, 'hexagon-clang++'),
    AR=os.path.join(tool_bin, 'hexagon-ar'),
    RANLIB=os.path.join(tool_bin, 'hexagon-ranlib'),
    AS=os.path.join(tool_bin, 'hexagon-as'),
    LINK=os.path.join(tool_bin, 'hexagon-clang++'),
    CPPPATH=[
        '#include',
        '#lib',
        qurt_inc,
        os.path.join(qurt_inc, 'posix'),
    ],
    CCFLAGS=[
        '-m' + hexagon_arch,
        '-G0',
        '-Wall',
        '-O2',
        '-fPIC',
        '-DQURT',
        '-D__QURT',
    ],
    LINKFLAGS=[
        '-m' + hexagon_arch,
        '-G0',
        '-nostdlib',
    ],
    LIBPATH=[
        '#build/qurt/lib',
        qurt_lib,
    ],
    LIBS=[
        'qurt',
        'qcc',
        'timer',
    ],
    ENV={
        'PATH': tool_bin + ':' + os.environ.get('PATH', ''),
        'HEXAGON_SDK_ROOT': hexagon_sdk,
    },
)

env['CCCOMSTR'] = '  HEX-CC   $TARGET'
env['CXXCOMSTR'] = '  HEX-CXX  $TARGET'
env['LINKCOMSTR'] = '  HEX-LINK $TARGET'
env['ARCOMSTR'] = '  HEX-AR   $TARGET'

Export('env')

lib = SConscript('lib/SConscript',
                 variant_dir='build/qurt/lib',
                 duplicate=0)

SConscript('src/SConscript',
           variant_dir='build/qurt/src',
           duplicate=0,
           exports={'mylib': lib})

This file does a lot, so it's worth going through the key parts in detail.

The first block validates and constructs file paths to the Hexagon toolchain. HEXAGON_SDK_ROOT is the standard environment variable set when you install the Hexagon SDK. If it's not set, the build exits with a clear error message instead of failing later with a cryptic "compiler not found" error. The tool_bin variable points to the directory containing hexagon-clang, hexagon-clang++, hexagon-ar, and other cross-compilation tools.

The architecture is configurable through the command line with scons arch=v66 or scons arch=v73. The hexagon_arch variable defaults to v73 and feeds into both the compiler flags (-mv73) and the QuRT directory path (computev73). This makes it easy to target different Hexagon versions from the same build file.

The qurt_root, qurt_inc, and qurt_lib variables locate the QuRT headers and prebuilt libraries. The posix subdirectory inside the include path contains POSIX-compatible wrappers that let you use familiar function signatures (like pthread_mutex_init) that map to QuRT's native API underneath.

The Environment() call overrides every tool. CC, CXX, AR, RANLIB, AS, and LINK all point to the Hexagon cross-compiler tools instead of the host system's native compiler.

This is the fundamental mechanism for cross-compilation in SCons: you swap out the tools in the construction environment. The same SConscript files that work for native builds work for cross-builds because they only interact with the environment through the env variable, never by calling gcc directly.

The CCFLAGS array contains Hexagon-specific flags. -mv73 (assembled from -m + the architecture variable) targets the V73 architecture and tells the compiler to generate Hexagon V73 instructions.

-G0 disables the small data section. On the Hexagon DSP, the small data section uses a special register (GP) for faster access to small global variables, but disabling it with -G0 is standard practice for shared libraries and position-independent code where the GP register cannot be relied upon.

-fPIC generates position-independent code, required for shared objects on the DSP. The -DQURT and -D__QURT defines are preprocessor macros that QuRT headers and application code check with #ifdef to detect a QuRT build and enable RTOS-specific code paths.

The LINKFLAGS include -nostdlib because QuRT provides its own C runtime. The standard GNU C library (glibc) is built for Linux and would pull in Linux system calls that don't exist on the Hexagon DSP. QuRT provides its own versions of functions like malloc, printf, and memcpy that are implemented on top of the QuRT kernel.

The LIBS list specifies QuRT-specific libraries: qurt (the RTOS kernel interface, providing threading, mutexes, and memory management), qcc (Qualcomm C compiler runtime, providing low-level arithmetic helpers and compiler intrinsics), and timer (hardware timer access for profiling and delay functions).

The ENV dictionary controls what environment the child processes (compilers, linkers) see when SCons invokes them. The Hexagon tool binary directory is prepended to PATH so that tools can find each other (for example, hexagon-clang may internally invoke hexagon-as for assembly steps). HEXAGON_SDK_ROOT is passed through because some Hexagon tools reference it internally to locate standard headers and runtime libraries.

The CCCOMSTR, CXXCOMSTR, LINKCOMSTR, and ARCOMSTR variables customize the build output. Instead of printing the full compiler command line (which can be hundreds of characters long with all the flags and paths), SCons prints a short summary like HEX-CXX build/qurt/lib/mathutils.o. This makes it easy to see at a glance that you're using the cross-compiler, not the host compiler.

To see the full commands (useful for debugging), remove these four lines or run scons with verbose=1 and add the corresponding check in the SConstruct.

Everything after the environment setup is identical to the native build: Export, SConscript calls with variant directories, and the same library and application SConscript files.

The SConscript files don't know or care whether they're building for the host or for QuRT. They just use whatever environment they receive through Import('env'). This separation is a key design advantage. Your build logic (what files to compile, what libraries to create) stays in the SConscript files. Your toolchain configuration stays in the SConstruct.

To build for QuRT, set the SDK path and run SCons.

export HEXAGON_SDK_ROOT=/path/to/hexagon/sdk
scons

The output shows the Hexagon compiler being invoked instead of GCC.

  HEX-CXX  build/qurt/lib/mathutils.o
  HEX-CXX  build/qurt/lib/stringutils.o
  HEX-AR   build/qurt/lib/libmyutils.a
  HEX-CXX  build/qurt/src/main.o
  HEX-CXX  build/qurt/src/app.o
  HEX-LINK build/qurt/src/myapp

Each line confirms that the Hexagon tools are running, not the host tools. The resulting myapp binary is a Hexagon executable. You can't run it directly on your development machine (it contains Hexagon instructions, not x86 or ARM). To test it, use the Hexagon simulator: hexagon-sim build/qurt/src/myapp.

To target a different Hexagon architecture, pass the arch argument.

scons arch=v66

This changes the compiler flag to -mv66 and selects the computev66 QuRT headers and libraries. Everything else remains the same.

Writing QuRT-Specific Application Code

Real QuRT applications use the RTOS API for threading, synchronization, and hardware interaction. The following example replaces the generic main.cpp with a QuRT-specific version that creates threads and uses a mutex.

// src/main_qurt.cpp
#include "app.h"
#include <qurt.h>
#include <qurt_thread.h>
#include <qurt_mutex.h>
#include <stdio.h>

#define STACK_SIZE 4096

static qurt_mutex_t print_mutex;
static char worker_stack[STACK_SIZE];

void worker_thread(void *arg) {
    int id = (int)(long)arg;
    qurt_mutex_lock(&print_mutex);
    printf("Worker thread %d running on QuRT\n", id);
    run_app();
    qurt_mutex_unlock(&print_mutex);
    qurt_thread_exit(0);
}

int main() {
    qurt_thread_t thread_id;
    qurt_thread_attr_t attr;

    qurt_mutex_init(&print_mutex);

    qurt_thread_attr_init(&attr);
    qurt_thread_attr_set_name(&attr, "worker");
    qurt_thread_attr_set_stack_addr(&attr, worker_stack);
    qurt_thread_attr_set_stack_size(&attr, STACK_SIZE);
    qurt_thread_attr_set_priority(&attr, 100);

    qurt_thread_create(&thread_id, &attr,
                       worker_thread, (void *)1);

    int status;
    qurt_thread_join(thread_id, &status);

    qurt_mutex_destroy(&print_mutex);
    return 0;
}

This code demonstrates the core QuRT threading API.

• qurt_mutex_init initializes a mutex for synchronizing access to printf (which isn't thread-safe on QuRT without protection).

• qurt_thread_attr_init creates a thread attribute structure, and the subsequent calls configure the thread's name (visible in the debugger), stack memory (you provide the buffer, QuRT doesn't allocate it for you), stack size (4096 bytes is typical for lightweight threads), and priority (QuRT uses priority-based preemptive scheduling where lower numbers mean higher priority).

• qurt_thread_create spawns the thread, passing a function pointer and an argument.

• qurt_thread_join blocks until the thread completes, similar to pthread_join.

• qurt_mutex_destroy cleans up the mutex.

Several differences from POSIX threading matter for correctness. On QuRT, you must provide the stack memory yourself as a statically allocated buffer (or dynamically allocated via qurt_malloc). The RTOS doesn't have a general-purpose malloc-like stack allocator the way Linux does. Thread priorities are explicit and mandatory – there's no default priority. And qurt_thread_exit must be called at the end of every thread function: falling off the end of the function without calling it is undefined behavior on QuRT.

To build with this QuRT-specific main instead of the generic one, modify the src/SConscript to select the right file:

# src/SConscript (QuRT-aware version)
Import('env')
Import('mylib')

import os
is_qurt = 'DQURT' in ' '.join(env.get('CCFLAGS', []))

main_src = 'main_qurt.cpp' if is_qurt else 'main.cpp'

app = env.Program(
    target='myapp',
    source=[main_src, 'app.cpp'],
    LIBS=[mylib, 'm'],
    LIBPATH=['#build/qurt/lib', '#build/release/lib', '#build/debug/lib'],
)

Return('app')

This SConscript inspects the environment's CCFLAGS to determine whether the QuRT preprocessor define is present. If it is, the build uses main_qurt.cpp. If not, it uses the standard main.cpp.

This is a simple example of using Python logic in a build file to adapt to different targets, something that requires convoluted syntax in Make and a separate toolchain file in CMake.

Building Both Native and QuRT From One SConstruct

If you need both a native build (for running unit tests on your development machine) and a QuRT build (for deployment to the DSP), you can configure both in a single SConstruct.

# SConstruct (dual-target: native + QuRT)
import os
import sys

native_env = Environment(
    CPPPATH=['#include', '#lib'],
    CCFLAGS=['-Wall', '-std=c++17', '-O2'],
)

hexagon_sdk = os.environ.get('HEXAGON_SDK_ROOT', '')
build_qurt = os.path.isdir(hexagon_sdk)

if build_qurt:
    hexagon_tools = os.path.join(hexagon_sdk, 'tools', 'HEXAGON_Tools')
    hexagon_ver = os.environ.get('HEXAGON_TOOLS_VER', '8.8.06')
    tool_bin = os.path.join(hexagon_tools, hexagon_ver, 'Tools', 'bin')
    hexagon_arch = ARGUMENTS.get('arch', 'v73')
    qurt_root = os.path.join(hexagon_sdk, 'rtos', 'qurt')
    qurt_variant = 'compute' + hexagon_arch
    qurt_inc = os.path.join(qurt_root, qurt_variant, 'include')
    qurt_lib = os.path.join(qurt_root, qurt_variant, 'lib')

    qurt_env = Environment(
        CC=os.path.join(tool_bin, 'hexagon-clang'),
        CXX=os.path.join(tool_bin, 'hexagon-clang++'),
        AR=os.path.join(tool_bin, 'hexagon-ar'),
        RANLIB=os.path.join(tool_bin, 'hexagon-ranlib'),
        LINK=os.path.join(tool_bin, 'hexagon-clang++'),
        CPPPATH=['#include', '#lib', qurt_inc,
                 os.path.join(qurt_inc, 'posix')],
        CCFLAGS=['-m' + hexagon_arch, '-G0', '-Wall',
                 '-O2', '-fPIC', '-DQURT', '-D__QURT'],
        LINKFLAGS=['-m' + hexagon_arch, '-G0', '-nostdlib'],
        LIBPATH=[qurt_lib],
        LIBS=['qurt', 'qcc', 'timer'],
        ENV={'PATH': tool_bin + ':' + os.environ.get('PATH', ''),
             'HEXAGON_SDK_ROOT': hexagon_sdk},
    )
    qurt_env['CXXCOMSTR'] = '  HEX-CXX  $TARGET'
    qurt_env['LINKCOMSTR'] = '  HEX-LINK $TARGET'
    qurt_env['ARCOMSTR'] = '  HEX-AR   $TARGET'

native_lib = SConscript('lib/SConscript',
                        variant_dir='build/native/lib',
                        duplicate=0,
                        exports={'env': native_env})
SConscript('src/SConscript',
           variant_dir='build/native/src',
           duplicate=0,
           exports={'env': native_env, 'mylib': native_lib})

if build_qurt:
    qurt_lib_node = SConscript('lib/SConscript',
                               variant_dir='build/qurt/lib',
                               duplicate=0,
                               exports={'env': qurt_env})
    SConscript('src/SConscript',
               variant_dir='build/qurt/src',
               duplicate=0,
               exports={'env': qurt_env, 'mylib': qurt_lib_node})

Each SConscript call passes a different environment through the exports parameter. The SConscript files themselves remain completely unchanged from the single-target version. SCons executes both variants in a single invocation and correctly handles dependencies between them. The native build always runs. The QuRT build runs only when HEXAGON_SDK_ROOT points to a valid directory. This means developers who don't have the Hexagon SDK installed can still build and test the native version without errors.

This pattern shows why Python build files are powerful. Conditional logic, environment detection, path validation, and multi-target builds all use standard Python constructs. There's no special cross-compilation syntax to learn, no separate toolchain file format, and no need to run the build tool twice with different arguments.

How SCons Detects Dependencies and Decides What to Rebuild

SCons ships with built-in scanners for C/C++ (#include directives), Fortran (INCLUDE and USE statements), Java (import statements), D (import statements), and LaTeX (\include and \input commands).

When SCons compiles app.cpp, it reads the file, finds #include "config.h", #include "mathutils.h", and the other includes, resolves them against the CPPPATH search path, and automatically adds those headers to the dependency graph.

If you change mathutils.h, SCons knows to recompile app.cpp even though you didn't list that dependency anywhere. Make requires you to set this up manually or use a tool like gcc -MM to generate dependency files, and if you forget, your build produces incorrect results silently.

The default rebuild strategy uses content hashing. SCons computes an MD5 hash of every source file and stores it in a database file called .sconsign.dblite in the project root. On the next build, it recomputes hashes and compares. If the hash hasn't changed, the file isn't rebuilt.

This extends to the build outputs themselves: if recompiling a .cpp file produces an identical .o file (for example, because you only changed a comment), SCons won't re-link the final executable.

This "short-circuiting" behavior can save significant time on large projects where a header change triggers recompilation of many files but only a few actually produce different object code.

The .sconsign.dblite file stores more than just content hashes. It records the full build signature for each target: the content hashes of all source files, the compiler command line (including all flags), and the implicit dependencies discovered by scanners. If you change a compiler flag (for example, switching from -O2 to -O3), SCons detects that the build signature has changed and recompiles everything, even though no source files changed. Make can't do this because it only tracks file timestamps.

You can change the rebuild strategy with the Decider function:

Decider('content')            # Default: MD5 hash comparison
Decider('timestamp-newer')    # Make-like: rebuild if source is newer
Decider('timestamp-match')    # Rebuild if timestamp changed at all
Decider('content-timestamp')  # Hybrid: only hash if timestamp changed

'content' is the default and the most correct. It reads every source file on every build to compute hashes, which is thorough but adds I/O overhead.

'timestamp-newer' mimics Make's behavior: rebuild if the source file's modification time is newer than the target's. This is fast but misses cases where a file is restored from backup (older timestamp, different content).

'timestamp-match' rebuilds if the timestamp has changed in either direction, which handles the restore case.

'content-timestamp' is the best hybrid: it only reads file contents (to compute hashes) when the timestamp has changed, skipping the I/O for files that haven't been touched. On projects with thousands of source files, this can cut SCons' startup overhead noticeably.

You can also change the hash algorithm:

SetOption('hash_format', 'sha256')

This switches from MD5 to SHA-256. MD5 is not collision-resistant for adversarial inputs, but for build system purposes (detecting accidental changes to source files), it's perfectly adequate. SHA-256 is an option for environments with strict compliance requirements.

You can write a custom decider function for specialized rebuild logic:

def my_decider(dependency, target, prev_ni, repo_node=None):
    return dependency.get_timestamp() != prev_ni.timestamp

env.Decider(my_decider)

The custom decider receives the dependency node, the target node, and the "node info" from the previous build. It returns True to trigger a rebuild or False to skip. This is useful for exotic scenarios like triggering rebuilds based on external state (database versions, API schemas) that aren't captured by file content.

Writing a Custom Scanner

If your project uses a file format that includes other files (similar to C's #include), you can write a custom scanner so SCons tracks those dependencies automatically.

Consider a custom configuration file format where @import filename.cfg includes another file:

import re

import_re = re.compile(r'^@import\s+(\S+)', re.MULTILINE)

def cfg_scan(node, env, path):
    contents = node.get_text_contents()
    includes = import_re.findall(contents)
    return [env.File(f) for f in includes]

cfg_scanner = Scanner(
    function=cfg_scan,
    skeys=['.cfg'],
    recursive=True,
)

env.Append(SCANNERS=cfg_scanner)

The cfg_scan function reads the file contents, finds all @import directives using a regular expression, and returns a list of File nodes representing the imported files.

The skeys parameter tells SCons to apply this scanner to files with the .cfg extension.

The recursive=True parameter tells SCons to scan the imported files as well, so transitive dependencies are tracked. After appending the scanner to the environment, any builder that processes .cfg files will automatically detect and track @import dependencies.

The Shared Build Cache

SCons supports CacheDir, a shared build cache that stores compiled artifacts indexed by their build signature (a hash incorporating the source content, compiler command, and flags). If another developer on your team has already built an identical configuration, you get the cached result instead of recompiling.

CacheDir('/shared/network/build_cache')

This line is all you need to enable caching. When SCons builds a file, it stores a copy in the cache directory, named by the build signature hash. On subsequent builds (by you or anyone else pointing to the same cache), if the build signature matches, the cached file is copied into the build directory instead of running the compiler. This works like ccache but applies to any build artifact, not just compiled objects. Libraries, executables, generated code, and any other builder output can be cached.

The build signature is comprehensive. It incorporates the content hashes of all source files, the full compiler command line (including flags), and the tool version. Different compiler flags produce different cache entries, so debug and release builds don't interfere with each other. If two developers use the same compiler version and the same flags on the same source code, they share cache hits.

Several command-line flags control cache behavior:

scons --cache-show       # Show what command would have run for cached targets
scons --cache-disable    # Ignore cache for this run
scons --cache-readonly   # Read from cache but do not write new entries
scons --cache-force      # Update cache even if target is up to date

--cache-show is useful for debugging. When a target is retrieved from cache, SCons normally prints nothing (or a short message). With --cache-show, it prints the command that would have been executed, so you can verify the cached entry matches your expectations.

--cache-readonly is useful for CI systems that should consume cache entries built by developers but not pollute the cache with CI-specific configurations.

Working with Shared Libraries

Building shared libraries (.so on Linux, .dylib on macOS, .dll on Windows) requires different compiler and linker flags than static libraries. SCons handles most of this automatically through the SharedLibrary builder.

env = Environment()
shared_lib = env.SharedLibrary('myutils', [
    'mathutils.cpp',
    'stringutils.cpp',
])

On Linux, this produces libmyutils.so. SCons automatically adds -fPIC to the compilation flags for source files that go into a shared library (it uses SharedObject internally instead of StaticObject). On Windows, it produces myutils.dll plus myutils.lib (the import library).

For versioned shared libraries on POSIX systems, use the SHLIBVERSION parameter:

shared_lib = env.SharedLibrary('myutils', sources,
                                SHLIBVERSION='1.2.3')

This produces three files: libmyutils.so.1.2.3 (the actual library), libmyutils.so.1 (the soname symlink used at runtime), and libmyutils.so (the development symlink used at link time). SCons creates all three and manages the symlinks.

You can't mix StaticObject and SharedObject files. If you compile a file with env.Object() (which creates a static object without -fPIC), you can't put it into a SharedLibrary. SCons enforces this and produces an error if you try. If you need the same source file compiled both ways, call each builder separately.

static_objs = [env.StaticObject(f) for f in sources]
shared_objs = [env.SharedObject(f) for f in sources]

static_lib = env.StaticLibrary('myutils', static_objs)
shared_lib = env.SharedLibrary('myutils', shared_objs)

Each source file gets compiled twice: once without -fPIC for the static library, once with -fPIC for the shared library. The resulting object files have different names (SCons appends different suffixes) so they don't collide.

Adding Command-Line Options with AddOption

The ARGUMENTS dictionary works for simple key=value pairs, but for more complex command-line interfaces (flags like --prefix, --enable-feature, or --with-library), use AddOption.

AddOption('--prefix',
    dest='prefix',
    type='string',
    nargs=1,
    action='store',
    metavar='DIR',
    default='/usr/local',
    help='Installation prefix (default: /usr/local)')

AddOption('--enable-tests',
    dest='enable_tests',
    action='store_true',
    default=False,
    help='Build and run unit tests')

prefix = GetOption('prefix')
build_tests = GetOption('enable_tests')

env = Environment(PREFIX=prefix)

app = env.Program('myapp', sources)
env.Install(os.path.join(prefix, 'bin'), app)

if build_tests:
    test_env = env.Clone()
    test_env.Program('test_runner', test_sources)

AddOption uses Python's optparse module under the hood, so the parameter names (dest, type, action, metavar, default, help) follow the same conventions. GetOption retrieves the parsed value. These options appear in scons --help output alongside SCons' built-in options, giving users a clean command-line interface.

Running scons --prefix=/opt/myapp --enable-tests installs to /opt/myapp/bin and builds the test suite. Running scons --help shows all available options with their descriptions.

The advantage over ARGUMENTS is discoverability. ARGUMENTS requires the user to know which key=value pairs your build file accepts. AddOption makes them visible in --help output and provides type checking and default values.

Configure Checks for Portability

SCons includes an autoconf-like system for probing the build environment. You can check for headers, libraries, functions, and type sizes before building.

env = Environment()
conf = Configure(env)

if not conf.CheckCHeader('math.h'):
    print('Error: math.h not found')
    Exit(1)

if not conf.CheckCXXHeader('iostream'):
    print('Error: C++ standard library headers not found')
    Exit(1)

if not conf.CheckLib('pthread', language='C'):
    print('Error: pthread library not found')
    Exit(1)

if conf.CheckFunc('posix_memalign'):
    conf.env.Append(CPPDEFINES=['HAVE_POSIX_MEMALIGN'])

if conf.CheckFunc('aligned_alloc'):
    conf.env.Append(CPPDEFINES=['HAVE_ALIGNED_ALLOC'])

if conf.CheckTypeSize('long') == 8:
    conf.env.Append(CPPDEFINES=['HAVE_64BIT_LONG'])

env = conf.Finish()

Configure() creates a configuration context that compiles and links small test programs behind the scenes to determine whether headers exist, libraries can be linked, and functions are available. Each Check method writes a tiny C or C++ program, compiles it with the current environment settings, and returns True or False based on whether compilation and linking succeeded. conf.Finish() returns the (possibly modified) environment and cleans up.

CheckCHeader verifies that a C header can be included. CheckCXXHeader does the same for C++ headers. CheckLib verifies that a library can be linked; the language parameter determines whether to use the C or C++ compiler for the test. CheckFunc checks whether a function is available (it creates a test program that references the function and attempts to link it). CheckTypeSize compiles a program that uses sizeof() and returns the size as an integer.

The CPPDEFINES added by the checks (like HAVE_POSIX_MEMALIGN) follow the standard autoconf convention. Your source code can then use these defines:

#ifdef HAVE_POSIX_MEMALIGN
    posix_memalign(&ptr, alignment, size);
#elif defined(HAVE_ALIGNED_ALLOC)
    ptr = aligned_alloc(alignment, size);
#else
    ptr = malloc(size);
#endif

This pattern makes your code portable across systems that may or may not have specific functions, without hardcoding platform assumptions.

Configure checks are cached in .sconf_temp/ and .sconsign.dblite. On subsequent builds, if the environment hasn't changed, SCons skips the checks and uses the cached results. You can force rechecking with scons --config=force.

Custom Builders for Non-Standard File Types

You can define builders for file types that SCons doesn't know about. A builder wraps a shell command (or a Python function) with source/target suffix handling.

Builder with an External Command

protobuf = Builder(
    action='protoc --cpp_out=\(TARGET.dir \)SOURCE',
    suffix='.pb.cc',
    src_suffix='.proto',
)
env.Append(BUILDERS={'Protobuf': protobuf})
env.Protobuf('messages.proto')

This creates a Protobuf builder that runs protoc on .proto files and produces .pb.cc files. The action string uses SCons variable substitution: \(SOURCE expands to the input file path and \)TARGET.dir expands to the directory of the output file. The suffix and src_suffix parameters let SCons infer target and source file names automatically. After appending the builder to the environment, you call env.Protobuf('messages.proto') and SCons produces messages.pb.cc.

The critical detail: use env.Append(BUILDERS={...}) to add your builder. If you set BUILDERS directly in the Environment() constructor, like Environment(BUILDERS={'Protobuf': protobuf}), you overwrite the entire builder dictionary and lose all the default builders (Program, Library, Object, and so on).

Builder with a Python Function

def generate_version_header(target, source, env):
    version = env.get('APP_VERSION', '0.0.0')
    with open(str(target[0]), 'w') as f:
        f.write('#ifndef VERSION_H\n')
        f.write('#define VERSION_H\n')
        f.write('#define VERSION "%s"\n' % version)
        f.write('#endif\n')
    return 0

version_builder = Builder(action=generate_version_header,
                           suffix='.h',
                           src_suffix='.ver')
env.Append(BUILDERS={'VersionHeader': version_builder})
env.VersionHeader('version.h', 'version.ver',
                  APP_VERSION='2.1.0')

The Python function receives three arguments: target (a list of target Node objects), source (a list of source Node objects), and env (the construction environment). Node objects must be converted to strings with str() to get the file path. The function must return 0 for success or a non-zero value for failure.

Using a Python function instead of a shell command is useful when the build step involves logic that is awkward to express in shell (like reading a file, parsing JSON, or generating code with complex structure).

The Command Builder for One-Off Rules

For build rules that are used only once, the Command builder avoids the overhead of defining a named builder.

env.Command('config.h', 'config.h.in',
            "sed 's/@VERSION@/1.0.0/g' < \(SOURCE > \)TARGET")

This runs sed to substitute a version placeholder in config.h.in and writes the result to config.h. The Command builder is the SCons equivalent of a Make rule with a custom recipe. It takes the target, source, and action as arguments. The action can be a shell command string, a Python function, or a list of either.

Aliases, Default Targets, and Install Rules

env.Alias() creates named targets you can invoke from the command line. Default() specifies what gets built when you run scons with no arguments.

app = env.Program('myapp', sources)
tests = env.Program('test_runner', test_sources)

Default(app)
env.Alias('test', tests)
env.Alias('all', [app, tests])

Running scons builds only myapp because it's the default target. Running scons test builds the test executable. Running scons all builds everything. Without the Default call, SCons builds everything in the current directory and below, which includes both the application and the tests.

Install targets copy built files to a destination directory.

env.Install('/usr/local/bin', app)
env.Install('/usr/local/lib', shared_lib)
env.InstallAs('/usr/local/bin/my-application', app)

env.Alias('install', '/usr/local/bin')
env.Alias('install', '/usr/local/lib')

env.Install() copies the specified file to the destination directory. env.InstallAs() copies it with a different name. Install targets aren't built by default because they write outside the project tree. You must invoke them explicitly with scons install (which works because the Alias connects the name "install" to the install directories).

You can combine Alias with a command action to create a "run" target.

env.Alias('run', app, './build/release/src/myapp')

Running scons run builds the application (if needed) and then executes it. The third argument to Alias is an action that runs after the target is built.

Platform-Specific Configuration

Because SConstruct files are Python, platform-specific configuration uses standard Python constructs.

import sys
import os

env = Environment(
    CPPPATH=['#include'],
    CCFLAGS=['-Wall'],
)

if sys.platform == 'win32':
    env.Append(LIBS=['ws2_32', 'advapi32'])
    env.Append(CPPDEFINES=['_WIN32', 'NOMINMAX'])
elif sys.platform == 'darwin':
    env.Append(FRAMEWORKS=['CoreFoundation', 'Security'])
    env.Append(CCFLAGS=['-mmacosx-version-min=10.15'])
elif sys.platform.startswith('linux'):
    env.Append(LIBS=['pthread', 'dl', 'rt'])
    env.Append(CPPDEFINES=['_GNU_SOURCE'])

sys.platform returns 'win32' on Windows, 'darwin' on macOS, and 'linux' on Linux. The FRAMEWORKS variable is macOS-specific and translates to -framework CoreFoundation -framework Security on the linker command line. On Linux, -lrt links the POSIX realtime library (for clock_gettime on older glibc versions), and -ldl links the dynamic loading library (for dlopen).

For more granular detection, use platform.machine() to check the CPU architecture.

import platform

if platform.machine() == 'aarch64':
    env.Append(CCFLAGS=['-march=armv8-a'])
elif platform.machine() == 'x86_64':
    env.Append(CCFLAGS=['-march=x86-64-v2'])

You can also use env['PLATFORM'] which SCons sets to 'posix', 'win32', or 'darwin'.

For integrating with system libraries that provide pkg-config metadata, use ParseConfig.

env.ParseConfig('pkg-config --cflags --libs libpng')
env.ParseConfig('pkg-config --cflags --libs zlib')

ParseConfig runs the specified command, captures its output, and parses the flags into the appropriate construction variables. -I flags go into CPPPATH, -L flags go into LIBPATH, -l flags go into LIBS, and remaining flags go into CCFLAGS. This is the SCons equivalent of $(pkg-config --cflags --libs libpng) in a Makefile.

Customizing Build Output

By default, SCons prints the full compiler command line for every file it processes. On projects with long include paths and many flags, this produces walls of text that obscure the build progress. You can customize the output with COMSTR variables:

env = Environment()

env['CCCOMSTR'] = '  CC    $TARGET'
env['CXXCOMSTR'] = '  CXX   $TARGET'
env['LINKCOMSTR'] = '  LINK  $TARGET'
env['ARCOMSTR'] = '  AR    $TARGET'
env['SHCCCOMSTR'] = '  CC    $TARGET (shared)'
env['SHCXXCOMSTR'] = '  CXX   $TARGET (shared)'
env['SHLINKCOMSTR'] = '  LINK  $TARGET (shared)'
env['RANLIBCOMSTR'] = '  INDEX $TARGET'
env['INSTALLSTR'] = '  INST  $TARGET'

With these settings, the build output looks clean and scannable. Each line shows the action type and the target file. The $TARGET variable in the string is expanded by SCons at runtime.

To support both quiet and verbose modes, check a command-line argument.

if ARGUMENTS.get('verbose', '0') != '1':
    env['CCCOMSTR'] = '  CC    $TARGET'
    env['CXXCOMSTR'] = '  CXX   $TARGET'
    env['LINKCOMSTR'] = '  LINK  $TARGET'
    env['ARCOMSTR'] = '  AR    $TARGET'

Running scons shows the short output. Running scons verbose=1 shows the full command lines. This pattern is common in SCons projects and mimics the V=1 convention used by the Linux kernel's build system.

How to Debug SCons Build Files

When a build doesn't do what you expect, SCons provides several debugging tools.

Print Variables

Because SConstruct files are Python, you can print anything.

env = Environment(CCFLAGS=['-Wall', '-O2'])
print('CCFLAGS:', env['CCFLAGS'])
print('CC:', env['CC'])
print('CPPPATH:', env.get('CPPPATH', []))

This prints the current values of construction variables. Use this to verify that your flags are set correctly, especially after Append, Prepend, or Clone calls.

The --debug flag

SCons has a --debug option with several modes.

scons --debug=explain

This tells SCons to print the reason for every rebuild. Instead of silently recompiling a file, it prints something like scons: rebuilding 'build/release/lib/mathutils.o' because 'lib/mathutils.h' changed. This is invaluable for understanding unexpected rebuilds.

scons --debug=tree

This prints the full dependency tree for every target, showing which files depend on which other files. The output can be large, so combine it with a specific target: scons --debug=tree build/release/src/myapp.

scons --debug=includes

This prints the include files found by the C/C++ scanner for each source file. Useful for diagnosing "header not found" errors or unexpected include paths.

scons --debug=presub

This prints the un-substituted command line (with \(CC, \)CCFLAGS, and so on still as variable names) before SCons expands them. Helps you understand which variables contribute to the final command.

The --dry-run flag

scons -n shows what SCons would do without actually doing it. Every command that would be executed is printed, but no files are created or modified. This is a safe way to verify your build logic before running it.

The Dump method

env.Dump() returns a formatted string of every construction variable and its value. It produces a lot of output, so pipe it to a file or search for specific variables.

print(env.Dump())

This is the nuclear option for debugging: it shows everything SCons knows about the environment.

The SCons Command-Line Reference

SCons accepts many command-line options. The ones you will use most frequently are listed here.

• scons builds the default targets (or everything if no Default() is set).

• scons -j N runs up to N build commands in parallel. Set N to the number of CPU cores on your machine for fastest builds. You can also set this in the SConstruct with SetOption('num_jobs', 4).

• scons -c cleans (removes) all built targets. This is the equivalent of make clean but doesn't require you to write a clean rule. SCons knows exactly which files it created and removes only those.

• scons -n is a dry run. Shows what would be built without building anything.

• scons -Q suppresses SCons' status messages ("Reading SConscript files", "Building targets", etc.) and shows only the build commands. Useful for piping build output to other tools.

• scons -s is silent mode. Suppresses both status messages and build commands. Only errors are printed.

• scons --debug=explain explains why each target is being rebuilt.

• scons --debug=tree prints the dependency tree.

• scons --config=force forces re-running of all Configure checks, ignoring cached results.

• scons target_name builds only the specified target and its dependencies. You can specify multiple targets: scons myapp test_runner.

• scons key=value passes a key-value pair accessible through ARGUMENTS.get('key') in the SConstruct.

• scons --help shows SCons' built-in options plus any options added with AddOption in the SConstruct.

Common Mistakes and How to Avoid Them

Overwriting default builders: Passing BUILDERS as a keyword argument to Environment() replaces the entire builder dictionary. You lose Program, Library, Object, and everything else. Always add custom builders with env.Append(BUILDERS={'Name': builder}).

Assuming shell environment variables are available: SCons deliberately doesn't import your shell environment. If your build fails because a tool isn't found, you probably need to pass PATH through explicitly.

The safest approach for finding the compiler is env['ENV']['PATH'] = os.environ['PATH']. Importing the entire environment with ENV=os.environ.copy() works but reduces build reproducibility because your build now depends on every variable in your shell.

Modifying a shared environment in a SConscript file: If the SConstruct exports one environment and multiple SConscript files import it, any Append or modification in one SConscript affects all of them because they all hold a reference to the same Python object. Clone the environment first with local_env = env.Clone() and modify the clone. The clone is a deep copy that can be modified independently.

Forgetting Return() in SConscript: If your SConstruct calls lib = SConscript('lib/SConscript') and the SConscript file has no Return() statement, lib is None. You'll get a confusing error later when you try to link against it, typically something like TypeError: expected a string or list of strings when None is passed as a library.

Confusing variant_dir with source paths: When you use variant_dir, the source file paths in your SConscript are still relative to the SConscript's original location, not the variant directory.

SCons handles the mapping internally. Don't use paths into the build directory in your SConscript files. Writing Object('build/release/lib/mathutils.cpp') is wrong, while writing Object('mathutils.cpp') inside lib/SConscript is correct.

Forgetting to add .sconsign.dblite to .gitignore: SCons stores its dependency database in this file. It should never be committed to version control because it contains absolute paths and machine-specific data.

Add .sconsign.dblite, the build/ directory, and the .sconf_temp/ directory (created by Configure checks) to your .gitignore.

# .gitignore
.sconsign.dblite
.sconf_temp/
build/

This .gitignore file has three entries.

• .sconsign.dblite is the dependency database.

• .sconf_temp/ is the directory where Configure check test programs are compiled.

• build/ is the variant directory containing all compiled artifacts.

Expecting touch to trigger a rebuild: SCons uses content hashing by default. Running touch on a source file changes its modification time but not its content, so the hash is identical and SCons doesn't rebuild. If you need Make-like timestamp behavior, call Decider('timestamp-newer') in your SConstruct.

Using string file names instead of Nodes: Passing raw strings with platform-specific extensions makes your build files non-portable.

# Fragile: hardcodes the .o extension
Program('myapp', ['main.o', 'utils.o'])

# Portable: let SCons handle extensions
main_obj = env.Object('main.cpp')
utils_obj = env.Object('utils.cpp')
env.Program('myapp', [main_obj, utils_obj])

The first version breaks on Windows where object files use the .obj extension. The second version works everywhere because the Node objects carry platform-specific metadata.

Getting the target/source argument order wrong: Builder methods take the target first, then the source. Program('output_name', 'source.c') is correct. Program('source.c', 'output_name') compiles output_name (which doesn't exist) and tries to create source.c as the executable. The convention mimics assignment: target = source.

Expecting Install targets to build by default: env.Install('/usr/local/bin', app) creates an install target, but SCons does not build it unless you explicitly request it. Targets outside the project directory tree are never default targets. Use env.Alias('install', '/usr/local/bin') and run scons install to trigger the installation.

Using Glob without understanding it returns Nodes: Glob('*.cpp') returns a list of Node objects, not strings. You can concatenate them with other Node lists using +, pass them to builders, and use them in most places that accept source lists. You can't call string methods on them directly. Use [str(n) for n in Glob('*.cpp')] if you need strings, but prefer working with Nodes whenever possible.

Summary

SCons replaces Make with a build system where every configuration file is a Python script.

The Environment object holds your compiler, flags, and paths. Builders like Program, StaticLibrary, and SharedLibrary know how to produce specific output types. SConscript files organize multi-directory projects, and variant_dir keeps build artifacts separate from source code. Content hashing eliminates unnecessary rebuilds, and automatic header scanning removes the need to manually specify implicit dependencies.

Cross-compilation to targets like QuRT requires nothing more than pointing the environment's tool variables (CC, CXX, LINK) at the cross-compiler and adding the target's include paths and libraries. The same SConscript files work for both native and cross-compiled builds because they operate on whatever environment they receive through Import.

QuRT-specific features (threading, mutexes, hardware timers) are accessed through standard C function calls, and the build system's only responsibility is making sure the right compiler, headers, and libraries are in place.

The Configure subsystem replaces autoconf for probing the build environment. Custom builders extend SCons to handle file types it does not know about (protocol buffers, shaders, firmware images).

Aliases and install rules give users a clean command-line interface (scons, scons test, scons install). And the --debug=explain flag tells you exactly why any file is being rebuilt, eliminating the guesswork that plagues Make-based builds.

SCons isn't the fastest build tool for very large codebases, and its ecosystem is smaller than CMake's. But for projects where build file clarity, correctness, cross-compilation flexibility, and the ability to express complex logic in a real programming language matter more than raw speed, it's a strong choice.

The Python foundation means you already know the language, and the content-based rebuild strategy means you can trust that what gets built actually needs to be built.

The operating system orchestrating that work on the DSP is QuRT (Qualcomm Real-Time Operating System), a POSIX-like, priority-based, preemptive RTOS purpose-built for Qualcomm's Hexagon Digital Signal Processor.

This article is a practical guide to Qualcomm's Real-Time Operating System. It covers QuRT from the ground up: architecture, thread creation, synchronization primitives, memory management, interrupt handling, timers, inter-processor communication through FastRPC, and a complete sensor fusion pipeline. Every concept includes working code and an explanation of what's happening under the hood.

Table of Contents

• Why QuRT Matters

• Setting Up Your Development Environment

• The QuRT Programming Model

• Creating Your First QuRT Thread

• How Thread Creation Works Internally

• Working with Multiple Threads

• Synchronization Primitives

• Memory Management

• Timers and Timing

• Interrupt Handling

• Pipes and Message Queues

• QuRT and FastRPC

• Building a Sensor Fusion Pipeline

• Debugging QuRT Applications

• Common Pitfalls

• Performance Optimization

• API Quick Reference

• Next Steps

Why QuRT Matters

Consider what happens during a phone call. The device is simultaneously running noise cancellation on the microphone audio, executing a neural network for wake word detection, reading accelerometer data 400 times per second, and managing Bluetooth audio streaming.

None of this runs on the main ARM CPU. It all happens on Qualcomm's Hexagon DSP, and the operating system coordinating it is QuRT.

QuRT (Qualcomm Real-Time Operating System) is a POSIX-like, priority-based, preemptive RTOS that runs on Qualcomm's Hexagon Digital Signal Processor. Where Linux is a general-purpose operating system designed for flexibility, QuRT is a precision instrument designed for deterministic, microsecond-level scheduling.

Where QuRT Fits in the System

This diagram shows the two-processor architecture inside a Qualcomm SoC. The ARM CPU on the left runs Android or Linux and handles general application logic. The Hexagon DSP on the right runs QuRT and handles latency-sensitive workloads: audio processing, sensor fusion, ML inference, and compute offload.

The two processors communicate through a framework called FastRPC. You write code for the DSP side using the Hexagon SDK, and QuRT is the OS that executes your code on the Hexagon processor.

Setting Up Your Development Environment

Before writing any QuRT code, you need the toolchain and either a simulator or physical hardware.

Prerequisites

You will need the Hexagon SDK (version 3.5+ or 4.x), which is Qualcomm's official SDK and includes the Hexagon Tools compiler toolchain.

For running your code, you can use either a Qualcomm development board (such as the Robotics RB5 or an SM8250 HDK) or the SDK's built-in simulator. A Linux host machine running Ubuntu 18.04 or 20.04 works best for development.

Installing the Hexagon SDK

# Download the Hexagon SDK from Qualcomm's developer portal
# https://developer.qualcomm.com/software/hexagon-dsp-sdk

# Extract and run the installer
chmod +x qualcomm_hexagon_sdk_4_x_x_x.bin
./qualcomm_hexagon_sdk_4_x_x_x.bin

# Set up environment variables
export HEXAGON_SDK_ROOT=~/Qualcomm/Hexagon_SDK/4.x.x.x
export HEXAGON_TOOLS_ROOT=~/Qualcomm/Hexagon_SDK/4.x.x.x/tools
source $HEXAGON_SDK_ROOT/setup_sdk_env.source

This installs the SDK to your home directory and sets up the environment variables that the build system and simulator need. The setup_sdk_env.source script configures your shell with paths to the compiler, simulator, and libraries.

Verifying Your Setup

# Check the Hexagon compiler
hexagon-clang --version

# You should see something like:
# Qualcomm Hexagon Clang version 8.x.xx

# Run the QuRT simulator to make sure it works
$HEXAGON_SDK_ROOT/tools/HEXAGON_Tools/8.x.xx/Tools/bin/hexagon-sim \
    --simulated_returnval --cosim_file \
    $HEXAGON_SDK_ROOT/libs/common/qurt/computev66/sdksim_bin/osam.cfg \
    -- $HEXAGON_SDK_ROOT/libs/common/qurt/computev66/sdksim_bin/bootimg.pbn

The first command confirms that the Hexagon Clang compiler is installed and accessible. The second command launches the QuRT simulator, which is analogous to an Android emulator: it lets you test QuRT programs without physical hardware. Timing won't match real hardware, but the simulator is valuable for validating correctness during development.

Project Structure

The Hexagon SDK uses SCons as its underlying build system. Projects live inside the SDK tree and are configured through .min files, which are declarative build descriptors that the SDK's SCons infrastructure parses.

A minimal project looks like this:

$HEXAGON_SDK_ROOT/examples/my_qurt_project/
├── src/
│   └── main.c              # Your QuRT application code
├── inc/
│   └── my_module.h         # Header files
├── hexagon.min              # SCons build config for Hexagon DSP side
└── android.min              # SCons build config for ARM side (if using FastRPC)

The hexagon.min file configures the DSP-side build, while android.min handles the ARM side when using FastRPC for cross-processor communication. Both are read by the SDK's top-level SConstruct file, which lives at $HEXAGON_SDK_ROOT/SConstruct. You don't need a separate Makefile or SConscript for projects inside the SDK tree.

Build Configuration with SCons

A minimal hexagon.min build file looks like this:

# hexagon.min - SCons build descriptor for the DSP side

BUILD_LIBS = libmy_qurt_app

# Source files
libmy_qurt_app_C_SRCS = src/main.c

# QuRT OS library
libmy_qurt_app_LIBS = atomic rpcmem

# Compiler flags
libmy_qurt_app_HEXAGON_CFLAGS = -O2 -Wall

# Link against QuRT
libmy_qurt_app_DLLS = libmy_qurt_app_skel

The .min file format is specific to the Hexagon SDK's SCons build system. BUILD_LIBS names the library target. C_SRCS lists source files. LIBS specifies libraries to link against. HEXAGON_CFLAGS sets compiler flags. DLLS defines the shared library output name, where the _skel suffix is a FastRPC convention for DSP-side implementations.

Under the hood, the SDK's SConstruct walks the project tree, reads each .min file, and translates its declarations into SCons build targets. The V (variant) parameter you pass at build time selects the target architecture, build type, and toolchain version. For example, V=hexagon_Release_dynamic_toolv84_v66 means: build for Hexagon, release mode, dynamic linking, using the v84 toolchain targeting the v66 DSP architecture.

For projects that need more control than the .min format provides, you can write a standalone SConscript file:

# SConscript - Standalone SCons build for a QuRT project

Import('env')

env = env.Clone()

# Add include paths
env.Append(CPPPATH = ['inc'])

# Compiler flags
env.Append(CCFLAGS = ['-O2', '-Wall'])

# Build the shared library
sources = ['src/main.c']
libs = ['atomic', 'rpcmem']

env.SharedLibrary(
    target = 'libmy_qurt_app_skel',
    source = sources,
    LIBS = libs
)

The SConscript approach gives you full access to SCons features: conditional compilation, custom build steps, dependency scanning, and variant builds. The Import('env') call pulls in the build environment configured by the SDK's top-level SConstruct, which already knows about Hexagon compiler paths, QuRT headers, and system libraries. env.Clone() creates a copy so your modifications do not affect other projects in the tree.

The QuRT Programming Model

The core mental model for QuRT programming is straightforward:

QuRT is a priority-based preemptive RTOS. That means everything runs in a thread (there is no bare-metal main loop). Higher priority threads always preempt lower priority ones, immediately and without negotiation. Threads at the same priority level are round-robin scheduled.

The scheduler is tick-less, meaning it doesn't wake up periodically. It only runs when something changes, such as a thread blocking, a signal being set, or a higher-priority thread becoming ready.

Priority Levels (0-255, lower number = higher priority)

 000  ┃ ████ Interrupt handlers (do not touch this)
 001  ┃ ████ Critical system tasks
 ...  ┃
 064  ┃ ████ Your high-priority audio processing
 ...  ┃
 128  ┃ ████ Your medium-priority sensor fusion
 ...  ┃
 192  ┃ ████ Your low-priority logging/reporting
 ...  ┃
 255  ┃ ████ Idle thread (QuRT's built-in background)

This priority map shows how QuRT's 256 priority levels are typically allocated. Priority 0 is the highest priority and 255 is the lowest. This is the opposite of FreeRTOS, where higher numbers mean higher priority.

Interrupt handlers occupy the top priority levels, system tasks sit just below, and user threads occupy the middle range. The idle thread at priority 255 runs only when nothing else is ready.

Creating Your First QuRT Thread

The simplest QuRT program creates a single thread that prints a message and exits.

/* main.c - First QuRT program */

#include <stdio.h>
#include <stdlib.h>
#include <qurt.h>

#define STACK_SIZE 4096

/* Thread stack must be 8-byte aligned */
static char thread_stack[STACK_SIZE] __attribute__((aligned(8)));

void my_thread_func(void *arg)
{
    int thread_id = (int)(uintptr_t)arg;

    printf("Hello from QuRT thread %d!\n", thread_id);
    printf("My thread ID: %lu\n", qurt_thread_get_id());

    /* Thread must explicitly exit */
    qurt_thread_exit(QURT_EOK);
}

int main(void)
{
    qurt_thread_t      thread_id;
    qurt_thread_attr_t attr;

    printf("Main thread starting on QuRT!\n");

    /* Initialize thread attributes */
    qurt_thread_attr_init(&attr);

    /* Configure the thread */
    qurt_thread_attr_set_name(&attr, "my_first_thread");
    qurt_thread_attr_set_stack_addr(&attr, thread_stack);
    qurt_thread_attr_set_stack_size(&attr, STACK_SIZE);
    qurt_thread_attr_set_priority(&attr, 128);  /* Medium priority */

    /* Create and start the thread */
    int result = qurt_thread_create(&thread_id, &attr,
                                     my_thread_func,
                                     (void *)42);

    if (result != QURT_EOK) {
        printf("Thread creation failed with error: %d\n", result);
        return -1;
    }

    printf("Thread created successfully! ID: %lu\n", thread_id);

    /* Wait for the thread to finish */
    int status;
    qurt_thread_join(thread_id, &status);

    printf("Thread finished with status: %d\n", status);
    return 0;
}

This program demonstrates the four-step thread creation process in QuRT. First, qurt_thread_attr_init() initializes a thread attribute's structure. Second, the program configures the thread with a debug name (which shows up in crash dumps), a stack address, a stack size, and a priority. Third, qurt_thread_create() creates and immediately starts the thread, passing a function pointer and an argument. Fourth, qurt_thread_join() blocks the calling thread until the new thread calls qurt_thread_exit().

Two details are critical. QuRT doesn't allocate stack memory for you: you must provide a statically allocated, 8-byte-aligned buffer. And every thread must call qurt_thread_exit() before returning. If a thread function simply returns without calling exit, the behavior is undefined.

Thread Creation Flow

     qurt_thread_attr_init()
              │
              ▼
    ┌─────────────────────┐
    │  Set name           │
    │  Set stack address  │
    │  Set stack size     │
    │  Set priority       │
    └─────────────────────┘
              │
              ▼
     qurt_thread_create()
              │
              ▼
    Thread starts running ──► my_thread_func()
              │                      │
              ▼                      ▼
     qurt_thread_join()       qurt_thread_exit()
     (waits for exit)         (signals "I'm done")

This flow shows the lifecycle of a single thread. The attributes structure acts as a configuration object: you set all the thread parameters, then pass it to qurt_thread_create(). Once created, the thread runs its entry function. When the entry function calls qurt_thread_exit(), the thread terminates and any thread blocked in qurt_thread_join() is unblocked and receives the exit status code.

How Thread Creation Works Internally

Most tutorials skip what happens inside qurt_thread_create(). Understanding the internals makes debugging and priority design decisions much clearer.

What the Kernel Does During Thread Creation

When you call qurt_thread_create(), you're making a system call into the QuRT kernel. The kernel performs five steps in sequence:

  Your code calls qurt_thread_create()
         │
         ▼
  ┌──────────────────────────────────────────────────────────┐
  │  1. VALIDATE                                             │
  │     • Is the stack pointer non-NULL and aligned?         │
  │     • Is the stack size >= minimum (typ. 2KB)?           │
  │     • Is the priority in range 0-255?                    │
  │     • Is the entry function pointer non-NULL?            │
  │     (If any check fails → return QURT_EINVALID)          │
  ├──────────────────────────────────────────────────────────┤
  │  2. ALLOCATE THREAD CONTROL BLOCK (TCB)                  │
  │     • QuRT allocates a kernel-side data structure        │
  │     • This holds: thread ID, priority, state, saved      │
  │       registers, signal masks, mutex wait list, etc.     │
  ├──────────────────────────────────────────────────────────┤
  │  3. INITIALIZE THE STACK FRAME                           │
  │     • The kernel sets up a synthetic stack frame at the  │
  │       top of YOUR stack memory                           │
  │     • It writes the initial register values:             │
  │       ┌──────────────────────────────────────┐           │
  │       │  Stack Top (high address)            │           │
  │       │  ┌──────────────────────────────────┐│           │
  │       │  │ PC  = my_thread_func (entry)     ││           │
  │       │  │ SP  = stack_addr + stack_size    ││           │
  │       │  │ R0  = arg (your void* argument)  ││           │
  │       │  │ LR  = qurt_thread_exit           ││           │
  │       │  │ SR  = default status register    ││           │
  │       │  │ R1-R31 = 0                       ││           │
  │       │ └──────────────────────────────────┘│            │
  │       │  ... (rest of stack is untouched) ...│           │
  │       │  Stack Bottom (low address)          │           │
  │       └──────────────────────────────────────┘           │
  ├──────────────────────────────────────────────────────────┤
  │  4. INSERT INTO READY QUEUE                              │
  │     • The TCB is added to the scheduler's ready queue    │
  │       at the appropriate priority level                  │
  │     • The thread's state is set to READY                 │
  ├──────────────────────────────────────────────────────────┤
  │  5. TRIGGER A RESCHEDULE                                 │
  │     • The scheduler checks: "Is this new thread's        │
  │       priority higher than the currently running         │
  │       thread?"                                           │
  │     • If YES: context switch happens RIGHT NOW           │
  │       (the calling thread is preempted)                  │
  │     • If NO: the new thread waits in the ready queue     │
  │       until it's the highest priority runnable thread    │
  └──────────────────────────────────────────────────────────┘
         │
         ▼
  qurt_thread_create() returns to the caller
  (but the new thread may already be running!)

The most surprising aspect of this flow is step 5. If the new thread has higher priority than the thread that created it, the new thread starts running before qurt_thread_create() returns to the caller. The creating thread is preempted mid-call. This is what "preemptive" means in practice: the scheduler doesn't wait for a convenient moment. It enforces priority ordering immediately.

How the Stack Frame Launches Your Function

When the scheduler context-switches to a brand-new thread for the first time, it does exactly what it does for any context switch: it restores the saved registers from the TCB and jumps to the saved Program Counter.

For a new thread, those registers were set up synthetically by the kernel during step 3. The PC (Program Counter) was set to my_thread_func, so the processor jumps to your function. R0 was set to your arg parameter, so your function receives it as the first argument (following the Hexagon calling convention). The SP (Stack Pointer) was set to the top of your stack, so your function has a working stack. And the LR (Link Register) was set to qurt_thread_exit, so if your function returns normally (which you should not rely on), it falls through to qurt_thread_exit.

The illusion:
──────────────
To your thread function, it looks like someone
"called" it normally with the argument you passed.

The reality:
──────────────
The scheduler restored a set of synthetic registers
that make the processor THINK it is returning from
a function call into your entry point.

It's like waking up in a room you have never been in,
but someone arranged everything so perfectly that
you do not realize you did not walk in through the door.

This diagram contrasts the programmer's mental model (a normal function call) with what actually happens at the hardware level (a register restore that simulates a function call). The thread function has no way to distinguish between these two scenarios, which is exactly the point. The kernel creates a seamless illusion.

Context Switch Walkthrough

Consider a concrete example: thread A (priority 128) creates thread B (priority 64, which is higher priority). The following timeline shows what happens at each step:

Time ──────────────────────────────────────────────►

Thread A (pri 128)          Kernel/Scheduler         Thread B (pri 64)
────────────────           ────────────────           ────────────────
Calls                      
qurt_thread_create()       
   │                       
   ├─► System call ──────►  Validates params
                            Allocates TCB
                            Sets up stack frame
                            Inserts B into ready queue
                            
                            "B (64) > A (128)?  YES."
                            
                            SAVE A's registers   ──┐
                            to A's TCB             │
                                                   │
                            LOAD B's registers   ◄─┘
                            from B's TCB (the
                            synthetic ones)
                            
                            Jump to PC ─────────► my_thread_func(arg)
                                                   │
                                                   │ does work...
                                                   │ calls qurt_thread_exit()
                                                   │
                            B is removed ◄─────── Exit system call
                            from ready queue
                            
                            "Who's next? A."
                            
                            LOAD A's registers
   │                        Jump to A's PC
   │◄──────────────────────
   │
   ├─► qurt_thread_create()
   │   returns QURT_EOK
   │
   ▼ continues...

From thread A's perspective, qurt_thread_create() is just a function call that takes a while to return. Thread A has no idea it was suspended. It doesn't know thread B already ran to completion during that pause.

The scheduler makes preemption invisible to the preempted thread. This is a fundamental property of preemptive scheduling: threads don't need to cooperate or even be aware of each other's existence.

Thread Control Block Contents

The TCB is the kernel's internal data structure for tracking each thread. You never access it directly, but understanding its contents explains a lot of QuRT behavior:

/* Conceptual TCB layout (simplified, not actual QuRT source) */
struct qurt_tcb {
    /* Identity */
    qurt_thread_t   thread_id;
    char            name[16];
    
    /* Scheduling */
    uint8_t         base_priority;
    uint8_t         effective_priority; /* May differ due to priority inheritance */
    uint8_t         state;             /* READY, RUNNING, BLOCKED, SUSPENDED */
    
    /* Saved CPU context (filled during context switch) */
    uint32_t        saved_regs[32];
    uint32_t        saved_pc;
    uint32_t        saved_sp;
    uint32_t        saved_sr;
    
    /* Stack info (for debugging and overflow detection) */
    void           *stack_base;
    size_t          stack_size;
    
    /* Blocking info */
    void           *wait_object;  /* Mutex/signal/pipe being waited on */
    uint32_t        wait_mask;    /* Signal bits being waited for */
    
    /* Linked list pointers */
    struct qurt_tcb *next_ready;
    struct qurt_tcb *next_waiting;
    
    /* Join support */
    int             exit_status;  /* Value passed to qurt_thread_exit() */
    qurt_thread_t   joiner;      /* Thread waiting in qurt_thread_join() */
};

The TCB stores everything the scheduler needs: identity information (thread ID and debug name), scheduling state (base and effective priority, current state), saved CPU context (all 32 general-purpose registers plus PC, SP, and status register), stack bounds, blocking information (what the thread is waiting on), linked list pointers for the ready and wait queues, and join support fields.

The effective_priority field may differ from base_priority when priority inheritance is active, which is covered in the synchronization section.

Thread State Machine

A QuRT thread is always in one of four states:

                    qurt_thread_create()
                           │
                           ▼
                    ┌──────────┐
          ┌─────────│  READY   │◄──────────────────────────┐
          │         └──────────┘                           │
          │              │ ▲                               │
          │  Scheduler   │ │ Preempted by                  │
          │  picks this  │ │ higher-priority               │
          │  thread      │ │ thread                        │
          │              ▼ │                               │
          │         ┌──────────┐     Signal/mutex/         │
          │         │ RUNNING  │     timer event           │
          │         └──────────┘     unblocks thread       │
          │              │                                 │
          │  Thread calls│                                 │
          │  blocking    │                                 │
          │  API:        │                                 │
          │  - mutex_lock│                                 │
          │  - signal_   │                                 │
          │    wait      │                                 │
          │  - pipe_     │                                 │
          │    receive   ▼                                 │
          │         ┌──────────┐                           │
          │         │ BLOCKED  │───────────────────────────┘
          │         └──────────┘
          │
          │  qurt_thread_exit()
          │         │
          │         ▼
          │    ┌──────────┐
          └───►│  DEAD    │
               └──────────┘

• READY means the thread can run and is waiting for a hardware thread slot.

• RUNNING means the thread is currently executing on a hardware thread (only one thread per hardware thread slot is in this state at a time).

• BLOCKED means the thread is waiting for an external event: a mutex to be released, a signal to be set, or a timer to expire.

• DEAD means the thread called qurt_thread_exit(). If another thread called qurt_thread_join() on it, that thread receives the exit status.

Hardware Thread Slots

The Hexagon DSP is a hardware-multithreaded processor with multiple hardware thread slots per core (typically 2 to 4). This means QuRT can run multiple threads truly simultaneously on a single core, not just time-sliced.

┌─────────────────────────────────────────┐
│          Hexagon DSP Core               │
│                                         │
│  ┌───────────┐  ┌───────────┐           │
│  │ HW Thread │  │ HW Thread │           │
│  │ Slot 0    │  │ Slot 1    │  ...      │
│  │           │  │           │           │
│  │ Thread A  │  │ Thread B  │           │
│  │ (running) │  │ (running) │           │
│  └───────────┘  └───────────┘           │
│                                         │
│  Ready Queue: [C, D, E, F, ...]         │
│  The scheduler fills HW slots with      │
│  the highest-priority READY threads     │
└─────────────────────────────────────────┘

This diagram shows a single Hexagon core with two hardware thread slots. Each slot can execute a thread independently and simultaneously. The scheduler fills the hardware slots with the highest-priority ready threads. When there are more software threads than hardware slots, the scheduler time-slices the lower-priority threads. But the highest-priority threads get dedicated hardware slots and run without context switching at all.

On a typical Hexagon v66 with 4 hardware threads, the top 4 priority threads each have their own execution pipeline. Context switches only happen when a thread blocks or a higher-priority thread wakes up and displaces one from a hardware slot. This is why QuRT achieves such low scheduling latency.

Full Thread Lifecycle

The following code shows a complete thread lifecycle with annotations for what QuRT does at each step:

static char stack[8192] __attribute__((aligned(8)));

void my_func(void *arg)
{
    /* State: RUNNING. Stack is fresh, R0 contains arg. */
    int val = *(int *)arg;

    qurt_mutex_lock(&some_mutex);
    /* If mutex is held: state becomes BLOCKED until holder unlocks */

    shared_data = val;
    qurt_mutex_unlock(&some_mutex);

    qurt_thread_exit(QURT_EOK);
    /* State becomes DEAD. Joiner (if any) is unblocked. */
}

int main(void)
{
    qurt_thread_t tid;
    qurt_thread_attr_t attr;
    int my_arg = 42;

    qurt_thread_attr_init(&attr);
    qurt_thread_attr_set_stack_addr(&attr, stack);
    qurt_thread_attr_set_stack_size(&attr, sizeof(stack));
    qurt_thread_attr_set_priority(&attr, 100);

    qurt_thread_create(&tid, &attr, my_func, &my_arg);
    /* If my_func's priority (100) > main's: main is preempted here */

    int status;
    qurt_thread_join(tid, &status);
    /* Blocks until my_func exits; returns immediately if already exited */

    return 0;
}

When my_func starts running, the kernel has already set up its registers so that arg contains the pointer to my_arg. The thread's state is RUNNING.

When it calls qurt_mutex_lock(), one of two things happens: if the mutex is available, the thread acquires it and continues. If the mutex is held by another thread, the calling thread's state changes to BLOCKED, its registers are saved to its TCB, and the scheduler picks the next highest-priority ready thread.

When the mutex holder calls qurt_mutex_unlock(), the blocked thread moves back to READY and the scheduler re-evaluates priorities.

On the main side, qurt_thread_create() may or may not return before my_func finishes. If my_func has higher priority than main, the scheduler preempts main immediately, and qurt_thread_create() doesn't return until my_func completes (or blocks). qurt_thread_join() either blocks main until my_func exits, or returns immediately if my_func has already exited.

One important note about stack sizing: if you set STACK_SIZE to something too small (say, 256 bytes) and your thread calls printf, the result is a stack overflow. QuRT doesn't detect stack overflows for you. The crash will be silent and difficult to diagnose. Always give your threads at least 8192 bytes of stack and optimize later after profiling.

Building and Running on the Simulator

The Hexagon SDK provides a make wrapper that invokes SCons underneath. Both of the following commands produce the same result:

# Option 1: Use the make wrapper (invokes SCons internally)
cd $HEXAGON_SDK_ROOT
make V=hexagon_Release_dynamic_toolv84_v66 \
     tree=my_qurt_project

# Option 2: Invoke SCons directly
cd $HEXAGON_SDK_ROOT
python tools/build/scons/scons.py \
    V=hexagon_Release_dynamic_toolv84_v66 \
    my_qurt_project

Both commands build the project for the Hexagon v66 architecture using the v84 toolchain in release mode. The make wrapper is a convenience layer: it parses the V= and tree= arguments and forwards them to SCons. Using SCons directly gives you access to additional flags such as --jobs=N for parallel builds and --verbose for full compiler command output.

# Run on the simulator
hexagon-sim --simulated_returnval \
    --cosim_file osam.cfg \
    -- bootimg.pbn \
    -- my_qurt_app.so

The hexagon-sim command launches the QuRT simulator with your compiled application. The --simulated_returnval flag captures the return value from your main function, and --cosim_file points to the QuRT OS configuration.

Working with Multiple Threads

Real QuRT applications have multiple threads running simultaneously. The producer-consumer pattern is one of the most common in DSP programming: one thread reads from hardware, another processes the data.

#include <stdio.h>
#include <qurt.h>

#define STACK_SIZE    8192
#define BUFFER_SIZE   16
#define NUM_ITEMS     100

/* Thread stacks */
static char producer_stack[STACK_SIZE] __attribute__((aligned(8)));
static char consumer_stack[STACK_SIZE] __attribute__((aligned(8)));

/* Shared buffer */
static int buffer[BUFFER_SIZE];
static int head = 0;
static int tail = 0;
static int count = 0;

/* Synchronization primitives */
qurt_mutex_t buffer_mutex;
qurt_cond_t  not_full;
qurt_cond_t  not_empty;

void producer_thread(void *arg)
{
    for (int i = 0; i < NUM_ITEMS; i++) {
        qurt_mutex_lock(&buffer_mutex);

        /* Wait until there is space in the buffer */
        while (count == BUFFER_SIZE) {
            qurt_cond_wait(&not_full, &buffer_mutex);
        }

        /* Produce an item */
        buffer[head] = i;
        head = (head + 1) % BUFFER_SIZE;
        count++;

        printf("[Producer] Put item %d (buffer count: %d)\n", i, count);

        /* Signal the consumer that data is available */
        qurt_cond_signal(&not_empty);
        qurt_mutex_unlock(&buffer_mutex);
    }

    qurt_thread_exit(QURT_EOK);
}

void consumer_thread(void *arg)
{
    for (int i = 0; i < NUM_ITEMS; i++) {
        qurt_mutex_lock(&buffer_mutex);

        /* Wait until there is data in the buffer */
        while (count == 0) {
            qurt_cond_wait(&not_empty, &buffer_mutex);
        }

        /* Consume an item */
        int item = buffer[tail];
        tail = (tail + 1) % BUFFER_SIZE;
        count--;

        printf("[Consumer] Got item %d (buffer count: %d)\n", item, count);

        /* Signal the producer that space is available */
        qurt_cond_signal(&not_full);
        qurt_mutex_unlock(&buffer_mutex);
    }

    qurt_thread_exit(QURT_EOK);
}

int main(void)
{
    qurt_thread_t producer, consumer;
    qurt_thread_attr_t attr;

    /* Initialize sync primitives BEFORE creating threads */
    qurt_mutex_init(&buffer_mutex);
    qurt_cond_init(&not_full);
    qurt_cond_init(&not_empty);

    /* Create producer (higher priority) */
    qurt_thread_attr_init(&attr);
    qurt_thread_attr_set_name(&attr, "producer");
    qurt_thread_attr_set_stack_addr(&attr, producer_stack);
    qurt_thread_attr_set_stack_size(&attr, STACK_SIZE);
    qurt_thread_attr_set_priority(&attr, 100);
    qurt_thread_create(&producer, &attr, producer_thread, NULL);

    /* Create consumer (lower priority) */
    qurt_thread_attr_init(&attr);
    qurt_thread_attr_set_name(&attr, "consumer");
    qurt_thread_attr_set_stack_addr(&attr, consumer_stack);
    qurt_thread_attr_set_stack_size(&attr, STACK_SIZE);
    qurt_thread_attr_set_priority(&attr, 110);
    qurt_thread_create(&consumer, &attr, consumer_thread, NULL);

    /* Wait for both threads to finish */
    int status;
    qurt_thread_join(producer, &status);
    qurt_thread_join(consumer, &status);

    /* Clean up */
    qurt_mutex_destroy(&buffer_mutex);
    qurt_cond_destroy(&not_full);
    qurt_cond_destroy(&not_empty);

    printf("All done! Produced and consumed %d items.\n", NUM_ITEMS);
    return 0;
}

This code implements a classic bounded-buffer producer-consumer pattern. The shared buffer is a circular array of 16 integers protected by a mutex. The producer writes items into the buffer and the consumer reads them out.

When the buffer is full, the producer blocks on the not_full condition variable. When the buffer is empty, the consumer blocks on not_empty. Each side signals the other after modifying the buffer.

The producer has higher priority (100) than the consumer (110) for a deliberate reason. In a real DSP scenario, the producer is typically reading from hardware (a microphone, a sensor). If the producer misses a hardware sample, that data is lost forever. The consumer can always process data later. This is a general RTOS design principle: never starve your hardware-facing threads.

Synchronization Primitives

QuRT provides five main synchronization mechanisms: mutexes, condition variables, signals, barriers, and semaphores.

┌──────────────┬────────────────────────────────────────────────────┐
│ Primitive    │ When to Use                                        │
├──────────────┼────────────────────────────────────────────────────┤
│ Mutex        │ Protecting shared data from concurrent access      │
│ Condition Var│ "Wait until X is true" (always paired with mutex)  │
│ Signal       │ One thread notifying another (like poking someone) │
│ Barrier      │ "Everyone wait here until all threads arrive"      │
├──────────────┼────────────────────────────────────────────────────┤
│ Semaphore    │ Controlling access to a limited resource pool      │
│              │ (for example, 4 DMA channels shared by 10 threads)        │
└──────────────┴────────────────────────────────────────────────────┘

This table summarizes each primitive and its primary use case. Mutexes enforce exclusive access to shared data. Condition variables let a thread sleep until a specific data condition becomes true, and are always used in combination with a mutex. Signals provide lightweight one-to-one notifications between threads. Barriers synchronize a group of threads at a common point. Semaphores control access to a pool of N identical resources.

Mutexes

A mutex ensures that only one thread accesses a critical section at a time. QuRT mutexes also support non-blocking acquisition through qurt_mutex_try_lock().

qurt_mutex_t my_mutex;

void init_example(void)
{
    /* Always initialize before use */
    qurt_mutex_init(&my_mutex);
}

void critical_section_example(void)
{
    qurt_mutex_lock(&my_mutex);

    /* Only one thread can be here at a time */
    shared_counter++;
    shared_buffer[index] = new_value;

    qurt_mutex_unlock(&my_mutex);
}

/* Non-blocking version */
void try_lock_example(void)
{
    int result = qurt_mutex_try_lock(&my_mutex);

    if (result == QURT_EOK) {
        shared_counter++;
        qurt_mutex_unlock(&my_mutex);
    } else {
        printf("Busy, will try later\n");
    }
}

void cleanup_example(void)
{
    qurt_mutex_destroy(&my_mutex);
}

The qurt_mutex_lock() call blocks the calling thread until the mutex is available, then acquires it. qurt_mutex_try_lock() attempts to acquire the mutex and returns immediately with QURT_EOK on success or an error code if the mutex is held. Always call qurt_mutex_destroy() when you're done with a mutex.

QuRT mutexes implement priority inheritance. If a high-priority thread is waiting for a mutex held by a low-priority thread, the low-priority thread temporarily gets boosted to the high-priority level. This prevents priority inversion, the classic bug that caused the Mars Pathfinder spacecraft to repeatedly reset during its mission.

QuRT handles priority inheritance automatically, but you should be aware it's happening so you don't get confused by unexpected priority behavior during debugging.

Signals

Signals in QuRT are a lightweight notification mechanism. A thread waits for specific signal bits, and another thread (or an ISR) sets those bits to wake it up.

#include <qurt.h>

#define SIGNAL_DATA_READY   0x01
#define SIGNAL_STOP         0x02
#define SIGNAL_ERROR        0x04

qurt_signal_t my_signal;

void signal_init(void)
{
    qurt_signal_init(&my_signal);
}

/* Waiting thread */
void waiter_thread(void *arg)
{
    unsigned int received_signals;

    while (1) {
        /* Wait for ANY of these signals */
        received_signals = qurt_signal_wait(
            &my_signal,
            SIGNAL_DATA_READY | SIGNAL_STOP | SIGNAL_ERROR,
            QURT_SIGNAL_ATTR_WAIT_ANY
        );

        if (received_signals & SIGNAL_STOP) {
            printf("Received stop signal. Exiting.\n");
            break;
        }

        if (received_signals & SIGNAL_DATA_READY) {
            printf("Data is ready! Processing...\n");
            process_data();
            /* Clear the signal after handling it */
            qurt_signal_clear(&my_signal, SIGNAL_DATA_READY);
        }

        if (received_signals & SIGNAL_ERROR) {
            printf("Error occurred! Handling...\n");
            handle_error();
            qurt_signal_clear(&my_signal, SIGNAL_ERROR);
        }
    }

    qurt_signal_destroy(&my_signal);
    qurt_thread_exit(QURT_EOK);
}

/* Signaling thread (or ISR) */
void sender_thread(void *arg)
{
    prepare_data();
    qurt_signal_set(&my_signal, SIGNAL_DATA_READY);

    /* Later, tell it to stop */
    qurt_signal_set(&my_signal, SIGNAL_STOP);

    qurt_thread_exit(QURT_EOK);
}

The waiting thread calls qurt_signal_wait() with a bitmask of the signals it cares about. QURT_SIGNAL_ATTR_WAIT_ANY means the thread wakes up when any of the specified bits are set. The sender thread calls qurt_signal_set() to set one or more bits. After handling a signal, the waiter must call qurt_signal_clear() to reset the bit. If you forget to clear a signal, the next call to qurt_signal_wait() returns immediately, and your thread processes the same event again.

The choice between signals and condition variables depends on the use case. Signals are best for notifications between unrelated threads, or from an ISR, because they're simpler and lighter weight. Condition variables are better when the notification is tied to a specific data condition (buffer full, queue empty) and you need mutex protection for the data check.

Barriers

A barrier blocks all participating threads until every one of them has reached the barrier point. This is useful when a computation is split into phases and each phase depends on the results of the previous one.

#define NUM_WORKER_THREADS  4

qurt_barrier_t sync_barrier;

void worker_thread(void *arg)
{
    int thread_num = (int)(uintptr_t)arg;

    /* Phase 1: Each thread computes its portion */
    printf("Thread %d: Computing phase 1...\n", thread_num);
    compute_partial_result(thread_num);

    /* All threads wait here until everyone finishes phase 1 */
    qurt_barrier_wait(&sync_barrier);

    /* Phase 2: All partial results are ready, combine them */
    printf("Thread %d: Computing phase 2...\n", thread_num);
    combine_results(thread_num);

    qurt_thread_exit(QURT_EOK);
}

int main(void)
{
    qurt_barrier_init(&sync_barrier, NUM_WORKER_THREADS);

    /* Create worker threads */
    for (int i = 0; i < NUM_WORKER_THREADS; i++) {
        create_worker(i);
    }

    join_all_workers();

    qurt_barrier_destroy(&sync_barrier);
    return 0;
}

The barrier is initialized with the number of participating threads. Each thread calls qurt_barrier_wait() when it reaches the synchronization point. The call blocks until all threads have arrived. Once the last thread calls qurt_barrier_wait(), all threads are released simultaneously and continue to phase 2.

Semaphores

A semaphore controls access to a pool of N identical resources. Unlike a mutex (which is a semaphore with N=1), a semaphore allows up to N threads to hold it simultaneously.

#define MAX_DMA_CHANNELS 4

qurt_sem_t dma_semaphore;

void init_dma_pool(void)
{
    /* 4 DMA channels available */
    qurt_sem_init_val(&dma_semaphore, MAX_DMA_CHANNELS);
}

void thread_needing_dma(void *arg)
{
    /* Acquire a DMA channel (blocks if all 4 are in use) */
    qurt_sem_down(&dma_semaphore);

    int channel = allocate_dma_channel();
    perform_dma_transfer(channel);
    release_dma_channel(channel);

    /* Release the semaphore slot */
    qurt_sem_up(&dma_semaphore);

    qurt_thread_exit(QURT_EOK);
}

The semaphore starts with a count of 4, matching the number of DMA channels. Each qurt_sem_down() decrements the count and blocks if the count reaches zero. Each qurt_sem_up() increments the count and unblocks one waiting thread if any are queued. This guarantees that no more than 4 threads use DMA channels simultaneously.

Memory Management

Memory on a DSP is limited. A typical Hexagon DSP has between 256 KB and 2 MB of tightly-coupled memory (TCM) plus access to DDR. QuRT provides tools to manage both effectively.

The Memory Map

┌───────────────────────────────────┐  High Address
│         DDR (Shared with ARM)     │
│   - Large buffers                 │
│   - Neural network weights        │
│   - Audio/video frames            │
├───────────────────────────────────┤
│         QuRT Virtual Memory       │
│   - User heap                     │
│   - Thread stacks                 │
├───────────────────────────────────┤
│         L2 Cache (TCM Mode)       │
│   - Frequently accessed buffers   │
│   - Lookup tables                 │
├───────────────────────────────────┤
│         QuRT Kernel               │
│   - Scheduler, ISR handlers       │
│   - System data structures        │
└───────────────────────────────────┘  Low Address

This diagram shows the Hexagon DSP memory layout from low to high addresses. The QuRT kernel occupies the lowest addresses and is off-limits to user code. Above that, L2 cache configured in TCM mode provides fast storage for hot data. The virtual memory region holds the user heap and thread stacks. At the top, DDR is shared with the ARM CPU and is used for large data buffers, ML model weights, and media frames. DDR has higher latency than TCM but much more capacity.

Dynamic Memory Allocation

#include <qurt.h>
#include <stdlib.h>

void memory_examples(void)
{
    /* Standard malloc/free works (QuRT provides a heap) */
    int *data = (int *)malloc(1024 * sizeof(int));
    if (!data) {
        printf("malloc failed! Out of heap memory.\n");
        return;
    }

    for (int i = 0; i < 1024; i++) {
        data[i] = i * 2;
    }

    free(data);
}

QuRT provides a standard C heap, so malloc and free work as expected. But malloc has unpredictable execution time because it may need to search the free list, split blocks, or coalesce adjacent free regions. This makes it unsuitable for real-time hot paths, where execution time must be deterministic. Use malloc for setup and teardown, not for per-frame or per-sample allocation.

Cache Management

On the Hexagon DSP, explicit cache management is essential when sharing memory with the ARM CPU.

#include <qurt.h>

void cache_management_example(void)
{
    void *buffer;
    size_t buffer_size = 4096;

    /* Allocate physically contiguous, cache-aligned memory */
    int result = qurt_mem_region_create(
        &buffer,
        buffer_size,
        qurt_mem_default_pool,
        QURT_MEM_REGION_SHARED
    );

    if (result != QURT_EOK) {
        printf("Memory region creation failed\n");
        return;
    }

    /* BEFORE reading data written by another processor (e.g., ARM): */
    qurt_mem_cache_clean(buffer, buffer_size,
                          QURT_MEM_CACHE_INVALIDATE);

    /* Read data from the buffer... */

    /* AFTER writing data that another processor will read: */
    fill_buffer_with_results(buffer, buffer_size);
    qurt_mem_cache_clean(buffer, buffer_size,
                          QURT_MEM_CACHE_FLUSH);
}

The qurt_mem_region_create() call allocates a physically contiguous memory region suitable for sharing with other processors. The QURT_MEM_REGION_SHARED flag marks it for cross-processor use.

The cache rules for shared memory are simple but critical:

1. Invalidate before you read, so you see the latest data written by the ARM CPU rather than stale cache entries.

2. Flush after you write, so the ARM CPU sees your changes rather than the old contents of main memory.

Forgetting these operations causes bugs where your code is logically correct but operates on stale data.

Memory Pools for Predictable Allocation

Memory pools provide O(1) allocation time, making them suitable for real-time hot paths.

#include <qurt.h>

#define BLOCK_SIZE    256
#define NUM_BLOCKS    32

/* Pool memory is statically allocated for determinism */
static char pool_memory[BLOCK_SIZE * NUM_BLOCKS] __attribute__((aligned(8)));
static qurt_mem_pool_t my_pool;

void pool_init(void)
{
    qurt_mem_pool_create(&my_pool, pool_memory,
                          BLOCK_SIZE * NUM_BLOCKS,
                          BLOCK_SIZE);
}

void *pool_alloc(void)
{
    void *block = qurt_mem_pool_alloc(&my_pool);
    if (!block) {
        printf("Pool exhausted!\n");
    }
    return block;
}

void pool_free(void *block)
{
    qurt_mem_pool_free(&my_pool, block);
}

This code creates a pool of 32 blocks, each 256 bytes. The pool memory is statically allocated to avoid any dependency on malloc at runtime.

qurt_mem_pool_alloc() returns a block in constant time, and qurt_mem_pool_free() returns it in constant time. If the pool is exhausted, the allocation returns NULL rather than blocking or searching for memory elsewhere.

This determinism makes memory pools the right choice for audio processing loops, sensor data handlers, and any other code that runs on a strict deadline.

Timers and Timing

QuRT provides hardware-backed timers for precise timing. This is critical for DSP work: if you're processing audio at 48 kHz, you need a new buffer every 10.67 milliseconds, with no exceptions.

One-Shot Timer

#include <qurt.h>
#include <qurt_timer.h>

qurt_timer_t my_timer;
qurt_signal_t timer_signal;

#define TIMER_EXPIRED_SIGNAL  0x01

void timer_example(void)
{
    qurt_signal_init(&timer_signal);

    qurt_timer_attr_t attr;
    qurt_timer_attr_init(&attr);

    /* Set timer duration: 10 milliseconds */
    qurt_timer_attr_set_duration(&attr,
        qurt_timer_convert_time_to_ticks(10000,  /* microseconds */
                                          QURT_TIME_USEC));

    /* Set the signal to fire when timer expires */
    qurt_timer_attr_set_signal(&attr, &timer_signal);
    qurt_timer_attr_set_signal_mask(&attr, TIMER_EXPIRED_SIGNAL);

    /* One-shot: fires once */
    qurt_timer_attr_set_type(&attr, QURT_TIMER_ONESHOT);

    /* Create and start the timer */
    qurt_timer_create(&my_timer, &attr);

    /* Wait for the timer to expire */
    qurt_signal_wait(&timer_signal,
                      TIMER_EXPIRED_SIGNAL,
                      QURT_SIGNAL_ATTR_WAIT_ANY);

    printf("Timer expired! 10ms have passed.\n");
    qurt_signal_clear(&timer_signal, TIMER_EXPIRED_SIGNAL);

    /* Clean up */
    qurt_timer_delete(my_timer);
    qurt_signal_destroy(&timer_signal);
}

This creates a one-shot timer that fires after 10 milliseconds. The timer is configured with an attributes structure that specifies the duration, the signal object to notify, the signal bitmask to set, and the timer type (QURT_TIMER_ONESHOT). When the timer expires, it sets the specified signal bit, which wakes up the thread blocked in qurt_signal_wait(). After handling the event, the thread clears the signal and cleans up the timer.

Periodic Timer

void periodic_timer_thread(void *arg)
{
    qurt_timer_t periodic_timer;
    qurt_signal_t periodic_signal;
    qurt_timer_attr_t attr;

    qurt_signal_init(&periodic_signal);
    qurt_timer_attr_init(&attr);

    /* Fire every 1 millisecond */
    qurt_timer_attr_set_duration(&attr,
        qurt_timer_convert_time_to_ticks(1000, QURT_TIME_USEC));
    qurt_timer_attr_set_signal(&attr, &periodic_signal);
    qurt_timer_attr_set_signal_mask(&attr, 0x01);
    qurt_timer_attr_set_type(&attr, QURT_TIMER_PERIODIC);

    qurt_timer_create(&periodic_timer, &attr);

    int iteration = 0;
    while (iteration < 1000) {
        qurt_signal_wait(&periodic_signal, 0x01,
                          QURT_SIGNAL_ATTR_WAIT_ANY);
        qurt_signal_clear(&periodic_signal, 0x01);

        /* This runs every 1ms */
        process_audio_frame(iteration);
        iteration++;
    }

    qurt_timer_delete(periodic_timer);
    qurt_signal_destroy(&periodic_signal);
    qurt_thread_exit(QURT_EOK);
}

The periodic timer uses QURT_TIMER_PERIODIC instead of QURT_TIMER_ONESHOT. It fires repeatedly at the specified interval. This example runs 1000 iterations at 1 ms intervals, processing one audio frame per tick. The signal must be cleared after each iteration, or the next qurt_signal_wait() will return immediately.

Reading the Current Time

void timing_example(void)
{
    unsigned long long start_ticks = qurt_sysclock_get_hw_ticks();

    heavy_computation();

    unsigned long long end_ticks = qurt_sysclock_get_hw_ticks();
    unsigned long long elapsed_ticks = end_ticks - start_ticks;

    unsigned long long elapsed_us =
        qurt_timer_convert_ticks_to_time(elapsed_ticks, QURT_TIME_USEC);

    printf("Computation took %llu microseconds\n", elapsed_us);
}

qurt_sysclock_get_hw_ticks() reads the hardware cycle counter, which provides the highest-resolution timing available on the DSP. qurt_timer_convert_ticks_to_time() converts raw ticks to human-readable units (microseconds in this case). Use this pattern to profile individual functions and identify performance bottlenecks.

Interrupt Handling

On a DSP, interrupts are how hardware signals that it needs attention. QuRT provides a thread-based interrupt model that's more structured than bare-metal ISR handlers.

#include <qurt.h>
#include <qurt_interrupt.h>

#define MY_SENSOR_IRQ      42
#define IRQ_SIGNAL         0x01

static qurt_signal_t irq_signal;

void sensor_isr_thread(void *arg)
{
    int irq = MY_SENSOR_IRQ;

    /* Register this thread as the handler for IRQ 42 */
    qurt_interrupt_register(irq, &irq_signal, IRQ_SIGNAL);

    printf("Sensor ISR thread ready, waiting for interrupts...\n");

    while (1) {
        /* Block until the hardware interrupt fires */
        unsigned int sigs = qurt_signal_wait(
            &irq_signal, IRQ_SIGNAL, QURT_SIGNAL_ATTR_WAIT_ANY);

        if (sigs & IRQ_SIGNAL) {
            qurt_signal_clear(&irq_signal, IRQ_SIGNAL);

            /* Read sensor data quickly */
            int sensor_value = read_sensor_register();

            /* Put data in a queue for the processing thread */
            enqueue_sensor_data(sensor_value);

            /* Signal the processing thread */
            qurt_signal_set(&processing_signal, DATA_READY);

            /* Re-enable the interrupt */
            qurt_interrupt_acknowledge(irq);
        }
    }
}

QuRT ISRs are different from bare-metal ISRs. They run in a dedicated thread context, which means you can use mutexes and signals inside them. But the ISR thread should still do minimal work: read the hardware register, enqueue the data, signal a processing thread, and acknowledge the interrupt. All expensive computation should happen in a separate, lower-priority processing thread.

Hardware IRQ
     │
     ▼
ISR Thread (high priority)     Processing Thread (medium priority)
┌──────────────────┐          ┌──────────────────────────┐
│ Read HW register │          │ Wait for DATA_READY      │
│ Enqueue data     │ ──────►  │ Dequeue data             │
│ Signal "ready"   │          │ Run FFT / filter / etc.  │
│ ACK interrupt    │          │ Write results            │
└──────────────────┘          └──────────────────────────┘

This diagram shows the ISR offloading pattern. The ISR thread on the left handles the hardware interrupt with minimal latency: it reads the sensor register, enqueues the raw data, signals the processing thread, and acknowledges the interrupt so it can fire again. The processing thread on the right does the expensive work (FFT, filtering, ML inference) at a lower priority.

This design ensures that the ISR thread is always available to service the next hardware interrupt, even if the processing thread is still working on the previous sample.

Pipes and Message Queues

QuRT provides built-in pipe support for safe, structured inter-thread communication. Pipes are fixed-size message queues with blocking send and receive operations.

#include <qurt.h>
#include <qurt_pipe.h>

#define PIPE_ELEMENTS   16
#define ELEMENT_SIZE    sizeof(sensor_msg_t)

typedef struct {
    int sensor_id;
    int value;
    unsigned long long timestamp;
} sensor_msg_t;

/* Pipe buffer must be allocated by you */
static char pipe_buffer[PIPE_ELEMENTS * ELEMENT_SIZE]
    __attribute__((aligned(8)));

qurt_pipe_t sensor_pipe;

void pipe_init(void)
{
    qurt_pipe_attr_t attr;
    qurt_pipe_attr_init(&attr);
    qurt_pipe_attr_set_buffer(&attr, pipe_buffer);
    qurt_pipe_attr_set_buffer_partition(&attr, PIPE_ELEMENTS);
    qurt_pipe_attr_set_elements(&attr, PIPE_ELEMENTS);
    qurt_pipe_attr_set_element_size(&attr, ELEMENT_SIZE);

    qurt_pipe_create(&sensor_pipe, &attr);
}

/* Producer: send sensor data into the pipe */
void sensor_reader_thread(void *arg)
{
    while (1) {
        sensor_msg_t msg;
        msg.sensor_id = 1;
        msg.value = read_accelerometer();
        msg.timestamp = qurt_sysclock_get_hw_ticks();

        /* Blocking send: waits if pipe is full */
        qurt_pipe_send(&sensor_pipe, (char *)&msg, ELEMENT_SIZE);
    }
}

/* Consumer: receive sensor data from the pipe */
void data_processor_thread(void *arg)
{
    sensor_msg_t msg;

    while (1) {
        /* Blocking receive: waits if pipe is empty */
        qurt_pipe_receive(&sensor_pipe, (char *)&msg, ELEMENT_SIZE);

        printf("Sensor %d: value=%d at tick=%llu\n",
               msg.sensor_id, msg.value, msg.timestamp);

        process_sensor_reading(&msg);
    }
}

A QuRT pipe is configured with a statically allocated buffer, a number of elements, and an element size. Like stacks, the buffer memory is your responsibility. qurt_pipe_send() copies a message into the pipe and blocks if the pipe is full. qurt_pipe_receive() copies a message out and blocks if the pipe is empty. The pipe handles all internal synchronization, so you don't need a separate mutex.

Pipes are a natural fit for the sensor data pattern shown here: the reader thread samples hardware at a fixed rate and pushes messages into the pipe, while the processor thread pulls messages out and handles them. The pipe provides buffering and backpressure automatically.

QuRT and FastRPC

In real Qualcomm devices, you rarely use QuRT alone. Your Android or Linux application on the ARM CPU offloads compute-intensive work to the DSP using FastRPC (Fast Remote Procedure Call). The following diagram shows the full pipeline:

┌───────────────────────────────────────────────────────────────┐
│                         ARM CPU Side                          │
│                                                               │
│   your_app.c                                                  │
│   ┌───────────────────────────────────────────────────┐       │
│   │  #include "my_dsp_module.h"  // auto-generated    │       │
│   │                                                   │       │
│   │  // This looks like a normal function call,       │       │
│   │  // but it actually executes on the DSP!          │       │
│   │  result = my_dsp_module_process_audio(            │       │
│   │      input_buffer, output_buffer, num_samples);   │       │
│   └───────────────────┬───────────────────────────────┘       │
│                       │ FastRPC                               │
└───────────────────────┼───────────────────────────────────────┘
            (crosses processor boundary)          
┌───────────────────────┼───────────────────────────────────────┐
│                       ▼                                       │
│                  DSP Side (QuRT)                              │
│   my_dsp_module_skel.c  // auto-generated skeleton            │
│   ┌───────────────────────────────────────────────────┐       │
│   │  int my_dsp_module_process_audio(                 │       │
│   │      const int16_t *input,                        │       │
│   │      int16_t *output,                             │       │
│   │      int num_samples)                             │       │
│   │  {                                                │       │
│   │      // This runs on the Hexagon DSP under QuRT   │       │
│   │      apply_noise_reduction(input, output,         │       │
│   │                             num_samples);         │       │
│   │      return 0;                                    │       │
│   │  }                                                │       │
│   └───────────────────────────────────────────────────┘       │
└───────────────────────────────────────────────────────────────┘

This diagram shows the FastRPC architecture. On the ARM CPU side, your application calls a function that appears to be a normal C function. Under the hood, FastRPC serializes the arguments, sends them across the processor boundary to the Hexagon DSP, executes the function under QuRT, and returns the result. The programmer experience is a transparent remote procedure call.

Step 1: Define the Interface (IDL File)

Create a .idl file that describes the functions the ARM can call on the DSP:

/* my_dsp_module.idl */
#include "remote.idl"
#include "AEEStdDef.idl"

interface my_dsp_module {

    /* Simple computation */
    long process_audio(
        in sequence<short> input,
        rout sequence<short> output,
        in long num_samples
    );

    /* Matrix multiply offload */
    long matrix_multiply(
        in sequence<float> mat_a,
        in sequence<float> mat_b,
        rout sequence<float> result,
        in long rows_a,
        in long cols_a,
        in long cols_b
    );
};

The IDL (Interface Definition Language) file defines the cross-processor API. Each function specifies its parameters with direction qualifiers: in for data flowing from ARM to DSP, rout for data flowing from DSP back to ARM. The sequence<type> syntax specifies a variable-length array. The Hexagon SDK's IDL compiler generates stub code for the ARM side and skeleton code for the DSP side from this definition.

Step 2: Implement the DSP Side

/* my_dsp_module_imp.c - DSP implementation */

#include "my_dsp_module.h"
#include <qurt.h>
#include <stdio.h>

int my_dsp_module_process_audio(
    const int16_t *input, int input_len,
    int16_t *output, int output_len,
    int num_samples)
{
    if (!input || !output || num_samples <= 0) {
        return -1;
    }

    /* Invalidate cache: ARM wrote this data */
    qurt_mem_cache_clean((void *)input,
                          num_samples * sizeof(int16_t),
                          QURT_MEM_CACHE_INVALIDATE);

    /* Process on the DSP */
    for (int i = 0; i < num_samples; i++) {
        /* Simple noise gate */
        if (abs(input[i]) < 100) {
            output[i] = 0;
        } else {
            output[i] = input[i];
        }
    }

    /* Flush cache: ARM will read this data */
    qurt_mem_cache_clean(output,
                          num_samples * sizeof(int16_t),
                          QURT_MEM_CACHE_FLUSH);

    return 0;
}

The DSP implementation receives the input buffer that the ARM CPU wrote. Before reading it, the code invalidates the cache so the DSP sees the latest data from main memory rather than stale cache entries. After writing the output, the code flushes the cache so the ARM CPU sees the DSP's results. The actual processing (a simple noise gate in this example) runs between the cache operations.

Step 3: Implement the ARM Side

/* main_arm.c - ARM/Android application */

#include <stdio.h>
#include <stdlib.h>
#include <rpcmem.h>
#include "my_dsp_module.h"

int main(void)
{
    int num_samples = 1024;

    /* Use ION memory for zero-copy sharing with DSP */
    rpcmem_init();

    int16_t *input = (int16_t *)rpcmem_alloc(
        RPCMEM_HEAP_ID_SYSTEM,
        RPCMEM_DEFAULT_FLAGS,
        num_samples * sizeof(int16_t));

    int16_t *output = (int16_t *)rpcmem_alloc(
        RPCMEM_HEAP_ID_SYSTEM,
        RPCMEM_DEFAULT_FLAGS,
        num_samples * sizeof(int16_t));

    if (!input || !output) {
        printf("rpcmem_alloc failed!\n");
        return -1;
    }

    /* Fill input with audio data */
    for (int i = 0; i < num_samples; i++) {
        input[i] = (int16_t)(i % 256);
    }

    /* This call goes to the DSP via FastRPC */
    int result = my_dsp_module_process_audio(
        input, num_samples,
        output, num_samples,
        num_samples);

    if (result != 0) {
        printf("DSP processing failed: %d\n", result);
    } else {
        printf("DSP processing succeeded!\n");
        printf("First 10 output samples: ");
        for (int i = 0; i < 10; i++) {
            printf("%d ", output[i]);
        }
        printf("\n");
    }

    rpcmem_free(input);
    rpcmem_free(output);
    rpcmem_deinit();

    return 0;
}

The ARM side uses rpcmem_alloc() to allocate ION memory, which is a shared memory region accessible by both the ARM CPU and the Hexagon DSP without copying. The call to my_dsp_module_process_audio() looks like a normal function call, but FastRPC transparently routes it to the DSP. When the call returns, the output buffer contains the DSP's results.

Building the Complete Project

A FastRPC project requires two SCons builds: one for the ARM CPU side and one for the Hexagon DSP side. Each side has its own .min file (android.min and hexagon.min), and both are processed by the SDK's SConstruct.

cd $HEXAGON_SDK_ROOT

# Build for ARM target (Android) via make wrapper
make V=android_Release tree=my_dsp_module

# Build for Hexagon DSP via make wrapper
make V=hexagon_Release_dynamic_toolv84_v66 tree=my_dsp_module

# Or invoke SCons directly for both variants
python tools/build/scons/scons.py \
    V=android_Release \
    V=hexagon_Release_dynamic_toolv84_v66 \
    my_dsp_module

# Push to device
adb push android_Release/ship/my_dsp_module /data/local/tmp/
adb push hexagon_Release_dynamic_toolv84_v66/ship/libmy_dsp_module_skel.so \
    /data/local/tmp/

# Run it
adb shell "cd /data/local/tmp && ./my_dsp_module"

The build produces two outputs: an ARM executable (compiled from the stub and your main_arm.c) and a Hexagon shared library (the _skel.so file, compiled from your DSP implementation). SCons handles the IDL compilation step automatically: it detects the .idl file, generates the stub and skeleton C source files, and includes them in the appropriate variant build. Both outputs are pushed to the device.

When the ARM executable runs and calls a FastRPC function, the system loads the skeleton library onto the DSP and routes the call through.

Building a Sensor Fusion Pipeline

This section brings together threads, synchronization, timers, and signals into a complete, realistic QuRT application. The pipeline reads from three simulated sensors (accelerometer, gyroscope, magnetometer), fuses the data using a complementary filter, and reports orientation at 100 Hz.

/*
 * sensor_fusion.c - Multi-sensor fusion pipeline on QuRT
 *
 * Architecture:
 *   [Accel ISR] ──► [Fusion Thread] ──► [Report Thread]
 *   [Gyro ISR]  ──►       ▲
 *   [Mag ISR]   ──►       │
 *                    [Timer Thread]
 *                    (triggers fusion every 10ms)
 */

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <qurt.h>
#include <qurt_timer.h>

/* Configuration */
#define STACK_SIZE          8192
#define FUSION_PERIOD_US    10000   /* 10ms = 100Hz fusion rate */
#define QUEUE_DEPTH         32

/* Data types */
typedef struct {
    float x, y, z;
    unsigned long long timestamp;
} vec3_sample_t;

typedef struct {
    vec3_sample_t accel;
    vec3_sample_t gyro;
    vec3_sample_t mag;
    float roll, pitch, yaw;
} fused_state_t;

/* Thread stacks */
static char accel_stack[STACK_SIZE]  __attribute__((aligned(8)));
static char gyro_stack[STACK_SIZE]   __attribute__((aligned(8)));
static char mag_stack[STACK_SIZE]    __attribute__((aligned(8)));
static char fusion_stack[STACK_SIZE] __attribute__((aligned(8)));
static char report_stack[STACK_SIZE] __attribute__((aligned(8)));

/* Shared state */
static vec3_sample_t latest_accel;
static vec3_sample_t latest_gyro;
static vec3_sample_t latest_mag;
static fused_state_t latest_fused;

static qurt_mutex_t sensor_mutex;
static qurt_mutex_t fused_mutex;
static qurt_signal_t fusion_signal;
static qurt_signal_t report_signal;

#define SIG_FUSION_TICK    0x01
#define SIG_NEW_FUSED_DATA 0x01
#define SIG_SHUTDOWN       0x80

static volatile int running = 1;

/* Simulated sensor reads */
static void read_accelerometer(vec3_sample_t *sample)
{
    sample->x = 0.01f;
    sample->y = 0.02f;
    sample->z = 9.81f;
    sample->timestamp = qurt_sysclock_get_hw_ticks();
}

static void read_gyroscope(vec3_sample_t *sample)
{
    sample->x = 0.001f;
    sample->y = -0.002f;
    sample->z = 0.0005f;
    sample->timestamp = qurt_sysclock_get_hw_ticks();
}

static void read_magnetometer(vec3_sample_t *sample)
{
    sample->x = 25.0f;
    sample->y = -5.0f;
    sample->z = 40.0f;
    sample->timestamp = qurt_sysclock_get_hw_ticks();
}

/* Accelerometer thread */
void accel_thread(void *arg)
{
    printf("[Accel] Thread started\n");

    while (running) {
        vec3_sample_t sample;
        read_accelerometer(&sample);

        qurt_mutex_lock(&sensor_mutex);
        latest_accel = sample;
        qurt_mutex_unlock(&sensor_mutex);

        /* ~400Hz sample rate */
        qurt_timer_sleep(2500);
    }

    printf("[Accel] Thread exiting\n");
    qurt_thread_exit(QURT_EOK);
}

/* Gyroscope thread */
void gyro_thread(void *arg)
{
    printf("[Gyro] Thread started\n");

    while (running) {
        vec3_sample_t sample;
        read_gyroscope(&sample);

        qurt_mutex_lock(&sensor_mutex);
        latest_gyro = sample;
        qurt_mutex_unlock(&sensor_mutex);

        /* 1kHz sample rate */
        qurt_timer_sleep(1000);
    }

    printf("[Gyro] Thread exiting\n");
    qurt_thread_exit(QURT_EOK);
}

/* Magnetometer thread */
void mag_thread(void *arg)
{
    printf("[Mag] Thread started\n");

    while (running) {
        vec3_sample_t sample;
        read_magnetometer(&sample);

        qurt_mutex_lock(&sensor_mutex);
        latest_mag = sample;
        qurt_mutex_unlock(&sensor_mutex);

        /* 100Hz sample rate */
        qurt_timer_sleep(10000);
    }

    printf("[Mag] Thread exiting\n");
    qurt_thread_exit(QURT_EOK);
}

/* Simplified complementary filter */
static void compute_orientation(
    const vec3_sample_t *accel,
    const vec3_sample_t *gyro,
    const vec3_sample_t *mag,
    fused_state_t *state)
{
    float dt = 0.01f;

    float accel_roll = atan2f(accel->y, accel->z) * 57.2958f;
    float accel_pitch = atan2f(-accel->x,
        sqrtf(accel->y * accel->y + accel->z * accel->z)) * 57.2958f;

    /* Trust gyro short-term, accel long-term */
    state->roll = 0.98f * (state->roll + gyro->x * dt * 57.2958f)
                + 0.02f * accel_roll;
    state->pitch = 0.98f * (state->pitch + gyro->y * dt * 57.2958f)
                 + 0.02f * accel_pitch;

    state->yaw = atan2f(mag->y, mag->x) * 57.2958f;

    state->accel = *accel;
    state->gyro = *gyro;
    state->mag = *mag;
}

/* Fusion thread (runs every 10ms) */
void fusion_thread(void *arg)
{
    qurt_timer_t fusion_timer;
    qurt_timer_attr_t timer_attr;

    printf("[Fusion] Thread started\n");

    qurt_timer_attr_init(&timer_attr);
    qurt_timer_attr_set_duration(&timer_attr,
        qurt_timer_convert_time_to_ticks(FUSION_PERIOD_US,
                                          QURT_TIME_USEC));
    qurt_timer_attr_set_signal(&timer_attr, &fusion_signal);
    qurt_timer_attr_set_signal_mask(&timer_attr, SIG_FUSION_TICK);
    qurt_timer_attr_set_type(&timer_attr, QURT_TIMER_PERIODIC);

    qurt_timer_create(&fusion_timer, &timer_attr);

    while (running) {
        unsigned int sigs = qurt_signal_wait(
            &fusion_signal,
            SIG_FUSION_TICK | SIG_SHUTDOWN,
            QURT_SIGNAL_ATTR_WAIT_ANY);

        if (sigs & SIG_SHUTDOWN) break;

        qurt_signal_clear(&fusion_signal, SIG_FUSION_TICK);

        /* Snapshot sensor data under lock */
        vec3_sample_t a, g, m;
        qurt_mutex_lock(&sensor_mutex);
        a = latest_accel;
        g = latest_gyro;
        m = latest_mag;
        qurt_mutex_unlock(&sensor_mutex);

        /* Run the fusion algorithm (no lock needed, local data) */
        fused_state_t state;
        qurt_mutex_lock(&fused_mutex);
        state = latest_fused;
        qurt_mutex_unlock(&fused_mutex);

        compute_orientation(&a, &g, &m, &state);

        /* Publish fused result */
        qurt_mutex_lock(&fused_mutex);
        latest_fused = state;
        qurt_mutex_unlock(&fused_mutex);

        /* Notify reporter */
        qurt_signal_set(&report_signal, SIG_NEW_FUSED_DATA);
    }

    qurt_timer_delete(fusion_timer);
    printf("[Fusion] Thread exiting\n");
    qurt_thread_exit(QURT_EOK);
}

/* Reporting thread */
void report_thread(void *arg)
{
    int report_count = 0;

    printf("[Report] Thread started\n");

    while (running) {
        unsigned int sigs = qurt_signal_wait(
            &report_signal,
            SIG_NEW_FUSED_DATA | SIG_SHUTDOWN,
            QURT_SIGNAL_ATTR_WAIT_ANY);

        if (sigs & SIG_SHUTDOWN) break;

        qurt_signal_clear(&report_signal, SIG_NEW_FUSED_DATA);

        fused_state_t state;
        qurt_mutex_lock(&fused_mutex);
        state = latest_fused;
        qurt_mutex_unlock(&fused_mutex);

        /* Report every 100th update (once per second at 100Hz) */
        if (++report_count % 100 == 0) {
            printf("[Report] Orientation - Roll: %.2f  Pitch: %.2f  "
                   "Yaw: %.2f  (update #%d)\n",
                   state.roll, state.pitch, state.yaw, report_count);
        }
    }

    printf("[Report] Thread exiting\n");
    qurt_thread_exit(QURT_EOK);
}

/* Main */
int main(void)
{
    qurt_thread_t threads[5];
    qurt_thread_attr_t attr;
    int status;

    printf("=== Sensor Fusion Pipeline Starting ===\n");

    /* Initialize synchronization primitives */
    qurt_mutex_init(&sensor_mutex);
    qurt_mutex_init(&fused_mutex);
    qurt_signal_init(&fusion_signal);
    qurt_signal_init(&report_signal);
    memset(&latest_fused, 0, sizeof(latest_fused));

    struct {
        const char *name;
        char *stack;
        int priority;
        void (*func)(void *);
    } thread_configs[] = {
        {"accel_reader", accel_stack,  60, accel_thread},
        {"gyro_reader",  gyro_stack,   60, gyro_thread},
        {"mag_reader",   mag_stack,    70, mag_thread},
        {"fusion",       fusion_stack, 80, fusion_thread},
        {"reporter",     report_stack, 120, report_thread},
    };

    /* Create all threads */
    for (int i = 0; i < 5; i++) {
        qurt_thread_attr_init(&attr);
        qurt_thread_attr_set_name(&attr, thread_configs[i].name);
        qurt_thread_attr_set_stack_addr(&attr, thread_configs[i].stack);
        qurt_thread_attr_set_stack_size(&attr, STACK_SIZE);
        qurt_thread_attr_set_priority(&attr, thread_configs[i].priority);

        int result = qurt_thread_create(&threads[i], &attr,
                                         thread_configs[i].func, NULL);
        if (result != QURT_EOK) {
            printf("Failed to create thread '%s': %d\n",
                   thread_configs[i].name, result);
            return -1;
        }
        printf("Created thread '%s' (priority %d)\n",
               thread_configs[i].name, thread_configs[i].priority);
    }

    /* Let it run for 10 seconds */
    printf("Pipeline running for 10 seconds...\n");
    qurt_timer_sleep(10000000);

    /* Shutdown */
    printf("Shutting down...\n");
    running = 0;
    qurt_signal_set(&fusion_signal, SIG_SHUTDOWN);
    qurt_signal_set(&report_signal, SIG_SHUTDOWN);

    /* Wait for all threads to finish */
    for (int i = 0; i < 5; i++) {
        qurt_thread_join(threads[i], &status);
    }

    /* Clean up */
    qurt_mutex_destroy(&sensor_mutex);
    qurt_mutex_destroy(&fused_mutex);
    qurt_signal_destroy(&fusion_signal);
    qurt_signal_destroy(&report_signal);

    printf("=== Sensor Fusion Pipeline Complete ===\n");
    return 0;
}

This pipeline demonstrates several QuRT patterns working together.

Three sensor reader threads run at the highest priority (60 for accel and gyro, 70 for the slower magnetometer) and continuously write the latest samples into shared state under a mutex.

A fusion thread, triggered by a periodic timer every 10 ms, snapshots all three sensor readings, runs a complementary filter to compute roll, pitch, and yaw, and publishes the fused result.

A reporting thread at the lowest priority (120) receives a signal each time new fused data is available and logs orientation once per second.

Priority Assignment

Priority 60:  Sensor readers (highest priority, never miss hardware data)
Priority 80:  Fusion engine (runs every 10ms, must finish quickly)
Priority 120: Reporter (lowest priority, only logging)

The priority assignments follow a strict rule: threads closer to hardware get higher priority. If the fusion thread takes too long, the reporter waits. That's acceptable because a delayed log message has no real-time consequence. If a sensor read gets delayed, the fusion algorithm operates on stale data.

In a real application controlling a drone or robot, stale IMU data means incorrect orientation estimates, which can lead to physical failures.

Debugging QuRT Applications

QuRT debugging is more limited than Linux debugging. There's no gdb with a TUI, and error messages from crashes are often unhelpful. The following techniques form a practical debugging toolkit.

Printf Debugging

#include <stdio.h>

void debug_example(void)
{
    printf("[%s:%d] value = %d\n", __func__, __LINE__, some_var);
}

QuRT supports printf through a semi-hosting mechanism. On the simulator, output goes to stdout. On hardware, it goes to a DIAG buffer (similar to Android's logcat). This is the most common debugging technique in QuRT development.

QuRT Error Codes

switch (result) {
    case QURT_EOK:
        break;
    case QURT_EINVALID:
        printf("Invalid argument\n");
        break;
    case QURT_EFAILED:
        printf("General failure\n");
        break;
    case QURT_EMEM:
        printf("Out of memory\n");
        break;
    case QURT_ENOTALLOWED:
        printf("Operation not allowed (check permissions)\n");
        break;
    case QURT_ETIMEOUT:
        printf("Operation timed out\n");
        break;
    default:
        printf("Unknown error: %d\n", result);
}

Always check return values from QuRT API calls. These are the error codes you'll encounter most frequently.

QURT_EINVALID usually means a bad parameter (unaligned stack, null pointer, out-of-range priority). QURT_EMEM means the kernel ran out of memory for internal structures. QURT_ENOTALLOWED often indicates a permissions issue on hardware.

Thread State Inspection

void dump_thread_info(void)
{
    qurt_thread_t tid = qurt_thread_get_id();
    char name[QURT_THREAD_ATTR_NAME_MAXLEN];

    qurt_thread_get_name(name, sizeof(name));

    printf("Thread: %s (ID: %lu)\n", name, tid);
}

This function prints the current thread's name and ID, which is useful when you have multiple threads writing to the same log output and need to distinguish which thread produced each message.

Stack Overflow Detection

#define STACK_CANARY 0xDEADBEEF

static char my_stack[STACK_SIZE] __attribute__((aligned(8)));

void init_stack_canary(void)
{
    /* Write canary at the bottom of the stack */
    ((unsigned int *)my_stack)[0] = STACK_CANARY;
    ((unsigned int *)my_stack)[1] = STACK_CANARY;
}

void check_stack_canary(void)
{
    if (((unsigned int *)my_stack)[0] != STACK_CANARY ||
        ((unsigned int *)my_stack)[1] != STACK_CANARY) {
        printf("STACK OVERFLOW DETECTED!\n");
    }
}

QuRT doesn't detect stack overflows. This canary pattern writes a known value at the bottom of the stack before the thread starts. If the stack grows downward past its bounds, it overwrites the canary value. Periodically checking the canary (or checking it on thread exit) catches overflows that would otherwise manifest as mysterious, unrelated crashes.

Using the Hexagon Simulator

# Run with instruction tracing
hexagon-sim --timing --pmu_statsfile stats.txt \
    --cosim_file osam.cfg \
    -- bootimg.pbn -- my_app.so

# The stats file gives you:
# - Total cycles
# - Cache hit/miss rates
# - Stall cycles
# - Instructions per cycle (IPC)

The --timing flag enables cycle-accurate simulation, and --pmu_statsfile writes performance counter data to a file. The stats file reports total cycles, cache hit and miss rates, stall cycles, and instructions per cycle (IPC). This data is essential for identifying whether your bottleneck is compute-bound, memory-bound, or stall-bound.

Common Pitfalls

Pitfall 1: Forgetting to Exit Threads

/* BAD: thread function returns without exit */
void bad_thread(void *arg) {
    do_work();
    return;  /* CRASH or undefined behavior */
}

/* GOOD */
void good_thread(void *arg) {
    do_work();
    qurt_thread_exit(QURT_EOK);
}

A QuRT thread that returns from its entry function without calling qurt_thread_exit() causes undefined behavior. The kernel set the link register to qurt_thread_exit as a safety net during thread creation, but you shouldn't rely on this. Always call qurt_thread_exit() explicitly.

Pitfall 2: Stack Allocated in Wrong Scope

/* BAD: stack is on the calling thread's stack */
void create_thread_bad(void) {
    char stack[4096];
    qurt_thread_attr_set_stack_addr(&attr, stack);
    qurt_thread_create(&tid, &attr, func, NULL);
}   /* stack disappears here, new thread crashes */

/* GOOD: use static or heap allocation */
static char stack[4096] __attribute__((aligned(8)));
void create_thread_good(void) {
    qurt_thread_attr_set_stack_addr(&attr, stack);
    qurt_thread_create(&tid, &attr, func, NULL);
}

The stack memory must outlive the thread that uses it. If you allocate the stack as a local variable in a function, it's freed when that function returns, but the thread may still be running. Use static allocation (as shown) or heap allocation with careful lifetime management.

Pitfall 3: Priority Inversion Without Awareness

/* BAD: manual spinlock, no priority inheritance */
volatile int lock = 0;
while (__sync_lock_test_and_set(&lock, 1)) { /* spin */ }

/* GOOD: QuRT mutex with priority inheritance */
qurt_mutex_lock(&my_mutex);

If a high-priority thread spins on a manual spinlock held by a low-priority thread, and a medium-priority thread preempts the lock holder, the high-priority thread is effectively blocked by the medium-priority thread.

QuRT mutexes solve this with automatic priority inheritance: the lock holder is temporarily boosted to the priority of the highest-priority waiter. Manual spinlocks don't get this treatment.

Pitfall 4: Unaligned Memory

/* BAD */
char stack[4096];

/* GOOD */
char stack[4096] __attribute__((aligned(8)));

/* For DMA buffers, you often need 256-byte alignment */
char dma_buffer[1024] __attribute__((aligned(256)));

Thread stacks must be 8-byte aligned. DMA buffers typically require 256-byte alignment. Unaligned memory causes hard faults on the Hexagon architecture that produce minimal diagnostic output.

Pitfall 5: Blocking in ISR Context

/* BAD: mutex_lock may block indefinitely */
void isr_handler(void *arg) {
    qurt_mutex_lock(&some_mutex);
    qurt_mutex_unlock(&some_mutex);
}

/* GOOD: non-blocking try_lock with fallback */
void isr_handler(void *arg) {
    if (qurt_mutex_try_lock(&some_mutex) == QURT_EOK) {
        /* Quick update */
        qurt_mutex_unlock(&some_mutex);
    } else {
        /* Defer to processing thread */
        qurt_signal_set(&deferred_signal, DEFERRED_WORK);
    }
}

Although QuRT ISR threads can technically call blocking APIs, doing so in a high-priority interrupt handler freezes interrupt processing until the blocking condition is resolved. Use qurt_mutex_try_lock() for non-blocking attempts, and defer work to a lower-priority thread using signals if the lock is unavailable.

Performance Optimization

Using HVX (Hexagon Vector Extensions)

#include <hexagon_types.h>
#include <hvx_hexagon_protos.h>

/* Process 128 bytes at once with HVX */
void vectorized_gain(int16_t *audio, int num_samples, int16_t gain)
{
    HVX_Vector *vptr = (HVX_Vector *)audio;
    HVX_Vector vgain = Q6_Vh_vsplat_R(gain);
    int num_vectors = num_samples * sizeof(int16_t) / sizeof(HVX_Vector);

    for (int i = 0; i < num_vectors; i++) {
        vptr[i] = Q6_Vh_vmpy_VhVh_sat(vptr[i], vgain);
    }
}

HVX provides 128-byte SIMD operations on the Hexagon DSP. The Q6_Vh_vsplat_R intrinsic broadcasts a scalar value across all lanes of a vector register. Q6_Vh_vmpy_VhVh_sat performs a saturating multiply of two half-word vectors. A single HVX instruction processes 64 16-bit samples, which can yield an order-of-magnitude speedup over scalar code for audio and signal processing workloads.

Locking L2 Cache for Hot Data

void lock_cache_example(void)
{
    extern float fft_twiddle_factors[];
    size_t twiddle_size = 1024 * sizeof(float);

    /* Pin data in L2 to prevent eviction */
    qurt_mem_l2cache_lock((unsigned int)fft_twiddle_factors,
                           twiddle_size);

    /* When done: */
    qurt_mem_l2cache_unlock((unsigned int)fft_twiddle_factors,
                             twiddle_size);
}

qurt_mem_l2cache_lock() pins a memory region in the L2 cache, preventing it from being evicted by other cache traffic. This is useful for lookup tables and constant data that are accessed frequently in hot loops (such as FFT twiddle factors).

Locking too much data in L2 reduces the cache available for other threads, so use this technique selectively.

Avoiding Dynamic Memory in Hot Paths

/* BAD: malloc in the audio processing loop */
void process_audio_bad(void) {
    while (1) {
        float *temp = malloc(1024 * sizeof(float));
        process(temp);
        free(temp);
    }
}

/* GOOD: pre-allocate everything */
static float temp_buffer[1024];
void process_audio_good(void) {
    while (1) {
        process(temp_buffer);
    }
}

malloc and free have non-deterministic execution time because they may traverse free lists, split or coalesce blocks, and in the worst case, request additional memory from the kernel.

In a real-time audio processing loop running at 48 kHz, a single slow allocation can cause an audible glitch. Pre-allocate all buffers during initialization and reuse them.

API Quick Reference

┌─────────────────────────────────────────────────────────────────┐
│                    QuRT API Quick Reference                     │
├─────────────────┬───────────────────────────────────────────────┤
│ THREADS         │                                               │
│  create         │ qurt_thread_create(&id, &attr, func, arg)     │
│  exit           │ qurt_thread_exit(status)                      │
│  join           │ qurt_thread_join(id, &status)                 │
│  get id         │ qurt_thread_get_id()                          │
│  sleep          │ qurt_timer_sleep(usec)                        │
├─────────────────┼───────────────────────────────────────────────┤
│ MUTEX           │                                               │
│  init           │ qurt_mutex_init(&mutex)                       │
│  lock           │ qurt_mutex_lock(&mutex)                       │
│  try lock       │ qurt_mutex_try_lock(&mutex)                   │
│  unlock         │ qurt_mutex_unlock(&mutex)                     │
│  destroy        │ qurt_mutex_destroy(&mutex)                    │
├─────────────────┼───────────────────────────────────────────────┤
│ SIGNALS         │                                               │
│  init           │ qurt_signal_init(&signal)                     │
│  wait           │ qurt_signal_wait(&sig, mask, attr)            │
│  set            │ qurt_signal_set(&signal, mask)                │
│  clear          │ qurt_signal_clear(&signal, mask)              │
│  destroy        │ qurt_signal_destroy(&signal)                  │
├─────────────────┼───────────────────────────────────────────────┤
│ TIMERS          │                                               │
│  create         │ qurt_timer_create(&timer, &attr)              │
│  delete         │ qurt_timer_delete(timer)                      │
│  sleep          │ qurt_timer_sleep(usec)                        │
│  ticks          │ qurt_sysclock_get_hw_ticks()                  │
├─────────────────┼───────────────────────────────────────────────┤
│ MEMORY          │                                               │
│  cache flush    │ qurt_mem_cache_clean(addr, sz, FLUSH)         │
│  cache inval    │ qurt_mem_cache_clean(addr, sz, INVALIDATE)    │
│  l2 lock        │ qurt_mem_l2cache_lock(addr, size)             │
│  l2 unlock      │ qurt_mem_l2cache_unlock(addr, size)           │
├─────────────────┼───────────────────────────────────────────────┤
│ SEMAPHORE       │                                               │
│  init           │ qurt_sem_init_val(&sem, count)                │
│  down (wait)    │ qurt_sem_down(&sem)                           │
│  up (post)      │ qurt_sem_up(&sem)                             │
│  destroy        │ qurt_sem_destroy(&sem)                        │
├─────────────────┼───────────────────────────────────────────────┤
│ BARRIER         │                                               │
│  init           │ qurt_barrier_init(&barrier, count)            │
│  wait           │ qurt_barrier_wait(&barrier)                   │
│  destroy        │ qurt_barrier_destroy(&barrier)                │
└─────────────────┴───────────────────────────────────────────────┘

This table lists the most commonly used QuRT API functions organized by category. The left column names the operation and the right column shows the function signature.

• Thread operations cover creation, termination, joining, and sleeping.

• Mutex operations provide lock, try-lock, and unlock.

• Signal operations support wait, set, and clear with bitmask-based notifications. Timer operations handle creation, deletion, and sleeping, plus reading the hardware tick counter.

• Memory operations cover cache flush and invalidate (essential for cross-processor buffers) and L2 cache locking for performance-critical data.

• Semaphore and barrier operations round out the synchronization primitives.

Next Steps

This handbook covered the fundamentals of QuRT programming: thread management, synchronization, memory, timers, interrupts, pipes, FastRPC, and a multi-sensor fusion pipeline. The next steps for deeper learning follow a natural progression.

Start by downloading the Hexagon SDK and running the included example projects on the simulator. The examples in $HEXAGON_SDK_ROOT/examples/ demonstrate real ARM-DSP communication patterns through FastRPC and are the best way to see complete, working projects.

Read the QuRT User Guide in $HEXAGON_SDK_ROOT/docs/. It covers every API discussed in this article in full detail, plus many that weren't covered (such as QuRT's TLB management and power management interfaces).

Experiment with HVX, the Hexagon Vector Extensions. HVX is where the real performance of the Hexagon DSP lives, and learning to write vectorized DSP code is the single largest performance lever available to you.

Finally, get a development board (such as the Qualcomm RB5) and run your code on real hardware. The simulator validates correctness, but only real hardware reveals timing behavior, cache effects, and the interaction between your code and other software running on the DSP.

Recommended Reading

The Hexagon SDK Documentation is located at \(HEXAGON_SDK_ROOT/docs/. The QuRT API Reference is at \)HEXAGON_SDK_ROOT/docs/qurt/. The Qualcomm Developer Network at developer.qualcomm.com provides additional resources, forums, and application notes. The Hexagon DSP Architecture Reference is the definitive guide to the hardware itself.

QuRT is a precision instrument. It won't hold your hand, but it gives you microsecond-level control over real-time processing on one of the most powerful DSP architectures in the world. The learning curve is steep, but once you are past it, you will understand why billions of devices trust this tiny OS with their most time-critical tasks.

Desktop and server processors hide memory latency behind multi-level caches. Many embedded processors, especially ARM Cortex-M and Cortex-R based chips, take a different approach. They give you direct control over multiple memory regions, each with very different performance characteristics.

This handbook covers what ITCM, DTCM, and DDR memory are, how they differ, how to place code and data in the right region, and how to profile and monitor firmware memory usage over time.

Table of Contents

• Prerequisites

• Why Embedded Memory Architecture Matters

• What is ITCM (Instruction Tightly-Coupled Memory)?

• What is DTCM (Data Tightly-Coupled Memory)?

• What is DDR (Double Data Rate) Memory?

• How They Compare: A Side-by-Side Overview

• How to Decide Where to Place Code and Data

• How the Linker Script Controls Memory Placement

• Common Mistakes to Avoid

• Performance Comparison With Real Numbers

• How TCM Affects Power Consumption

• How to Profile Memory Usage

• Summary

Prerequisites

To get the most from this guide, you should have a basic understanding of C programming, including pointers, structs, and the difference between static and local variables.

Some familiarity with embedded development concepts like compiling, linking, and flashing firmware to a target board will also help.

Finally, a general sense of how a CPU fetches and executes instructions will make the performance discussions easier to follow.

You don't need to be an expert in any of these. The article explains each concept as it comes up.

Why Embedded Memory Architecture Matters

A modern embedded processor might be clocked at 400 MHz or higher. It can execute an instruction every few nanoseconds.

But when it needs to fetch that instruction from memory, or read a variable, the memory might not keep up. The processor ends up stalling, waiting for the memory subsystem to deliver the data it asked for. Those stall cycles add up fast.

On a desktop computer, hardware caches (L1, L2, L3) sit between the CPU and main memory, automatically keeping recently-used data nearby. The cache hardware decides what to keep and what to evict, and it does this transparently. The programmer rarely needs to think about it, and performance is generally good enough without manual intervention.

On many embedded processors, the situation is different. Instead of hardware caches, you get three distinct memory regions, each attached to the CPU in a different way.

The table above shows the three memory types you'll encounter on a typical ARM Cortex-M or Cortex-R-based embedded system. ITCM and DTCM are fast but small. DDR is slow but large.

The "deterministic" label on TCM means that the access time is always the same, every single time, regardless of what accessed that memory before or what else is happening on the chip. The "variable" label on DDR means the access time can change depending on the internal state of the DDR chip and its controller.

You, the developer, control which region each piece of your firmware lives in. The compiler and linker don't make these decisions automatically. You specify them through section attributes in your source code and placement rules in your linker script. Getting this right is often the difference between firmware that meets its real-time deadlines and firmware that misses them.

What is ITCM (Instruction Tightly-Coupled Memory)?

ITCM stands for Instruction Tightly-Coupled Memory.

The "Instruction" part means this memory is used for storing executable machine code, the compiled instructions your CPU fetches and runs.

The "Tightly-Coupled" part means the memory is physically located on the same silicon die as the CPU core, connected through a dedicated bus with no arbitration or contention. There's no shared bus to compete with. There's no cache hierarchy to traverse. The CPU asks for an instruction, and ITCM delivers it directly, through a private path that nothing else on the chip can interfere with.

The CPU can fetch an instruction from ITCM in a single clock cycle, every time. This access time is both fast and deterministic. It doesn't vary based on access patterns, recent history, or what else is happening on the bus.

This determinism is just as important as the raw speed, because it makes worst-case execution time analysis possible. In safety-critical systems, you need to be able to prove that a function will always complete within a certain number of cycles. ITCM makes that proof much simpler.

Why Single-Cycle Fetch Matters

Every line of C code compiles down to one or more machine instructions. Each of those instructions must be fetched from memory before the CPU can decode and execute it. This fetch step happens for every single instruction, so even small per-instruction delays compound rapidly in loops and frequently-called functions.

Consider a loop that runs 1,000,000 iterations, where each iteration involves 10 instruction fetches. That's 10 million fetches total.

ITCM:  10,000,000 fetches x 1 cycle  = 10,000,000 cycles
DDR:   10,000,000 fetches x 8 cycles = 80,000,000 cycles

Difference: 70,000,000 cycles
At 400 MHz: 70,000,000 / 400,000,000 = 0.175 seconds = 175 ms

This calculation compares the total cycle count when the same loop runs from ITCM versus DDR. With ITCM, each fetch takes 1 cycle, so 10 million fetches cost 10 million cycles.

With DDR, each fetch takes 8 cycles (a conservative average), so the same 10 million fetches cost 80 million cycles. The difference is 70 million cycles, which at 400 MHz translates to 175 milliseconds.

In a real-time system running a control loop at 1 kHz (one iteration every 1 ms), 175 ms of extra latency spread across your processing isn't a minor inconvenience. It can cause the system to miss deadlines, drop sensor readings, or produce incorrect outputs. In motor control applications, a missed deadline can mean physical damage to the hardware. In audio processing, it means audible glitches. The cost of slow instruction fetch isn't abstract.

What Should Go in ITCM?

Because ITCM is small (typically 512 KB to 2 MB), you can't fit your entire firmware in it. You need to be selective about what earns a spot.

Interrupt Service Routines (ISRs) are the highest-priority candidates. ISRs run in response to hardware events like a timer tick, an ADC conversion completing, or a communication peripheral receiving data. They need to execute and return as quickly as possible.

A slow ISR delays all lower-priority interrupts and can cause missed events. If your ISR fetches its instructions from DDR, each fetch takes multiple cycles, and the total ISR execution time increases by a factor that could push it past its deadline.

Placing ISRs in ITCM ensures they run at maximum speed with completely predictable timing.

Real-time processing functions are the next priority. These include signal processing routines, motor control loops, audio processing pipelines, and any function that runs at a fixed rate and must complete within a strict time budget.

If your audio codec callback needs to process a buffer of samples every 5 ms, every instruction fetch cycle counts. Placing these functions in ITCM gives you the maximum amount of CPU time for actual computation rather than waiting on memory.

Inner loops of your main processing pipeline also benefit significantly from ITCM placement. If your firmware spends 80% of its time in a handful of functions, those functions should be in ITCM. Profiling tools and the linker map file (covered later in this article) can help you identify which functions are the hottest.

Functions that require deterministic timing belong in ITCM even if they aren't the fastest path. ITCM access time doesn't vary, which makes timing analysis predictable. This matters for safety-critical systems (automotive, medical, aerospace) where you need to prove worst-case execution times to a certification authority.

How to Place a Function in ITCM

You use a GCC section attribute to tell the compiler that a function belongs in a specific memory section. Then, in your linker script, you map that section to the ITCM memory region.

__attribute__((section(".itcm_text")))
void my_critical_isr(void) {
    volatile uint32_t *sensor_reg = (volatile uint32_t *)0x40001000;
    uint32_t reading = *sensor_reg;
    process_sample(reading);
}

In this code, the __attribute__((section(".itcm_text"))) directive tells the compiler to emit this function's compiled machine code into a section called .itcm_text instead of the default .text section. The function itself reads a sensor register at the memory-mapped address 0x40001000, stores the result in a local variable, and passes it to process_sample() for further processing. The volatile keyword tells the compiler that this memory address can change at any time (because it is a hardware register), so the compiler must not optimize away the read.

On its own, the section attribute doesn't determine where the function ends up in physical memory. It just tells the compiler to label the function's code with a specific section name.

The actual memory placement is the linker script's job, which maps .itcm_text to the ITCM address range. We'll cover the linker script in detail in a later section.

How Much ITCM is Typical?

A real-world memory profile from an embedded project, to give you a sense of scale:

Memory region         Used Size  Region Size  %age Used
            ITCM:      570936 B         2 MB     27.22%
            DTCM:      727240 B    1572608 B     46.24%
             DDR:      622915 B         4 MB     14.85%

This output comes from the linker map file's summary section. It shows three memory regions and how much of each one is used by the compiled firmware.

ITCM has 2 MB available and the firmware is using about 557 KB (27.22%). DTCM has about 1.5 MB available and is using 727 KB (46.24%). DDR has 4 MB available and is using about 609 KB (14.85%).

This project uses about 557 KB of the available 2 MB of ITCM, roughly 27%. That leaves good headroom for growth.

In practice, you want to keep ITCM utilization below 80-85% to leave room for future features and library updates. If utilization climbs above 90%, you're one feature addition away from a build failure, and you should proactively move less-critical code to DDR.

What is DTCM (Data Tightly-Coupled Memory)?

DTCM stands for Data Tightly-Coupled Memory. It works on the same principle as ITCM (physically close to the CPU core, connected via a dedicated bus, single-cycle access) but it stores data instead of instructions.

If ITCM is where your code lives, DTCM is where your code works. It's the fast scratch space that the CPU reads from and writes to while executing your performance-critical functions. Every variable read, every array access, every stack push and pop in your hot code paths goes through data memory. Making that data memory as fast as possible eliminates one of the biggest sources of stall cycles.

What Kind of Data Belongs in DTCM?

Stack frames are the most important thing in DTCM. Every function call pushes a stack frame containing local variables, the return address, and saved registers. Every function return pops that frame. I

f your stack is in DTCM, the memory-access portion of function calls and returns happens in a single cycle. If your stack were in DDR, every function call and return would incur multiple cycles of memory latency just for the stack operations alone, before the function even begins doing useful work.

On most Cortex-M and Cortex-R configurations, the startup code initializes the stack pointer to point into DTCM by default, so you get this benefit without any extra configuration.

Frequently accessed global variables are another strong candidate. State machine variables, control flags, sensor readings that are updated and read in every loop iteration, counters that are incremented in ISRs and read in the main loop: all of these benefit from single-cycle access.

If a variable is read or written thousands of times per second, the cumulative latency difference between DTCM and DDR adds up.

Small lookup tables used in hot paths belong in DTCM when they're small enough to fit. Sine/cosine tables for motor control, filter coefficients for audio processing, and CRC tables for communication protocols are common examples.

These tables are typically a few hundred bytes to a few kilobytes, and they get accessed on every iteration of a processing loop. The key word is "small." A 512-byte sine table is a good fit for DTCM. A 64 KB calibration table is not, and should go in DDR instead.

DMA buffers can sometimes go in DTCM, but this depends on your chip's bus architecture. On some chips, the DMA controller has a direct path to DTCM through the bus matrix. On others, the DMA controller can only reach DDR and possibly other SRAM regions. If you place a DMA buffer in DTCM on a chip where the DMA controller can't reach it, the transfer will silently fail or write to a completely wrong address.

Always check your chip's bus matrix diagram in the reference manual before putting DMA buffers in DTCM.

How to Place Data in DTCM

Placing data in DTCM uses the same section attribute mechanism as ITCM, but with a section name that your linker script maps to the DTCM address range.

__attribute__((section(".dtcm_data")))
static int16_t audio_buffer[256];

__attribute__((section(".dtcm_data")))
static volatile uint32_t sensor_state = 0;

In this code, audio_buffer is an array of 256 signed 16-bit integers (512 bytes total) that will be placed in DTCM. This could be a buffer for audio samples that gets filled by a DMA transfer and processed by an ISR. The static keyword means the buffer has file scope and persists for the lifetime of the program (it's not allocated on the stack).

The sensor_state variable is a 32-bit unsigned integer marked as volatile, meaning the compiler must read it from memory every time it's accessed rather than caching it in a register.

This is important for variables that are written in an ISR and read in the main loop, since the compiler needs to know the value can change at any time. Placing it in DTCM ensures that both the ISR write and the main loop read happen in a single cycle.

DTCM Fills Up Faster Than ITCM

Looking at the memory profile again:

            DTCM:      727240 B    1572608 B     46.24%

This single line from the linker map file summary shows that DTCM has 1,572,608 bytes (about 1.5 MB) available, and the firmware is using 727,240 bytes (about 710 KB), which is 46.24% of the total capacity.

DTCM fills up faster than ITCM because many things compete for it: your stack, your heap (if you have one), your global variables, and data sections from every library you link against. Every C library function that uses static data, every RTOS data structure, every middleware component brings its own data footprint. This creates a constant sizing exercise.

For every data structure, you need to ask: does this really need single-cycle access, or can it work from DDR?

A Concrete Example of the Performance Impact

Say your processor runs at 400 MHz. DTCM gives you 1-cycle access. DDR gives you 8-cycle access. You have a lookup table that gets accessed 100,000 times per second.

DTCM: 100,000 accesses x 1 cycle  = 100,000 cycles/sec
DDR:  100,000 accesses x 8 cycles = 800,000 cycles/sec

Difference: 700,000 cycles/sec
At 400 MHz: 700,000 / 400,000,000 = 0.00175 seconds = 1.75 ms

This calculation shows the cycle cost of 100,000 memory accesses per second in both memory types. In DTCM, each access is 1 cycle, totaling 100,000 cycles. In DDR, each access is 8 cycles, totaling 800,000 cycles. The difference of 700,000 cycles per second, at a 400 MHz clock rate, translates to 1.75 milliseconds of additional CPU time spent waiting on memory.

If you're running a real-time control loop at 1 kHz (1 ms period), 1.75 ms of additional memory latency per second means that some individual iterations are running longer than their 1 ms budget. Whether this causes actual deadline misses depends on how the accesses are distributed across iterations and how much slack you have in your time budget, but it shows why memory placement decisions have real consequences in embedded systems.

What is DDR (Double Data Rate) Memory?

DDR is external memory. It sits on the circuit board outside the processor die, connected through a memory controller. It's much larger than TCM (typically 4 MB to several GB), but significantly slower to access.

The name "Double Data Rate" refers to how data is transferred between the DDR chip and the memory controller: data is sent on both the rising edge and the falling edge of the clock signal, effectively doubling the transfer rate compared to a single-data-rate design. But this doesn't eliminate the latency of activating rows and columns inside the DDR chip, which is where the slowness comes from.

How DDR Access Works

When your CPU reads from DDR, a multi-step process occurs inside the memory controller and DDR chip.

First, the CPU sends an address request to the memory controller. The memory controller is a hardware block inside the processor that translates CPU addresses into the specific row and column addresses that the DDR chip understands.

Second, the memory controller activates the correct row inside the DDR chip. This step is called the RAS (Row Address Strobe) phase. The DDR chip is organized as a grid of tiny capacitors, and "activating a row" means reading all the capacitors in that row into a row buffer inside the DDR chip. This takes several clock cycles.

Third, the memory controller selects the correct column within the activated row. This is called the CAS (Column Address Strobe) phase. The DDR chip uses the column address to pick the right bits out of the row buffer. This also takes several clock cycles.

Fourth, the data is transferred back to the memory controller, and from there to the CPU. The data transfer happens on both clock edges (the "double data rate" part), which helps with throughput but doesn't reduce the initial latency of the RAS and CAS phases.

The total latency depends on what state the memory is in when the request arrives. If the correct row is already activated from a previous access (a "row hit"), the RAS phase can be skipped, and the access is faster. If a different row is active and needs to be closed (precharged) before the new row can be opened (a "row miss"), the access takes longer. If the DDR chip happens to be performing a refresh cycle at that moment, the access is delayed further.

In practice, DDR access latency ranges from about 5 to 20+ CPU clock cycles, depending on the access pattern and timing.

Why DDR is Necessary

Because firmware often doesn't fit in TCM alone. Real embedded projects include protocol stacks, connectivity libraries, file system drivers, debug interfaces, and more. TCM is typically 2 to 3.5 MB total (ITCM + DTCM combined), and a full-featured firmware image can easily exceed that.

A real example showing memory usage before and after adding a wireless connectivity stack:

Without connectivity stack:
    ITCM:      506,996 B     (24.18%)
    DTCM:      628,408 B     (39.96%)
    DDR:       558,779 B     (13.32%)

With connectivity stack:
    ITCM:      570,936 B     (27.22%)
    DTCM:      727,240 B     (46.24%)
    DDR:       622,915 B     (14.85%)

Delta:
    ITCM: +63,940 B   (~62 KB of additional code)
    DTCM: +98,832 B   (~96 KB of additional data)
    DDR:  +64,136 B   (~62 KB of additional data/code)

This comparison shows memory usage from the same project built with and without a wireless connectivity stack.

The "Without" rows show the baseline. The "With" rows show the usage after adding the connectivity feature. The "Delta" rows show the difference.

Adding this single feature consumed an extra ~220 KB across all three memory regions. The time-critical parts of the stack (interrupt handlers, buffer management) went into ITCM and DTCM. The rest (packet parsers, connection management, configuration logic) went into DDR where it doesn't need single-cycle performance.

What Belongs in DDR?

Initialization and configuration code is the easiest category. Functions that run once at boot, like parsing a configuration file, initializing peripherals, or setting up data structures, don't need fast execution. They run once, take a few extra milliseconds because of DDR latency, and then never run again. Nobody notices. Put them in DDR and save TCM space for the code that runs a million times per second.

Large buffers must go in DDR because they simply can't fit in TCM. An image framebuffer for a 320x240 display at 16 bits per pixel is 150 KB. A network packet pool might be 32 KB or more. A file system cache might be 64 KB. These buffers would consume a significant fraction of DTCM's total capacity, leaving no room for the stack and variables that actually need single-cycle access.

Infrequently accessed data belongs in DDR as well. Calibration tables that are loaded once at boot and then read occasionally during operation, string tables for debug messages that are only printed during development or error conditions, and error description tables are all fine in DDR. The extra latency per access is irrelevant when the access count is low.

Non-time-critical code rounds out the DDR category. Protocol stacks (Bluetooth, Wi-Fi, TCP/IP), file system drivers, OTA update handlers, and shell/debug command interpreters all do important work, but none of them need to execute in a single clock cycle per instruction. They can tolerate the higher latency of DDR without affecting system behavior.

How to Place Code and Data in DDR

__attribute__((section(".ddr_text")))
void parse_config_file(const char *path) {
    // Runs from DDR, slower instruction fetch,
    // but config parsing happens once at boot,
    // so the latency does not affect runtime performance.
}

__attribute__((section(".ddr_bss")))
static uint8_t network_packet_pool[32768];

__attribute__((section(".ddr_bss")))
static uint8_t framebuffer[320 * 240 * 2];  // 150 KB, far too large for TCM

In this code, parse_config_file is placed in the .ddr_text section, which the linker script maps to DDR. Every instruction in this function will be fetched from DDR at multi-cycle latency, but since config parsing happens once at boot, the extra time is negligible.

The network_packet_pool is a 32 KB buffer placed in .ddr_bss. The .bss suffix is a convention indicating that this is zero-initialized data (the linker will ensure the memory is zeroed at startup rather than storing 32 KB of zeros in the firmware image). This buffer is used for network packet storage, which is not time-critical enough to justify DTCM space.

The framebuffer is a 150 KB buffer (320 pixels wide, 240 pixels tall, 2 bytes per pixel) also placed in .ddr_bss. At 150 KB, this single buffer would consume about 10% of DTCM's total capacity, which is far too expensive when the display update isn't a hard real-time operation.

How They Compare: A Side-by-Side Overview

This table summarizes the key differences between the three memory types. The most important columns are "Access latency" and "Typical size," because they represent the fundamental tradeoff: TCM is fast but small, DDR is slow but large.

The "Technology" column explains why: TCM uses SRAM (static RAM), which stores each bit using a flip-flop circuit that holds its state as long as power is applied. DDR uses DRAM (dynamic RAM), which stores each bit as charge in a tiny capacitor. Because capacitors leak charge, DRAM must be periodically refreshed, which adds power consumption and introduces occasional access delays when a refresh cycle coincides with a read request.

The Memory Map

Address Space:
  +------------------------------+  0x00000000
  |                              |
  |         ITCM (2 MB)          |  Single-cycle Inst Fetch
  |    ISRs, real-time loops,    |
  |    DSP, critical code        |
  |                              |
  +------------------------------+  0x00200000
  |       (reserved/gap)         |
  +------------------------------+  0x20000000
  |                              |
  |       DTCM (~1.5 MB)         |  Single-cycle Data Access
  |    Stack, hot variables,     |
  |    lookup tables, DMA bufs   |
  |                              |
  +------------------------------+  0x20180000
  |       (reserved/gap)         |
  +------------------------------+  0x80000000
  |                              |
  |         DDR (4 MB)           |  Multi-cycle Access
  |    Large buffers, init code, |
  |    protocol stacks, config   |
  |                              |
  +------------------------------+  0x80400000

This diagram shows the CPU's address space laid out from low addresses at the top to high addresses at the bottom. ITCM occupies the lowest 2 MB starting at address 0x00000000. After a gap of reserved/unused address space, DTCM sits at 0x20000000 and spans about 1.5 MB. Another gap of reserved space follows, and then DDR starts at 0x80000000 with 4 MB of space.

The gaps between regions are important. They're reserved address ranges that don't map to any physical memory. If your code accidentally reads from or writes to an address in one of these gaps, the result depends on the chip's bus fault configuration: it might trigger a HardFault exception, or it might silently return garbage data.

These addresses are illustrative. Every chip has its own memory map, documented in its Technical Reference Manual (TRM). Always consult your chip's TRM for the exact addresses and sizes.

How to Decide Where to Place Code and Data

Is it code or data?
|
+-- CODE (instructions):
|   +-- Called from an ISR or runs in a real-time loop?
|   |   +-- YES -> ITCM (deterministic timing is critical)
|   +-- Called frequently in the main processing pipeline?
|   |   +-- YES -> ITCM (if space is available)
|   +-- Called rarely (init, config, debug)?
|       +-- DDR (save ITCM space for critical code)
|
+-- DATA (variables, buffers, tables):
    +-- Accessed in an ISR or real-time context?
    |   +-- YES -> DTCM (single-cycle, deterministic)
    +-- Small and frequently accessed?
    |   +-- YES -> DTCM (if space is available)
    +-- Large buffer (>16 KB)?
    |   +-- Probably DDR (DTCM cannot afford the space)
    +-- Accessed only once at boot or very rarely?
        +-- DDR (do not use DTCM for this)

This decision tree captures the thought process for placing each piece of firmware into the right memory region.

Start by asking whether you're placing code (instructions) or data (variables, buffers, tables). For code, the primary question is how often it runs and whether it has timing constraints. ISR code and real-time loop code goes in ITCM. Everything else goes in DDR. For data, the primary question is how often it's accessed and how large it is. Small, frequently accessed data goes in DTCM. Large buffers and rarely-accessed data go in DDR.

The general principle: put the hottest code and data in TCM, and everything else in DDR. "Hot" means frequently accessed, latency-sensitive, or requiring deterministic timing. When in doubt, start with DDR placement and move things to TCM only when profiling shows it's necessary. It's much easier to promote a function from DDR to ITCM after discovering it's a bottleneck than to cram everything into ITCM from the start and run out of space.

How the Linker Script Controls Memory Placement

Everything we've discussed so far (section attributes, memory placement, address assignments) comes together in the linker script. This is a file (usually with a .ld extension) that tells the linker exactly which sections go into which memory regions. The linker script is the single source of truth for your firmware's memory layout.

MEMORY
{
    ITCM    (rx)  : ORIGIN = 0x00000000, LENGTH = 2M
    DTCM    (rw)  : ORIGIN = 0x20000000, LENGTH = 1536K
    DDR     (rwx) : ORIGIN = 0x80000000, LENGTH = 4M
}

SECTIONS
{
    /* === ITCM: Critical code === */
    .itcm_text :
    {
        KEEP(*(.isr_vector))          /* Interrupt vector table */
        *(.itcm_text)                 /* Functions with __attribute__((section(".itcm_text"))) */
        *audio_processing.o(.text)    /* All code from audio_processing.c */
        *motor_control.o(.text)       /* All code from motor_control.c */
    } > ITCM

    /* === DDR: Non-critical code === */
    .ddr_text :
    {
        *(.text)                      /* Default catch-all for remaining code */
        *(.text*)
        *(.rodata)                    /* Read-only data (string literals, constants) */
        *(.rodata*)
    } > DDR

    /* === DTCM: Critical data === */
    .dtcm_data :
    {
        *(.dtcm_data)                 /* Data with __attribute__((section(".dtcm_data"))) */
        *audio_processing.o(.data)    /* All initialized data from audio_processing.c */
        *audio_processing.o(.bss)     /* All zero-initialized data from audio_processing.c */
    } > DTCM

    /* === DTCM: Stack === */
    .stack (NOLOAD) :
    {
        . = ALIGN(8);
        __stack_start = .;
        . = . + 8K;                  /* 8 KB stack */
        __stack_end = .;
    } > DTCM

    /* === DDR: Everything else === */
    .ddr_data :
    {
        *(.data)                      /* Default catch-all for remaining initialized data */
        *(.bss)                       /* Default catch-all for remaining zero-initialized data */
        *(COMMON)
    } > DDR
}

This linker script has two main blocks: MEMORY and SECTIONS.

The MEMORY block defines the physical memory regions available on the chip. Each line declares a region name, its permissions (rx for read-execute, rw for read-write, rwx for read-write-execute), its starting address (ORIGIN), and its size (LENGTH). These values must match your chip's actual memory map as documented in its reference manual.

The SECTIONS block defines how the linker should distribute compiled code and data across those memory regions. Each section rule consists of a section name (like .itcm_text), a list of input patterns that specify which object file sections to include, and a > REGION directive that tells the linker which memory region to place the output section in.

The .itcm_text section collects the interrupt vector table (KEEP(*(.isr_vector))), any functions explicitly marked with __attribute__((section(".itcm_text"))), and all code from audio_processing.o and motor_control.o. The KEEP directive prevents the linker from discarding the interrupt vector table during garbage collection, even if no code appears to reference it directly. All of this goes into ITCM.

The .ddr_text section uses catch-all patterns *(.text) and *(.text*) to collect all remaining code that wasn't claimed by the ITCM section above. It also collects read-only data (.rodata), which includes string literals and const variables. All of this goes into DDR.

The .dtcm_data section collects explicitly-placed data and all data from audio_processing.o. The .stack section reserves 8 KB for the stack with 8-byte alignment, and exports the __stack_start and __stack_end symbols that your startup code and stack profiling code can reference. Both go into DTCM.

The .ddr_data section collects all remaining data with catch-all patterns, and goes into DDR.

How Section Matching Works

The linker processes sections from top to bottom. When it encounters a wildcard pattern like *(.text), it matches all .text sections that haven't already been claimed by a more specific rule earlier in the script.

So in the example above, *audio_processing.o(.text) in the ITCM section claims all code from audio_processing.c first. Then, when the linker reaches *(.text) in the DDR section, audio_processing.o's .text section has already been placed, so it's skipped. Only unclaimed .text sections from other object files match the DDR catch-all.

This means the order of sections in your linker script matters. Place your specific rules (individual object files, named sections) before the generic catch-all rules. If you put the *(.text) catch-all before the *audio_processing.o(.text) rule, the catch-all would claim everything first, and the specific rule would match nothing.

Common Mistakes to Avoid

1. Stack Overflow in DTCM

Your stack lives in DTCM. DTCM is small. If you declare a large local array inside a function, it goes on the stack:

void problematic_function(void) {
    uint8_t huge_local_buffer[65536];  // 64 KB allocated on the stack
    // This consumes 64 KB of DTCM immediately
}

This code declares a 64 KB local array. Because it's a local variable (not static), it is allocated on the stack when the function is called. If your total stack size is 8 KB (as in the linker script example above), this single declaration overflows the stack by 56 KB, writing into whatever memory is adjacent to the stack in DTCM.

On a desktop OS, a stack overflow triggers a segmentation fault because the OS uses virtual memory and guard pages to detect it.

In an embedded system without memory protection, the stack silently grows into adjacent memory regions, corrupting whatever data is stored there. The resulting bugs are extremely difficult to diagnose because the symptoms (corrupted variables, erratic behavior, intermittent crashes) appear unrelated to the actual cause. You might spend days debugging a seemingly random data corruption issue before realizing the root cause is a stack overflow from a function three call levels deep.

The fix: Use static allocation or heap allocation for large buffers, and place them in DDR:

void fixed_function(void) {
    __attribute__((section(".ddr_bss")))
    static uint8_t huge_buffer[65536];  // In DDR, not on the stack

    // Stack is safe, DTCM is not wasted
}

By making the buffer static, it's no longer allocated on the stack. Instead, the linker allocates it once in the .ddr_bss section, which maps to DDR. The buffer persists for the entire lifetime of the program (like a global variable), but its name is scoped to this function. The stack only holds a pointer to the buffer, which is a few bytes instead of 64 KB.

2. Overfilling ITCM

If you exceed ITCM's capacity, the linker will produce an error along the lines of "region ITCM overflowed by N bytes." But if you're close to the limit, you're one library update or feature addition away from a build failure. A minor version bump of your RTOS or connectivity stack could add enough code to push ITCM over the edge.

Keep headroom. The 27% utilization shown earlier is healthy. If you're above 85%, you should actively work on moving less-critical code to DDR. If you're above 95%, you have no room for growth and need to make immediate changes. Setting up automated memory budget checks in your CI pipeline (covered later in this article) prevents surprises.

3. Ignoring Alignment Requirements

TCM memories often have alignment requirements. On Cortex-M processors with strict alignment enforcement, accessing a 32-bit value at an unaligned address causes a HardFault exception.

/* Problematic: packed struct can create unaligned fields */
__attribute__((section(".dtcm_data"), packed))
struct badly_aligned {
    uint8_t  flag;
    uint32_t counter;  // May be at byte offset 1, unaligned
};

/* Correct: natural alignment, with minor padding */
__attribute__((section(".dtcm_data")))
struct properly_aligned {
    uint32_t counter;  // At offset 0, 4-byte aligned
    uint8_t  flag;     // At offset 4
    // 3 bytes of padding follow, a small cost for correctness
};

In the first struct, the packed attribute tells the compiler to use no padding between fields. This means counter starts at byte offset 1 (right after the 1-byte flag), which isn't a multiple of 4. When the CPU tries to read a 32-bit value from a non-4-byte-aligned address in TCM, it triggers a HardFault on processors with strict alignment (which includes most Cortex-M cores).

In the second struct, the fields are ordered so that counter (4 bytes) comes first at offset 0, which is naturally 4-byte aligned. The flag (1 byte) follows at offset 4. The compiler inserts 3 bytes of padding after flag to bring the struct size to 8 bytes (a multiple of 4), but this is a small price for correct, crash-free operation.

4. DMA Transfers to TCM on Incompatible Bus Architectures

Some DMA controllers can't access TCM memory. Whether DMA can reach TCM depends entirely on your chip's internal bus architecture (the bus matrix).

If you set up a DMA transfer from a peripheral to a DTCM buffer, but the DMA controller doesn't have a bus path to DTCM, the transfer will either silently fail or write to an incorrect address.

Neither produces an obvious error. The DMA controller thinks it completed successfully, your code reads the buffer expecting fresh data, and you get stale or garbage values instead. This is one of the most confusing bugs in embedded development because everything looks correct in the code.

Always check your chip's bus matrix diagram in the reference manual before using DMA with TCM buffers. The bus matrix diagram shows which masters (CPU, DMA, USB, and so on) can access which slaves (ITCM, DTCM, SRAM, DDR, peripherals). Look for whether the DMA controller's master port has a connection line to the TCM slave port. If it doesn't, your DMA transfers to TCM will not work.

Performance Comparison With Real Numbers

The following table compares access latencies across memory types, assuming a Cortex-R class processor at 400 MHz:

+---------------------+----------+----------+----------+
| Operation           | ITCM/    |   DDR    | Slowdown |
|                     | DTCM     |          | Factor   |
+---------------------+----------+----------+----------+
| Instruction fetch   | 1 cycle  | 5-20 cyc |   5-20x  |
| Data read (32-bit)  | 1 cycle  | 5-20 cyc |   5-20x  |
| Data write (32-bit) | 1 cycle  | 5-20 cyc |   5-20x  |
| Sequential burst    | 1 cyc/wd | 2-4 cy/wd|    2-4x  |
| Random access       | 1 cycle  | 10-20 cyc|  10-20x  |
+---------------------+----------+----------+----------+

This table shows the latency for five different types of memory operations. The first three rows (instruction fetch, data read, data write) show that individual accesses to TCM are always 1 cycle, while individual accesses to DDR range from 5 to 20 cycles depending on the memory's internal state. The slowdown factor is the ratio between the two.

The "Sequential burst" row shows what happens when you read or write consecutive addresses. DDR performs much better in burst mode (2-4 cycles per word instead of 5-20) because once a row is activated, subsequent reads from the same row skip the RAS phase. TCM is still 1 cycle per word because it doesn't have the row/column structure of DDR.

The "Random access" row shows the worst case for DDR. When each access hits a different row, the memory controller must precharge the old row and activate the new one every time. This is the 10-20 cycle range, and it's common in workloads that jump around in memory (traversing linked lists, hash table lookups, and indirect function calls through function pointer arrays).

The practical takeaway: if your code accesses DDR data, try to access it sequentially. Iterating through an array in order is much faster than jumping to random positions. Your memory controller and the DDR chip's internal prefetch logic work in your favor during sequential access patterns.

How TCM Affects Power Consumption

Memory placement has a direct impact on power consumption, something that becomes critical for battery-powered products.

DDR requires constant refresh cycles. DRAM stores each bit as charge in a tiny capacitor, and that charge leaks over time.

To prevent data loss, the memory controller must read and rewrite every row in the DDR chip approximately every 64 ms. This refresh process consumes power even when the processor is sleeping and no code is running. On some systems, DDR refresh can account for a significant portion of the total sleep-mode power budget.

TCM is SRAM-based and doesn't require refresh. SRAM stores data using flip-flop circuits that hold their state as long as power is applied. There is some leakage current (no transistor is perfect), but it is orders of magnitude lower than DDR refresh power.

For battery-powered devices (wearables, IoT sensors, medical devices), this means you should keep data that must survive sleep modes in DTCM when possible.

If your hardware supports it, power-gate the DDR chip during deep sleep to eliminate its refresh power entirely. The less DDR your firmware uses at runtime, the more aggressively you can manage DDR power states, which directly extends battery life.

How to Profile Memory Usage

After placing code and data into ITCM, DTCM, and DDR, you need to verify that everything fits, monitor usage over time, and catch regressions before they become build failures. There are several techniques for this, ranging from simple command-line tools to automated CI checks.

Method 1: The Linker Map File

Every time you build your firmware, the linker can produce a map file, a detailed text file that records where every symbol (function, variable, constant) ended up and how large it is. This is the most useful single artifact in embedded development for understanding memory usage.

To generate one, add -Wl,-Map=output.map to your linker flags:

arm-none-eabi-gcc \
    -T linker_script.ld \
    -Wl,-Map=firmware.map \
    -o firmware.elf \
    main.o audio.o bluetooth.o

This command invokes the ARM GCC toolchain to link three object files (main.o, audio.o, bluetooth.o) using the linker script linker_script.ld. The -Wl,-Map=firmware.map flag tells GCC to pass the -Map=firmware.map option to the linker, which causes it to write a detailed map file alongside the output ELF binary. The map file can be thousands of lines long, but the most useful part is the summary at the end.

The summary at the end of the map file shows overall utilization per memory region:

Memory region         Used Size  Region Size  %age Used
            ITCM:      570936 B         2 MB     27.22%
            DTCM:      727240 B    1572608 B     46.24%
             DDR:      622915 B         4 MB     14.85%

This summary shows three columns: how many bytes are used, the total size of the region, and the percentage used. It gives you the health of your firmware at a glance. As a rule of thumb, below 80% is healthy with room for growth. Between 80% and 90% is getting tight, and you should plan for how you will accommodate the next feature. Above 90% requires action: start moving things to a cheaper memory region or optimizing existing placement.

Method 2: Parsing the Map File for Per-Module Breakdown

The summary tells you how much memory is used, but not who is using it. The map file contains per-symbol details, but they're difficult to read manually because the file can be thousands of lines long with a format that isn't designed for human consumption.

The following Python script parses the map file and produces a per-module report showing which object files are consuming memory in which regions.

#!/usr/bin/env python3
"""Parse a linker map file and report memory usage per object file."""

import re
import sys
from collections import defaultdict

def parse_map_file(map_path):
    """Extract symbol placements from a GCC linker map file."""
    usage = defaultdict(lambda: defaultdict(int))

    regions = {
        'ITCM': (0x00000000, 0x00200000),
        'DTCM': (0x20000000, 0x20180000),
        'DDR':  (0x80000000, 0x80400000),
    }

    def addr_to_region(addr):
        for name, (start, end) in regions.items():
            if start <= addr < end:
                return name
        return 'UNKNOWN'

    symbol_re = re.compile(
        r'^\s+\S+\s+(0x[0-9a-fA-F]+)\s+(0x[0-9a-fA-F]+)\s+(\S+\.o)'
    )

    with open(map_path) as f:
        for line in f:
            m = symbol_re.match(line)
            if m:
                addr = int(m.group(1), 16)
                size = int(m.group(2), 16)
                obj = m.group(3).split('/')[-1]
                region = addr_to_region(addr)
                usage[obj][region] += size

    return usage

def print_report(usage):
    """Print a sorted memory usage report."""
    print(f"{'Object File':<35} {'ITCM':>10} {'DTCM':>10} {'DDR':>10} {'Total':>10}")
    print("-" * 80)

    totals = defaultdict(int)
    rows = []

    for obj, regions in usage.items():
        total = sum(regions.values())
        rows.append((obj, regions, total))
        for r, s in regions.items():
            totals[r] += s

    rows.sort(key=lambda x: x[2], reverse=True)

    for obj, regions, total in rows[:20]:
        print(f"{obj:<35} "
              f"{regions.get('ITCM', 0):>10,} "
              f"{regions.get('DTCM', 0):>10,} "
              f"{regions.get('DDR', 0):>10,} "
              f"{total:>10,}")

    print("-" * 80)
    grand = sum(totals.values())
    print(f"{'TOTAL':<35} "
          f"{totals.get('ITCM', 0):>10,} "
          f"{totals.get('DTCM', 0):>10,} "
          f"{totals.get('DDR', 0):>10,} "
          f"{grand:>10,}")

if __name__ == '__main__':
    usage = parse_map_file(sys.argv[1])
    print_report(usage)

This script does three things. First, parse_map_file reads the map file line by line, looking for lines that match the format of a symbol placement entry (a section name, an address, a size, and an object file name). For each match, it converts the hex address to an integer, determines which memory region it falls in using the addr_to_region helper, and accumulates the size into a nested dictionary keyed by object file and region.

Second, print_report sorts the object files by total memory usage (largest first), prints the top 20, and shows how much each one uses in each region.

Third, the if __name__ == '__main__' block makes the script runnable from the command line.

You'll need to adjust the address ranges in the regions dictionary to match your chip's memory map.

Run it with:

python3 parse_map.py firmware.map

Sample output:

Object File                              ITCM       DTCM        DDR      Total
--------------------------------------------------------------------------------
bluetooth_stack.o                      42,380     65,200     38,400    146,080
audio_processing.o                     89,200     32,000          0    121,200
wifi_driver.o                          21,560     33,632     25,736     80,928
sensor_hub.o                           45,000     18,400          0     63,400
libc.a(memcpy.o)                       12,340          0          0     12,340
...
--------------------------------------------------------------------------------
TOTAL                                 570,936    727,240    622,915  1,921,091

This output shows the top memory consumers in the firmware, sorted by total usage. Each row shows an object file and how many bytes it contributes to each memory region.

The bluetooth_stack.o file is the largest consumer at 146 KB total, spread across all three regions. The audio_processing.o file uses 121 KB, all in ITCM and DTCM (0 bytes in DDR), which makes sense because audio processing is time-critical and was placed entirely in TCM. The libc.a(memcpy.o) entry shows a C library function that was placed in ITCM, likely because it is called from performance-critical code paths.

Method 3: The size Command

For a quick check without parsing the map file, use arm-none-eabi-size:

arm-none-eabi-size -A firmware.elf

Output:

firmware.elf  :
section               size        addr
.itcm_text          570936           0
.dtcm_data          530240   536870912
.dtcm_bss           196000   537401152
.stack                8192   537600000
.ddr_text           422915  2147483648
.ddr_data           120000  2147906563
.ddr_bss             80000  2148026563
Total              1928283

This output lists every section in the ELF binary, its size in bytes, and its starting address (shown in decimal).

You can map sections to memory regions by looking at the address: addresses near 0 are ITCM, addresses near 536 million (0x20000000) are DTCM, and addresses near 2.1 billion (0x80000000) are DDR.

Alternatively, the section names themselves indicate the region (.itcm_text is in ITCM, .dtcm_data and .dtcm_bss are in DTCM, .ddr_text and .ddr_data and .ddr_bss are in DDR).

The -A flag gives per-section sizes instead of the default BSD-format output. It's less detailed than the map file approach, but it runs instantly and gives you the big picture.

Method 4: Runtime Stack Profiling

Static analysis (map files, size output) tells you about compile-time placement. But some memory usage is dynamic, particularly the stack, which grows and shrinks at runtime based on call depth and local variable sizes. A function that allocates a 2 KB local buffer only uses that stack space while it is executing, so static analysis can't tell you the peak stack usage.

A common technique is stack watermarking: fill the entire stack region with a known pattern at boot, then periodically check how much of the pattern has been overwritten.

#define STACK_FILL_PATTERN 0xDEADBEEF

void stack_watermark_init(void) {
    extern uint32_t __stack_start;
    extern uint32_t __stack_end;
    uint32_t *p = &__stack_start;

    register uint32_t sp asm("sp");
    while (p < (uint32_t *)(sp - 64)) {
        *p++ = STACK_FILL_PATTERN;
    }
}

uint32_t stack_usage_bytes(void) {
    extern uint32_t __stack_start;
    extern uint32_t __stack_end;
    uint32_t *p = &__stack_start;

    while (p < &__stack_end && *p == STACK_FILL_PATTERN) {
        p++;
    }

    return (uint32_t)(&__stack_end) - (uint32_t)p;
}

void check_stack_health(void) {
    uint32_t used = stack_usage_bytes();
    uint32_t total = 8192;
    uint32_t percent = (used * 100) / total;

    if (percent > 80) {
        log_warning("Stack usage: %lu / %lu bytes (%lu%%)",
                    used, total, percent);
    }
}

The stack_watermark_init function fills the stack memory (from __stack_start to just below the current stack pointer) with the pattern 0xDEADBEEF. The extern declarations reference the linker symbols defined in the linker script's .stack section. The register uint32_t sp asm("sp") line reads the current stack pointer value so the function knows where to stop filling (you do not want to overwrite your own stack frame). The 64-byte safety margin ensures the fill loop doesn't get too close to the active stack.

The stack_usage_bytes function scans from the bottom of the stack upward, counting how many words still contain the fill pattern. The first word that does not match the pattern indicates the deepest point the stack has reached (the high-water mark). The function returns the number of bytes from that point to the top of the stack.

The check_stack_health function computes the percentage of stack used and logs a warning if it exceeds 80%. Call this function periodically during normal operation to monitor stack usage.

Call stack_watermark_init() as early as possible in your startup code (before main() if you can), then call check_stack_health() periodically during normal operation. This tells you the high-water mark, the maximum stack depth your firmware has reached so far.

Method 5: Tracking Memory Across Builds

Every time you add a feature or merge a change, run the memory profile before and after:

arm-none-eabi-size -A firmware_before.elf > mem_before.txt
arm-none-eabi-size -A firmware_after.elf > mem_after.txt
diff mem_before.txt mem_after.txt

These three commands capture the section sizes of two firmware builds (before and after a change) into text files, then diff them to see what changed. This is useful but the raw diff output can be hard to read. The following script provides a cleaner view by computing the delta per memory region:

#!/bin/bash
# memory_diff.sh - Compare memory usage between two builds

echo "Memory Impact of Change:"
echo "========================"

parse_size() {
    arm-none-eabi-size -A "$1" | awk '
    /\.itcm/  { itcm += $2 }
    /\.dtcm/  { dtcm += $2 }
    /\.ddr/   { ddr += $2 }
    /\.stack/ { dtcm += $2 }
    END { printf "%d %d %d", itcm, dtcm, ddr }
    '
}

read itcm_before dtcm_before ddr_before <<< \((parse_size "\)1")
read itcm_after  dtcm_after  ddr_after  <<< \((parse_size "\)2")

printf "ITCM: %+d bytes (%d -> %d)\n" \
    \(((itcm_after - itcm_before)) \)itcm_before $itcm_after
printf "DTCM: %+d bytes (%d -> %d)\n" \
    \(((dtcm_after - dtcm_before)) \)dtcm_before $dtcm_after
printf "DDR:  %+d bytes (%d -> %d)\n" \
    \(((ddr_after - ddr_before)) \)ddr_before $ddr_after

This script takes two ELF files as arguments (the "before" and "after" builds). The parse_size function runs arm-none-eabi-size -A on the given ELF file and uses awk to sum up section sizes by memory region. Sections whose names contain .itcm are counted toward ITCM, sections containing .dtcm or .stack toward DTCM, and sections containing .ddr toward DDR. The main body reads the before and after values, then prints the delta for each region with a + or - sign.

Usage and output:

$ ./memory_diff.sh firmware_without_bt.elf firmware_with_bt.elf

Memory Impact of Change:
========================
ITCM: +63940 bytes (506996 -> 570936)
DTCM: +98832 bytes (628408 -> 727240)
DDR:  +64136 bytes (558779 -> 622915)

This output shows that adding the Bluetooth feature increased ITCM by about 62 KB, DTCM by about 96 KB, and DDR by about 62 KB. You can put this in your CI/CD pipeline so that every pull request shows exactly how much memory it costs.

Method 6: Automated Memory Budget Checks in CI

You can integrate memory profiling into your CI/CD pipeline to catch overflows before they land in your main branch.

#!/bin/bash
# memory_check.sh - Fail CI if memory usage exceeds thresholds

ITCM_LIMIT=85   # percent
DTCM_LIMIT=80
DDR_LIMIT=90

check_region() {
    local name=\(1 used=\)2 total=\(3 limit=\)4
    local percent=$((used * 100 / total))

    if [ \(percent -ge \)limit ]; then
        echo "FAIL: \(name usage is \){percent}% (limit: ${limit}%)"
        echo "      Used: \(used / \)total bytes"
        return 1
    else
        echo "OK:   \(name usage is \){percent}% (limit: ${limit}%)"
        return 0
    fi
}

ITCM_USED=\((grep "ITCM:" firmware.map | awk '{print \)2}')
ITCM_TOTAL=$((2 * 1024 * 1024))

DTCM_USED=\((grep "DTCM:" firmware.map | awk '{print \)2}')
DTCM_TOTAL=1572608

DDR_USED=\((grep "DDR:" firmware.map | awk '{print \)2}')
DDR_TOTAL=$((4 * 1024 * 1024))

FAILED=0
check_region "ITCM" \(ITCM_USED \)ITCM_TOTAL $ITCM_LIMIT || FAILED=1
check_region "DTCM" \(DTCM_USED \)DTCM_TOTAL $DTCM_LIMIT || FAILED=1
check_region "DDR"  \(DDR_USED  \)DDR_TOTAL  $DDR_LIMIT  || FAILED=1

exit $FAILED

This script reads memory usage numbers from the linker map file and compares them against configurable percentage thresholds. The check_region function takes a region name, the number of bytes used, the total bytes available, and the percentage limit. It computes the actual percentage and prints either "OK" or "FAIL" along with the numbers. If any region exceeds its limit, the script exits with a non-zero status, which causes the CI build to fail.

The thresholds at the top (85% for ITCM, 80% for DTCM, 90% for DDR) should be adjusted based on your project's growth rate and how much headroom you want to maintain. DTCM has a lower limit because it fills up faster and is harder to free up.

Add this script to your build pipeline so every pull request shows its memory cost. If a change pushes any region past its threshold, the build fails and the developer knows immediately.

Method 7: Heap Tracking at Runtime

If your embedded project uses dynamic memory allocation (malloc/free), you can wrap the allocator to track usage.

static size_t heap_used = 0;
static size_t heap_peak = 0;

void *tracked_malloc(size_t size) {
    size_t *block = (size_t *)malloc(size + sizeof(size_t));
    if (!block) return NULL;

    *block = size;
    heap_used += size;
    if (heap_used > heap_peak) {
        heap_peak = heap_used;
    }

    return (void *)(block + 1);
}

void tracked_free(void *ptr) {
    if (!ptr) return;
    size_t *block = ((size_t *)ptr) - 1;
    heap_used -= *block;
    free(block);
}

void print_heap_stats(void) {
    printf("Heap: current=%zu bytes, peak=%zu bytes\n",
           heap_used, heap_peak);
}

This code wraps malloc and free with tracking logic. The tracked_malloc function allocates slightly more memory than requested (an extra sizeof(size_t) bytes) and stores the requested size in the first word of the allocation. It then updates the heap_used counter and, if the new total exceeds the previous peak, updates heap_peak. It returns a pointer that's offset past the size header, so the caller sees a normal pointer to their data.

The tracked_free function reverses the process: it subtracts one size_t from the pointer to find the hidden size header, subtracts that size from heap_used, and calls the real free on the original block.

The print_heap_stats function prints the current and peak heap usage. Call it periodically or on demand through a debug interface (UART console, debug CLI) to monitor how much heap your firmware is using.

This approach has a small overhead (one extra word per allocation), but it gives you visibility into dynamic memory usage that's otherwise completely invisible. It's especially useful for tracking down memory leaks: if heap_used keeps growing over time without ever decreasing, something is allocating without freeing.

Summary

Embedded processors based on ARM Cortex-M and Cortex-R architectures give you direct control over three memory regions with very different performance characteristics.

ITCM (Instruction Tightly-Coupled Memory) stores your most performance-critical code. It provides single-cycle, deterministic instruction fetch. It's small (typically 512 KB to 2 MB), so reserve it for ISRs, real-time processing functions, and hot loops.

DTCM (Data Tightly-Coupled Memory) stores your most performance-critical data. It also provides single-cycle, deterministic access. Your stack lives here by default. It's even smaller than ITCM and fills up quickly, so be deliberate about what you place in it.

DDR (Double Data Rate) memory stores everything else. It's much larger but slower (5 to 20+ cycles per access, with variable latency). Use it for initialization code, large buffers, protocol stacks, and anything that doesn't need deterministic timing.

You control placement through __attribute__((section(...))) in your C code and section-to-region mappings in your linker script. You verify placement through map files, the size command, and runtime profiling techniques like stack watermarking. The core skill is knowing which region each piece of your firmware belongs in, and having the tooling to catch mistakes early.

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

Now look at your desk. Your wireless earbuds just connected to your phone. Your smartwatch is syncing health data. Your laptop found your Bluetooth keyboard in milliseconds. No one told these devices how to find each other. They just... figured it out.

That's not a coincidence. That's the same playbook.

In this article, I'm going to take you on a journey from ant colonies to Bluetooth stacks, from bee democracies to mesh networks. You'll see how nature solved the problem of "how do a million dumb agents work together without a boss?" long before we started slapping wireless radios into everything.

By the end, you'll never look at your earbuds the same way again.

Table of Contents

• What Even Is Swarm Intelligence?

• Nature's Greatest Hits: Swarms That Actually Work

• The Algorithms We Stole from Bugs

• A Quick Bluetooth Primer (I Promise It Won't Hurt)

• Bluetooth Is a Swarm and Nobody Told You

• BLE Mesh: The Ant Colony Living in Your Smart Home

• Where Bluetooth Breaks the Swarm Analogy

• What's Next: Swarms All the Way Down

• Wrapping Up

What Even Is Swarm Intelligence?

Let's start with the basics. Swarm Intelligence is the idea that a group of simple, "dumb" agents, each following a few basic rules, can collectively produce behavior that looks astonishingly smart.

No individual ant knows the fastest route to food. No single bee has the floor plan of the hive in its head. No starling has a GPS with "turn left at the oak tree." And yet, the group as a whole solves problems that would stump the smartest individual.

The term was coined in 1989 by Gerardo Beni and Jing Wang while they were working on cellular robotic systems at a NATO workshop in Tuscany (because apparently even robotics researchers need a good excuse to visit Italy). They described it as collective behavior emerging from simple agents interacting locally, no central command required.

The Four Pillars of Swarm Intelligence

Think of these as the cheat codes that nature figured out:

1. Decentralization: There's no boss. No CEO ant. No president bee. Every agent is autonomous and makes decisions based only on what it can see right around it.

2. Self-Organization: Order arises from the bottom up. Nobody designs the traffic pattern, it just happens because everyone follows the same simple rules.

3. Stigmergy: This is a fancy word (coined by French zoologist Pierre-Paul Grassé in 1959) that means "indirect communication through the environment." An ant doesn't call its friends and say "Hey, food over here!" It drops a chemical on the ground, and other ants respond to the chemical. The environment carries the message.

4. Emergence: The whole becomes greater than the sum of its parts. Individual ants are basically biological robots with a few simple instructions. A colony of millions of them can build climate-controlled cities, run supply chains, and wage wars. That's emergence.

If this sounds familiar, it should. Every time your devices discover each other, negotiate connections, and adapt to interference without you lifting a finger, that's these same principles at work.

Nature's Greatest Hits: Swarms That Actually Work

Before we get to Bluetooth, let's build our intuition with the OGs of swarm intelligence. Nature has been running these algorithms for millions of years, and honestly? They're still better than most of our software.

Ant Colonies: The Original Distributed System

Ants are nearly blind. They have brains smaller than a pinhead. Individually, an ant is about as smart as a thermostat. And yet, a colony of leafcutter ants, which can number 5 to 8 million workers, can excavate 40 tons of soil, build underground cities with climate control, and run the most efficient supply chain in the animal kingdom.

How? Two words: pheromone trails.

Here's the algorithm:

1. An ant leaves the nest and wanders randomly looking for food.

2. It finds food. Jackpot.

3. On the way back, it lays down a chemical trail, a pheromone, like breadcrumbs.

4. Other ants smell the trail and follow it.

5. When they find the food, they come back and lay more pheromone.

6. More pheromone = more ants = more pheromone. This is a positive feedback loop.

But here's the genius part: pheromone evaporates.

If a trail leads to food that's been depleted, ants stop walking it. The pheromone fades. The trail disappears. The colony redirects itself to new food sources, without anyone making the decision. That evaporation is negative feedback, and it prevents the system from getting stuck.

In 1990, researcher Jean-Louis Deneubourg proved this with an elegant experiment. He gave Argentine ants two bridges to food, one short, one long. At first, ants split roughly evenly. But ants on the shorter bridge completed round trips faster, so pheromone accumulated faster on that path. Within minutes, virtually all the ants were using the short bridge.

The colony had "computed" the shortest path. No calculus. No graph theory. Just chemistry and walking.

Honeybees: Democratic House Hunters

When a bee colony outgrows its hive, about 10,000 to 15,000 bees leave with the old queen and form a temporary cluster on a tree branch. They need a new home, fast.

Here's their process (studied in gorgeous detail by Cornell researcher Thomas Seeley, who wrote an entire book called Honeybee Democracy):

1. Several hundred scout bees (3-5% of the swarm) fly out to search for potential homes, like tree cavities, gaps in walls, or hollow logs.

2. Each scout evaluates what she finds: Is the cavity about 40 liters? Is the entrance small enough to defend? Is it off the ground?

3. Scouts return and perform the waggle dance (decoded by Karl von Frisch, who won a Nobel Prize for it in 1973). The angle of the dance tells direction relative to the sun. The duration tells distance, roughly 1 second of waggle = 1 kilometer. The intensity tells quality.

4. Other scouts check out the advertised sites. If they like what they see, they dance for it too. If not, they stop dancing.

5. Over hours, a quorum mechanism kicks in: when about 20-30 scouts are simultaneously present at a single site, the decision is made.

The result? The swarm picks the best available site about 80% of the time. That's better than most human committees.

No vote. No debate. No PowerPoint. Just dances and quorums.

Birds: Three Rules to Rule Them All

In 1986, computer graphics researcher Craig Reynolds asked a deceptively simple question: How do birds flock?

His answer was a simulation called "Boids" (bird-oid objects), and it used just three rules:

1. Separation: Don't crash into your neighbors. Maintain personal space.

2. Alignment: Fly in roughly the same direction as the birds near you.

3. Cohesion: Don't stray too far from the group. Stay close to the center of your neighbors.

That's it. Three rules. No leader bird. No flight plan. Each boid only sees its nearest 6-7 neighbors. And from those three trivial rules, beautiful, realistic flocking emerges.

Reynolds' model was so good that WETA Digital used a descendant of it to generate the epic battle scenes in The Lord of the Rings, hundreds of thousands of autonomous warrior agents fighting without individual choreography. Reynolds received a Scientific and Technical Academy Award in 1998 for his contributions.

Fish Schools: The Selfish Herd

Why do fish swim in schools of millions? It's not teamwork. It's selfishness.

W.D. Hamilton's Selfish Herd Theory (1971) explains it beautifully: each fish moves toward the center of the group to put other fish between itself and the predator. "I don't need to be faster than the shark, I just need you between me and the shark."

This selfish behavior produces coordinated movement. Fish detect neighbors through lateral line organs that sense pressure changes in the water, responding to neighbors' movements within milliseconds. The result: entire schools turn in unison, confusing predators with an information-overload effect.

The school is not cooperating. It's each member looking out for number one. And it works.

Termites: Architects Without Blueprints

Individual termites are a few millimeters long. Their mounds can reach 5 to 9 meters tall, proportionally equivalent to a human building a structure 1.5 kilometers tall.

These mounds contain sophisticated ventilation systems that maintain temperature within 1°C despite outside temperature swings of 40+ degrees. There's no architect. No blueprint. No foreman.

How? Stigmergy. A termite drops a mud pellet infused with pheromone. The pheromone attracts other termites to deposit their mud pellets nearby. Pellets accumulate. Pillars form. Pillars lean toward each other and become arches. Arches connect into tunnels.

From "drop mud where it smells" to climate-controlled skyscrapers. That's emergence.

The Algorithms We Stole from Bugs

Nature's been running these systems for millions of years. We've been copying them for about three decades. Here's the highlight reel:

Ant Colony Optimization (ACO) — 1992

Marco Dorigo looked at ant foraging and said, "I can turn that into an algorithm." His PhD thesis at Politecnico di Milano introduced Ant Colony Optimization, and it changed computational optimization forever.

How it works:

1. Release a bunch of virtual "ants" on a graph (nodes and edges).

2. Each ant builds a solution by walking the graph. At each step, the ant chooses the next node with probability proportional to pheromone level × heuristic desirability (for example, shorter distance = more desirable).

3. After all ants finish, deposit pheromone on edges proportional to solution quality (shorter total path = more pheromone).

4. Evaporate some pheromone from all edges.

5. Repeat.

The result: over many iterations, virtual pheromone accumulates on good paths, and the colony converges on near-optimal solutions.

Where it's used in the real world:

• Traveling Salesman Problem (the benchmark)

• Telecommunications routing — British Telecom explored ACO-based routing for their networks. AntNet (1998, by Di Caro & Dorigo) uses mobile software agents like artificial ants to adaptively route packets.

• Vehicle routing and logistics — optimizing delivery truck routes

• Airline crew scheduling

• Protein folding (yes, really)

Particle Swarm Optimization (PSO) — 1995

James Kennedy (a social psychologist) and Russell Eberhart (an electrical engineer) were originally trying to simulate bird flocking behavior. Instead, they accidentally invented one of the most popular optimization algorithms in history.

Each "particle" in the swarm flies through the search space, adjusting its velocity based on three things:

1. Inertia: Keep going in your current direction (momentum)

2. Personal best: Move toward the best solution you've ever found

3. Global best: Move toward the best solution anyone in the swarm has found

The elegant part: PSO can be implemented in about 20 lines of code, requires no gradient information, and works on problems where you can't even take a derivative. It's used for training neural networks, antenna design, power grid optimization, financial modeling – you name it.

The Others

• Artificial Bee Colony (ABC): Modeled on honeybee foraging, with employed bees, onlooker bees, and scout bees playing different roles.

• Firefly Algorithm: Brighter fireflies attract dimmer ones, naturally forming subgroups around multiple good solutions, perfect for problems with many local optima.

All of them follow the same recipe: simple agents + local rules + iteration = surprisingly good solutions.

A Quick Bluetooth Primer (I Promise It Won't Hurt)

Before we draw the swarm parallels, let's make sure we're on the same page about how Bluetooth actually works. I'll keep this painless.

The Basics

Bluetooth operates in the 2.4 GHz ISM band (the same band as Wi-Fi, microwaves, and that baby monitor from next door). It was originally designed for short-range cable replacement: think wireless headsets, keyboards, and file transfers between phones.

There are two main flavors:

• Bluetooth Classic (BR/EDR): Higher bandwidth, designed for continuous streaming (music, voice). Uses 79 channels, each 1 MHz wide.

• Bluetooth Low Energy (BLE): Lower power, designed for intermittent data exchange (sensors, beacons, smartwatches). Uses 40 channels, each 2 MHz wide.

How Devices Find Each Other

This is where it gets interesting. BLE devices discover each other through a process that's eerily similar to pheromone trails:

Advertising (The Pheromone):

• A device that wants to be found broadcasts short packets called advertisements on three specific channels (37, 38, and 39).

• These three channels are strategically placed in the gaps between the most popular Wi-Fi channels, already an engineered avoidance behavior.

• The device broadcasts every 20 ms to 10.24 seconds, depending on how urgently it needs to be found.

• Each broadcast has a tiny random delay (0-10 ms) added to prevent two devices from perpetually colliding, like fireflies slightly randomizing their flash timing.

Scanning (The Ant Following the Trail):

• A device looking for connections (the Central, typically your phone) listens on those advertising channels.

• It picks up the "pheromone", the advertising packet, and learns about the other device.

• If it wants more info, it can send a Scan Request, and the advertiser responds with additional data. This is like an ant touching antennae for a closer inspection after detecting pheromone.

Connection:

• The Central sends a CONNECT_IND packet saying "let's talk", and from that point, both devices synchronize clocks, agree on a hopping pattern across 37 data channels, and start exchanging data.

The Piconet: A Tiny Self-Organizing Flock

When devices connect, they form a piconet, the fundamental unit of Bluetooth networking. A piconet has:

• 1 Central (master): the device that initiated the connection

• Up to 7 active Peripherals (slaves): each assigned a 3-bit address

• Up to 255 parked devices: synced to the master's clock but not actively communicating (they can be swapped in when needed)

Here's the self-organizing part: nobody decides who's the master. The device that initiates discovery and connection naturally assumes the role. It's emergent role assignment, like how the bee that discovers food becomes the de facto leader others follow.

Multiple piconets can interconnect through bridge nodes, a device that participates in two piconets by time-slicing between them. This creates a scatternet, which is essentially a network of flocks connected through shared members. Sound familiar? It's how information spreads between different ant foraging groups.

Bluetooth Is a Swarm and Nobody Told You

Now we get to the good stuff. Let me show you the swarm intelligence principles hiding inside Bluetooth. Once you see them, you can't unsee them.

Adaptive Frequency Hopping: The Ant Colony of Radio

This is my favorite parallel, and it's hiding in plain sight.

The problem: Bluetooth shares the 2.4 GHz band with Wi-Fi, microwaves, baby monitors, and approximately 47 other things that also want to use it. If Bluetooth just sat on one frequency, it would get stepped on constantly.

The solution: Frequency Hopping.

Bluetooth Classic hops across 79 channels 1,600 times per second (every 625 microseconds). The hopping pattern is pseudo-random, seeded by the master's address and clock. An eavesdropper or interferer can't predict where the conversation will be next.

But basic hopping isn't enough. What if channels 40-50 are permanently trashed by a nearby Wi-Fi router? You'd hit interference 14% of the time.

Enter Adaptive Frequency Hopping (AFH):

1. Every device monitors channel quality — tracking packet error rates on each channel. This is the "ant exploring paths" step.

2. Channels are classified as Good, Bad, or Unknown. The master collects these assessments from all devices in the piconet, distributed sensing.

3. The master creates a channel map — a 79-bit bitmap saying which channels are safe. At least 20 channels must remain "good" (to maintain hopping diversity).

4. The hopping sequence adapts — when the pseudo-random sequence would land on a "bad" channel, the hop is remapped to a "good" one instead.

5. This runs continuously. When that microwave oven turns off, the previously bad channels recover, are reclassified, and re-enter the rotation.

Why this is swarm intelligence:

Replace "channels" with "foraging paths," "packet errors" with "empty food sources," and "the master's channel map" with "pheromone concentration", and you basically have ant colony foraging.

BLE Advertising: Pheromone Trails in Radio

The parallel between BLE advertising and pheromone trails is almost too perfect:

When your phone walks into a room and discovers your smart speaker, it's not because someone told your phone where the speaker is. The speaker has been laying down "pheromone", broadcasting advertising packets into the environment, and your phone's scanner picked up the trail.

That's stigmergy. Pierre-Paul Grassé would be proud.

BLE Mesh: The Ant Colony Living in Your Smart Home

If basic Bluetooth is a small flock of birds, Bluetooth Mesh is a full-blown ant colony. Standardized by the Bluetooth SIG in 2017, BLE Mesh takes the swarm analogy from "interesting metaphor" to "basically the same thing."

How Mesh Works: Managed Flooding

Traditional networks (your Wi-Fi, the internet) use routing: each message follows a pre-determined path from A to B, calculated by a router that knows the network topology.

Bluetooth Mesh says: "Nah. Let's just yell."

This approach is called managed flooding, and it works like a rumor spreading through a crowd:

1. Node A publishes a message. It broadcasts the message as a BLE advertising packet.

2. Every relay node within radio range hears it and rebroadcasts it. They don't know where the destination is. They don't care. They just pass it along.

3. Those nodes' neighbors hear it and rebroadcast again.

4. The message ripples outward like a stone dropped in a pond, until it reaches the destination or the TTL (Time To Live) expires.

Three mechanisms prevent this from becoming an infinite echo chamber:

• TTL: Each message starts with a TTL (0-127). Every relay decrements it by 1. When it hits 0, the message stops propagating. Like a rumor that loses energy with each retelling.

• Message Cache: Every node remembers recently-seen messages (by source address + sequence number). See a duplicate? Drop it silently.

• Sequence Numbers: A 24-bit counter ensures every message from a given source is unique.

This is almost identical to how ants propagate alarm signals. When one ant detects a predator, it releases alarm pheromone. Nearby ants detect it and release their own. A wave of alarm sweeps through the colony, no central nervous system needed. The signal naturally attenuates with distance (like TTL decrementing) and fades over time (like pheromone evaporation).

The Players in a Bluetooth Mesh

A mesh network has different node types, and they map surprisingly well to colony roles:

Publish-Subscribe: The Waggle Dance of Mesh

Bluetooth Mesh uses a publish-subscribe communication model that's remarkably similar to the honeybee waggle dance.

Here's how it works:

• Publishing: A node sends a message to a specific address. This can be a unicast address (one specific device) or a group address (like "Kitchen Lights" or "3rd Floor Sensors").

• Subscribing: Nodes subscribe to the addresses they care about. A kitchen light subscribes to "Kitchen Lights." A 3rd-floor smoke detector subscribes to "3rd Floor Sensors."

When a light switch publishes "turn on" to the "Kitchen Lights" group, the message floods through the mesh. Every node relays it, but only the kitchen lights act on it. All other nodes just relay and ignore the content.

This is the waggle dance. A forager bee dances in the hive (publishes) with information about a food source. Every bee in the hive can see the dance (the message floods). But only bees interested in foraging (subscribers) decode the message and fly to the source. The rest ignore it.

Broadcast the message widely. Let the interested parties self-select. No central dispatcher needed.

Real World: Silvair and the Swarm-Lit Warehouse

Silvair built what they describe as the largest Bluetooth Mesh lighting installation in the world. Their deployments include commercial offices and warehouses with thousands of luminaires, each one a mesh node.

Picture this: a warehouse floor with 500 lights. An occupancy sensor detects someone walking into Zone 3. It publishes a "turn on" message to the "Zone 3 Lights" group address. The message floods through the mesh. Every relay node passes it along. All lights subscribed to that group address turn on. If any relay node between the sensor and a distant light fails, the message reaches the light through alternative relay paths.

No server processed the command. No router calculated a path. No single point of failure. The system is robust precisely because it has no brain.

If that's not an ant colony, I don't know what is.

Self-Healing: What Happens When a Node Dies

In a traditional network, when a router fails, you call IT and panic.

In Bluetooth Mesh, when a relay node fails... nothing dramatic happens. Messages that used to flow through that node simply take alternative paths through other relay nodes. There are no routing tables to update, no convergence algorithms to run. The flooding mechanism inherently routes around the gap.

New nodes can be added and they immediately begin relaying, no reconfiguration of existing nodes needed.

This is identical to how an ant colony handles a blocked trail. Place an obstacle on an established path, and ants don't hold an emergency meeting. Individual ants encountering the obstacle explore alternatives, lay pheromone on the new paths, and within minutes, a new route emerges. The supply chain continues without a hitch.

This property, robustness through decentralization, is the single most important gift swarm intelligence gives to Bluetooth Mesh.

Where Bluetooth Breaks the Swarm Analogy

I've been painting a rosy picture, and honesty demands I point out where the analogy breaks down. Bluetooth borrows from swarm intelligence, but it's not a pure swarm system. Here's where it differs:

1. Managed Flooding ≠ Ant Colony Optimization

Bluetooth Mesh uses flooding: messages go everywhere, regardless of whether that path is "good" or not. True ACO gets smarter over time as pheromone accumulates on good paths. Bluetooth Mesh doesn't learn. It just yells louder.

This is a deliberate trade-off: flooding is simpler, more robust, and has lower latency for small control messages (like "turn on the light"). But it wouldn't scale to high-throughput data streaming. You wouldn't want to stream Spotify over managed flooding.

2. Provisioning Requires a Central Authority

When a new device joins a Bluetooth Mesh network, it goes through a provisioning process, and this step requires a Provisioner (typically your phone running an app). The Provisioner distributes cryptographic keys, assigns addresses, and authenticates the device.

This is a centralized bottleneck. An ant colony doesn't need a "queen" to approve new workers. A new ant just shows up and starts following pheromone. Bluetooth Mesh requires a human-operated onboarding step.

Once provisioned, the network operates in a decentralized fashion. But the front door has a bouncer.

3. AFH Isn't Fully Decentralized

In Adaptive Frequency Hopping, individual devices sense channel quality (distributed), but the master compiles and distributes the channel map (centralized). It's distributed sensing followed by centralized decision-making, more like "crowd-sourcing a report for the CEO" than "ants collectively choosing a path."

A true swarm would have each device independently avoiding bad channels without needing to agree on a shared map. Some research (like the eAFH algorithm from a 2021 paper) is moving in this direction.

4. The Hub Problem

Despite mesh being "flat," in practice, many Bluetooth Mesh deployments still rely on a few key relay nodes or proxy nodes. If those go down, the mesh might fragment. True swarm systems degrade more gracefully because every agent is truly interchangeable.

What's Next: Swarms All the Way Down

The convergence of swarm intelligence and wireless communication is just getting started. Here's where things are headed:

Smarter Mesh Routing

Research is exploring hybrid approaches where Bluetooth Mesh uses pheromone-like reinforcement on successful message paths, rather than pure flooding.

Imagine a mesh where frequently-used relay paths get "stronger" (prioritized) while rarely-used paths are deprioritized: true ACO applied to mesh routing.

Swarm Robotics and BLE

Harvard's Kilobot project (2014) demonstrated 1,024 tiny robots ($14 each) that self-organized into complex shapes using local interactions. Each Kilobot communicates with neighbors via infrared, but future swarm robots are increasingly using BLE for coordination.

When you combine BLE Mesh with swarm robotics, you get networks of devices that can physically move, reorganize, and self-heal in the real world.

DARPA's OFFSET program tested swarms of up to 250 autonomous drones working together in urban environments using similar principles – no central control, just local rules and emergence.

Multi-Agent AI Meets Wireless Swarms

The hottest trend in AI right now, multi-agent systems where multiple AI agents collaborate on tasks, draws heavily on swarm intelligence principles. Frameworks like OpenAI's Swarm borrow concepts like decentralized coordination and emergent behavior.

Now imagine combining this with BLE Mesh: a network of smart devices, each running a lightweight AI agent, collectively making decisions about your building's lighting, HVAC, and security without a central cloud server. Your smart home doesn't have a brain. It has an ant colony.

Bluetooth 6.0 and Beyond

Bluetooth continues evolving. Direction Finding (Bluetooth 5.1) enables sub-meter indoor positioning using Angle of Arrival/Departure techniques. Channel Sounding (Bluetooth 6.0) enables centimeter-level distance measurement.

These capabilities make Bluetooth devices even more "spatially aware", like ants with better antennae, enabling richer swarm-like behaviors based on precise location information.

Wrapping Up

Let's take a step back and appreciate what we've covered:

Nature solved the problem of decentralized coordination billions of years before we invented the transistor. Ants figured out shortest-path routing without Dijkstra. Bees built a consensus algorithm without Paxos. Birds invented distributed coordination without gRPC.

And Bluetooth? Whether by design or convergent evolution, it runs on the same playbook.

The next time your wireless earbuds connect to your phone in two seconds flat, with no help from you and no server in the cloud, tip your hat to the ants. They did it first.

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.")
    }
}