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.

The product requirement is identical on both platforms. The contracts underneath are opposites.

On iOS, Apple Push Notification service (APNs) updates a system-owned SwiftUI widget for you, and your app code never runs. On Android there's no system-managed remote update at all. A data-only Firebase Cloud Messaging (FCM) message wakes a background service, and your own code re-posts the notification every single time.

In this handbook you'll build both. You'll write one TypeScript API backed by two native implementations: a Swift one that talks to ActivityKit and a Kotlin one that talks to NotificationManager. You'll also write an APNs client and an FCM client from scratch, in about sixty lines each, with no libraries. And you'll learn the silent failure modes that make this API hard, because almost every mistake here produces no error at all.

I built a delivery-tracking demo called DropTrack to work through this. Everything below comes from that build, including a three-device Samsung investigation that ends with a screenshot of a hardcoded allowlist.

Table of Contents

1. Prerequisites

2. What Live Activities and Live Updates Actually Are

3. Where You Have Already Seen This Feature

4. Why You Need a Custom Native Module

5. How the iOS Contract Works

6. How to Build the Widget in SwiftUI

7. How to Bridge ActivityKit to JavaScript

8. Four iOS Gotchas That Cost Me an Evening Each

9. How to Drive iOS From a Server With APNs

10. How to Write an APNs Client From Scratch

11. How to Test on Real Hardware

12. Why Android Has No ActivityKit

13. How to Build the Kotlin Side

14. How to Drive Android From a Server With FCM

15. Three UX Gaps the Naive Implementation Leaves

16. How to Script the Simulators and Devices

17. How iOS and Android Compare

18. The Samsung Reality Check

19. The Demo Repository

20. What to Know Before You Start

21. Conclusion

22. Sources and Further Reading

Prerequisites

To follow along, you'll need:

• Node.js 20 or later.

• Xcode 26 or later, plus a paid Apple Developer account. APNs requires a real signing key and a device build. The simulator can't receive Live Activity pushes.

• Android Studio with an API 36 emulator built from a google_apis system image. Google Play services are required for FCM, and a bare Android Open Source Project image doesn't include them.

• A Firebase project, for the Android half.

• Working knowledge of Swift, Kotlin, and TypeScript. This is a native modules article, not a JavaScript-only one.

The versions I used throughout:

The androidx.core version isn't optional. Version 1.17.0 backports the Android 16 promotion APIs so they compile against base SDK 36. I'll explain why in a moment.

What Live Activities and Live Updates Actually Are

A Live Activity isn't a push notification. A notification is a fire-and-forget event. A Live Activity is a persistent, glanceable card with its own state that changes in place, a bounded lifetime, and dedicated system surfaces.

Here's where each platform landed:

• iOS 16.1 introduced lock-screen Live Activities. 16.2 added the Dynamic Island. 17.2 added push-to-start. 18 added broadcast channels. See Apple's ActivityKit documentation and the Live Activities Human Interface Guidelines.

• Android 16 (API 36) introduced Notification.ProgressStyle, the segmented progress bar.

• Android 16 QPR1 (API 36.1), the first Quarterly Platform Release, introduced the promotion pipeline: the status-bar chip and the elevated lock-screen slot. Google calls the whole feature progress-centric notifications.

I built DropTrack to exercise all of it. An order moves through seven steps, from "Order placed" to "Arriving now". A courier can be reassigned mid-run. The card is driven either locally from an in-app console or remotely from a push.

Where You Have Already Seen This Feature

Before any code, it helps to know why this API exists, because "a card on the lock screen" undersells it.

Think about the last time you ordered food. You place the order, lock your phone, and then what? Without a Live Activity, the app's only way to reach you is a push notification per state change. Order confirmed. Restaurant is preparing your food. Rider assigned. Rider is two stops away. Rider has arrived.

That's five notifications for one order. Multiply that by every order, and you've trained the user to mute you.

A Live Activity replaces all five with one card that mutates in place. Same information with one surface and no notification fatigue. That's the entire product argument.

Apple's own Human Interface Guidelines name the recurring use cases: sports scores, workouts, rides, and deliveries. Google's progress-centric notifications documentation converges on almost the same list, stating that "key use cases include rideshare, delivery, and navigation." That page even describes the delivery example in terms of progress points for food preparation and delivery milestones, and segments colored by traffic conditions, which is precisely the widget you're about to build.

Apps That Have Shipped it

Rather than repeat the roundup posts, I checked each app's own App Store listing, because a company describing its own feature is the strongest evidence available. Every app below states that it uses Live Activities in its own words:

Apple ships them in its own software, too. The Apple Sports support page says that with Live Activities turned on "you can get real-time information on your iPhone Lock Screen or your Apple Watch so that you can follow every moment of the game."

Two more are well documented by the technology press rather than by the companies themselves. Uber Eats rolled out Live Activities in May 2023, showing order status, estimated time of arrival, and the driver's name and photo. DoorDash followed in December 2023 with a real-time estimated time of arrival in the Dynamic Island.

Two honest caveats about that table. First, an app not mentioning Live Activities in its listing doesn't mean it lacks the feature, only that I couldn't confirm it first-hand. Uber Eats is exactly that case. Second, this reflects the listings as I read them, and any app can add or drop the feature in a release.

Food delivery is the canonical case, and it's what DropTrack models. Ride-hailing is the highest-stakes version: "driver arriving in 3 minutes", the plate number, the trip in progress, glanced at while you stand on a curb with a locked phone. The Dynamic Island's compact presentation exists almost for this: a glyph and a percentage read in half a second.

Finance is the case people forget, and it's where a segmented bar would earn its keep. A crypto deposit isn't "pending, then done". It's "3 of 12 network confirmations", which is a segmented progress bar with discrete steps, mapping cleanly onto ProgressStyle's segments and points and onto the SwiftUI capsules you will write below. The same shape fits a bank transfer clearing or a card payment settling.

I want to be careful here, though: I checked the App Store listings for the major exchanges and neobanks and found none that documents a Live Activity. Treat this one as an obvious fit that the category hasn't yet taken up, not as prior art.

Here's the table I wish someone had shown me before I started:

Look at the third column. In every commercially interesting case the update is driven by your server, not by the device. That means the entire value of the feature lives in the push path. And the push path is exactly where the two platforms diverge, where the failures are silent, and where most of this handbook's pain is concentrated.

The pretty SwiftUI card is the easy half. Getting a backend to reliably mutate that card while the app is dead is the hard half, and it's different on each platform.

Why You Need a Custom Native Module

Before writing a line of Swift, I evaluated the shortcuts. Both fail, for instructive reasons.

expo-live-activity ships a predefined widget layout and a fixed content-state shape. DropTrack needs a custom segmented progress bar, a rider-reassignment treatment, and its own Dynamic Island layouts. All of those require owning ActivityAttributes and the SwiftUI that renders it. You reach first render fastest, and then you eject.

Notifee, the notification library most React Native developers reach for, is archived. As of this writing its GitHub repository is marked archived, its last published release was @notifee/react-native@9.1.8 in December 2024, and its Android module still targets compileSdk 34. It has no Live Updates support. A custom module is currently the only React Native route to Android 16 Live Updates.

So: one local Expo module, one TypeScript API, two native backends.

modules/droptrack-live/
├── expo-module.config.json   ← autolinking (apple + android)
├── index.ts                  ← the public JS API
├── src/                      ← TS types, native binding, web no-op
├── ios/
│   ├── DeliveryAttributes.swift    ← the ActivityKit contract
│   └── DroptrackLiveModule.swift   ← JS to ActivityKit
└── android/
    ├── DroptrackLiveModule.kt      ← JS to NotificationManager
    ├── DeliveryNotifier.kt         ← the shared notification builder
    └── DroptrackFcmService.kt      ← push to NotificationManager

The JavaScript surface is deliberately small, and identical across platforms:

// The dynamic half of the card: every update replaces this object wholesale.
// Keep it small. iOS rejects an ActivityKit push payload over 4 KB.
export type DeliveryState = {
  status: string;           // free text shown as the headline: "Picked up"
  progress: number;         // 0.0 to 1.0, drives the bar on both platforms
  etaEpochMillis: number;   // Unix ms, the shape JS speaks. Swift converts it.
  stopsRemaining: number;   // renders as "2 stops away" / "you're next"
  courierName: string;      // dynamic, because riders get reassigned mid-run
  riderReassigned: boolean; // flips the courier row to the "new rider" style
};

// Three verbs, mirroring the ActivityKit lifecycle. Android fakes the same
// shape with notify / notify / cancel, so callers never branch on platform.

// Starts the activity and returns the system-assigned id. Hold on to it:
// every later call needs it, and it does NOT survive an app restart.
startDelivery(info: DeliveryInfo, state: DeliveryState): Promise<string>;

// Replaces the ContentState in place. The card mutates, it does not re-appear.
updateDelivery(id: string, state: DeliveryState): Promise<void>;

// Final state, then dismissal. Omit dismissAfterSeconds to let the card linger.
endDelivery(id: string, state: DeliveryState, dismissAfterSeconds?: number): Promise<void>;

isSupported(): boolean;          // false on iOS < 16.2, Android < 16, and web
areActivitiesEnabled(): boolean; // false if the USER switched them off in Settings

Those last two are separate on purpose. A device can support Live Activities while the user has switched them off in Settings, and only areActivitiesEnabled() catches that. Activity.request throws in that case, so startDelivery throws too.

The dismissAfterSeconds argument maps onto ActivityKit's dismissal policy. Under the default policy, Apple's documentation says "the system keeps a Live Activity that ended on the Lock Screen for up to four hours after it ends." Passing a value shortens that window.

This project uses Expo's Continuous Native Generation (CNG), which means the ios and android folders are generated by prebuild and aren't committed. Every line of native code therefore lives in the module or in a config plugin, so it survives prebuild --clean. The widget extension itself is generated by @bacons/apple-targets for the same reason.

One structural detail matters later: the module compiles as its own CocoaPod, not into the app target.

How the iOS Contract Works

An ActivityKit activity is split in two. ActivityAttributes holds static data, set once and never changed. Its nested ContentState holds the dynamic half, which every update replaces wholesale.

Most tutorials state that rule and move on. It's worth understanding why the platform forces it, because the reason tells you exactly which half any given field belongs in.

Why the Split Exists

The split isn't a style convention. It's about what can physically cross the wire.

When you call Activity.request(...), you hand ActivityKit two things at once: the attributes and the first content state. The system files the attributes away and never accepts a new copy of them. From that moment on, the only thing you can ever send is a new ContentState.

You can see this in the shape of an ActivityKit push payload. Here's what my APNs client actually transmits:

aps: {
  // Older-than-last timestamps are discarded by APNs (ordering guard).
  timestamp: Math.floor(Date.now() / 1000),
  event,                        // "update" or "end"
  'content-state': contentState, // the only field that carries data
}

There is no attributes key. There can't be one. Nothing in the payload can reach the static half.

So "should this field be static or dynamic?" is really the question "will my server ever need to change this value?" If the answer is yes, the field must live in ContentState, because that's the only thing a push can move.

That's the whole design. ActivityAttributes is the activity's identity, fixed at birth. ContentState is its current reading, replaced wholesale on every update rather than patched. Send a content state that omits a field and you haven't left that field alone, you've failed to decode. The Codable conformance is what lets the system serialize the state across a process boundary, and the Hashable conformance lets it tell whether an incoming state actually differs from the one already on screen.

The Bet I Lost

Here's what I wrote first. It looks reasonable:

// BEFORE: courierName is static. This compiles, ships, and works fine,
// right up until a dispatcher reassigns the rider mid-delivery.
struct DeliveryAttributes: ActivityAttributes {
  public struct ContentState: Codable, Hashable {
    var status: String
    var progress: Double
    var eta: Date
    var stopsRemaining: Int
  }
  var orderId: String
  var courierName: String   // the bet: a delivery has one courier
}

Putting a field in the static half is a bet that it can never change for the activity's lifetime. I bet that a delivery has one courier. Then I built rider reassignment, where a dispatcher swaps the courier mid-run, and the bet came due.

Because courierName was static, there was no way to express the change. Not through activity.update(), not through a push, not at all. The only escape would have been to end the activity and start a new one, which means the card disappears from the lock screen and returns as a different card, mid-delivery. That's not a fix, it's a regression.

So the field moved:

// AFTER: only orderId is genuinely immutable. Everything a dispatcher
// can change lives in ContentState, because ContentState is the only
// thing an APNs push can carry.
struct DeliveryAttributes: ActivityAttributes {
  public struct ContentState: Codable, Hashable {
    /// Human-readable status, e.g. "Picked up", "2 stops away"
    var status: String
    /// Overall delivery progress, 0.0 ... 1.0
    var progress: Double
    /// Estimated arrival time
    var eta: Date
    /// Stops before the courier reaches the user
    var stopsRemaining: Int
    /// Courier display name, dynamic since riders can be reassigned mid-run
    var courierName: String
    /// True right after a reassignment, drives the "new rider" treatment
    var riderReassigned: Bool
  }

  /// Order identifier shown on the card, the only truly immutable fact
  var orderId: String
}

Moving one field touched twelve files, because the contract is duplicated at every layer that has to encode or decode it:

9  DeliveryNotifier.kt          Android notification builder
3  DroptrackLive.types.ts       the TypeScript contract
3  DroptrackLiveModule.swift    the Swift bridge record
3  App.tsx                      React state and the push handler
2  DeliveryLiveActivity.swift   the widget's SwiftUI
2  DeliveryAttributes.swift     the module's copy
2  DeliveryAttributes.swift     the widget's copy (yes, twice)
2  DroptrackLiveModule.kt       the Kotlin bridge record
1  DroptrackFcmService.kt, dispatch-server.mjs, push-update.mjs,
   apns.test.mjs, delivery.ts

The asymmetry here is what matters. A dynamic field you never change costs you a few bytes in every push. A static field you need to change costs you the entire stack. When in doubt, put the field in ContentState. In the end, only orderId earned its place in the static half.

The Identical-Copy Trap

The widget extension is a separate binary. It's a different process, launched by the system, that doesn't link your app's code. Your app target compiles the module's DeliveryAttributes.swift. The widget target compiles its own. Two compilations produce two independent types that merely share a name.

At runtime, ActivityKit has to connect them. Your app says "start an activity of type DeliveryAttributes", and the system asks the widget whether it has a WidgetConfiguration for a type by that name whose ContentState decodes this data. The match is structural, on the type's name and its Codable shape, performed by a system daemon, at runtime, across a process boundary.

Now rename courierName to riderName in one copy and forget the other. The app compiles. The widget compiles. Both are internally consistent. Activity.request() succeeds and returns an id. But when the system hands the encoded state to the widget, the widget's decoder looks for riderName, doesn't find it, and throws inside a daemon in another process, where your breakpoints and your log statements don't exist.

The card never appears. No crash, no warning, no console line, and Activity.activities still lists the activity as running. You'll spend an hour on your SwiftUI layout, and the layout was never the problem.

Two things follow. A shared source file doesn't save you, because the module compiles as its own CocoaPod rather than into the app target, so no build phase naturally covers both. And since the compiler will never catch this, the check has to be external:

diff modules/droptrack-live/ios/DeliveryAttributes.swift \
     targets/widgets/DeliveryAttributes.swift

If that command ever prints anything, your Live Activity is already broken. It costs nothing to wire into a pre-commit hook, and it's the single highest-value guardrail in this project.

How to Build the Widget in SwiftUI

The widget declares one Widget with two presentations: the lock-screen card and the Dynamic Island.

Before reading the code, hold one idea in your head: these closures are a pure function from state to view. The widget extension isn't a running program. The system launches the process, calls your closure with the current ContentState, keeps the rendered result, and kills the process.

When a push delivers a new state, it runs the closure again. There's no @State, no timer, no network call, and no onAppear doing work. That's also why widget extensions have no network access: there's nobody home to make a request.

Two things about the type signature before the code. Widget is a WidgetKit protocol, not a SwiftUI View, and body returns some WidgetConfiguration, not some View. You're not describing pixels, you're declaring what kind of widget this is.

And the for: argument on line 3 is the binding point from the previous section: this is the exact spot where the app's DeliveryAttributes and the widget's copy are matched by name and Codable shape, so it's where the identical-copy trap either works or silently fails.

struct DeliveryLiveActivity: Widget {
  var body: some WidgetConfiguration {
    ActivityConfiguration(for: DeliveryAttributes.self) { context in
      // Closure 1 of 2: the lock screen and banner.
      DeliveryCardView(context: context)
        .activityBackgroundTint(Color(red: 0.07, green: 0.07, blue: 0.12))
        .activitySystemActionForegroundColor(.white)

    } dynamicIsland: { context in          // closure 2 of 2, labelled
      DynamicIsland {
        // Expanded (long-press): four named slots, arranged around the cutout.
        DynamicIslandExpandedRegion(.leading) {
          Image(systemName: "bicycle").foregroundStyle(brandOrange)
        }
        DynamicIslandExpandedRegion(.trailing) {
          Text(context.state.eta, style: .time).font(.callout.bold())
        }
        DynamicIslandExpandedRegion(.center) {
          Text(context.state.status).font(.callout.weight(.semibold)).lineLimit(1)
        }
        DynamicIslandExpandedRegion(.bottom) {
          VStack(spacing: 4) {
            SegmentedProgressBar(progress: context.state.progress)
            HStack {
              CourierLabel(state: context.state, compact: true)
              Spacer()
              Text(stopsLabel(context.state.stopsRemaining))
            }
            .font(.caption2).foregroundStyle(.secondary)
          }
        }
      } compactLeading: {                   // the default pill, left of the cutout
        Image(systemName: "bicycle").foregroundStyle(brandOrange)
      } compactTrailing: {                  // ...and right of it
        Text("\(Int(context.state.progress * 100))%").font(.caption2.bold())
      } minimal: {                          // when another app shares the island
        Image(systemName: "bicycle").foregroundStyle(brandOrange)
      }
      .keylineTint(brandOrange)
    }
  }
}

That's one state object rendered four ways, and a few of the choices are load-bearing:

• The two closures: ActivityConfiguration takes a content closure and a dynamicIsland: closure. The bare-then-labelled form is Swift's multiple-trailing-closure syntax, not two separate statements. The first is the lock-screen and banner card, and the second is every Dynamic Island form.

• context: Each closure receives context.state, the dynamic ContentState replaced on every update, and context.attributes, the static half, read exactly once, for the order id on the card.

• The two .activity… modifiers: These are ActivityKit-specific, not general SwiftUI. You don't draw the system's swipe-to-end chrome, so all you can do is tint it.

• eta, style: .time renders a localized clock time such as "5:42 PM", honouring the user's 12- or 24-hour setting. It's not a countdown. A ticking countdown would use style: .timer, which the system animates with no push at all, which is how a timer-style activity stays live with zero server traffic.

• lineLimit(1) isn't decoration. The centre slot is a few dozen points wide, and an unbounded status string wraps and wrecks the layout. The bar lives in .bottom for the opposite reason: it's the only region wide enough.

• .font and .foregroundStyle on the HStack apply to both children through SwiftUI's environment, and a child's explicit modifier still wins over the inherited one, which is how CourierLabel overrides the colour on a reassignment.

• Int(progress * 100) truncates rather than rounds, so 0.999 would render as "99%". The scripted steps end on exactly 1.0 so it lands on 100, but server-computed progress would want .rounded().

• minimal is the presentation people forget. When another app's activity is also running, the island shrinks yours to a single circle. Skip it and your activity looks broken whenever a timer is going. keylineTint sets the glow the system draws around the whole island on update.

The Segmented Progress Bar

The capsule bar is an HStack of rounded rectangles. ContentState carries progress as a double rather than a step index, so the widget derives how many segments to fill.

private struct SegmentedProgressBar: View {
  let progress: Double
  var segments: Int = 7   // one capsule per delivery step

  // ContentState carries a 0...1 fraction, never a step index, so the bar has
  // to work backwards to a segment count. Keeping the wire format numeric means
  // the widget never needs to know what the seven steps are called.
  private var filled: Int {
    // Clamp first: a server that sends 1.4 must not paint 10 of 7 segments.
    let clamped = min(max(progress, 0), 1)
    // .rounded(.up) so a step that has merely BEGUN already lights its capsule.
    // progress 0.05 * 7 = 0.35 -> ceil -> 1 segment lit, not 0.
    // The outer min() guards the exact 1.0 case against a 8th segment.
    return min(segments, Int((clamped * Double(segments)).rounded(.up)))
  }

  var body: some View {
    HStack(spacing: 5) {
      // ForEach over a constant range, so `id: \.self` on the index is safe.
      ForEach(0..<segments, id: \.self) { i in
        RoundedRectangle(cornerRadius: 3, style: .continuous)
          // The only stateful decision in the whole view: lit, or track colour.
          .fill(i < filled ? brandOrange : trackGray)
          // Fixed height, no width: the HStack divides the width evenly, so the
          // same view fits the wide lock-screen card and the narrow island.
          .frame(height: 7)
      }
    }
  }
}

With progress values of 0.05, 0.15, 0.35, 0.55, 0.7, 0.85, 0.95, and 1.0, rounding progress * 7 upward fills one through seven segments in lockstep with the steps. The same view renders on the lock-screen card and inside the expanded island, so the component reads as one thing across surfaces.

The Reassignment Treatment

Reassignment is an in-place update: same activity id, same step, new courierName, and riderReassigned set to true. The courier row swaps its icon and copy.

// Shared by the lock-screen card and the expanded island, so a reassignment
// reads identically wherever the user happens to be looking.
private struct CourierLabel: View {
  let state: DeliveryAttributes.ContentState
  let compact: Bool   // true inside the island, where horizontal space is scarce

  var body: some View {
    // Both branches are driven purely by ContentState. No local state, because
    // the widget process does not live long enough to hold any.
    if state.riderReassigned {
      Label(
        // The island cannot fit "New rider · Tunde", so it drops the prefix and
        // leans on the swap icon plus the orange tint to carry the meaning.
        compact ? state.courierName : "New rider · \(state.courierName)",
        systemImage: "arrow.triangle.2.circlepath"
      )
      // An explicit style on the child overrides the .secondary the parent
      // HStack pushed down through the environment. This is what makes the
      // swapped rider the one thing on the card that draws the eye.
      .foregroundStyle(brandOrange).bold()
    } else {
      // Steady state: inherits the parent's caption font and secondary colour.
      Label(state.courierName, systemImage: "bicycle")
    }
  }
}

Advancing a step retires the badge. That's the whole feature, and the reason courierName had to leave the static half.

How to Bridge ActivityKit to JavaScript

Expo's Record type gives you type-safe bridging. Expo validates the JavaScript object against these fields before your function body runs.

// A Record is Expo's typed bridge struct. Every @Field is decoded out of the
// JS object BEFORE your function body runs, so a missing or wrong-typed key
// fails at the boundary with a clear error rather than deep inside Swift.
// The defaults are what a field falls back to when JS omits it.
struct DeliveryStateRecord: Record {
  @Field var status: String = ""
  @Field var progress: Double = 0
  @Field var etaEpochMillis: Double = 0   // Double, not Int: JS numbers are f64,
                                          // and epoch ms overflows Int32.
  @Field var stopsRemaining: Int = 0
  @Field var courierName: String = ""
  @Field var riderReassigned: Bool = false

  // The bridge type and the ActivityKit type are deliberately NOT the same
  // struct. This function is the single place the two vocabularies meet.
  @available(iOS 16.2, *)
  func toContentState() -> DeliveryAttributes.ContentState {
    DeliveryAttributes.ContentState(
      status: status,
      // Clamp at the boundary, so no downstream view has to defend itself.
      progress: min(max(progress, 0), 1),
      // JS speaks Unix milliseconds; Foundation.Date wants seconds. Divide once,
      // here, rather than scattering /1000 through the codebase.
      eta: Date(timeIntervalSince1970: etaEpochMillis / 1000),
      stopsRemaining: stopsRemaining,
      courierName: courierName,
      riderReassigned: riderReassigned
    )
  }
}

And the module itself:

AsyncFunction("startDelivery") { (info: DeliveryInfoRecord, state: DeliveryStateRecord) -> String in
  // Runtime OS guard: the module compiles against older targets, so this is
  // what stops it calling into a framework that isn't there.
  guard #available(iOS 16.2, *) else { throw LiveActivityUnsupportedException() }

  let activity = try Activity.request(
    attributes: DeliveryAttributes(orderId: info.orderId),                  // static half, set once
    content: ActivityContent(state: state.toContentState(), staleDate: nil), // dynamic half
    pushType: .token                                                        // ask APNs for a token
  )
  return activity.id   // the only handle JS gets, and the one it forgets on reload
}

AsyncFunction("updateDelivery") { (activityId: String, state: DeliveryStateRecord) in
  let activity = try Self.findActivity(id: activityId)
  // .update() replaces the whole ContentState. There is no partial-patch API.
  await activity.update(ActivityContent(state: state.toContentState(), staleDate: nil))
}

A few notes on the arguments, so they stay out of the code. AsyncFunction (rather than Function) is what makes the JS side a Promise, and Expo infers the rest of the signature from the parameter types.

staleDate: nil means the card is never marked stale. Pass a date and, once it passes, the system flips the activity's state so your widget can read context.isStale and render a degraded view, but it doesn't grey the card out for you.

And pushType: .token is what asks APNs for a per-activity token, where passing nil instead gives you a purely local activity that no server can update.

Notice findActivity. Activities are looked up fresh by id on every call rather than cached in a property, because activity handles live inside ActivityKit, not in your process. That distinction matters enormously, as the next section shows.

@available(iOS 16.2, *)
private static func findActivity(id: String) throws -> Activity<DeliveryAttributes> {
  // `Activity.activities` is a live, system-owned list. It survives an app
  // relaunch, a JS reload, and a process kill. Caching a handle in a Swift
  // property would not, which is precisely why this lookup runs every time.
  guard let activity = Activity<DeliveryAttributes>.activities.first(where: { $0.id == id }) else {
    // Reached when the user swiped the card away, or the activity aged out.
    throw ActivityNotFoundException(id)
  }
  return activity
}

Four iOS Gotchas That Cost Me an Evening Each

Each of these wasted an evening because the failure looked like a bug in my code when it was really a quirk of the platform. They share a shape, so I've written each one the same way: the symptom you see, why it happens, and what to do about it.

Gotcha 1: The Compact Island Looks Broken

You build the compact Dynamic Island, run the app, and it never appears.

This happens because the compact presentation is hidden while your own app is in the foreground. This is by design, but nothing tells you so, and I spent twenty minutes certain my layout was wrong.

To fix this, lock the device, or switch to another app, before you judge whether the island works. There's nothing to fix in the code.

Gotcha 2: An Old Activity Renders Nothing After a Rebuild

You change the widget, rebuild, and an activity that was already running goes blank. No error appears anywhere.

This happens when an activity is tied to the exact build that started it. Once you rebuild the widget extension, the running activity no longer matches the code on the device.

To fix this, after any change to the widget extension, end the stale activity and start a fresh one. Don't expect a warning to remind you.

Gotcha 3: Reinstalling Can Jam the System Daemon

Right after simctl install, your first activity refuses to render. Activity.activities says it's active, yet the screen shows nothing.

This happens because Live Activities are drawn by a background system process called chronod. A reinstall can leave it wedged: in my case it threw widgetDescriptorNotFound and logged internal errors, and no amount of ending and restarting the activity cleared it.

This is a fault in the daemon, not in your app, which is why the usual checks mislead you. Listing the extension with pluginkit -m shows it present and healthy while the daemon behind it is stuck.

To fix this, reboot the simulator with simctl shutdown && boot, then start a fresh activity.

Gotcha 4: Tapping the Card Opens an App That Forgot Everything

This is the subtle one, the most visible to users, and the reason for the next two code samples.

The user taps the live card to open your app. The app launches into an empty screen that insists nothing is being tracked, every control disabled, while the card sits right there on the lock screen still updating.

This happens because tapping the card cold-starts the app, which means your JavaScript begins from scratch. The activity id lived in React state, and that state died with the previous process.

The activity itself is completely fine: Activity.activities still lists it, and an APNs push to it still returns 200. (A dead activity returns 410, which makes a handy liveness probe.) The app simply forgot the id it needs to reconnect.

To fix this, stop treating your in-memory id as the source of truth, and ask the system what is running on launch. Expose the live activities to JavaScript.

AsyncFunction("getRunningActivities") { () -> [[String: Any]] in
  guard #available(iOS 16.2, *) else { return [] }

  // The system's list, populated even on a brand-new process. That is the point.
  return Activity<DeliveryAttributes>.activities.map { activity in
    self.observePushToken(of: activity)   // resubscribe: see note below
    let state = activity.content.state    // the live state, kept current by push
    return [
      "activityId": activity.id,                // the handle JS lost
      "orderId": activity.attributes.orderId,   // the static half
      "status": state.status,
      "progress": state.progress,
      "courierName": state.courierName,
      "riderReassigned": state.riderReassigned,
    ]
  }
}

That observePushToken call is the line everyone misses. The for await loop watching this activity's push token died with the previous process, so without resubscribing here the card recovers. But the server never learns the token again after a rotation, and pushes quietly stop landing.

Then rehydrate on mount, and again on every foreground, because a push that lands while you're backgrounded updates the widget without running your JavaScript at all. React Native's AppState gives you the hook.

useEffect(() => {
  const sync = () => {
    void DroptrackLive.getRunningActivities().then((running) => {
      const activity = running[0];
      if (!activity) return;   // nothing running: leave the empty state alone

      setActivityId(activity.activityId);   // this line re-enables the whole UI
      setRider({ name: activity.courierName, justReassigned: activity.riderReassigned });

      // The card carries a status string, not a step index. Guard the -1.
      const index = STEPS.findIndex((s) => s.status === activity.status);
      if (index >= 0) setStepIndex(index);
    });
  };

  sync();   // case 1: cold start (e.g. the user tapped the card and we launched)
  const sub = AppState.addEventListener("change", (s) => {
    if (s === "active") sync();   // case 2: resume from background
  });
  return () => sub.remove();
}, []);

The whole tracking interface is gated on activityId, so restoring it is what turns the app back on. Miss that one line and the app looks dead while the card is live on the lock screen.

The two call sites cover the two ways state goes stale. sync() on mount handles a cold start, and the AppState listener handles a resume, because the mount effect won't re-run and a push may have advanced the card while you were backgrounded without executing any JavaScript. The empty dependency array means this wiring is set up once, for the app's lifetime.

That last gotcha generalises into the sentence I wish I'd read first: Live Activities are owned by the system, not by your process. The API hands you an activity id and it's easy to assume the id is yours to keep. It's not. The activity outlives the variable, and the moment a user is most likely to open your app, by tapping the live card, is precisely the moment your in-memory copy of that id doesn't exist.

How to Drive iOS From a Server With APNs

Here's the payoff: updating the card while the app is fully force-quit. The API surface is almost insultingly small. You change one argument. Apple documents the flow in Starting and updating Live Activities with ActivityKit push notifications.

let activity = try Activity.request(
  attributes: attributes,
  content: ActivityContent(state: state.toContentState(), staleDate: nil),
  pushType: .token   // this was `nil`. That is the entire feature.
)

Task {
  for await tokenData in activity.pushTokenUpdates {
    let token = tokenData.map { String(format: "%02x", $0) }.joined()   // raw Data -> hex
    NSLog("[DropTrack] push token for %@: %@", activity.id, token)       // NSLog, so devicectl sees it
    self.sendEvent("onPushTokenReceived", ["activityId": activity.id, "token": token])
  }
}

pushTokenUpdates is an AsyncSequence, not a one-shot getter, which is why this is a for await loop and not a single read. Reading activity.pushToken right after request() reliably returns nil, because the token hasn't arrived from APNs yet, and it can also rotate mid-flight.

The token arrives as raw Data, so it's hexed before use. It's logged with NSLog rather than print because a standalone Release build has no Metro to receive console.log, and NSLog is what devicectl --console surfaces. And the token is per-activity, so it's keyed by activity id when handed to JS rather than stored globally.

Everything after that is plumbing, and two pieces of it fail without a single error message.

pushType: .token does nothing without the aps-environment entitlement. Activity.request still succeeds. Local updates still work. The token stream simply never yields. Nothing logs. Add the entitlement in app.json:

"ios": {
  "entitlements": {
    "aps-environment": "development",
    "com.apple.security.application-groups": ["group.com.fasarticle.droptrack"]
  }
}

Two notes on those values, since app.json can't carry comments. aps-environment set to development means your tokens are only valid against api.sandbox.push.apple.com. A shipping build needs production, and mixing the two produces an afternoon of BadDeviceToken. The application group is the shared container between the app and the widget extension, and both targets must carry the identical group id or shared reads silently return nothing.

Then verify that the entitlement survived signing, because an entitlement in your config isn't the same as an entitlement in your binary:

# Reads the entitlements actually baked into the signed .app.
# If aps-environment is absent here, the token stream will never yield,
# no matter what app.json says.
codesign -d --entitlements - --xml Build/Products/Release-iphoneos/DropTrack.app

The push token is per-activity, not per-device. It arrives asynchronously after request() returns, and the system can rotate it mid-flight. Consume the pushTokenUpdates async sequence. A single read of activity.pushToken immediately after request() is reliably nil. Every startDelivery mints a brand-new token. I verified that by starting two activities and comparing the hex.

How to Write an APNs Client From Scratch

You don't need a library. Two Node.js built-ins and about sixty lines will do it.

Sending one push comes down to three steps. First, sign a token that proves the request is really from you. Second, open a connection to Apple and attach a precise set of headers. Third, send the state you want the card to show. The rest of this section walks each step, then covers the two ways it fails silently.

One thing to get out of the way first: APNs speaks HTTP/2 only, so fetch() can't reach it. You need Node's node:http2 module, which is why this is written by hand rather than as a fetch call.

Step 1: Sign a Token That Proves Who You Are

APNs won't accept a push until you prove you own the app. You do that with an ES256 JSON Web Token, signed by the .p8 key you download from Apple, following Establishing a token-based connection to APNs. A JWT is just three base64url chunks joined by dots: a header, a claims object, and a signature over the first two.

import { createPrivateKey, sign } from "node:crypto";

const b64url = (buf) => Buffer.from(buf).toString("base64url");   // JWT uses base64url, not base64

export function mintJWT({ keyPath, keyId, teamId }) {
  const header = b64url(JSON.stringify({ alg: "ES256", kid: keyId }));   // kid: the 10-char key id
  const claims = b64url(JSON.stringify({ iss: teamId, iat: Math.floor(Date.now() / 1000) }));
  const signingInput = `${header}.${claims}`;   // a JWT signs header AND claims joined

  const signature = sign("sha256", Buffer.from(signingInput), {
    key: createPrivateKey(readFileSync(keyPath, "utf8")),
    dsaEncoding: "ieee-p1363",   // THE line. The default (DER) fails silently. See below.
  });

  return `${signingInput}.${b64url(signature)}`;
}

That one dsaEncoding line is the whole reason to write this by hand rather than trust a snippet off the internet.

Node signs in DER format by default, which wraps the signature's two halves in an envelope, but the JWT standard (RFC 7518) wants those two halves raw and joined. Use the wrong one and APNs answers 403 InvalidProviderToken, which reads like your key is bad and sends you re-downloading the .p8 for an hour, when the key was fine all along.

Two smaller details. kid is the ten-character key id (it is in the .p8 filename), and it tells APNs which of your registered keys should check the signature. And the iat timestamp can't be more than an hour old, per Apple, which also asks you to refresh it no more than once every 20 minutes, so cache the token instead of minting a fresh one for every push.

Step 2: Open the Connection and Send the Push

With the token in hand, open an HTTP/2 session to the APNs host and make one POST. The headers have to be exact, and the one people get wrong is the topic: it's your bundle id with .push-type.liveactivity appended, not the bundle id on its own.

// Pseudo-headers (":method", ":path") are HTTP/2's way of encoding the request
// line. `client` here is an http2 session opened against the APNs host.
const req = client.request({
  ":method": "POST",
  // The device token in the path is the PER-ACTIVITY token, not a device token
  // from UNUserNotificationCenter. Those are different values entirely.
  ":path": `/3/device/${token}`,
  authorization: `bearer ${jwt}`,   // lowercase "bearer" is what APNs expects

  // Live Activity pushes get a SUFFIXED topic. Send the bare bundle id and
  // APNs rejects the request outright.
  "apns-topic": `${bundleId}.push-type.liveactivity`,
  "apns-push-type": "liveactivity", // must match the topic suffix
  "apns-priority": "10",            // 10 = deliver immediately, 5 = opportunistic
  "apns-expiration": "0",           // 0 = do not retry a failed push
});

req.end(JSON.stringify({
  aps: {
    // Ordering guard, in SECONDS. APNs discards a push whose timestamp is older
    // than the last one it applied, so out-of-order retries cannot rewind the card.
    timestamp: Math.floor(Date.now() / 1000),
    event: "update",              // "update" mutates the card, "end" finishes it
    // Decoded straight into the widget's Codable ContentState. Field names and
    // types must match that struct EXACTLY. See the eta trap below.
    "content-state": contentState,
  },
}));

The body is small on purpose. timestamp is an ordering guard in seconds: APNs drops any push older than the last one it applied, so a delayed retry can't rewind the card. event is "update" to change the card or "end" to finish the activity, and there's no "start" here because push-to-start is a separate token that needs iOS 17.2. Everything else lives in content-state, which the widget decodes directly, and that's where the second silent failure hides, below.

How to Test Your Auth Without a Phone

This one trick saved me the most time, so do it before you involve a device at all. Send a push to the sandbox using a deliberately fake device token, and read the response code APNs gives back.

• 400 BadDeviceToken is the good outcome. It means your key, key id, team id, and JWT encoding are all correct, and APNs got far enough to look up the token and simply not find it. Your auth works.

• 403 InvalidProviderToken means the token itself is wrong, so the problem is your key or your signing, not the device.

That single request separates "my auth is broken" from "my token is broken" with no phone in the room. On this project it returned 400 on the first try, which told me the auth was solid and I should look elsewhere for the real bug. That was exactly the reassurance I needed.

The eta Trap: a 200 That Renders Nothing

This is the most instructive bug in the project, and it hit the moment a second code path reused a shared helper.

The same delivery data takes two different routes to the widget, and the routes expect two different shapes. The native module path carries etaEpochMillis (Unix milliseconds), and Swift converts it into a Date on the way through. The push path skips Swift entirely: the JSON content-state is decoded directly by the widget's Codable struct, which expects a field literally named eta, holding seconds since 2001 (Apple's reference date), and knows nothing about etaEpochMillis.

So if you reuse the native-bridge object as a push payload, APNs returns 200, iOS quietly throws the update away because it won't decode, and nothing is logged anywhere. The fix is to translate at the boundary, converting to the widget's shape only when building a push.

const APPLE_EPOCH_OFFSET = 978_307_200;   // seconds between 1970 and 2001

// The shape the WIDGET decodes, not the shape the native bridge takes.
function toContentState({ etaEpochMillis, ...rest }) {
  return {
    ...rest,
    eta: Math.floor(etaEpochMillis / 1000) - APPLE_EPOCH_OFFSET,   // ms->s, then rebase to 2001
  };
}

Two details make this work. Foundation.Date's reference point is 2001-01-01, not the Unix epoch, and Swift's Codable encodes a Date as seconds since that date, which is why the offset is subtracted. And destructuring etaEpochMillis out of rest is what drops the wrong key: leave it in and the widget's Codable init sees an unexpected field next to a missing eta, fails to decode, and the update vanishes after a 200.

The lesson generalises past the eta field. A 200 from APNs means only that Apple accepted your bytes, not that the card changed. Any content-state that fails to decode is discarded with no error on any surface, so confirm on the lock screen every time rather than trusting the status code.

Two last environment traps to note. Development-signed builds must talk to api.sandbox.push.apple.com, because the production host returns 400 BadDeviceToken for a sandbox token, which looks exactly like a malformed token and sends you debugging the wrong layer. And if you push frequently, add NSSupportsLiveActivitiesFrequentUpdates to your Info.plist, or the system budgets and drops your rapid pushes.

How to Test on Real Hardware

The simulator will lie to you about push, so at some point you need a real phone. Four things can trip you up there that the documentation never mentions. Here is each one with the fix.

Build in Release, not Debug

A Debug build expects to download its JavaScript from Metro over your local network. The build script bakes your Mac's network address into the app, so the moment the phone is on a different network, or simply not tethered to your Mac, it shows a red screen reading No script URL provided. There's no adb reverse equivalent on iOS to paper over this.

Build with --configuration Release instead, which embeds the JavaScript bundle inside the app. That's the more honest test anyway, because a Release build is the only way to fully force-quit the app and prove the push, not a live Metro connection, is doing the work.

Read Logs with devicectl, Not console.log

Once you drop Metro, console.log has nowhere to go. To read something like a push token off the device, you need the app's real standard output, and NSLog in the Swift code plus devicectl on the Mac is the reliable way to get it.

# --console            stream the app's stdout/stderr back to this terminal
# --terminate-existing kill a running copy first, so we catch launch-time logs
# --device             the COREDEVICE id (see the identifier trap below)
xcrun devicectl device process launch --console --terminate-existing \
  --device <coredevice-id> com.fasarticle.droptrack
# → [DropTrack] push token for 3095ACA0-...: 80875cb137590013a4c9...
#   ^ the hex string the dispatch server scrapes and pushes to

Know Which of the Two Device Identifiers You Need

The same phone has two identifiers, and the tools disagree about which they want. expo run:ios --device wants the hardware UDID, listed by xcrun xctrace list devices. The devicectl command above wants the CoreDevice identifier, listed by xcrun devicectl list devices.

Pass one where the other belongs and you get No device UDID or name matching, which reads as though the phone is unplugged. It's not, so check that you copied the right kind of id before you check the cable.

Handle Cold-start Deep Links, Not Just Live Ones

If your test driver opens the app with a deep link, note that devicectl ... --payload-url cold-starts the app, so the link arrives through Linking.getInitialURL() rather than the url event that the simulator's simctl openurl fires. A driver that listens only for the url event will appear to do nothing on a device. Handle both entry points.

With all four handled and the app confirmed fully quit, I drove three pushes through it (a status change, a rider reassignment, and an "arriving now"). Each one rendered on the lock screen and in the Dynamic Island.

One bonus comes free. Sign the Mac into the same Apple ID, and Continuity mirrors the same Live Activity onto the macOS menu bar, segmented bar, and all. One APNs push, three surfaces.

Why Android Has No ActivityKit

Android has no equivalent of ActivityKit, so there's no system-owned card and no framework keeping it up to date. What you have instead is an ordinary notification that you keep re-posting.

The trick is the notification id. Re-post under the same id and Android replaces the existing notification in place, which reads as an update. Post under a new id and you get a second notification instead. So the three lifecycle verbs map onto plain notification calls:

• start is notify() with a fresh id.

• update is notify() again under that same id.

• end is a final notify() with ongoing = false, followed by a delayed cancel().

That is the entire model. The catch is that everything iOS did for you (keeping the card current, recovering it after a restart, and updating it from a push) is now code you have to write.

The Trap That Shapes Everything: Android 16 is Two Releases in One

One versioning quirk shapes the whole Android side, so it's worth thirty seconds up front. "Android 16" ships as two releases that share a single API number:

Both report 36 because Build.VERSION.SDK_INT, the value your code reads to check the OS version, is a plain integer with no room for a .1. Two different releases, one number.

That collision is the entire source of the friction, and it leaves you three things to handle. None is hard once you know it is coming.

1. Compile through the backport, not the platform classes

The promotion methods (setRequestPromotedOngoing, setShortCriticalText, and the POST_PROMOTED_NOTIFICATIONS permission) live only in the 36.1 SDK, and React Native 0.86 compiles against base 36. Call them on the platform classes directly and the build fails with "no such method" before the app ever runs. One dependency fixes that:

dependencies {
  // NotificationCompat backports the 36.1 promotion APIs so they compile
  // against base SDK 36. Without this, ProgressStyle, setRequestPromotedOngoing
  // and setShortCriticalText are simply not on the classpath.
  implementation 'androidx.core:core-ktx:1.17.0'
}

Call the NotificationCompat versions rather than the platform ones. They compile against 36, take effect on a real 36.1 device, and are ignored on older releases, so one build is safe everywhere.

2. Read SDK_INT_FULL only when you truly need the minor version

A normal SDK_INT >= 36 check can't tell base 36 from 36.1, since both say 36. When you genuinely need to know which release you are on, Build.VERSION.SDK_INT_FULL carries the minor version, with named values in Build.VERSION_CODES_FULL. Because of rule 1 you rarely need it for the promotion request itself. You reach for it to decide what to show the user, or to guard the call in rule 3.

3. Wrap the capability check so it can't crash you

NotificationManager.canPostPromotedNotifications() reports whether the device will actually honour a promotion. Its reference lists it as added in API 36, so in theory it belongs to base Android 16, while the POST_PROMOTED_NOTIFICATIONS permission it depends on only arrived in 36.1. On the pre-QPR build I tested, though, the call was absent at runtime and threw. A capability probe should never be the thing that crashes your app, so wrap it and default to false:

Function("canPostPromotedNotifications") {
  // Function, not AsyncFunction: this is a cheap synchronous read, and the UI
  // wants it during the first render to decide what to disable.
  val manager = notificationManager ?: return@Function false

  // Cheapest gate first: below API 36 there is nothing to promote to.
  if (Build.VERSION.SDK_INT < 36) return@Function false

  // Docs list this as added in API 36, but on the pre-QPR build I tested it was
  // absent at runtime and threw. runCatching stops a capability probe from
  // crashing the app, defaulting to false when the call is unavailable.
  return@Function runCatching { manager.canPostPromotedNotifications() }.getOrDefault(false)
}

How to Build the Kotlin Side

Here's the notification builder. Notice how many of these lines are promotion requirements rather than cosmetics.

// Whole percent, clamped: a server that sends 1.4 must not become 140.
val progressPercent = (progress.coerceIn(0.0, 1.0) * 100).toInt()

val builder = NotificationCompat.Builder(ctx, CHANNEL_ID)
  .setSmallIcon(R.drawable.ic_delivery)
  .setContentTitle(status)                     // promotion REQUIRES a title
  .setContentText(courierLine(courierName, riderReassigned, stopsRemaining))
  .setSubText("Order $orderId")
  .setOngoing(ongoing)                         // promotion REQUIRES ongoing
  .setOnlyAlertOnce(true)                      // buzz once, then update silently
  .setColor(BRAND_ORANGE)                      // NOT setColorized: that disqualifies it
  .setShortCriticalText("$progressPercent%")   // text inside the status-bar chip
  .setRequestPromotedOngoing(ongoing)          // the promotion request itself

// `when` is the ETA in the header. It must be in the future (see note below).
if (etaEpochMillis > System.currentTimeMillis()) {
  builder.setWhen(etaEpochMillis.toLong()).setShowWhen(true)
}

if (Build.VERSION.SDK_INT >= 36) {
  val style = NotificationCompat.ProgressStyle()
    .setStyledByProgress(true)                 // colour follows the value
    .setProgress(progressPercent)
    .setProgressTrackerIcon(IconCompat.createWithResource(ctx, R.drawable.ic_delivery))
    .setProgressSegments(listOf(               // segments: spans of the bar
      NotificationCompat.ProgressStyle.Segment(100).setColor(BRAND_ORANGE)
    ))
    .setProgressPoints(listOf(                 // points: milestone dots on top
      NotificationCompat.ProgressStyle.Point(35).setColor(Color.WHITE)
    ))
  builder.setStyle(style)
} else {
  builder.setProgress(100, progressPercent, false)  // pre-16 fallback bar
}

val notification = builder.build()
if (Build.VERSION.SDK_INT >= 36) {
  Log.d(TAG, "hasPromotableCharacteristics=${notification.hasPromotableCharacteristics()}")
}
manager.notify(notificationIdFor(activityId), notification)   // stable id = update in place

Several of those lines carry non-obvious weight:

• setOnlyAlertOnce(true) stops each of the seven re-posts per delivery from buzzing the phone. Only the first notify() alerts, and the rest land silently.

• setColor versus setColorized: setColor tints the notification and is fine, but setColorized(true) would disqualify it from promotion. They're not interchangeable.

• setWhen must be a future timestamp, or the update can be skipped entirely. One UI renders it as an absolute clock time, Pixel as a relative countdown.

• ProgressStyle segments versus points: Segments are spans of the bar (one Segment(100) fills the whole thing, several draw the divided look). Points are milestone dots painted on top at a given percent.

• The else branch: Below API 36 the compat layer has no ProgressStyle at all, so it falls back to the classic determinate bar.

Two runtime checks are your only debugging signal, and they answer different questions:

• hasPromotableCharacteristics(), logged after build(), tells you whether you satisfied every promotion precondition. It says nothing about the device.

• canPostPromotedNotifications() tells you whether the device will honour the request. The two genuinely disagree on Samsung, which is why you need both.

And notificationIdFor() derives a stable int from the activity id, so a re-post under the same id updates the card in place. A different id would post a second notification, the classic "why do I have seven delivery cards" bug.

Promotion eligibility is all-or-nothing, and silent. It flips true only when every condition holds: notification permission, setRequestPromotedOngoing(true), ongoing, a content title, an allowed style, importance above MIN, and not colorized. Miss one and you get an ordinary notification with no explanation. Log hasPromotableCharacteristics() after every build(), and surface canPostPromotedNotifications() in your development interface. Those two booleans are the only debugging signal the platform gives you.

Note also that custom RemoteViews aren't allowed for promoted notifications. You get the ProgressStyle template, or you get no promotion. That's the biggest design constraint compared with iOS, where you write arbitrary SwiftUI.

When it does promote on a real API 36.1 build, you get the chip and the elevated lock-screen slot.

The same APK behaves three different ways:

How to Drive Android From a Server With FCM

This is the deepest difference between the two platforms.

On iOS, APNs updates the widget through the system, and your app code never runs. On Android, there's no system-managed remote update. A data-only FCM message wakes a FirebaseMessagingService, and your code re-posts the notification. The app is the updater, even from the background.

// Registered in the manifest, so Android can instantiate it WITHOUT your
// Activity, your React context, or your module ever existing.
class DroptrackFcmService : FirebaseMessagingService() {

  // Called on install, and again whenever FCM rotates the token. Never assume
  // the token you saw at startup is still valid.
  override fun onNewToken(token: String) {
    Log.i(DeliveryNotifier.TAG, "[DropTrack] fcm token: $token")
  }

  override fun onMessageReceived(message: RemoteMessage) {
    // FCM `data` is always Map<String, String>. Every number and boolean was
    // stringified on the way out and has to be parsed back here.
    val d = message.data

    // No activityId means we cannot address a notification. Bail rather than
    // guess: posting under the wrong id creates a duplicate card.
    val activityId = d["activityId"] ?: return
    val event = d["event"] ?: "update"

    // This service is a SEPARATE entry point. It cannot see the module's
    // in-memory state, so every field must come from the payload, and every
    // parse must be defensive, because a crash here kills the update.
    DeliveryNotifier.ensureChannel(this)   // the process may be brand new
    DeliveryNotifier.post(
      ctx = this,
      activityId = activityId,
      // Every `?:` below is load-bearing. toDoubleOrNull returns null rather
      // than throwing on malformed input, so a bad payload degrades the card
      // instead of killing the service.
      orderId = d["orderId"] ?: "",
      status = d["status"] ?: "",
      progress = d["progress"]?.toDoubleOrNull() ?: 0.0,
      etaEpochMillis = d["etaEpochMillis"]?.toDoubleOrNull() ?: 0.0,
      stopsRemaining = d["stopsRemaining"]?.toIntOrNull() ?: 0,
      courierName = d["courierName"] ?: "",
      riderReassigned = d["riderReassigned"]?.toBoolean() ?: false,
      // "end" clears `ongoing`, which lets the user finally swipe the card away.
      ongoing = event != "end",
    )
  }
}

That "separate entry point" comment is the crux, so it's worth slowing down on. Android can start this service on its own to deliver a push, at a moment when the rest of your app isn't running. There's no React, no module instance, and none of the objects the app was holding in memory. So the push handler can't look up "what delivery is in progress" from app state, because there's no app state to look at. Everything it needs has to come from the push payload itself.

That forces a specific design. The code that builds a notification can't live inside the app and read app state. It has to be standalone code that takes plain values and nothing else.

So I pulled all of it into a shared DeliveryNotifier object, and both paths call it: the in-app path when JavaScript drives an update, and the push path when the service does. Because they run the same builder from the same inputs, they produce an identical notification, and that shared builder is the single most important structural change on the Android side.

The Four Rules of Android Push

Four things have to be right, or the push half quietly fails. In short: send the right kind of message, authenticate the harder way, read the error codes correctly, and wire the plugin through prebuild. Each one in full below.

Rule 1: send a data-only message, never one with a notification block

This is the rule that catches everyone. A message with a notification block, while the app is backgrounded or killed, is handled by the system tray, and your onMessageReceived code never runs, so the card never updates. Only a data-only message (no notification block) reaches your code in the background.

Firebase documents this in Receive messages in an Android app. Send data-only, and set android.priority to high so the app wakes promptly.

Rule 2: authenticate with a service-account token, not a static key

FCM v1 auth is heavier than APNs, with no one-shot .p8. You mint an RS256 JWT from a service account, exchange it for a short-lived OAuth access token, and send that access token as a bearer credential to projects.messages.send. The consolation is that FCM v1 is plain HTTPS, so fetch() works.

// `sa` is the parsed service-account JSON from Firebase. This JWT is not the
// credential you send to FCM; it is the one you trade for a short-lived token.
export function buildAuthJWT(sa) {
  const now = Math.floor(Date.now() / 1000);
  const header = b64url(JSON.stringify({ alg: "RS256", typ: "JWT" }));  // RSA key, so no ieee-p1363 trap
  const claims = b64url(JSON.stringify({
    iss: sa.client_email,
    scope: "https://www.googleapis.com/auth/firebase.messaging",  // exact scope, or every send 403s
    aud: sa.token_uri,        // the JWT is FOR Google's token endpoint
    iat: now,
    exp: now + 3600,          // one hour, Google's maximum
  }));
  const signingInput = `${header}.${claims}`;
  const sig = createSign("RSA-SHA256").update(signingInput).sign(sa.private_key);
  return `${signingInput}.${b64url(sig)}`;
}

export async function sendDataMessage({ token, data, sa }) {
  const accessToken = await getAccessToken(sa);   // trades the JWT for a token; cache the result
  const res = await fetch(
    `https://fcm.googleapis.com/v1/projects/${sa.project_id}/messages:send`,
    {
      method: "POST",
      headers: { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/json" },
      body: JSON.stringify({
        message: {
          token,                        // per-DEVICE token (APNs is per-activity)
          data,                         // note: NO `notification` key (see below)
          android: { priority: "high" },
        },
      }),
    }
  );
  const body = await res.json().catch(() => ({}));   // never throw on a bad error body
  return { status: res.status, reason: body?.error?.status ?? null };
}

The design turns on two absences and one indirection. The indirection is the token exchange. Unlike APNs, where the JWT is the credential, here you POST the JWT to Google's token endpoint, get back a short-lived access token, and send that, so cache it rather than re-minting per message.

The first absence is any notification key in the body, which is deliberate and covered next. The second is high priority over normal, because normal may be held until the device leaves Doze, by which time the delivery has finished.

On the response, 404 UNREGISTERED means drop the token while 400 INVALID_ARGUMENT means it was never a token. The caller needs to tell those apart, so the reason string is returned rather than swallowed.

FCM data values are a map of string to string, so everything is stringified on the way out and parsed on the way in. Unlike iOS, there's no silent shape mismatch, because you wrote the parser. But your parser must never throw.

Rule 3: treat 400 and 404 as different failures

FCM splits two cases that APNs collapses. A malformed token returns 400 INVALID_ARGUMENT, while a well-formed but unregistered token returns 404 UNREGISTERED (the full list is in the FCM ErrorCode reference).

APNs reports both as BadDeviceToken. This matters for the fake-token auth probe from the iOS section: on FCM a fake token gives INVALID_ARGUMENT, not UNREGISTERED. Either one still proves your auth works, since a bad service account fails earlier with 401 or 403. I wrote my probe expecting UNREGISTERED, and correcting the test is how I learned the distinction.

Rule 4: wire the google-services plugin through prebuild

The google-services plugin is what reads your Firebase config into the build. Because Continuous Native Generation regenerates the android folder on every prebuild, a config plugin has to re-place google-services.json and re-add the Gradle wiring each time, or the setting is lost on the next prebuild.

// plugins/withAndroidFcm.js
function withGoogleServicesJson(config) {
  // withDangerousMod runs arbitrary filesystem work during prebuild. It is
  // "dangerous" because nothing validates the result. It is also the only way
  // to place a file the Gradle plugin expects to already exist.
  return withDangerousMod(config, ["android", (cfg) => {
    // Kept at the repo root, gitignored, and copied in on every prebuild.
    const src = path.join(cfg.modRequest.projectRoot, "google-services.json");
    // Must land in android/app/, where the google-services plugin looks for it.
    const dest = path.join(cfg.modRequest.platformProjectRoot, "app", "google-services.json");

    // Fail loudly at prebuild. Without this the build succeeds, the app starts,
    // and FCM initialisation quietly no-ops at runtime.
    if (!fs.existsSync(src)) {
      throw new Error("[withAndroidFcm] google-services.json not found at project root");
    }

    fs.copyFileSync(src, dest);
    return cfg;
  }]);
}
// plus withProjectBuildGradle for the classpath,
// and withAppBuildGradle to apply the plugin.

Have it throw when the file is missing. Failing fast at prebuild beats a mystery at runtime.

The Honest Caveat

A data message can be dropped under Doze or after a force-kill. An iOS Live Activity is system-owned and updates regardless. High priority helps. This is a platform limitation to document rather than engineer around. Test with the app backgrounded, not swiped away, and be honest with your product team about the difference.

Three UX Gaps the Naïve Implementation Leaves

Because your code owns the Android side, you inherit three responsibilities that iOS handles quietly for you. I shipped all three only after hitting each one in testing.

Tapping the Notification Does Nothing

NotificationCompat posts happily, but with no setContentIntent(PendingIntent) there is no tap target, so Android just expands and collapses the notification. Nothing in the documentation shouts this at you.

private fun launchIntent(ctx: Context, activityId: String): PendingIntent? {
  // Ask the package manager for our own launcher intent, rather than naming
  // MainActivity. Under Expo's Continuous Native Generation that class name is
  // generated, so hardcoding it breaks on the next prebuild.
  val intent = ctx.packageManager.getLaunchIntentForPackage(ctx.packageName)
    // SINGLE_TOP: reuse the existing task instead of stacking a second copy.
    // CLEAR_TOP: drop anything above it, so the user lands on the tracking screen.
    ?.apply { flags = Intent.FLAG_ACTIVITY_SINGLE_TOP or Intent.FLAG_ACTIVITY_CLEAR_TOP }
    ?: return null

  return PendingIntent.getActivity(
    ctx,
    // The request code. Keyed per activity so two concurrent deliveries get
    // two distinct PendingIntents rather than silently sharing one.
    notificationIdFor(activityId),
    intent,
    // FLAG_IMMUTABLE is mandatory on Android 12+; omit it and this throws.
    // FLAG_UPDATE_CURRENT refreshes the extras of the existing PendingIntent
    // rather than handing back a stale one from an earlier delivery.
    PendingIntent.FLAG_IMMUTABLE or PendingIntent.FLAG_UPDATE_CURRENT,
  )
}

FLAG_IMMUTABLE is required on Android 12 and later. Verify the result with adb shell dumpsys notification, which should show contentIntent=PendingIntent{... startActivity}.

A Push Updates the Notification But Not Your Interface

The service is a separate entry point from your JavaScript state, so a push arriving while the app is open leaves the app showing a stale step. The fix is a static bridge, set when a module instance exists and cleared when it does not.

companion object {
  // Static, because the FCM service cannot reach a module INSTANCE. @Volatile
  // because the service runs on a different thread than the one that sets this.
  // Nullable because, most of the time, there is no live module to emit into.
  @Volatile private var pushEmitter: ((Map<String, String>) -> Unit)? = null

  // Safe to call from anywhere. The `?.` is the entire "is the app alive?" check.
  fun emitPush(data: Map<String, String>) { pushEmitter?.invoke(data) }
}

override fun definition() = ModuleDefinition {
  // Declares the events JS may subscribe to. Emitting an undeclared name throws.
  Events("onFcmTokenReceived", "onDeliveryPush")

  // Register the bridge when a module instance exists...
  OnCreate  { pushEmitter = { data -> sendEvent("onDeliveryPush", data) } }
  // ...and tear it down when it does not. Skip this and you leak a closure
  // holding a dead React context, then crash on the next push.
  OnDestroy { pushEmitter = null }
  // ...
}

The service calls DroptrackLiveModule.emitPush(d) after notify(). It does nothing when the app is dead, in which case the notification still updates and there's simply nothing to sync. This is the Android analogue of the iOS foreground resync.

A Cold-started App Comes Up Empty

iOS recovers from Activity.activities. Android has no such store, so a killed app reopened by tapping its own notification shows "Not tracking". Persist the delivery to SharedPreferences on every notify(), then read it back.

// Same JS name as the iOS implementation, so App.tsx never branches on platform.
AsyncFunction("getRunningActivities") {
  val ctx = context ?: return@AsyncFunction emptyList<Map<String, Any?>>()

  // Our stand-in for iOS's Activity.activities: the record written on notify().
  val active = DeliveryNotifier.activeDelivery(ctx)
    ?: return@AsyncFunction emptyList<Map<String, Any?>>()
  val activityId = active["activityId"] as String

  // Phantom guard: trust the system's notification list over our own record.
  if (!DeliveryNotifier.isActive(ctx, activityId)) {
    DeliveryNotifier.clear(ctx)
    return@AsyncFunction emptyList<Map<String, Any?>>()
  }

  // Repopulate the per-process map, or a later update/end throws after cold start.
  deliveries[activityId] = DeliveryInfoRecord().apply { orderId = active["orderId"] as String }
  return@AsyncFunction listOf(active)
}

Two subtleties here I only found by breaking them. Guard the rehydration with getActiveNotifications(). Without that check, a stale record produces an uncancellable phantom delivery whose Cancel button throws ActivityNotFoundException. And make endDelivery forgiving. If the activity isn't in the in-memory map because you cold-started, still cancel the notification and clear the state rather than throwing. Tearing something down should never fail because you've forgotten about it.

Because the resync effect in App.tsx is cross-platform, implementing Android's getRunningActivities() lights up the existing cold-start path with no JavaScript changes. That's the payoff of keeping one API across two backends.

How to Script the Simulators and Devices

Two small tools saved more time than any feature.

The iOS simulator has no scriptable tap. There's no uiautomator equivalent, and synthetic clicks need macOS accessibility grants. So I added a development-only deep-link driver, fifteen lines, stripped from release builds.

useEffect(() => {
  // Dead code in release builds: the bundler strips the whole effect body.
  if (!__DEV__) return;

  // "droptrack://drive/next" -> "next" -> call actions.next().
  // actionsRef, not actions: the listener is registered once, so a plain
  // closure would capture the first render's handlers forever.
  const run = (url: string) => actionsRef.current[url.split("/").pop() ?? ""]?.();

  // Case 1: app already running. simctl openurl fires this event.
  const sub = Linking.addEventListener("url", ({ url }) => run(url));

  // Case 2: devicectl --payload-url COLD-STARTS the app: the URL arrives as the
  // initial URL and never fires the 'url' event. Handle both or device
  // automation silently does nothing while simulator automation works.
  void Linking.getInitialURL().then((url) => url && run(url));

  return () => sub.remove();
}, []);

# Drives the running app one step forward, with no tap and no accessibility grant.
xcrun simctl openurl booted "com.fasarticle.droptrack://drive/next"

For the push half I built a small web dispatcher. A browser cannot reach APNs or FCM, because of HTTP/2, missing cross-origin headers, and the fact that signing keys must never leave the server. So it talks to a zero-dependency local Node.js signing server that scrapes push tokens off the device console, streams them to the browser with server-sent events, and sends to whichever platform you select.

iPhone  --NSLog--> devicectl --console --+
Android --Log.i--> adb logcat -----------+
                                         | scrape
browser <--SSE /events-- dispatch-server (127.0.0.1:8787)
   \--POST /push--------> apns.mjs / fcm.mjs --> APNs / FCM --> device

Pick a step, pick a courier, and press one button. It turns a two-minute test into a ten-second one, and it made the Samsung investigation below possible at all.

How iOS and Android Compare

The Samsung Reality Check

Version numbers lie, and Samsung is where they lie loudest. I tested by hand across three real Galaxy devices using Samsung Remote Test Lab, whose Remote Debug Bridge turns out to be a full local adb tunnel to a phone in Korea. The entire emulator automation playbook (granting permissions, tapping, taking screenshots, and reading dumpsys) works unchanged against remote hardware.

Here's what the same unmodified APK did on each:

Two findings come out of that table.

1. On the base-36 device, the two capability checks disagree

The S25 Ultra runs base 36, which has no promotion pipeline, so nothing promotes. But hasPromotableCharacteristics() returns true there (Samsung backported some framework pieces) while canPostPromotedNotifications() returns false. A base-36 Pixel emulator returns false for both. So you can't infer one check from the other. Detect both at runtime, and trust canPostPromotedNotifications() for whether promotion will actually happen.

2. On the 36.1 devices, promotion works but only partly

Both the S26 Ultra and the A37 genuinely grant FLAG_PROMOTED_ONGOING to the unmodified APK, which you can confirm in dumpsys. You get top-of-shade pinning and the status-bar icon. You do not get the chip pill, the lock-screen card, or a Now Bar entry, even though the promotion succeeded.

That "only partly" was the mystery, until I found where the missing surfaces went. In Settings, under Lock screen and Always On Display, there's a page called Live notifications (searchable as "live notification", notably not as "Now bar"). It promises exactly the surfaces I was missing: the lock screen, the status bar, and the top of the notification panel, illustrated with the Now Bar pill. And directly below that promise sits a fixed, six-app allowlist: Audio broadcast, Emergency sharing, Google Finance, Maps, Media player, and Sports from Google.

DropTrack isn't on that list. Yet its promoted delivery was live on that very device at that very second, and the page's own "Not seeing Live notifications?" checklist (three notification permissions) was fully satisfied. The feature was working. Samsung simply doesn't offer its best surfaces to apps outside the six.

So the screenshot-backed conclusion for these units is this: One UI 8.5 accepts Google's promotion contract and ships the minor surfaces to any app, but reserves the headline ones for a hardcoded list. This reflects those specific devices at the time of testing, and Samsung may change it.

It leaves the three platforms in three different places. Apple offers a public API on every device. Google offers a public API on its own hardware. Samsung offers the framework to everyone but keeps the best stage by invitation.

The Demo Repository

Everything in this handbook is one working project, DropTrack, released under the MIT licence. It's not a snippet dump. It's a single React Native app whose one delivery-tracking feature reaches down through five layers. The point of reading it is to see how those layers connect rather than how any one of them looks in isolation.

Here's what lives in the repo, layer by layer:

A few things make it worth cloning rather than skimming:

• It genuinely runs on all three surfaces: The same DeliveryState object drives a SwiftUI Live Activity, an Android promoted notification, and a web console, so you can watch one API produce three very different results.

• The push clients have no dependencies: scripts/apns.mjs and scripts/fcm.mjs use only Node built-ins, so you can read the entire APNs and FCM path end to end without unpacking a library. Both have small test files next to them.

• Every gotcha in this article is written up in GOTCHAS.md: The long checklist that used to live in this section now lives there, next to the code it refers to, alongside DEVLOG.md (how the build unfolded) and ARTICLE_NOTES.md.

• It's safe to fork: The Firebase service account, the google-services.json, and the APNs .p8 key are all gitignored, so nothing sensitive is in the history. The README.md lists exactly which of those you supply to run the push phase yourself.

Clone it, run the app on a simulator, open the web console, and push an update to your own device. That loop is the fastest way to make everything above concrete.

What to Know Before You Start

The product feature is identical, and the platform contracts are opposites. iOS gives you a system-owned widget and updates it for you. Android gives you a notification and makes you the update engine, down to re-posting it from a background service on every message. Design your module's seam accordingly. The same three-function API can hide wildly different machinery, and that is exactly what a good native module is for.

The silent failures are the tax. Almost every hard bug in this project, from the mismatched widget struct, to the missing entitlement, the wrong epoch, the un-promoted notification, and the notification-instead-of-data message, fails with zero errors. So instrument aggressively. Log promotable characteristics. Verify entitlements survived signing. Probe push auth with fake tokens before you involve a device. Always confirm on the real surface rather than trusting a 200.

Version numbers lie, so detect features instead. Android 16 is two releases. Samsung's Android 16 is a third. canPostPromotedNotifications() and hasPromotableCharacteristics() can disagree on the same build. Check both at runtime, and never infer one from the other.

The system owns the activity, not your process. On iOS the activity outlives your variable, your React state, and your process. On Android the notification outlives your process too, but nothing recovers it for you. Both platforms punish you for assuming the id in your useState is the source of truth.

Conclusion

You now have a complete picture of both platforms. You built one TypeScript API over two native backends, a SwiftUI widget with four presentations, a Kotlin notification that satisfies Android's promotion contract, and two push clients written from scratch with no libraries. You also know the failure modes that produce no error message, which is most of them.

Three things are worth exploring next:

1. Push-to-start, on iOS 17.2 and later. You can start a Live Activity from a push, with no app launch at all. The token is per-app rather than per-activity, which rewrites the token plumbing described above.

2. Broadcast channels, on iOS 18. One push updates an activity for many users, which suits live scores. Every push in this handbook targets a single token.

3. An Android foreground service. It narrows the Doze and force-kill delivery gap. It won't close it, but it makes long-running deliveries more durable than a bare data message.

The interesting part was never Activity.request(). It was everything the two platforms decline to tell you when you get it wrong.

Sources and Further Reading

Apple, ActivityKit and APNs:

• ActivityKit and ActivityAttributes

• Displaying live data with Live Activities

• Starting and updating Live Activities with ActivityKit push notifications

• Live Activities, Human Interface Guidelines

• The aps-environment entitlement

• Sending notification requests to APNs, Establishing a token-based connection to APNs, and Handling notification responses from APNs

• Date, and the 2001 reference date

• WidgetKit

Android and Firebase:

• Progress-centric notifications in Android 16 and Android 16 overview

• Notification.ProgressStyle and NotificationCompat.ProgressStyle

• NotificationCompat.Builder, where setRequestPromotedOngoing and setShortCriticalText are backported

• Build.VERSION.SDK_INT_FULL and Build.VERSION_CODES_FULL, the 36 versus 36.1 distinction

• NotificationManager.canPostPromotedNotifications(), Notification.hasPromotableCharacteristics(), and getActiveNotifications()

• PendingIntent.FLAG_IMMUTABLE and SharedPreferences

• androidx.core release notes

• Doze and App Standby

• Firebase Cloud Messaging, Receive messages in an Android app, FirebaseMessagingService, projects.messages.send, and the FCM ErrorCode reference

• Using OAuth 2.0 for server to server applications and the google-services Gradle plugin

Apps that document their own Live Activity, cited in "Where You Have Already Seen This Feature":

• Chowdeck, ESPN, MLB, FotMob, CARROT Weather, and Structured, all via their App Store listings

• Flighty's Live Activities help page

• Apple Sports, following games in real time

• MacRumors on Uber Eats, May 2023 and DoorDash, December 2023

• MacStories, the iOS 16.1 Live Activities roundup

React Native, Expo, and tooling:

• Expo Modules API overview and the module API reference

• Expo config plugins and Continuous Native Generation

• @bacons/apple-targets, which generates the widget extension

• expo-live-activity, the packaged alternative

• Notifee, archived, and its last release @notifee/react-native@9.1.8

• React Native AppState and Linking

• Node.js crypto and http2

• RFC 7519, JSON Web Token and RFC 7518, JSON Web Algorithms, which define the ES256 and RS256 signature formats

• Samsung Remote Test Lab

Within a week, the bug reports started coming in.

Screens freezing, API calls failing silently, Users losing form data they'd spent ten minutes filling out, one user reported the app just... stopped responding after they walked through a tunnel on the subway. I had never tested that. Why would I? It worked fine on my machine.

That experience taught me something I wish someone had told me earlier: there's a real gap between an app that works and an app that is production-ready.

I've now shipped multiple Flutter apps, and I've hit almost every wall this article covers — network failures, memory leaks, state management that made sense at first and became a nightmare at scale, and performance that felt fine in development and janked badly on a user's old device.

This article is everything I've learned from those experiences. Not theory, but actual patterns that came from actual problems.

Table of Contents

• Why "It Works on My Machine" is Dangerous in Flutter

• Development vs Production: What Actually Changes

• Network Reliability and Defensive Request Handling

• Retry Logic and the Production Request Lifecycle

• Offline Support and Local Persistence

• State Management at Scale

• Widget Rebuilds and Rendering Performance

• Async Pitfalls and the Disposed Widget Problem

• Memory Leaks and Lifecycle Management

• Observability and Crash Reporting

• Testing Production Flutter Apps

• Architecture and Long-Term Maintainability

• End-to-End Example: a Production-Grade Profile Feature

• Final Thoughts

Why "It Works on My Machine" is Dangerous in Flutter

Here's what your development environment looks like: fast internet, a powerful machine or emulator, a clean app state on every hot reload, APIs that respond in milliseconds, and you, a careful developer who deliberately follows the happy path.

Here's what your users look like: spotty mobile data, old mid-range devices, six other apps running in the background, and zero patience for a screen that stops loading without explanation.

That gap is where production bugs live.

The tricky part is that Flutter makes development feel so smooth that it's easy to mistake "works on my machine" for "ready for users."

I've made that mistake. Most Flutter developers I know have made it too. The app looks polished. The animations are butter. You demo it to a colleague, and everything goes perfectly. Then someone tries to use it while commuting on patchy mobile data, and the whole thing falls apart.

Production-ready Flutter engineering starts with accepting one uncomfortable truth: things will go wrong. Networks will fail. Devices will run low on memory. Users will background your app at the worst possible moment. The question isn't whether these things happen, but rather whether your app handles them gracefully when they do.

Development vs Production: What Actually Changes

I want to be specific here because "production is different" is easy to say and hard to internalize until you've been burned by it.

In development, a failed API call is something you notice immediately in your terminal, fix in a few minutes, and move on from. In production, that same failed API call happens to a user who sees a blank screen, has no idea why, waits a few seconds, and then either retries or uninstalls. You find out three days later when someone leaves a one-star review.

In development, a widget that rebuilds unnecessarily costs a few milliseconds you never feel. In production, on an older or lower-powered device with several apps running in the background, that same unnecessary rebuild is the thing that pushes a frame over the 16ms budget and creates a stutter the user notices.

In development, a memory leak that adds 5MB of usage over ten minutes is invisible. I once had a leak in a chat feature, an undisposed stream subscription that was completely undetectable during testing. In production, after an hour of use on a low-memory device, the OS started killing the app mid-session. Users thought it was crashing randomly. It took me an embarrassingly long time to track down.

The pattern is always the same: problems that are invisible at development scale become significant at production scale, and problems that are minor on development hardware become severe on the hardware your actual users own.

Network Reliability and Defensive Request Handling

If I had to pick one category of bug that has bitten me the most across multiple apps, it would be this one. Mobile networks are genuinely unreliable, and Flutter apps are often written as though they're not.

The most common networking pattern I see (and wrote myself for longer than I'd like to admit) looks like this:

final response = await dio.get('/user');

setState(() {
  user = response.data;
});

This works perfectly in development. But it has four ways to fail in production:

1. The request fails due to a network error, and the exception propagates unhandled

2. The user navigates away before the response arrives and setState is called on a disposed widget

3. The API returns unexpected data, and the cast throws at runtime

4. The request hangs indefinitely, and the user stares at a spinner forever

I've hit all four. Here's a version that handles them:

Future<void> loadUser(String userId) async {
  setState(() {
    isLoading = true;
    error = null;
  });

  try {
    final response = await dio.get('/user/$userId');

    // mounted checks whether this widget is still in the widget tree.
    // If the user navigated away while the request was running,
    // mounted is false. Calling setState on a disposed widget throws
    // an error — this one line prevents that entire class of crash.
    if (!mounted) return;

    setState(() {
      user = User.fromJson(response.data as Map<String, dynamic>);
      isLoading = false;
    });
  } on DioException catch (e) {
    if (!mounted) return;

    setState(() {
      // Give the user a message that is actually useful.
      // "Something went wrong" is not helpful. Knowing whether
      // they have no internet vs the server failed lets them
      // decide whether to move or wait.
      error = e.type == DioExceptionType.connectionError
          ? 'No internet connection. Please try again.'
          : 'Failed to load profile. Please try again.';
      isLoading = false;
    });
  }
}

The Three States Every Screen Needs

I used to design screens for the success case and treat loading and error as afterthoughts. That was a mistake. Every screen that fetches remote data needs all three:

@override
Widget build(BuildContext context) {
  // Loading: never leave users staring at a blank screen.
  // A spinner tells them something is happening.
  if (isLoading) {
    return const Center(child: CircularProgressIndicator());
  }

  // Error: show what went wrong and how to recover.
  // A dead end with no retry button is one of the most
  // frustrating things a user can experience.
  if (error != null) {
    return Center(
      child: Column(
        mainAxisSize: MainAxisSize.min,
        children: [
          Text(error!, style: const TextStyle(color: Colors.red)),
          const SizedBox(height: 16),
          ElevatedButton(
            onPressed: () => loadUser(widget.userId),
            child: const Text('Try again'),
          ),
        ],
      ),
    );
  }

  // Success: show the data.
  return UserProfileView(user: user!);
}

The error state with a retry button isn't a nice-to-have. It's the difference between a user who recovers from a network hiccup and a user who thinks your app is broken.

Retry Logic and the Production Request Lifecycle

Mobile networks fail all the time temporarily. A user walks past a dead zone, enters an elevator, or switches from WiFi to mobile data mid-request. The request fails but if retried two seconds later, it would succeed.

Without retry logic, every temporary network failure is a permanent failure from the user's perspective. That's a bad trade.

Future<T> withRetry<T>(
  Future<T> Function() request, {
  int maxAttempts = 3,
  Duration delay = const Duration(seconds: 1),
}) async {
  for (int i = 0; i < maxAttempts; i++) {
    try {
      return await request();
    } catch (e) {
      // On the final attempt, stop retrying and let the
      // error propagate to the caller.
      if (i == maxAttempts - 1) rethrow;

      // Wait before trying again. This gives temporary network
      // issues time to resolve and avoids hammering a server
      // that might already be struggling.
      await Future.delayed(delay);
    }
  }

  throw Exception('Retry failed');
}

Usage is straightforward:

final user = await withRetry(
  () => dio.get('/user/$userId'),
  maxAttempts: 3,
  delay: const Duration(seconds: 2),
);

For production apps with heavier traffic, look at dio_smart_retry. This implements exponential backoff, and the delay doubles between each retry, which is much more considerate of server load during actual outages.

Offline Support and Local Persistence

I learned to take offline support seriously after an embarrassing support ticket. A user had filled out a long onboarding form (15 fields), which took them several minutes, and hit submit on a spotty connection. The request failed. The form cleared. All their data was gone. They were furious, and honestly, they had every right to be.

The goal of offline support is not to replicate every feature without internet. It's to make sure users don't lose progress and don't hit dead ends.

Caching Remote Data

The strategy here is simple: every time a network request succeeds, save the result locally. Then, if the next request fails, serve what you saved last time instead of showing an error screen.

class UserRepository {
  final Dio _dio;
  final Box _cache; // Hive box

  UserRepository(this._dio, this._cache);

  Future<User> getUser(String userId) async {
    try {
      final response = await _dio.get('/user/$userId');
      final user = User.fromJson(response.data as Map<String, dynamic>);

      // Save fresh data to the cache every time a request succeeds.
      // This means the next request can fall back to this
      // if the network is unavailable.
      await _cache.put('user_$userId', user.toJson());

      return user;
    } catch (e) {
      // Network failed. See if we have something cached.
      final cached = _cache.get('user_$userId');

      if (cached != null) {
        // Stale data is better than an error screen.
        // The user sees something useful even without internet.
        return User.fromJson(Map<String, dynamic>.from(cached));
      }

      // Nothing cached. We have no choice but to surface the error.
      rethrow;
    }
  }
}

Preserving User Input

This is the fix for the onboarding ticket I mentioned:

// Save whatever the user has typed whenever the field changes.
_contentController.addListener(() async {
  await _cache.put('draft_post', _contentController.text);
});

// When the screen opens, restore any saved draft.
@override
void initState() {
  super.initState();
  final draft = _cache.get('draft_post') as String?;
  if (draft != null && draft.isNotEmpty) {
    _contentController.text = draft;
  }
}

// Clear the draft once the user successfully submits.
Future<void> _submit() async {
  await _repository.createPost(_contentController.text);
  await _cache.delete('draft_post');
}

Three lines of code that save users from losing their work. This is worth doing in any form that takes more than a minute to fill out.

Packages I use for local persistence:

1. Hive for simple key-value storage

2. Isar when I need more powerful queries

3. sqflite for relational data

4. shared_preferences strictly for user settings, not for anything substantial

State Management at Scale

setState is fine. I want to say that clearly because there's a tendency in the Flutter community to treat it like it's always wrong. For local, simple UI state – a button toggling, a form field showing validation — setState is exactly the right tool.

The problems start when you use it for state that multiple widgets depend on, or for async operations, or for anything that needs to survive navigation. I've done all of these. Here's what goes wrong:

// This setState call lives high in the widget tree.
// Every widget below it rebuilds — including expensive ones
// that have nothing to do with this state change.
setState(() {
  currentUser = updatedUser;
});

As the app grows, this gets worse. Rebuilds spread. Side effects happen in unexpected order. You start spending more time debugging state than building features.

Moving to Riverpod

After hitting these walls in my second app, I switched to Riverpod and haven't looked back. The core idea is simple: state lives outside widgets, and widgets subscribe to exactly the state they need.

@riverpod
class UserNotifier extends _$UserNotifier {
  @override
  AsyncValue<User> build(String userId) {
    _load();
    return const AsyncValue.loading();
  }

  Future<void> _load() async {
    state = const AsyncValue.loading();

    // AsyncValue.guard runs the future and wraps the result
    // in AsyncValue.data on success or AsyncValue.error on failure.
    // It saves you from writing try/catch every single time.
    state = await AsyncValue.guard(
      () => ref.read(userRepositoryProvider).getUser(userId),
    );
  }

  Future<void> refresh() => _load();
}

In the widget:

@override
Widget build(BuildContext context) {
  // ref.watch subscribes this widget to the notifier.
  // It rebuilds only when userAsync changes — not when
  // unrelated state elsewhere in the app changes.
  final userAsync = ref.watch(userNotifierProvider(widget.userId));

  return userAsync.when(
    // when() forces you to handle loading, error, and data.
    // Miss one and it's a compile error, not a runtime surprise.
    loading: () => const CircularProgressIndicator(),
    error: (e, _) => Text('Error: $e'),
    data: (user) => UserProfileView(user: user),
  );
}

The part I appreciate most: when() makes it a compile error to forget the loading or error state. The compiler enforces what I used to forget.

Immutable State

One thing that burned me hard in a real-time chat feature: a mutable list shared across multiple parts of the app.

List<Message> messages = [];

// Later, in different places:
messages.add(newMessage);       // socket handler
messages.removeAt(0);          // pagination
messages.insert(0, pinned);    // push notification handler

When a message appeared twice, or disappeared at random, tracing which mutation caused it was genuinely painful. The fix is to never mutate and always create a new list:

// The old list is unchanged. The new state is a new list.
// Every change is explicit and traceable.
state = [...state, newMessage];

It feels like a small thing until you spend two hours debugging a mutation bug. Then it feels very important.

Widget Rebuilds and Rendering Performance

Flutter is fast. But unnecessary rebuilds accumulate, and on low-end devices the accumulation is noticeable.

Const Widgets Skip Rebuilds Entirely

The const keyword tells Dart this widget can be created at compile time and reused indefinitely. Any widget whose content will never change is a candidate.

// Without const: a new Text instance is created on every
// rebuild of the parent, even though the content never changes.
Text('Welcome to the app')

// With const: Flutter reuses the same instance.
// No rebuild work, no allocation.
const Text('Welcome to the app')

This sounds like a small thing. In a large widget tree with many static elements, the cumulative effect is real. Make it a habit.

Keep the Rebuild Scope Small

When setState lives high in the widget tree, every widget below it rebuilds — even ones that have nothing to do with the state that changed. The fix is to push state as far down the tree as possible, ideally into its own extracted widget.

// The problem: counter lives in the parent, so every
// setState call rebuilds the entire subtree — including
// ExpensiveListWidget, which has nothing to do with the counter.
class _BadExampleState extends State<BadExample> {
  int _counter = 0;

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        Text('Count: $_counter'),
        ElevatedButton(
          onPressed: () => setState(() => _counter++),
          child: const Text('Increment'),
        ),
        const ExpensiveListWidget(), // rebuilds for no reason
      ],
    );
  }
}

Now, only that widget rebuilds when the count changes. ExpensiveListWidget is untouched.

ListView.builder for Anything of Unknown Length

A Column with a mapped list builds every item upfront regardless of whether it is visible. On a list of 200 items, that is 200 widgets created before the user has scrolled at all.

// This builds every single item widget upfront.
// With 200 items, 200 widgets are created on first render,
// most of which are immediately off-screen.
Column(
  children: items.map((item) => ItemCard(item: item)).toList(),
)

// This builds only what is visible, plus a small buffer.
// Scrolling through 10,000 items uses the same memory as 10.
ListView.builder(
  itemCount: items.length,
  itemBuilder: (context, index) {
    return ItemCard(items[index]);
  },
)

ListView.builder isn't an optimization for large lists. It's the correct default for any list of unknown or variable size. I use Column with a mapped list only when I know for certain the list will always be tiny.

Async Pitfalls and the Disposed Widget Problem

This is one of those bugs that's completely invisible during development and shows up constantly in production.

The scenario: an async operation starts, the user navigates away before it finishes, and the operation completes and tries to call setState on a widget that no longer exists.

Future<void> _loadData() async {
  final data = await repository.fetchData();

  // If the user navigated away during the await above,
  // this widget is gone. setState throws:
  // "setState() called after dispose()"
  setState(() => this.data = data );
}

The fix is one line:

Future<void> _loadData() async {
  final data = await repository.fetchData();

  // mounted is true while the widget is in the tree,
  // false after dispose() has been called.
  if (!mounted) return;

  setState(() => this.data = data);
}

I now write this check automatically after every await that leads to a setState. It becomes muscle memory quickly.

Never Create Futures Inside Build

This is an easy-to-overlook issue. When you create a Future directly inside the build method, a new Future is created on every rebuild — meaning FutureBuilder treats it as a brand new operation each time and resets to the loading state unnecessarily.

// Bad: a new Future is created on every rebuild.
// FutureBuilder sees a different Future each time
// and resets to loading state unnecessarily.
@override
Widget build(BuildContext context) {
  return FutureBuilder(
    future: repository.fetchUser(userId), // new Future every build
    builder: (context, snapshot) { ... },
  );
}

// Good: create the Future once in initState.
// FutureBuilder holds the same reference across rebuilds.
late final Future<User> _userFuture;

@override
void initState() {
  super.initState();
  _userFuture = repository.fetchUser(widget.userId);
}

@override
Widget build(BuildContext context) {
  return FutureBuilder(
    future: _userFuture,
    builder: (context, snapshot) { ... },
  );
}

Move Heavy Work Off the UI Thread

Dart renders UI on the main isolate. Anything CPU-intensive that blocks it causes dropped frames.

// Parsing a large API response synchronously on the main isolate
// can block rendering for 50-200ms on slower devices.
final users = (response.data as List)
    .map((json) => User.fromJson(json))
    .toList();

// compute() runs the function in a separate isolate.
// The main isolate stays free to render frames.
// Note: the function must be top-level or static —
// closures that capture local state cannot be sent to another isolate.
final users = await compute(parseUsers, response.data);

List<User> parseUsers(dynamic data) {
  return (data as List)
      .map((json) => User.fromJson(json as Map<String, dynamic>))
      .toList();
}

I reach for compute whenever I am parsing a large JSON response, doing image processing, or running anything that feels slow in a quick profile. The threshold in my head is roughly 16ms — if an operation might take longer than that, it shouldn't be on the main isolate.

Memory Leaks and Lifecycle Management

This one cost me the most debugging time across all the apps I've shipped. Memory leaks in Flutter don't crash immediately. They build slowly — a few megabytes per session, every session — until the app starts feeling heavy, the OS starts killing it in the background, and users file bug reports about "random crashes."

The root cause is almost always the same: something created inside a widget keeps running after the widget is gone.

Controllers That Are Never Disposed

The most common source of memory leaks I've seen, including in my own code, is controllers that are created in initState and never released. Flutter doesn't clean these up automatically.

class _ProfileScreenState extends State<ProfileScreen> {
  late final TextEditingController _nameController;
  late final AnimationController _fadeController;
  late final ScrollController _scrollController;

  @override
  void initState() {
    super.initState();
    _nameController = TextEditingController();
    _fadeController = AnimationController(
      vsync: this,
      duration: const Duration(milliseconds: 300),
    );
    _scrollController = ScrollController();
  }

  @override
  void dispose() {
    // Every controller created in initState needs to be
    // disposed here. This is not optional — it releases
    // native resources and removes listeners that would
    // otherwise keep this widget's memory alive indefinitely.
    _nameController.dispose();
    _fadeController.dispose();
    _scrollController.dispose();
    super.dispose(); // always last
  }
}

An undisposed AnimationController is particularly bad. It holds a ticker that fires on every frame — so it keeps consuming CPU even after the screen it belonged to is gone. I've seen this cause noticeable battery drain in addition to memory issues.

Stream Subscriptions

class _ChatScreenState extends State<ChatScreen> {
  StreamSubscription<Message>? _messageSubscription;

  @override
  void initState() {
    super.initState();
    _messageSubscription = messageStream.listen((message) {
      // Without cancellation, this callback keeps firing
      // even after the screen is removed from the tree.
      // It will call setState on a disposed widget and
      // hold message objects in memory that should be freed.
      if (mounted) setState(() => messages.add(message));
    });
  }

  @override
  void dispose() {
    _messageSubscription?.cancel();
    super.dispose();
  }
}

Timers

@override
void dispose() {
  // A timer that fires after dispose will try to run
  // a callback on a widget that no longer exists.
  _dismissTimer?.cancel();
  super.dispose();
}

A rule I follow without exception: anything created in initState that has a dispose, cancel, or close method gets a corresponding call in dispose. No exceptions, no "I'll add it later."

Observability and Crash Reporting

Before I integrated crash reporting into my first production app, debugging was genuinely painful. A user would report a crash. I would ask what they were doing. They would say "I just opened it." I would stare at the code looking for anything that could cause that. Half the time I never figured it out.

With crash reporting, that changes completely.

Set it Up Before Launch

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp();

  // Catch Flutter framework errors — widget build errors,
  // rendering errors, etc.
  FlutterError.onError =
      FirebaseCrashlytics.instance.recordFlutterFatalError;

  // Catch errors in async code that Flutter does not catch —
  // errors in event handlers, timers, isolates.
  PlatformDispatcher.instance.onError = (error, stack) {
    FirebaseCrashlytics.instance.recordError(error, stack, fatal: true);
    return true;
  };

  runApp(const MyApp());
}

Never Let Failures Be Silent

// This is how I used to write it. If submitOrder throws,
// nothing happens. The user has no idea. I have no idea.
await api.submitOrder(order);

// This is how I write it now.
try {
  await api.submitOrder(order);
  setState(() => orderStatus = OrderStatus.confirmed);
} catch (e, stackTrace) {
  // recordError sends the full exception and stack trace
  // to Crashlytics, with device info and the user's
  // recent session activity attached automatically.
  FirebaseCrashlytics.instance.recordError(e, stackTrace);
  setState(() => orderStatus = OrderStatus.failed);
}

Breadcrumbs

Raw crash logs tell you what broke. Breadcrumbs tell you what the user was doing when it broke. These aren't the same thing.

FirebaseCrashlytics.instance.log('User opened checkout');
FirebaseCrashlytics.instance.log('Payment sheet presented');
FirebaseCrashlytics.instance.log('User submitted payment');
// crash here — now I know the exact sequence

Testing Production Flutter Apps

I'll be honest: I under-tested my first app. I was moving fast, the features worked, and writing tests felt slow. Then I refactored a pricing calculation, introduced a bug that wasn't immediately obvious, and shipped it. A user caught it before I did.

I test more carefully now. Not everything — but the things that matter.

Unit Test Business Logic

test('discount applies percentage correctly', () {
  final result = calculateDiscountedPrice(
    price: 100.0,
    discountPercent: 10,
  );

  // 10% off 100.00 should be 90.00
  expect(result, equals(90.0));
});

test('discount throws for negative percentage', () {
  expect(
    () => calculateDiscountedPrice(price: 100, discountPercent: -5),
    throwsA(isA<ArgumentError>()),
  );
});

Business logic – pricing, validation, authorization – should be in plain Dart functions with no Flutter dependencies, so they can be tested in milliseconds without any test infrastructure.

Widget Test UI States

Flutter's widget testing is genuinely one of its best features. You can test loading states, error states, and user interactions without a device or emulator.

testWidgets('shows error state with retry button on load failure',
    (tester) async {
  final mockRepo = MockUserRepository();
  when(mockRepo.getUser(any)).thenThrow(Exception('Network error'));

  await tester.pumpWidget(
    ProviderScope(
      overrides: [
        userRepositoryProvider.overrideWithValue(mockRepo),
      ],
      child: const MaterialApp(home: ProfileScreen(userId: 'test')),
    ),
  );

  // pumpAndSettle waits for all animations and async
  // operations to complete before asserting.
  await tester.pumpAndSettle();

  expect(find.text('Failed to load profile. Please try again.'), findsOneWidget);
  expect(find.text('Try again'), findsOneWidget);
});

What I prioritize testing: core business logic, error and loading states, any flow that involves money or data the user can't recover, and the integration points between my app and the backend. Static UI widgets that contain no logic I generally leave uncovered.

Architecture and Long-Term Maintainability

The first app I shipped had no real architecture. Everything was in widgets. Business logic sat next to UI code. State was scattered.

It worked fine for six months. Then I needed to add a feature that touched several existing screens, and what should have taken a day took a week because I couldn't change anything without breaking something else.

The second app I was more deliberate about. Features in their own folders. Repositories separate from widgets. State managed outside the UI layer. When requirements changed — and they always change — the changes were contained.

Separate Concerns at the Layer Boundary

lib/
  features/
    profile/
      data/
        profile_repository.dart     # network + cache logic
      domain/
        user.dart                   # clean domain model
      presentation/
        profile_screen.dart         # widget
        profile_notifier.dart       # state

Widgets shouldn't make network calls. Repositories shouldn't import Flutter. Neither should know anything about the other's internals.

When you need to swap the data source, or test the notifier with a mock, or change the UI without touching the business logic — this separation is what makes that possible.

Technical Debt Accumulates Faster Than You Expect

A shortcut that saves thirty minutes today tends to cost several hours a month from now. The shortcuts that compound fastest in Flutter:

• Business logic inside widgets (impossible to test, impossible to reuse)

• dynamic instead of typed models (runtime errors instead of compile-time errors)

• Copy-pasted validation logic (change it in one place and forget the others)

• Mutable global state without clear ownership

None of these are catastrophic on day one. All of them make the next change harder than it should be, and the change after that harder still.

End-to-End Example: a Production-Grade Profile Feature

Here's everything from this article assembled into one feature. A repository with caching and retry, a Riverpod notifier with optimistic updates, a widget that handles all three states, and proper lifecycle management throughout.

The Repository

class ProfileRepository {
  final Dio _dio;
  final Box _cache;

  ProfileRepository(this._dio, this._cache);

  Future<User> getUser(String userId) async {
    try {
      final response = await withRetry(
        () => _dio.get('/users/$userId'),
      );

      final user = User.fromJson(
        response.data as Map<String, dynamic>,
      );

      // Cache successful responses for offline fallback.
      await _cache.put('user_$userId', user.toJson());

      return user;
    } on DioException catch (e) {
      final cached = _cache.get('user_$userId');

      if (cached != null) {
        return User.fromJson(Map<String, dynamic>.from(cached));
      }

      if (e.type == DioExceptionType.connectionError) {
        throw NoInternetException();
      }

      throw ServerException(e.response?.statusCode ?? 0);
    }
  }

  Future<void> updateDisplayName(String userId, String name) async {
    await withRetry(
      () => _dio.patch('/users/$userId', data: {'displayName': name}),
    );

    // Invalidate cache so the next read fetches fresh data.
    await _cache.delete('user_$userId');
  }
}

The Notifier

@riverpod
class ProfileNotifier extends _$ProfileNotifier {
  @override
  AsyncValue<User> build(String userId) {
    _load();
    return const AsyncValue.loading();
  }

  Future<void> _load() async {
    state = const AsyncValue.loading();
    state = await AsyncValue.guard(
      () => ref.read(profileRepositoryProvider).getUser(userId),
    );
  }

  Future<void> refresh() => _load();

  Future<void> updateName(String newName) async {
    final current = state.valueOrNull;
    if (current == null) return;

    try {
      await ref
          .read(profileRepositoryProvider)
          .updateDisplayName(userId, newName);

      // Update the UI immediately without waiting for a reload.
      state = AsyncValue.data(current.copyWith(displayName: newName));
    } catch (e, st) {
      FirebaseCrashlytics.instance.recordError(e, st);
      // Restore the previous state if the update fails.
      state = AsyncValue.data(current);
      rethrow;
    }
  }
}

The Widget

class ProfileScreen extends ConsumerWidget {
  final String userId;
  const ProfileScreen({required this.userId, super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final profileAsync = ref.watch(profileNotifierProvider(userId));

    return Scaffold(
      appBar: AppBar(title: const Text('Profile')),
      body: profileAsync.when(
        loading: () => const Center(child: CircularProgressIndicator()),
        error: (e, _) => _ErrorView(
          message: e is NoInternetException
              ? 'No internet connection.'
              : 'Failed to load profile.',
          onRetry: () => ref
              .read(profileNotifierProvider(userId).notifier)
              .refresh(),
        ),
        data: (user) => _ProfileView(user: user, userId: userId),
      ),
    );
  }
}

class _ProfileView extends ConsumerStatefulWidget {
  final User user;
  final String userId;
  const _ProfileView({required this.user, required this.userId});

  @override
  ConsumerState<_ProfileView> createState() => _ProfileViewState();
}

class _ProfileViewState extends ConsumerState<_ProfileView> {
  late final TextEditingController _nameController;

  @override
  void initState() {
    super.initState();
    _nameController = TextEditingController(text: widget.user.displayName);
  }

  @override
  void dispose() {
    _nameController.dispose();
    super.dispose();
  }

  Future<void> _saveName() async {
    try {
      await ref
          .read(profileNotifierProvider(widget.userId).notifier)
          .updateName(_nameController.text);

      if (!mounted) return;

      ScaffoldMessenger.of(context).showSnackBar(
        const SnackBar(content: Text('Name updated.')),
      );
    } catch (_) {
      if (!mounted) return;

      ScaffoldMessenger.of(context).showSnackBar(
        const SnackBar(content: Text('Failed to update name.')),
      );
    }
  }

  @override
  Widget build(BuildContext context) {
    return ListView(
      padding: const EdgeInsets.all(16),
      children: [
        TextField(
          controller: _nameController,
          decoration: const InputDecoration(labelText: 'Display name'),
        ),
        const SizedBox(height: 16),
        ElevatedButton(
          onPressed: _saveName,
          child: const Text('Save'),
        ),
      ],
    );
  }
}

Final Thoughts

None of this is particularly advanced. It's mostly habits — checking mounted, disposing controllers, handling the error state, caching for offline. Each habit prevents one specific category of production failure, and together they add up to an app that users experience as reliable.

I wish I'd written my first app this way. I didn't, because I didn't know what I didn't know yet. That is normal.

But if you're reading this before shipping your first production app, you now have the benefit of what took me multiple shipped apps and a lot of frustrated user feedback to learn.

The best time to add these patterns is at the start of a feature. The second-best time is now.

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

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

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

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

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

• Debug connection issues like a seasoned detective.

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

Prerequisites:

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

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

Table of Contents

1. A Brief History of Bluetooth in Android

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

3. Deep Dive #1: Passive Scanning

4. Understanding the BluetoothLeScanner

5. Hands-On: Building Your First Passive Scanner

6. Deep Dive #2: Bluetooth Bond Loss Reasons

7. Deep Dive #3: Service UUIDs from Advertisements

8. Advanced Topics: Leveling Up Your Scanning Game

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

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

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

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

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

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

The Dark Ages: Classic Bluetooth

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

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

The Renaissance: Enter Bluetooth Low Energy (BLE)

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

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

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

The Problem Child: Scanning

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

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

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

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

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

A Tale of Two Releases

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

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

The Three Musketeers of Bluetooth

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

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

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

Deep Dive #1: Passive Scanning

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

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

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

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

Active vs. Passive: The Technical Showdown

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

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

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

Why Go Passive? The Power of Silence

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

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

The Code: How to Become a Bluetooth Ninja

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

Previously, you might have done something like this:

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

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

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

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

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

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

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

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

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

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

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

Understanding BluetoothLeScanner (The Star of Our Show)

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

The Architecture: A Peek Behind the Curtain

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

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

The Alphabet Soup: GATT, GAP, and Friends

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

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

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

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

The Scanning Lifecycle: A Dramatic Play in Three Acts

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

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

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

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

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

Hands-On: Building Your First Passive Scanner

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

Step 1: The Permission Inquisition

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

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

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

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

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

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

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

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

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

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

Step 2: The Code Awakens

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

Get the Scanner

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

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

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

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

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

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

Define the Callback

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

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

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

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

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

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

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

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

Configure the Scan

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

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

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

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

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

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

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

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

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

Start and Stop the Scan

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

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

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

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

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

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

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

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

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

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

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

Putting It All Together

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

// In your Activity class

class MainActivity : AppCompatActivity() {

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

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

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

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

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

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

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

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

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

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

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

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

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

Deep Dive #2: Bluetooth Bond Loss Reasons

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

Until it's not.

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

Finally, Some Closure!

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

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

The Code: Playing Detective

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Deep Dive #3: Service UUIDs from Advertisements

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

What in the World is a Service UUID?

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

The Old Way: The Awkward First Date

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

1. Scan: Find the device.

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

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

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

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

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

The New Way: The Glorious Name Tag

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

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

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

The Code: Reading the Name Tag

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

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

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

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

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

    // ... onScanFailed ...
}

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

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

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

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

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

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

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

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

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

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

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

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

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

Advanced Topics: Filtering, Batching, and Other Sorcery

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

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

Hardware Filtering: Your Personal Assistant

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

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

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

The Code: Building Your VIP List

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

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

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

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

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

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

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

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

But the builder has many other options you can use:

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

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

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

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

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

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

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

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

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

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

Batch Scanning: The Daily Report

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

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

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

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

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

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

    // ... onScanFailed ...
}

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

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

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

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

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

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

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

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

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

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

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

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

OnFound/OnLost: The Drama of Presence

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

1. The "Find My Everything" App

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

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

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

2. The Smart Supermarket

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

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

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

3. The Overly-Attached Smart Home

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

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

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

4. The Corporate Asset Tracker

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

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

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

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

API Version Checking: How to Not Crash Your App

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

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

The Problem: A Tale of Two Android 16s

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

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

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

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

The Old Guard: SDK_INT

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

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

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

The New Hotness: SDK_INT_FULL

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

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

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

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

val scanSettings = scanSettingsBuilder.build()

Graceful Degradation: The Art of Falling with Style

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

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

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

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

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

There are two universal truths in software development:

• It works on my machine, and

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

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

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

The Emulator: A Land of Make-Believe

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

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

The Real World: Where the Bugs Live

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

Your testing arsenal should include:

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

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

Common Errors: The Usual Suspects

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

Debugging Tools: Your Ghost-Hunting Kit

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

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

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

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

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

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

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

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

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

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

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

2. Stop Your Scan!

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

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

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

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

3. Choose the Right Scan Mode

ScanSettings gives you a few different modes. Choose wisely.

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

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

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

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

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

4. Use Hardware Filtering and Batching

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

5. Be Mindful of Memory

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

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

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

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

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

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

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

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

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

Then you try to connect one more thing. Maybe a fitness band, a smart lock, or that tiny temperature sensor you ordered online because it was on sale. That is when the charm fades and reality walks in. Suddenly the connection drops, your phone cannot find the device anymore, and the once-friendly Bluetooth logo on your screen starts to feel like a taunt. You restart, you unpair, you try again, and somehow it only gets worse. What was once effortless turns into a puzzle with no clear solution.

Here is the secret that few people know: Bluetooth was never meant to handle the chaos we put it through today. When engineers designed it in the late 1990s, they imagined a world of simple one-to-one connections. A laptop talking to a mouse. A phone connecting to a headset. That was the whole idea. Fast-forward to the present and we are using the same technology to run entire networks of wearables, sensors, and smart appliances. We ask it to connect not just one or two devices but sometimes dozens of them at the same time, each running on different hardware and software. It is a miracle that it works at all.

To make things even more interesting, these devices live in very different worlds. Android devices are like an open playground where every manufacturer adds its own slide and swing set. iPhones live inside Apple’s carefully fenced garden where everything is polished but also tightly controlled. Embedded devices, like the ones built on tiny chips inside sensors or IoT boards, are the quiet introverts of the group. They have little memory, tiny batteries, and a strong preference for naps to save power. Getting all three to cooperate is a bit like trying to organize a band where one member only plays jazz, another insists on classical, and the third speaks in Morse code.

That is what engineers mean when they talk about scaling Bluetooth. It is not just about adding more devices. It is about making sure completely different systems can talk to each other reliably and continuously without draining their batteries or losing their minds. It requires design decisions that consider timing, power management, data formats, and even how the operating system schedules background tasks.

This article will guide you through that strange world. We will peel back the layers of how Bluetooth actually works and what happens when Android, iOS, and embedded devices try to share the same airwaves. We will explore why each one behaves the way it does and what you can do to build systems that stay connected instead of collapsing under their own complexity.

By the end, you will see that Bluetooth is not really broken. It is simply overworked. It is a polite translator trying to keep three very different languages in sync. Once you learn how to manage its quirks and give it the structure it needs, Bluetooth becomes not a source of frustration but a quiet, invisible network that holds the modern world together.

Table of Contents

• Bluetooth Has Two Personalities — Meet Classic and BLE

• Android, iOS, and Embedded Devices — The Odd Trio

• Architecting for Scale — Herding Cats, but Wirelessly

• Connection, Discovery, and Data Flow — The Bluetooth Dating Game

• Platform Quirks — And How to Stay Sane

• Security and Privacy at Scale

• Power and Performance Tuning

• Provisioning and Firmware Updates — Welcome to Device Kindergarten

• Debugging, Monitoring, and Testing Across Platforms

• Real-World Architecture Example — When Bluetooth Finally Behaves

• Checklist — Building a Truly Scalable Bluetooth System

• Wrap-Up — Lessons from the Field

Bluetooth Has Two Personalities — Meet Classic and BLE

Before we can talk about scaling Bluetooth, we have to understand that Bluetooth itself has a bit of an identity crisis. It actually comes in two flavors: Classic Bluetooth and Bluetooth Low Energy, also called BLE. They share the same name and sometimes even live on the same chip, but under the hood they behave very differently. Think of them as twins who went to completely different schools and now have opposite personalities.

Classic Bluetooth is the older sibling. It was designed for steady, high-speed data streams. This is the version your headphones, speakers, and car systems use. It is reliable for sending large amounts of data like audio, but it is also chatty and power-hungry. It likes to stay connected all the time, constantly keeping the line open so it can send sound packets smoothly. You could say Classic Bluetooth is like that one friend who calls instead of texting and keeps the conversation going even when there is nothing left to say.

Then there is Bluetooth Low Energy, the younger, more introverted sibling. BLE was designed for devices that need to last for weeks or months on tiny batteries. It does not keep a constant connection open. Instead, it wakes up, sends or receives a little bit of data, and then goes back to sleep. It is the protocol behind fitness trackers, heart rate monitors, smart locks, and most modern IoT devices. If Classic Bluetooth is a full-time conversation, BLE is more like sending quick text messages throughout the day, short, efficient, and battery-friendly.

The funny thing is that even though they share the same wireless spectrum and sometimes even the same antenna, these two modes do not talk to each other directly. A BLE device cannot communicate with a Classic Bluetooth-only device. This is why your wireless headphones can pair with your phone, but your BLE heart rate monitor cannot talk to your old Bluetooth speaker. They live in the same neighborhood but never attend the same parties.

Most of the world’s scaling problems come from BLE, not Classic Bluetooth. Classic has been around long enough that its use cases are stable and well understood. BLE, on the other hand, is used in thousands of different kinds of devices, each with different timing requirements, power limits, and operating systems. When you try to make Android, iOS, and embedded systems all use BLE together, you are juggling three slightly different interpretations of the same rulebook.

To make things trickier, each platform implements BLE its own way. Android exposes it through flexible but sometimes unpredictable APIs. iOS keeps it tidy under Apple’s strict Core Bluetooth framework. Embedded devices rely on lightweight vendor stacks that can vary from chip to chip. Every one of these stacks follows the same Bluetooth specification, but like recipes written by different chefs, the results can taste a little different.

Understanding this dual nature is key to building anything that scales. You must know when to use Classic Bluetooth for high-speed continuous data, when to use BLE for low-power bursts, and how to design your system so that the right devices use the right mode. It is the first step in turning Bluetooth from a confusing mystery into a reliable network you can actually control.

Android, iOS, and Embedded Devices — The Odd Trio

Now that we know Bluetooth has two personalities, let’s meet the three characters that make scaling it so complicated: Android, iOS, and embedded devices. They all speak Bluetooth, but in their own unique accents. Sometimes they understand each other perfectly, and other times it feels like they’re arguing in three different languages while pretending they’re on the same page.

Let’s start with Android. Android is the enthusiastic extrovert of the group. It gives you tons of control and freedom. You can scan, connect, advertise, read, write, and basically poke around every corner of the Bluetooth stack. But that freedom comes with chaos. Because Android runs on phones made by dozens of manufacturers, each one tweaks the Bluetooth implementation a little differently. On one phone, everything works flawlessly. On another, the same code randomly drops connections or refuses to scan in the background. Even Android engineers joke that if your Bluetooth works the same on every device, you’ve probably entered a parallel universe.

Android is powerful but unpredictable. It’s like a sports car that can win a race on a good day but sometimes refuses to start if it doesn’t like the weather. The trick is to write code that expects weird behavior, to build your own connection queues, add retries, and prepare for the occasional glitch. Developers who survive Android Bluetooth bugs don’t just gain experience, they gain humility.

Then there’s iOS, Apple’s polished and opinionated perfectionist. Unlike Android, iOS is consistent. The same code usually behaves the same way across every iPhone and iPad. Apple’s Bluetooth framework, called Core Bluetooth, is beautifully organized and well-documented. But Apple also has strict rules about what you can and can’t do. Background scanning? Only in very specific cases. Advertising? Only for certain UUIDs. Access to lower-level Bluetooth layers? Absolutely not. Apple’s approach is like a luxury hotel: everything looks gorgeous, but you’re not allowed in the kitchen.

Working with iOS feels calm at first. Your connections are stable, your APIs are clear, and your devices behave predictably. But the moment you need to do something slightly unconventional, like connecting to multiple peripherals at once or keeping the app alive in the background, iOS politely says, “No, that’s not how we do things here.” Developers often end up performing delicate dances with background modes, notifications, and clever reconnection tricks just to make things feel seamless for users.

And then we have the third member of the trio: embedded devices. These are the quiet, uncomplaining ones that actually do most of the work. They live inside your smart sensors, wearables, and IoT nodes. They’re usually built around tiny chips with limited memory and low-power processors. They don’t have fancy operating systems or flashy UI frameworks. All they know is how to advertise, connect, send data, and then go back to sleep to save battery.

Embedded devices are loyal but easily overwhelmed. They can’t handle constant large data transfers, and they get cranky if you make them maintain too many simultaneous connections. Imagine trying to run a marathon after eating one grape, that’s what it’s like for a small BLE chip to handle too much traffic. Yet, these little devices are the backbone of every scalable Bluetooth network. They measure your heart rate, control your smart lights, and track your environmental sensors, all while running quietly in the background.

The real challenge begins when you try to make these three cooperate. Android wants freedom, iOS wants structure, and embedded devices just want a nap. Getting them all to work together is like managing a group project where one person writes essays at midnight, another color-codes everything, and the third forgets to charge their laptop. But when you finally get it right, when Android, iOS, and your embedded nodes connect seamlessly, it feels like magic again.

In the next section, we’ll explore how to actually make that happen. You’ll see how to design a Bluetooth architecture that scales gracefully across these platforms instead of collapsing into a pile of logs and retries. It’s part engineering, part patience, and part diplomacy.

Architecting for Scale — Herding Cats, but Wirelessly

If there’s one secret to scaling Bluetooth, it’s this: treat it like herding cats. You’ll never truly control it, but with enough structure, patience, and a bit of catnip (or clever engineering), you can convince all the cats to move in roughly the same direction.

Building a Bluetooth system that spans Android, iOS, and embedded devices isn’t just about writing code that connects things. It’s about designing relationships, the rules and boundaries that keep those connections healthy. The key idea here is architecture, which is a fancy word for “deciding who does what, when, and how.” Without a solid architecture, your Bluetooth project quickly turns into a tangle of callbacks, disconnections, and unanswered packets.

The first principle of Bluetooth architecture is abstraction. Every platform has its own Bluetooth API, but the basic idea is always the same: scan for devices, connect, exchange data, and disconnect. So instead of writing separate logic for each platform, you create one unified interface, a sort of translator layer, that hides all the messy differences underneath. In practice, this means you can write something like connect(device) in your app, and whether you’re on Android, iOS, or even a Raspberry Pi, the underlying code figures out how to make it happen.

This abstraction layer is your peacekeeper. It prevents the rest of your app from needing to know whether it’s talking to a Nordic chip on a wristband, a smart bulb using an ESP32, or an iPhone pretending to be a peripheral. When you have hundreds or thousands of devices, abstraction isn’t just convenient, it’s survival.

Next comes connection management. BLE connections are like toddlers: they demand constant attention and can vanish the moment you look away. A scalable Bluetooth system can’t afford to panic every time a device disconnects. Instead, you design it to expect chaos. You add automatic retries, reconnection strategies, and timeouts that gracefully handle failures instead of freezing your app. Good systems don’t assume the network will always behave, they assume it won’t.

Then there’s data orchestration, deciding who talks first, how much data gets sent, and how you keep multiple connections from tripping over each other. Imagine you’re a conductor in an orchestra where half the instruments fall asleep randomly to save power. You need a plan that lets each device play its part in harmony without draining its battery. That’s what managing Bluetooth data flow feels like.

And finally, there’s power strategy. Embedded devices live on tight energy budgets. Every scan, advertisement, and data exchange eats into their lifespan. So, your architecture must schedule communication intelligently, let devices wake up briefly, share data, and return to sleep before they burn out. The best Bluetooth systems look lazy on the surface but are actually brilliant planners underneath.

When you put all of this together, abstraction, connection management, orchestration, and power control, you get something that scales. It doesn’t matter if you’re managing three wearables or three thousand sensors. The system behaves predictably, logs issues instead of panicking, and recovers from disconnections automatically.

Think of it like a well-run airport. Planes (your devices) take off and land constantly. The control tower (your app’s Bluetooth manager) keeps track of who’s in the air, who’s landing next, and who needs maintenance. No single pilot needs to know everything, they just follow the protocol.

Scaling Bluetooth isn’t about being clever with one device. It’s about designing systems that keep working even when dozens of devices act unpredictably. You don’t tame Bluetooth by force; you do it by creating a world where even chaos feels organized.

In the next section, we’ll dig deeper into how these connections actually behave in real time, how devices discover each other, exchange data, and, sometimes, break up without warning.

Connection, Discovery, and Data Flow — The Bluetooth Dating Game

Every Bluetooth connection starts like a modern love story. One device sends out signals into the air, announcing that it’s available. Another device scans the surroundings, hoping to find something compatible. When they finally spot each other, they exchange a few polite packets, decide they’re a good match, and try to make it official with a connection. It’s wireless romance, until one of them walks away without saying goodbye.

This is the heart of how Bluetooth works: advertising, discovery, and connection. An embedded sensor or wearable device usually plays the role of the advertiser. It broadcasts tiny packets called advertisements that contain just enough information to say, “Hey, I’m here, and I can measure temperature or heart rate or unlock your door.” These packets are intentionally small because transmitting data takes energy, and low-power devices have to conserve every drop of battery life.

Meanwhile, your phone or tablet acts as the scanner, it listens to the radio waves around it, searching for those signals. When it finds one that matches what it’s looking for, it sends a request to connect. If the peripheral accepts, they move into a new relationship phase: the GATT connection. GATT stands for Generic Attribute Profile, which is basically the language they use to talk. Once connected, your phone can ask the device for specific data, like reading a heart rate measurement or writing a configuration setting.

Now, if all of this sounds peaceful and predictable, that’s because we haven’t talked about what happens in the real world. In reality, devices move around, signals weaken, and phones go into power-saving modes that forget they were even connected. Connections drop. Pairing sometimes fails. And when you have ten or more devices talking at once, managing all those tiny wireless conversations becomes a circus act.

Scaling Bluetooth is all about keeping this circus under control. You can’t force every device to stay connected forever, that would drain batteries and jam the radio channels. Instead, you design a rhythm. Devices connect only when needed, exchange data quickly, and then disconnect to rest. This constant dance of connecting and disconnecting keeps the system efficient and stable.

Think of it like a well-run coffee shop. Customers (phones) walk in, place their order (data request), get their coffee (response), and leave. The barista (the embedded device) doesn’t serve one person all day, it serves everyone in quick cycles. The trick is to make sure no one gets stuck waiting for their latte forever.

Timing is everything in this dance. If a device advertises too infrequently, the phone might not discover it in time. If it advertises too often, it wastes power. If the phone sends too many requests at once, the device might crash or slow down. Bluetooth connections live in this delicate balance between performance and efficiency.

When you scale, you also have to think about coordination. Imagine one phone trying to talk to ten sensors at once. You can’t have it flood them all with requests simultaneously, it needs a queue, a polite way of saying “you first, then me.” This is called connection orchestration, and it’s one of the hardest parts of scaling BLE systems.

And then there’s the breakup. Devices disconnect all the time, sometimes intentionally, sometimes accidentally. The best Bluetooth systems treat disconnections not as failures but as normal events. The app automatically retries, reconnects, and syncs data without asking the user to “try again.” To users, it feels seamless. Underneath, there’s a lot of quiet heroism happening, background threads, timers, and reconnection logic all working together to patch up relationships on the fly.

So, at its core, Bluetooth is less like a stable marriage and more like speed dating with excellent scheduling. Everyone meets briefly, exchanges information, and moves on. When done right, this model scales effortlessly. When done wrong, it’s chaos.

In the next section, we’ll explore the quirks that make Android, iOS, and embedded devices behave differently in this dating game, and how to keep the peace when one of them inevitably ghosts the others.

Platform Quirks — And How to Stay Sane

Once you start scaling Bluetooth, you’ll notice something odd. The same code that works perfectly on one device suddenly refuses to behave on another. It’s like watching identical twins argue about who gets the last slice of pizza, they may look the same, but their personalities couldn’t be more different.

Let’s start with Android, the unpredictable one. Android gives developers more power than any other mobile platform. You can scan however you like, filter by services, read and write any characteristic, and even customize connection intervals. But that power comes at a price. Every phone manufacturer modifies the Bluetooth stack slightly. Samsung, Pixel, OnePlus, Xiaomi, each adds its own flavor of “enhancement,” which sometimes translates to “surprise, nothing works the same.”

One Android phone might handle ten connections at once without blinking. Another might drop all of them the moment the screen turns off. Some versions ignore Bluetooth permissions until you grant location access. Others claim they’re scanning when they actually stopped five minutes ago. Android developers eventually stop asking why and simply build more logging instead. The rule of thumb with Android Bluetooth is simple: test everything, assume nothing, and expect the unexpected.

Then there’s iOS, which at first feels like a breath of fresh air. Apple’s Core Bluetooth framework is clean, consistent, and almost elegant. You get predictable callbacks, smooth reconnections, and well-behaved devices. But if you step outside Apple’s boundaries, you’ll quickly find invisible fences. iOS doesn’t let apps scan in the background freely. It limits how often you can advertise. And if your app tries to keep too many simultaneous connections alive, iOS politely steps in and shuts them down.

Apple’s philosophy is control. It wants Bluetooth connections to behave in ways that don’t drain the battery or clutter the radio. That’s great for users, but for developers it can feel like being handed the keys to a Ferrari and told you can only drive in the parking lot. It works beautifully, as long as you color inside the lines.

And then we have embedded devices, which are in a category of their own. These are the little chips sitting inside your wearables, sensors, or IoT gadgets. They don’t have operating systems or background processes. They just run tiny loops of firmware that listen, respond, and sleep. Their quirks are more about physics than software. If the antenna isn’t tuned properly, signals drop. If the power supply fluctuates, the radio turns off. Sometimes they disconnect simply because a human walked between two devices and absorbed the signal.

Embedded Bluetooth stacks also differ by manufacturer. Nordic, Espressif, Silicon Labs, Texas Instruments, each has its own libraries, quirks, and limitations. Even small changes like increasing the packet size or adjusting the advertising interval can make or break communication. It’s a careful dance between efficiency and reliability.

Now imagine you’re trying to get all three of these worlds to cooperate. Android wants freedom, iOS enforces discipline, and embedded devices want long naps. Building a Bluetooth system that works across all of them is like running a daycare with overachievers, rule-followers, and kids who fall asleep mid-activity. You can’t treat them all the same, but you can design a routine that keeps everyone content.

The secret is resilience. Instead of expecting perfect behavior, build your system around imperfections. Add retries when connections fail. Cache data so you don’t lose progress during disconnections. Keep your embedded devices simple, your mobile apps forgiving, and your logs brutally honest.

If you design with these quirks in mind, your Bluetooth system will feel almost magical, even though, behind the scenes, it’s a web of error handling, reconnections, and polite compromise.

In the next section, we’ll take a look at another side of scaling: keeping everything secure and private while all these devices whisper secrets over the air.

Security and Privacy at Scale

Once your Bluetooth system starts working reliably, there’s another challenge waiting in the wings: keeping it secure. It’s one thing to get devices talking to each other, it’s another to make sure no one else is eavesdropping on the conversation. Bluetooth security can sound intimidating, but at its core, it’s about making sure your devices trust each other and that strangers can’t sneak into the chat.

Let’s start with pairing. Pairing is Bluetooth’s version of saying, “Hey, can I trust you?” It’s a handshake where two devices exchange keys that let them communicate securely in the future. There are a few ways this handshake can happen. The simplest is called Just Works, which basically means, “We’ll trust each other without asking too many questions.” It’s convenient but about as safe as leaving your front door unlocked because you live in a nice neighborhood. For harmless gadgets like wireless speakers, that’s fine. But for medical devices or smart locks, “Just Works” can turn into “Just Got Hacked.”

A safer approach is Passkey Entry, where one device shows a code and the other types it in, proving they’re physically near each other. Even better is Out-of-Band (OOB) pairing, where the devices exchange security information through another method, maybe a QR code, NFC tap, or even an optical blink, before connecting over Bluetooth. OOB pairing is like verifying someone’s identity face-to-face before continuing a conversation online.

Once paired, devices use encryption to scramble their communication. Anyone listening nearby will hear only gibberish. The strength of that encryption depends on the version of Bluetooth being used. Modern devices using Bluetooth 4.2 or later support something called LE Secure Connections, which is based on advanced cryptography. Older devices use weaker methods that are easier to crack. So, if you’re building something new, never rely on outdated pairing modes.

But security isn’t just about encryption. It’s also about privacy. Every Bluetooth device has an address, kind of like its phone number, that it uses when broadcasting. If that address stays the same, someone could track you by following your device’s broadcasts. That’s why newer standards support random address rotation, where devices periodically change their Bluetooth address. Your phone and smartwatch still recognize each other, but strangers can’t follow your signal around the city.

When you scale Bluetooth systems, these little details become critical. A single insecure device in your network can become the weak link that compromises everything. It’s like locking every door in your house but leaving one window open. Attackers don’t need to break the whole system, they just need to find the lazy one.

Building security into a large Bluetooth deployment means standardizing your pairing process, using strong encryption everywhere, and handling key storage carefully. On embedded devices, that can be tricky because they have limited memory and no secure element by default. Still, even small steps help, like regenerating keys periodically and disabling “Just Works” mode for devices that control anything important.

On mobile platforms, the rules are slightly different. Android and iOS handle much of the heavy lifting for you, but you still have to design your app logic carefully. Always confirm which device you’re connecting to before exchanging sensitive data. Always check bonding state before sending configuration commands. In short, treat Bluetooth communication with the same seriousness you’d give to a login session or an online payment.

At scale, security isn’t something you bolt on later. It’s part of the system’s DNA. You can’t fix a weak handshake by adding a stronger password later. You have to start from the first pairing and make sure every connection trusts the right partner.

The reward is worth it. When done right, your Bluetooth network becomes invisible but secure, a quiet, encrypted web of trust that just works. No drama, no leaks, and no nearby strangers hijacking your sensors.

In the next section, we’ll talk about another invisible problem that decides whether your Bluetooth network lives for days or months: power. Because what good is a secure device if its battery dies halfway through the handshake?

Power and Performance Tuning

If you’ve ever wondered why your Bluetooth gadget dies right when you need it most, you’ve just met the oldest enemy in wireless communication: power consumption. Bluetooth may be clever, flexible, and everywhere, but it also has a bit of a caffeine problem. It loves to talk, and talking burns energy. Keeping your devices alive longer, especially when you scale, means learning the quiet art of power management.

At first, it’s easy to assume that Bluetooth is low power by default. After all, it’s called Bluetooth Low Energy, right? But BLE’s efficiency only shines when it’s used correctly. A poorly tuned BLE system can drain a battery faster than streaming music over Classic Bluetooth. The magic lies in controlling when devices talk, how long they talk, and how much they say each time.

Let’s start with the advertising interval. This is how often a device shouts, “I’m here!” into the air. If you set it to broadcast every 20 milliseconds, you’ll discover devices quickly, but you’ll also burn through the battery like it’s running a marathon. Increase the interval to once every second, and your device will last much longer, but phones may take a moment to find it. It’s a tradeoff between speed and stamina. Every system has to find its sweet spot.

Next comes the connection interval, how often two connected devices exchange data. This is like deciding how frequently you check your messages. If you check every second, you stay perfectly up to date but never get anything else done. If you check once every minute, you save time but risk missing something important. In Bluetooth terms, a shorter connection interval means faster communication but higher power usage. Longer intervals conserve battery but add delay. Smart systems adjust these intervals dynamically depending on what the device is doing.

Then there’s the MTU, or Maximum Transmission Unit, the size of each Bluetooth data packet. Bigger packets mean fewer total transmissions for large chunks of data, which can improve efficiency. But some devices, especially older ones, can’t handle large MTUs, so finding the right balance is important.

Power management is not just about numbers, it’s about habits. A well-designed embedded device spends most of its life asleep. It wakes up only to advertise or exchange data, then returns to rest as quickly as possible. Imagine a hummingbird darting out for a sip of nectar and then zipping back to rest before anyone notices. That’s how efficient Bluetooth devices survive on coin-cell batteries for months or even years.

On the phone side, energy management is just as critical, especially when your app needs to handle multiple connections. Constant scanning, reconnecting, or keeping GATT channels open drains your user’s battery, and patience. Android and iOS both have built-in mechanisms that throttle background Bluetooth activity to save power. Developers have to work with these rules, not against them. The best apps schedule scans intelligently, reconnect only when necessary, and avoid holding connections open when no data needs to be sent.

Scaling Bluetooth systems makes these power decisions even more important. When you have one device, wasting a bit of energy doesn’t matter. When you have hundreds of devices, each one burning just a few extra milliwatts, the total waste adds up quickly. Power efficiency becomes the difference between a network that runs for months and one that collapses after a week.

The golden rule of power tuning is simple: talk less, talk smarter. A Bluetooth device that knows when to speak and when to stay quiet can scale beautifully, even in large networks. It’s not about being fast all the time, it’s about being clever with timing.

In the next section, we’ll look at how these devices join your network in the first place and what happens when you need to update their software later. Because once your system scales, you’re not just connecting devices, you’re managing an entire population.

Provisioning and Firmware Updates — Welcome to Device Kindergarten

Imagine setting up one Bluetooth device. It’s easy: you pair it, give it a name, and maybe tweak a few settings. Now imagine doing that a hundred times. Or a thousand. Suddenly, what felt like a simple task starts to look like a factory assembly line powered by frustration. That’s where provisioning comes in, the process of onboarding new devices into your Bluetooth network so they can start working right away, without manual babysitting.

Provisioning is like a first day at school for your devices. Each new student needs to be identified, assigned to a class, and given a name tag. In the Bluetooth world, a newly manufactured device begins life in an “unprovisioned” state. It doesn’t belong to any network yet, so it advertises with a special signal that says, “Hey, I’m new here.” When your mobile app or gateway spots that advertisement, it can connect, authenticate the device, and hand over the credentials it needs to join the system.

The app usually performs a few key steps during provisioning. It verifies that the device is genuine, assigns it a unique identifier, and exchanges security keys so future connections can happen securely. It might also store metadata like which room the sensor belongs to or what type of data it will report. After provisioning, the device switches to its normal operation mode, where it advertises with its new identity and starts behaving like a member of the family.

When you have just one or two devices, you can do all this manually. But when you scale up to hundreds or thousands, manual setup becomes impossible. That’s when you start thinking about automation, QR codes on packaging, NFC tags for instant pairing, or out-of-band provisioning where a separate channel (like Wi-Fi or a wired link) handles secure onboarding. The goal is to make provisioning quick, repeatable, and error-free, even when your factory or users are adding new devices by the dozens.

Once your devices are out in the world, the next challenge appears: firmware updates. Every system eventually needs to fix bugs, patch security holes, or add new features. For Bluetooth devices, this means pushing new firmware over the same wireless link, a process known as FOTA, or firmware-over-the-air updates.

Updating firmware over Bluetooth can be nerve-wracking. The connection is relatively slow, and interruptions can leave a device half-updated and confused about who it is. Good update systems handle this carefully. They divide the firmware into chunks, verify each piece with checksums, and only switch to the new version once the whole update has been safely received and validated. If anything fails midway, the device rolls back to the old firmware instead of bricking itself.

Scaling makes this even more complex. Updating ten devices is fine. Updating a thousand can overwhelm your network if you try to do them all at once. Smart systems stagger the updates in waves, track which devices have finished, and retry the ones that didn’t. Some even let devices report their status back to a central dashboard, so you can see which ones are ready and which ones are still stuck halfway through.

Provisioning and firmware updates might not sound glamorous, but they’re the backbone of every scalable Bluetooth system. Without smooth onboarding and reliable updates, your network slowly falls apart as devices drift out of sync or miss critical fixes.

Think of it this way: provisioning is how devices join the family, and firmware updates are how they grow up. Both are essential if you want your Bluetooth ecosystem to stay healthy and dependable over time.

In the next section, we’ll talk about what happens when something inevitably goes wrong, how to debug and monitor a network full of devices without losing your mind.

Debugging, Monitoring, and Testing Across Platforms

At some point, every Bluetooth developer faces the same moment of quiet despair. The logs look fine, the devices are paired, the code hasn’t changed, and yet… nothing works. Connections fail, packets vanish, and everything that worked yesterday now refuses to cooperate. Welcome to the wonderful, mysterious world of Bluetooth debugging, a place where logic takes a vacation and patience becomes your most valuable skill.

Debugging Bluetooth is tricky because so much of it happens invisibly. The data is flying through the air, hopping between frequencies dozens of times per second, and all you can see is whether the connection succeeds or fails. It’s like trying to diagnose a conversation between two people whispering in another room. You can tell they’re talking, but not what they’re saying.

The first rule of Bluetooth debugging is simple: log everything. Log when you start scanning, when you find a device, when you connect, and when you disconnect. Log the signal strength, the UUIDs you discover, the number of bytes you read, and the time it took. Bluetooth problems rarely announce themselves loudly, they hide in tiny details. A small delay in a callback or a missing acknowledgment can reveal exactly why your system seems haunted.

Different platforms give you different kinds of help. Android, for example, offers detailed Bluetooth logs through developer options or tools like adb. You can capture the raw Bluetooth HCI logs and analyze them later to see what really happened under the hood. iOS, on the other hand, gives you less direct visibility. Apple handles most of the Bluetooth stack internally, so your only clues come from Core Bluetooth callbacks. Embedded devices often let you log directly from the firmware, showing connection events, error codes, and sometimes even packet-level information if the stack supports it.

Testing across platforms is just as important as debugging. You can’t assume that if it works on one phone, it will work on another. Android devices, especially, have a habit of interpreting Bluetooth timing slightly differently. A system that’s rock-solid on a Pixel may stutter on a Samsung or freeze on a low-cost tablet. The only cure is diversity, test on multiple brands, OS versions, and firmware builds until you’re confident the system behaves everywhere.

For embedded devices, testing is a different challenge. Because they often run continuously, you need long-term endurance tests to catch issues that only appear after hours or days of operation. You might discover that a connection fails only after 300 reconnections, or that a memory leak appears after a week of normal use. Building test rigs that automate these scenarios: connecting, disconnecting, and verifying data repeatedly, is a huge time saver.

Monitoring is what happens after you’ve deployed your devices into the real world. It’s like keeping a health tracker on your entire Bluetooth network. Your mobile apps or gateways can collect statistics such as signal strength, connection failures, uptime, and battery levels. That data tells you which devices are performing well and which ones might be drifting toward trouble.

Adding this kind of visibility pays off enormously at scale. When you’re managing hundreds of devices, it’s impossible to check each one manually. Instead, you rely on trends, for example, if one location shows consistently weak signal strength, maybe there’s interference nearby. If multiple devices drop connections at the same time, maybe the central device needs a firmware update. Monitoring transforms guesswork into insight.

The truth is, debugging and monitoring never really end. Even after your system is stable, new versions of Android and iOS will appear with small Bluetooth changes that break something you didn’t know could break. Treat Bluetooth maintenance like car maintenance: routine, ongoing, and essential.

Once you learn to capture good logs, read them calmly, and build systems that report their own health, debugging stops being a nightmare and becomes a science. Bluetooth may always be a little mysterious, but with the right tools and attitude, you can keep the ghosts out of your connection list.

In the next section, we’ll put everything together with a real-world example of what scaling Bluetooth actually looks like when all the pieces: mobile apps, embedded devices, and architecture, finally work in harmony.

Real-World Architecture Example — When Bluetooth Finally Behaves

Let’s take everything we’ve talked about and bring it to life with a real-world scenario. Imagine you’re building a smart factory system with hundreds of Bluetooth sensors scattered across the floor. Each sensor measures temperature, vibration, or humidity. Some are attached to machines, others hang on walls, and a few are hidden in places even the janitor doesn’t know about. Your goal is simple on paper: collect data from all these sensors, send it to a central dashboard, and keep everything running smoothly.

The reality, of course, is much more complicated. Each sensor is an embedded device powered by a coin-cell battery that has to last for months. They advertise periodically to announce they’re alive. Your Android or iOS tablets, placed around the factory as gateways, act as Bluetooth centrals. Their job is to scan, connect to nearby sensors, read data, and upload it to the cloud. It sounds straightforward, but you’re juggling dozens of invisible connections at once, and they all have different moods.

The architecture begins with careful planning. Each gateway tablet knows which part of the factory it’s responsible for. That way, you avoid overcrowding the airwaves with multiple devices trying to connect to the same sensors. The sensors use slightly staggered advertising intervals so they don’t all shout at the same time. The gateways maintain a queue, connecting to a few sensors at a time, reading data, and then disconnecting before moving on to the next group. This rotation keeps everything balanced and prevents Bluetooth traffic jams.

Power management is built into every step. Each sensor wakes up, advertises briefly, sends its data when connected, and goes right back to sleep. The connection interval and MTU size are tuned for efficiency, large enough for smooth data transfer, but not so large that slower devices choke. Every byte is treated like gold because every transmission costs energy.

The gateways handle the messy parts: reconnections, retries, and data aggregation. They buffer readings in case the Wi-Fi link to the cloud goes down and sync later when it’s back. They also monitor each sensor’s signal strength, battery level, and uptime. If a sensor hasn’t reported in a while, the system flags it automatically so a technician can check on it.

Now imagine scaling this setup to multiple factory buildings. Suddenly, you’re managing thousands of sensors, dozens of gateways, and countless wireless interactions. At this scale, the design choices you made early, abstracted Bluetooth logic, retry mechanisms, power optimization, and logging, are the difference between a quiet, self-running network and a system that collapses into constant reconnections.

When everything works as intended, something beautiful happens. The sensors collect data silently. The gateways synchronize automatically. The dashboards stay green. Nobody has to restart anything, and Bluetooth quietly fades into the background where it belongs. It’s the rare moment when technology stops demanding attention and simply does its job.

This kind of architecture isn’t science fiction. Companies use it in factories, hospitals, and warehouses every day. From smart lighting systems to patient monitors, Bluetooth at scale can be astonishingly reliable, but only if you treat it like a distributed system, not a single gadget. Each device is a citizen of a larger ecosystem, and your job as the architect is to keep that ecosystem healthy.

The biggest takeaway is that success doesn’t come from fancy algorithms or expensive hardware. It comes from the small, deliberate decisions that make your system resilient: how you handle disconnections, how you schedule connections, how you monitor performance. Scaling Bluetooth is not about avoiding problems, it’s about designing a system that recovers gracefully when problems happen.

In the next section, we’ll wrap up everything we’ve learned into a practical checklist, a simple guide you can use whenever you’re designing a Bluetooth system that has to survive in the wild.

Checklist — Building a Truly Scalable Bluetooth System

By now, you’ve seen Bluetooth in all its moods, charming, confusing, unpredictable, and surprisingly capable when handled with care. So how do you actually put everything together? What makes a Bluetooth system scalable instead of just “working on my desk”? The answer isn’t a single trick or secret API. It’s a mindset, a way of designing your system to expect chaos and still function gracefully when it happens.

The first part of that mindset is consistency. Every Bluetooth system should have one clear and stable way of communicating. Keep your data formats simple, your GATT profiles predictable, and your naming conventions sensible. If you have ten devices made by ten different vendors, make them all speak the same language. The moment one device starts improvising, the whole orchestra sounds off.

Next comes patience, and in Bluetooth, patience means retries. Connections drop. Devices go out of range. A phone might go to sleep or decide that scanning is no longer fashionable. Instead of treating every disconnection as a crisis, treat it as part of the process. A good Bluetooth app quietly retries in the background, restores the connection, and carries on as if nothing happened. To the user, it feels seamless. Underneath, it’s a flurry of logic keeping the experience smooth.

Then there’s the question of power. Remember that every advertisement and connection eats into battery life. A scalable Bluetooth system doesn’t talk all the time, it talks smart. It plans when to wake up, when to exchange data, and when to stay silent. Devices that last longer need fewer replacements, fewer updates, and far less human attention. Power efficiency is the hidden currency of scalability.

Monitoring is another essential habit. If you can’t see what’s happening inside your system, you’re flying blind. Log your connections, track your signal strengths, record how often devices drop out, and visualize it somewhere. A simple dashboard that shows which devices are healthy and which ones are struggling can save you countless hours later. When you scale, visibility turns guesswork into control.

Security, too, can’t be an afterthought. Use secure pairing, proper encryption, and rotating addresses. The bigger your system gets, the more interesting it becomes to people who might want to peek at it. Make sure they can’t. A secure Bluetooth network doesn’t just protect users, it protects your reputation.

Finally, build for change. Bluetooth isn’t static, Android and iOS update their stacks every year, chip vendors release new firmware, and new security standards appear. A scalable system doesn’t break when something changes, it adapts. That’s why abstraction layers, modular code, and updatable firmware matter so much. They keep your system flexible long after the first version ships.

If you do all of this, keep it consistent, patient, efficient, observable, secure, and adaptable, something magical happens. Your Bluetooth system starts to feel less like a fragile web of devices and more like a living network. It keeps running, keeps healing, and quietly gets the job done without constant supervision. That’s when you know you’ve built something that scales.

In the final section, we’ll step back and reflect on the bigger picture, what scaling Bluetooth really teaches us about building technology that has to work not just once, but over and over again in the messy, beautiful real world.

Wrap-Up — Lessons from the Field

If you’ve made it this far, you’ve probably realized that scaling Bluetooth isn’t really about Bluetooth at all. It’s about learning how complex systems behave when they leave the comfort of your desk and enter the real world. It’s about understanding that wireless connections are not just electrical signals, they’re relationships between unpredictable, battery-powered, opinionated little machines.

Bluetooth gets a bad reputation because people expect it to be simple. They imagine it’s like Wi-Fi or USB, plug and play, pair and forget. But in truth, Bluetooth is more like a polite conversation at a crowded party. Everyone is talking at the same time, the music is loud, and you have to keep repeating yourself until the other person hears you correctly. When you think of it that way, it’s a miracle that it works as well as it does.

Scaling Bluetooth across Android, iOS, and embedded devices teaches you humility. You stop assuming things will always behave, and instead you start building systems that recover when they don’t. You learn that error handling is not an afterthought, it’s the main event. You discover that batteries are precious, timing is everything, and the smallest design decisions can ripple through an entire ecosystem of devices.

You also start to appreciate the quiet beauty of resilience. There’s something deeply satisfying about watching dozens of sensors, gateways, and phones connect, share data, and disconnect, all without human intervention. When it works, it feels effortless. You forget about the retries, the power cycles, the reconnections, and the debugging sessions that made it possible. All you see is a smooth network humming quietly in the background, doing exactly what it was meant to do.

And that’s the real magic of Bluetooth, not the flashy tech demos or the pairing animations, but the invisible collaboration that happens beneath the surface. It’s the heartbeat of every wearable, every sensor, every tiny device that quietly makes our lives a little easier. Scaling it isn’t just an engineering challenge; it’s a lesson in patience, design, and empathy for systems that can’t always speak for themselves.

So, the next time your Bluetooth device disconnects, take a breath. Somewhere in the chaos, it’s just trying to reconnect, to find its partner again and pick up where it left off. Because deep down, that’s what Bluetooth really is: a network built on trust, persistence, and tiny packets of hope flying through the air.

Every time your watch syncs your steps, every time your earbuds receive another chunk of audio, every time a background device checks in – the main application processor inside your phone is forced to wake up, look at the data, decide what to do with it, and then go back to sleep. Do that a few thousand times, and suddenly that nice 5000 mAh battery starts feeling suspiciously small.

Android engineers looked at this pattern and basically said, what if we don’t wake up the big CPU for every tiny Bluetooth thing? What if we had a smaller helper brain whose entire job is to handle boring repetitive Bluetooth traffic while the main CPU relaxes? That’s exactly where the concept of a Low Power Island, usually shortened to LPI, comes in.

In modern Android Bluetooth architecture, especially from the AOSP 16 generation onward, a good chunk of Bluetooth work can be offloaded to a dedicated low power processor that sits closer to the Bluetooth radio. This little processor is embedded in the Bluetooth controller or SoC and is designed to run very efficiently. It consumes much less power than the main CPU and can stay awake without draining your battery like a full application processor would. Android’s job is to decide which traffic can live on this island and which traffic still needs the main CPU.

But how does Android make that decision in practice? This is where Bluetooth sockets and something called BluetoothSocketSettings enter the story.

In a regular app, when you open a BluetoothSocket, it feels like you’re just opening a pipe so you can send and receive bytes. Under the hood though, the framework is asking a much deeper question: should this pipe go through the big highway that wakes up the main CPU, or can this pipe be connected directly into the low power island’s private road network?

In the latest AOSP Bluetooth stack, the answer to that question is expressed through a tiny configuration object: BluetoothSocketSettings. This class lets system level code describe how a socket should behave. It can specify whether the data should be kept on the normal host path or offloaded into a hardware data path that ends on the low power processor.

Inside, there are fields like DATA_PATH_NO_OFFLOAD and DATA_PATH_HARDWARE_OFFLOAD, plus extra information like hubId, endpointId, and requestedMaximumPacketSize that help the controller understand how to route packets in the LPI world.

From the outside, it still looks like you’re dealing with a normal BluetoothSocket. Inside the Bluetooth framework though, that socket is now tagged with extra metadata that quietly tells the Bluetooth stack: this one is special, send it to the island.

The host stack then talks to a new layer of code in the Bluetooth system called the LPP offload manager and a socket specific HAL (Hardware Abstraction Layer) so that the low power processor can be informed whenever a socket is opened or closed, and can claim responsibility for handling the data.

So if we keep the café analogy, previously every Bluetooth customer shouted their order directly at the main barista. With Low Power Island and BluetoothSocketSettings, Android can say, “these regular espresso orders can go through the junior barista at the side counter. Only the weird custom drinks still go to the main barista”. Same Bluetooth experience for the user, but far less chaos and far less wasted energy behind the counter.

In this article, we will zoom in from this high level story into the actual Android APIs. We’ll look at how BluetoothSocketSettings is defined in the framework, how you request hardware offload, and what those scary looking fields like hubId and endpointId actually mean in plain English.

Table of Contents

1. The Anatomy of BluetoothSocketSettings

2. Inside the HAL: How Bluetooth Offload Really Works

3. When the CPU Sleeps but Bluetooth Doesn’t: Power Management in Action

4. How Developers Can Harness BluetoothSocketSettings

5. The Grand Finale: The Elegance of Sleeping Smart

The Anatomy of BluetoothSocketSettings

So far we’ve been talking about BluetoothSocketSettings like it’s some magical ticket that sends your packets to a sunny low-power island somewhere inside your phone. Now let’s actually look at what that ticket looks like in code.

If you open the Android Open Source Project tree and navigate to the framework layer, you will find a class definition hiding under frameworks/base/core/java/android/bluetooth/BluetoothSocketSettings.java. At first glance it looks small, almost too simple for something that saves you so much battery. But this little class carries the secret instructions that tell the Bluetooth stack where your socket’s data should flow.

Here’s what a stripped-down version looks like:

public final class BluetoothSocketSettings implements Parcelable {
    public static final int DATA_PATH_NO_OFFLOAD = 0;
    public static final int DATA_PATH_HARDWARE_OFFLOAD = 1;

    private int mDataPath;
    private int mHubId;
    private int mEndpointId;
    private int mRequestedMaxPacketSize;

    public BluetoothSocketSettings(int dataPath, int hubId, int endpointId,
                                   int requestedMaxPacketSize) {
        mDataPath = dataPath;
        mHubId = hubId;
        mEndpointId = endpointId;
        mRequestedMaxPacketSize = requestedMaxPacketSize;
    }

    public int getDataPath() { return mDataPath; }
    public int getHubId() { return mHubId; }
    public int getEndpointId() { return mEndpointId; }
    public int getRequestedMaxPacketSize() { return mRequestedMaxPacketSize; }
}

When a new socket is created in Android Bluetooth, the system or privileged service can pass one of these settings objects down to the stack. The key line is DATA_PATH_HARDWARE_OFFLOAD. That’s the switch that tells the Bluetooth system, hey, try to keep this traffic on the controller’s microprocessor rather than waking up the main CPU.

hubId and endpointId are like addresses on the island. They tell the firmware which logical port or queue to use for that particular socket. The requestedMaxPacketSize helps it tune buffer allocation, so it can balance throughput and power efficiency.

At this point you might be wondering, how does this tiny Java object actually make its way down to the hardware? The answer lies in the HAL (Hardware Abstraction Layer). When you call something like BluetoothSocket.connect(), it eventually funnels down through native code in files such as btif_sock.cc and btif_core.cc. There, you will see traces like:

bt_status_t status = BTA_SockConnect(type, addr, channel, flags);
if (settings.data_path == DATA_PATH_HARDWARE_OFFLOAD) {
    BTIF_TRACE_DEBUG("Configuring socket for hardware offload path");
    BTA_SockSetOffloadParams(settings.hub_id, settings.endpoint_id);
}

This snippet may look simple, but it represents a major shift in responsibility. Instead of sending every packet up to the host stack, the Bluetooth controller can now claim ownership of the data path. The Bluetooth firmware inside the SoC will then take over, handling packet retransmissions, acknowledgments, and flow control without constantly waking the main CPU.

If you monitor your device’s kernel log during such a connection, you might even spot something like:

bt_vendor: enabling LPI offload for handle 0x0041
bt_controller: lpi path active, cpu wakelocks released

That log line is your quiet confirmation that the data path has successfully migrated to the low power island.

In human terms, the phone just decided that this Bluetooth conversation is predictable enough to be handled by the mini-processor, so it politely told the big CPU, “You can take a nap now. I got this.”

In the next section we will follow this journey one level deeper, right into the HAL and firmware boundary, to see how these socket settings turn into actual low-power data routing inside the controller chip. This is where the real hardware magic happens, and where the savings start adding up every milliwatt at a time.

Inside the HAL: How Bluetooth Offload Really Works

So far, we’ve stayed mostly in Android’s Java and native layers, the comfy apartment where frameworks and system services live. But beneath that lies a basement full of clever machinery: the Hardware Abstraction Layer, or HAL. This is where Android stops talking in “objects” and starts speaking in opcodes and buffers, and it’s the bridge between software and silicon.

When the BluetoothSocketSettings flag tells the system “please use hardware offload”, that request doesn’t magically teleport to the chip. It walks step by step down the Bluetooth stack, crossing through JNI (Java Native Interface) into C++, then into HAL, which is defined inside hardware/interfaces/bluetooth/.

Starting from Android 14 and especially in AOSP 16, the HAL has grown smarter: it now understands LPI capabilities and can route certain socket traffic to them.

Let’s take a peek inside a simplified HAL function. This is not a fictional snippet. It’s close to what you might find in bluetooth_audio_hw.cc or bluetooth_socket_hal.cc:

Return<void> BluetoothHci::createSocketChannel(
        const hidl_string& device, const BluetoothSocketSettings& settings,
        createSocketChannel_cb _hidl_cb) {
    int fd = -1;
    if (settings.data_path == DATA_PATH_HARDWARE_OFFLOAD) {
        ALOGI("LPI offload requested for socket on hub %d endpoint %d",
              settings.hub_id, settings.endpoint_id);
        fd = controller->allocateLpiChannel(settings.hub_id, settings.endpoint_id);
    } else {
        fd = controller->allocateHostChannel();
    }
    _hidl_cb(Status::SUCCESS, fd);
    return void();
}

In plain English, this method is like the traffic officer at the Bluetooth crossroads. It looks at your socket settings and decides which road to send your data on. If DATA_PATH_HARDWARE_OFFLOAD is set, the data path is wired to the controller’s internal MCU instead of the regular host-side buffer.

The call to controller->allocateLpiChannel() is where the HAL says, “Okay chip, please create a queue that lives entirely inside your low-power processor.” This microcontroller is physically closer to the Bluetooth radio. It can handle acknowledgments, small data bursts, and even some protocol timing on its own, things that would normally require waking the main CPU.

Once this channel is created, the Android framework and apps still see a normal file descriptor, as if the socket were entirely local. The magic lies in the fact that this descriptor is backed by firmware-managed memory and DMA paths rather than by Linux kernel buffers.

If you were to attach a debugger or dump logs from the controller, you might see something like:

bt_lpi_mcu: channel 0x03 opened for handle 0x0041
bt_hci: diverting ACL packets to LPI path
bt_lpi_mcu: sleeping host processor

That third line, sleeping host processor, is the dream come true for every power engineer. The phone literally turns off big chunks of the CPU subsystem while keeping Bluetooth alive.

This is also where vendors like Qualcomm or Broadcom add their special sauce. Their HALs often include extra hooks for “keep-alive” timers, “coalescing intervals,” and “firmware-driven retransmissions.” These ensure the connection feels smooth even though the main processor is off-duty.

From a high-level view, the pipeline now looks like this:

App -> Bluetooth Framework -> JNI -> btif_sock -> HAL -> Controller MCU (LPI)

Every layer understands just enough to pass the baton cleanly to the next. The HAL acts as the translator, taking high-level settings and turning them into low-level commands that the chip firmware can execute.

By the time your smartwatch sends a packet or your earbuds request an audio chunk, the main CPU doesn’t even blink. The entire transaction lives and dies within the Bluetooth controller’s tiny domain, sipping power rather than gulping it.

In the next section, we’ll explore how this offload architecture integrates with Android’s power management system, including wakelocks, doze modes, and kernel coordination, and how it ensures that even though the main CPU is asleep, the connection never misses a beat.

When the CPU Sleeps but Bluetooth Doesn’t: Power Management in Action

Alright, we have seen how the socket offload travels from the app layer down into the HAL and finally lands on that tiny MCU that lives inside the Bluetooth chip. But what happens next? What if your phone’s main CPU decides to take a nap while a file transfer or an audio stream is still going on? Doesn’t that risk breaking the Bluetooth connection?

This is where Android’s power management choreography steps in. It is a dance between three performers: the Power HAL, the Bluetooth stack, and the kernel wakelock system.

When a Bluetooth socket gets configured for Low Power Island, Android’s Bluetooth stack signals the kernel that this connection can be maintained without the help of the main CPU. Internally, it clears or downscales the wakelock timers that would normally keep the processor awake during Bluetooth traffic. In kernel logs, you might see something like this:

wakelock: release "bt_wake" (LPI mode active)
bt_controller: firmware handling link supervision locally

This message is gold for system engineers. It tells you the controller has taken full ownership of the connection. The Bluetooth firmware is now monitoring supervision timeouts, handling retransmissions, and maintaining encryption counters.

From the power manager’s point of view, the Bluetooth device looks “idle” because no interrupts are being generated toward the main CPU. Meanwhile, the controller MCU quietly exchanges packets with your earbuds or smartwatch using its own low-power clock domain.

To coordinate this, the Bluetooth HAL exposes small callbacks that inform the Power HAL whenever traffic levels change. You might find a snippet like this in bt_vendor_qcom.cc:

void bt_lpi_activity_update(bool active) {
    if (active)
        power_hint(POWER_HINT_LPI_ACTIVITY, 1);
    else
        power_hint(POWER_HINT_LPI_ACTIVITY, 0);
}

When active goes to zero, the Power HAL knows it can allow deeper system sleep states (like suspend-to-RAM), because Bluetooth will keep things alive on its own.

The real magic is that the user never notices any of this. The phone can appear “asleep”, display off, CPU cores gated, yet your Bluetooth audio still plays, your smartwatch still syncs, and your phone remains discoverable.

It’s almost poetic. The main processor is dreaming, the controller hums softly, and your playlist keeps rolling like nothing happened.

If you want to verify this on a real Android device, you can use the command:

adb shell cat /sys/kernel/debug/wakeup_sources | grep bt

When you see that bt_wake counter stays low even during streaming, congratulations! The Low Power Island offload is doing its job beautifully.

In the next section, we’ll climb back up from the firmware depths to see how all this fits into the everyday developer’s world. Can you, as an app or system developer, actually control or benefit from these socket settings directly? And how can understanding them help you build Bluetooth apps that sip rather than chug power?

How Developers Can Harness BluetoothSocketSettings

Now that we’ve peered deep into the heart of the Bluetooth stack, let’s climb back up to where you and I actually live: the developer layer. You might be wondering, “Okay, all that hardware wizardry is cool, but what can I actually do with it?”

Here’s the fun part: even though Low Power Island is mostly a system-level feature, understanding how it works can still help you design Bluetooth apps that are more power-friendly and predictable.

At the framework level, you can’t directly toggle LPI on or off from your app. Those switches live deep in system components like BluetoothService and BluetoothSocketManagerService. But every time you use a BluetoothSocket or BluetoothServerSocket, your data silently flows through those layers that check whether LPI offload is available.

That means your app benefits automatically, as long as you don’t do anything that forces the CPU to stay awake unnecessarily. For example, using proper thread sleeps, avoiding busy loops, and letting Android’s own Bluetooth I/O streams handle buffering will keep you in the good graces of the offload logic.

If you dive into AOSP’s system server logs while connecting a Bluetooth socket, you might notice something like this:

BluetoothSocketManager: Offload eligible socket detected, enabling LPI mode
Bluetooth HAL: LPI channel activated for fd=42

That little line tells you that your socket has been quietly rerouted through the island, without you lifting a finger.

Underneath, the framework created a BluetoothSocketSettings object and passed it down the chain when the socket was opened. In pseudo-Java, it looks like this:

BluetoothSocketSettings settings =
    new BluetoothSocketSettings(
        BluetoothSocketSettings.DATA_PATH_HARDWARE_OFFLOAD,
        /* hubId */ 1,
        /* endpointId */ 2,
        /* maxPacketSize */ 512);

BluetoothSocket socket = adapter.createSocket(device, settings);
socket.connect();

Of course, this isn’t part of the public SDK yet, but system apps or privileged frameworks use similar calls to describe how traffic should be handled.

So why should you, the developer, care? Because knowing that such a path exists means you can design with it in mind. For instance, you can:

• Batch small BLE writes instead of sending them one by one, allowing the controller to process them efficiently inside the offload buffer.

• Avoid frequent connect/disconnect cycles, which would force the stack to wake the main CPU repeatedly.

• Structure your background transfers to fit neatly within the limits of low-power buffers (think smaller chunks and longer intervals).

Essentially, the more predictable your data pattern is, the more likely it is to stay in the island without waking the host.

If you’re building system software, say for a custom Android device or embedded product, then you can go even further. You can tweak the HAL behavior, assign custom hub or endpoint IDs, and even tune the maximum packet size that the firmware uses for DMA transfers. This allows you to build Bluetooth features: such as low-energy telemetry streaming or wearable sensor sync, that run almost entirely offloaded.

At that point, your Bluetooth chip becomes a mini server that keeps working while the main OS sleeps, delivering remarkable battery life and snappy reconnections.

In the final section, we’ll wrap things up and look back at the big picture, why BluetoothSocketSettings and Low Power Island together represent one of the most elegant examples of Android’s “invisible engineering.” It’s one of those quiet triumphs you’ll rarely see in a keynote but feel every day when your phone still has juice at midnight.

The Grand Finale: The Elegance of Sleeping Smart

Let’s take a step back for a moment. We started in a coffee shop with an overworked barista. Then we discovered a hidden assistant, the Low Power Island, that quietly keeps the café running even when the main barista steps away.

We followed the path of a humble Bluetooth socket, watched it get wrapped in BluetoothSocketSettings, journeyed through the HAL, and finally land on a miniature processor inside the controller that hums along while the big CPU dreams.

And that’s the beauty of it: Android’s Bluetooth offload mechanism is one of the most elegant examples of invisible engineering. It doesn’t announce itself with a new API or a fancy animation. It just silently makes your battery last longer, your Bluetooth more reliable, and your phone feels smoother, all without you even knowing it’s there.

From a technical point of view, the brilliance lies in the balance. The system still allows full-featured sockets and rich protocol handling when you need it, but for common data flows, audio, telemetry, notifications, or heart rate streaming, it lets the low-power controller take the wheel. It’s like Android learned to delegate.

Every time your smartwatch syncs while your phone screen is off, or your earbuds stay connected during a long flight without draining your battery, you are seeing BluetoothSocketSettings and the Low Power Island framework at work. They are part of a larger philosophy in modern Android design, moving intelligence closer to hardware. The more we teach our chips to handle autonomic tasks, the more we can let the main processor rest.

If you are a developer or system engineer, understanding this architecture isn’t just academic. It can inspire how you design your own features. Whether you’re building a custom Android ROM, optimizing firmware for wearables, or creating IoT devices with a Bluetooth chip, the lesson is clear: don’t make your main CPU babysit every packet. Offload when you can, sleep when you should, and your devices will thank you with hours of extra uptime.

So the next time you plug in your earbuds and notice your phone staying cool and your battery percentage barely moving, remember: somewhere deep inside, a tiny Bluetooth MCU is doing all the heavy lifting while the main CPU enjoys a nap in its low-power hammock.

That’s the quiet genius of Android’s Low Power Island and BluetoothSocketSettings. It’s not just about Bluetooth. It’s about teaching our devices to be smarter, not busier. And maybe, just maybe, that’s a lesson worth remembering for ourselves too.

Inside your Android device, something very similar is happening every moment. One second the processor is streaming your playlist over Bluetooth, the next it’s processing notifications, tracking your location, or syncing data in the background. Somehow it manages all this without melting through your jeans or begging for a charger before lunch.

The secret behind this superhuman stamina lies in a small sanctuary inside the silicon known as the Low Power Island, often abbreviated as LPI. Think of it as a meditation corner for your processor. When there is nothing urgent to do, parts of the chip quietly retreat into this space to rest, while a few essential components stay awake to keep an eye on the world.

Imagine your CPU as a busy coffee shop. The main baristas are the high-performance cores, darting around to prepare fancy espresso drinks for demanding apps like games or video editors. The smaller efficiency cores handle lighter orders such as notifications or background tasks. Now picture a lonely drip coffee machine humming in the corner after closing hours. It keeps the essentials running without using much energy. That humble machine is your Low Power Island.

When Android realizes that no one is touching the screen, no heavy computation is in progress, and no critical wake locks are active, it lets the device drift into this gentle half-sleep. The system is not entirely unconscious because someone still needs to listen for alarms, network activity, or Bluetooth packets. It’s more like a cat napping with one ear twitching for sound.

This design allows modern devices to conserve power while staying responsive. In older systems, going to sleep meant shutting everything down and then painfully waking up for a single event. That would be like turning off the coffee shop’s electricity every time there were no customers, then waiting for the machines to warm up when the next order arrived. The Low Power Island avoids that waste by keeping only the essentials alive.

So the next time your phone lights up instantly after hours of lying still, remember that deep inside your processor, a few quiet transistors were guarding the gates. They were not fully awake or fully asleep but floating peacefully in the middle. That is the Low Power Island, the hidden hero of Android’s battery endurance.

In this article, we’re going to lift the curtain on that hero. You’ll see how the LPI works, not just as a sleepy nook for the CPU but as a full-fledged power-management strategy woven into Android’s architecture. We’ll also explore how Bluetooth keeps chatting quietly inside the island without waking the big cores, how the Power HAL and kernel orchestrate every nap and wake cycle, and how firmware plays the role of a tireless night guard.

You’ll get real AOSP snippets, real kernel logs, and practical advice on writing Bluetooth code that cooperates with the island instead of barging in loudly.

By the end, you’ll understand why your phone lasts as long as it does, and how this hidden corner of silicon keeps everything running with calm precision.

Table of Contents

• What is the Low Power Island (LPI) in Android Bluetooth?

• The Silent Orchestra: How LPI Works with Power HAL & Kernel

• Debugging and Verifying Low Power Island in Bluetooth

• Teaching Bluetooth to Nap Smarter

• Conclusion: The Quiet Genius Inside Your Phone

What is the Low Power Island (LPI) in Android Bluetooth?

Bluetooth is a social butterfly. Even when the screen is dark, it keeps whispering to your earbuds, smartwatch, or car stereo, exchanging packets of data that make life feel seamless. The problem is that constant conversation consumes energy. Waking the entire phone every few seconds just to send a few bytes would be like turning on stadium floodlights to find your keys.

This is where the Low Power Island becomes the hero again. Inside modern Android phones, Bluetooth communication is handled by a dedicated Bluetooth controller, a small microprocessor within the same system-on-chip as the main CPU. This controller has its own memory and its own power domain. It can stay partially awake while the big CPU cores rest, maintaining connections and handling radio traffic with almost no help from the main processor.

When Android’s Power Manager decides the system can sleep, it sends signals through the Bluetooth HAL and vendor driver to let the controller know that the host side is entering a low-power state. The controller then takes over lightweight tasks on its own, such as keeping connections alive, scheduling sniff intervals, and handling encryption handshakes. The result is a seamless experience where your earbuds remain paired and responsive while the rest of your phone quietly saves power.

A simplified peek inside AOSP’s Bluetooth service shows this collaboration in action:

// From system/bt/service/btif/src/btif_core.cc

void btif_pm_enter_low_power_mode() {
    LOG_INFO("%s: entering low power mode", __func__);
    // Notify controller to enter sleep mode
    BTA_dm_pm_btm_status_evt(BTA_DM_PM_BTM_STATUS_IDLE);
    // Suspend host stack threads
    btif_thread_suspend();
}

void btif_pm_exit_low_power_mode() {
    LOG_INFO("%s: exiting low power mode", __func__);
    // Resume host stack threads
    btif_thread_resume();
    // Notify controller that the host is active again
    BTA_dm_pm_btm_status_evt(BTA_DM_PM_BTM_STATUS_ACTIVE);
}

These functions represent a small slice of a much larger conversation between Android and the controller. The host stack quietly pauses while the controller keeps watch. On many chip vendor platforms, this state is called Controller Sleep or Snooze Mode. The Bluetooth controller can wake the host only when something meaningful occurs, such as an incoming call or a button press from your headset.

It works like a night security guard who patrols a building after everyone has gone home. The lights stay off, the air is still, but someone is always alert. If something happens, the guard rings the bell, and the rest of the crew wakes up. That is how your phone’s Bluetooth keeps working even when the display is dark and the CPU cores are resting inside the Low Power Island.

This collaboration between hardware, firmware, and Android’s power management makes it possible for you to listen to music, receive smartwatch notifications, or resume playback instantly without draining the battery. It’s quiet efficiency at its finest, a balance between awareness and rest that defines the beauty of modern Android design.

The Silent Orchestra: How Low Power Island Works with Android Power HAL and the Kernel

If you could peek under Android’s hood while your phone is asleep, you would see something that looks a lot like a perfectly timed orchestra. Every instrument knows when to play softly, when to rest, and when to come back in without missing a beat.

The Low Power Island is not a solo performer in this show. It is more like the gentle rhythm section, coordinated by a set of invisible conductors that live inside the Power HAL, the kernel, and the firmware.

Let’s start with the Power HAL, or Hardware Abstraction Layer. In Android, the Power HAL acts as the middleman between the system framework and the low-level kernel drivers. Whenever Android decides it can lower power consumption, it communicates this decision through HAL interfaces. The Power HAL talks to the chipset vendor’s implementation to decide which parts of the hardware can safely go to sleep. It controls not only the CPU clusters but also the GPU, display pipeline, and peripheral controllers like Bluetooth and Wi-Fi.

In a simplified sense, Android’s power manager says something like, “Hey HAL, we are idle now, can we nap for a bit?” The Power HAL then checks with the kernel and hardware to see who can afford to sleep. If the Bluetooth controller confirms that it can handle ongoing communication alone, the Power HAL signals the kernel to start shutting down parts of the main processor.

The kernel, in turn, manages this transition through its power domains and clock gating systems. Each hardware block in the chip belongs to a specific power domain. The kernel knows which domains can be turned off entirely and which must stay partially active.

The Bluetooth controller usually belongs to a domain that supports retention mode, meaning that some of its memory and logic stay powered just enough to preserve state.

A typical flow looks something like this inside the kernel logs when the device starts entering LPI mode:

PM: suspend entry (deep)
controller-bluetooth 0001:00:00.0: entering controller sleep
PM: suspend devices complete
PM: suspend exit
controller-bluetooth 0001:10:00.0: waking host

In this short exchange, you can see how Android’s power manager orchestrates the entire sleep-wake process. The Bluetooth driver reports that it’s entering controller sleep, the kernel confirms that all devices have suspended, and then later wakes everything up when an interrupt occurs.

At the hardware level, this behavior depends on voltage islands and clock domains defined by the SoC manufacturer. The term “island” is not metaphorical here – it literally represents an electrically isolated region on the chip that can be powered independently. When the kernel puts the main CPU to sleep, power to that island is lowered or shut off, while another island containing the Bluetooth controller continues to operate using a small independent oscillator.

Meanwhile, the firmware running on the Bluetooth controller performs light housekeeping. It manages scheduled events such as connection intervals, sniff subrate transitions, and link supervision timeouts. It can even decrypt or re-encrypt packets without disturbing the host processor. This allows Android to maintain a live Bluetooth connection while consuming a fraction of the power it would normally use.

When an event that requires higher-level attention occurs, such as a user pressing a button on their headset, the controller raises a host wake signal over the UART or shared memory transport. The kernel receives this interrupt, restores the CPU clock, and resumes Android’s power manager. The host stack reactivates, processes the event, and then gracefully hands control back once it’s idle again.

This dance between the Power HAL, kernel, and firmware might sound complicated, but it’s one of the most elegant designs inside Android. Each layer plays its role precisely. The Power HAL negotiates the policies, the kernel enforces them, and the firmware quietly executes them in the background. Together, they make sure that your phone feels instantly awake even after hours of rest.

The next time your earbuds reconnect without delay after your phone has been sleeping in your pocket, know that a whole chain of software and silicon cooperated flawlessly to make it happen. The Low Power Island was not just saving power – it was conducting a silent orchestra beneath your fingertips.

Debugging and Verifying Low Power Island in Bluetooth

If you have ever watched a sleeping cat twitch its ears and wondered whether it’s dreaming, that’s pretty much what debugging the Low Power Island looks like on Android. The device may appear still, but deep within the logs, tiny ripples of life show up every few seconds. Engineers love this quiet chaos because it tells them the system is balancing perfectly between rest and readiness.

When Bluetooth enters its low power phase, Android leaves behind a breadcrumb trail of clues. You can see them in both logcat and kernel dmesg outputs. These logs help confirm whether the Bluetooth controller is indeed entering its low power state while the host CPU retreats to the island of calm.

A simple way to peek into this process is to run:

adb logcat -b all | grep -i "btif_pm"

You might see something like this:

08-05 12:23:44.732  1712  1725 I bt_btif_pm: entering low power mode
08-05 12:23:44.733  1712  1725 I bt_btif_pm: controller idle, suspending host threads
08-05 12:23:46.008  1712  1725 I bt_btif_pm: exiting low power mode

Each line tells part of the story. The first message confirms that Android’s Bluetooth stack has requested entry into the low power state. The second shows that the host-side threads have paused, and the final message shows that the controller has woken the host again.

To see what is happening underneath, you can check kernel logs:

adb shell dmesg | grep -i bluetooth

You might find entries such as:

[ 1423.347102] controller-bluetooth 0001:00:00.0: entering controller sleep
[ 1423.347117] PM: suspend entry (deep)
[ 1425.105993] controller-bluetooth 0001:00:00.0: host wake received
[ 1425.106005] PM: resume complete

These lines confirm that the Bluetooth driver and the power management system are cooperating correctly. The controller went to sleep, the kernel suspended the CPU clusters, and everything woke back up when a wake signal arrived from the Bluetooth controller.

If you ever see the host waking up too frequently, it usually means some component is not respecting sleep boundaries. Common culprits include misbehaving wake locks, noisy apps requesting continuous scanning, or timers that never expire. In such cases, Android’s PowerStats HAL and Batterystats framework can help track down who is preventing deep sleep.

You can check the overall low-power statistics using:

adb shell dumpsys batterystats | grep "bluetooth"

This reveals how long the Bluetooth subsystem stayed active compared to how long the system was in low power mode. Ideally, the numbers should show that Bluetooth remains mostly idle except for brief wake periods.

Engineers working on system bring-ups often use specialized tracing tools such as systrace, ftrace, or perfetto to visualize power transitions. A power trace shows a rhythm: a long flat line representing sleep, interrupted by sharp spikes of activity when the controller wakes the host for a meaningful event. If those spikes are too frequent, you know the system is not entering Low Power Island efficiently.

Here is an excerpt from a typical Perfetto trace snippet:

bluetooth_host_state: IDLE → SUSPENDED
bluetooth_controller_state: ACTIVE → SLEEP
kernel_cpu_cluster_0: ACTIVE → RETENTION
kernel_cpu_cluster_1: ACTIVE → POWER_OFF

This simple sequence tells a powerful story. The host stack suspended, the controller slept, and the CPU clusters powered down gracefully. When the next event occurs, the transitions reverse, and the device wakes almost instantly.

Behind the scenes, vendor firmware plays a crucial role in making this magic look effortless. The Bluetooth controller firmware maintains timing slots, sniff intervals, and link-layer encryption keys, all while running on a few milliwatts of power. It’s astonishingly efficient. A typical controller can maintain an active ACL connection with power consumption under one milliwatt, even while the main CPU cores are completely powered down.

Debugging this system feels a bit like birdwatching. You have to stay patient, quiet, and observant. Most of the time, nothing dramatic happens in the logs. But when you finally catch a perfect sleep–wake cycle, it feels like witnessing nature in harmony. That is the beauty of Android’s Low Power Island at work with Bluetooth.

So when your earbuds reconnect in half a second or your smartwatch syncs data silently while your phone rests on the table, remember this quiet orchestra behind the scenes. It’s not brute power but smart power management that makes the experience feel smooth. The Low Power Island is the invisible craftsman that gives your Android Bluetooth its calm precision, saving battery one sleepy packet at a time.

Teaching Bluetooth to Nap Smarter

If the Low Power Island were a yoga retreat for your processor, then your job as a developer would be to make sure your Bluetooth code doesn’t show up with a drum set. It’s easy to accidentally keep the system awake when you don’t need to. A single careless wake lock, a recurring timer, or a never-ending scan request can prevent the hardware from entering that calm, power-efficient state.

The goal of optimizing for Low Power Island is not to make your Bluetooth logic work less. It’s to make it work wisely, to let the controller handle small background exchanges while the main CPU sleeps peacefully. Android’s Bluetooth stack and vendor drivers already handle most of the heavy lifting, but developers can make a big difference by writing energy-conscious code that respects those boundaries.

The first rule is simple: scan responsibly. Continuous scanning is the number-one villain in Bluetooth power profiles. Each scan wakes the radio, the controller, and often the host processor. If your app continuously calls BluetoothLeScanner.startScan() without a clear stop condition, you are effectively shining a flashlight into the Low Power Island every few seconds.

Instead, batch your scans and use filters. The system’s ScanSettings.SCAN_MODE_LOW_POWER mode is specifically designed to allow scanning that cooperates with LPI transitions.

Here’s an example from AOSP that shows how you can trigger a scan in a power-friendly way:

ScanSettings settings = new ScanSettings.Builder()
        .setScanMode(ScanSettings.SCAN_MODE_LOW_POWER)
        .setReportDelay(5000) // batch results every 5 seconds
        .build();

bluetoothLeScanner.startScan(filters, settings, scanCallback);

By batching results and letting the hardware handle scanning internally, you reduce host wakeups dramatically. The Bluetooth controller can gather advertisements on its own, waking the CPU only once every few seconds to deliver results.

The second rule is to let the stack sleep. Many developers unknowingly block Bluetooth threads by holding wake locks or running unnecessary callbacks. The Android Bluetooth stack maintains internal synchronization through message loops that can safely pause during idle periods.

Avoid long-running operations in callbacks such as BluetoothGattCallback.onCharacteristicChanged(). Instead, offload work to background executors that respect Android’s Doze and App Standby policies.

Another optimization lies in using connection intervals and latency wisely. BLE connections allow you to configure how frequently devices exchange packets. A shorter interval improves responsiveness but burns energy. A longer interval gives more opportunities for the controller to rest between events. If your use case allows it, choose higher connection intervals and peripheral latency values when initializing connections.

// Example: Requesting a higher connection interval in GATT
bluetoothGatt.requestConnectionPriority(BluetoothGatt.CONNECTION_PRIORITY_LOW_POWER);

Under the hood, this tells the Bluetooth controller to lengthen its sniff interval, letting both ends of the link spend more time in low power mode. The result is longer battery life with almost no visible impact on user experience for background updates or sensor reads.

At the system level, engineers tuning platform behavior can also adjust parameters in the Power HAL and kernel configuration. The /sys/power directory contains tunables for CPU retention and controller wake thresholds. Tools like perfetto, systrace, and btsnooz.py can visualize Bluetooth power events, helping verify that sleep cycles are happening as expected.

For example, a trace showing too many wakeups per second might look like this:

bluetooth_host_state: SUSPENDED → ACTIVE
reason: controller wake (LL control packet)
interval: 150 ms

If you see dozens of such wakeups in a short time, it might indicate an overly aggressive connection interval or constant GATT notifications from a peripheral. Adjusting those parameters can bring the wake interval down to seconds instead of milliseconds, drastically improving power efficiency.

The third and perhaps most important rule is know when to let go. When your app finishes a Bluetooth operation, always close the GATT connection, stop scanning, and release references. Many developers forget this step, leaving ghost connections or scans running silently in the background. Each one is like leaving a window open during winter: the heater works harder, and battery life suffers.

Finally, remember that not every Bluetooth event deserves a host wakeup. Modern controllers can handle encryption refreshes, supervision timeouts, and advertisement filtering entirely on their own. Trust the hardware. Android’s Low Power Island and Bluetooth stack are designed to delegate intelligently. The less your app interferes, the smoother the dance becomes.

Optimizing for Low Power Island is not about disabling features. It’s about building harmony between layers. The Android framework, kernel, and controller firmware already communicate like seasoned musicians in an orchestra. Your code is another instrument in that ensemble. Play lightly, leave room for silence, and let the rest of the system breathe.

When you do it right, your users will never notice a thing. Their earbuds will reconnect instantly, their fitness trackers will sync quietly, and their phones will last an extra few hours each day. Behind the scenes, that serene rhythm of sleep and wake continues, powered by the elegant balance that Low Power Island brings to Android Bluetooth.

Conclusion: The Quiet Genius Inside Your Phone

If your phone were a musician, the Low Power Island would be its silent metronome, keeping time, holding rhythm, and making sure the melody never skips a beat. It does not demand attention or boast about its work. It simply exists in the background, saving power in ways most people never realize.

Throughout this journey, we have seen how the Low Power Island serves as the meeting point between hardware and software, where silence becomes strategy. We began with the idea that your CPU, much like a restless friend, needs a place to breathe. We then saw how Bluetooth, the most social of all radios, learns to whisper instead of shout when the rest of the system drifts to sleep. Together, they form one of the most delicate yet powerful mechanisms in Android’s design.

The Bluetooth controller becomes the night guard of the silicon city. While the big CPU cores sleep soundly behind closed gates, the controller patrols quietly, keeping connections alive, listening for signals, and ringing the bell only when something truly important happens. It’s a small but crucial act of cooperation that gives modern Android devices their elegance.

Behind the scenes, the Power HAL negotiates policies, the kernel enforces them, and the firmware executes them with surgical precision. They move like an orchestra, sometimes lively, sometimes silent, but always in harmony. And when your phone wakes instantly to play music, take a call, or reconnect your earbuds, that smoothness is not luck. It is the Low Power Island doing exactly what it was built for: making power management feel invisible.

For developers, understanding this system is not just an exercise in curiosity. It’s a reminder that true optimization does not always come from brute force or faster code. Sometimes it comes from restraint, from knowing when to let go, when to rest, and when to let the system do its quiet magic. Each small decision, batching scans, adjusting connection intervals, respecting sleep boundaries, contributes to a bigger story of balance.

The next time your phone makes it through an entire day of Bluetooth streaming, navigation, and notifications without flinching, take a moment to appreciate what’s happening beneath that glass screen. Inside, a city of transistors is asleep yet awake, calm yet alert, working together in perfect synchronization. The Low Power Island is not just an engineering trick. It is a philosophy: that even in the world of machines, peace and patience can be more powerful than constant motion.

And if you think about it, that is a lesson worth keeping, for both phones and humans alike.

Table of Contents

• What is a Page Size?

• Why is this Change Being Implemented Now?

• What are the Pros and Cons of this Change?

• Should You worry About this Change?

• Is this Mandatory?

• What if You Don’t Upgrade Your App?

• How Does this Affect Hybrid Apps?

• What Would be the Code Change for This?

• How to Verify if Your App is Upgraded to a 16 KB Page Size

• Conclusion

What is a Page Size?

Think of your device's memory like a book. An operating system doesn't read memory one tiny word at a time; it reads in chunks. These chunks are called "pages." For a long time, on most ARM64 Android devices, these pages were 4 KB in size. Now, for some newer Android devices (specifically those launching with Android 13 and later), that page size has quadrupled to 16 KB.

Why is this Change Being Implemented Now?

It's all about making Android run better on modern hardware. Here are some of the reasons why is it being implemented:

Better Performance: Modern processors can handle larger memory chunks more efficiently. A 16 KB page size means the CPU spends less time managing tiny bits of memory and more time doing actual work, which can lead to faster app performance.

Smoother Operations: With fewer, larger pages to keep track of, the system itself has a little less overhead, making things a bit more streamlined.

Keeping Up with Tech: This change helps Android align with how newer ARM64 processors are designed to work best.

What are the Pros and Cons of this Change?

Every big change has its own pros and cons.

Pros

• Apps that move a lot of data around or are memory-intensive might just feel a bit snappier

• The system could run a bit more efficiently, benefiting all apps indirectly

Cons

• If your native code is constantly asking for very small bits of memory (less than 16 KB), each of those might now take up a full 16 KB page, potentially using a little more memory than before.

• If your native code makes assumptions that "memory pages are always 4 KB," it could run into issues on 16 KB page devices.

Should You worry About this Change?

You need to pay attention if:

• Your app includes native libraries (like .so files) written in C/C++. This is where the impact is most direct. If your native code does anything with memory mapping (mmap, shmem) or file I/O where it calculates offsets or sizes based on a fixed page size.

• You're developing games or other highly performance-sensitive apps with native components.

• You're targeting Android 15+ with your app updates.

You need not worry if:

• Your app is built purely in Java or Kotlin with no native components. The Android Runtime (ART) handles memory for you, so these underlying page size changes are largely invisible. You'll still get the performance benefits!

• You're using React Native or Flutter, unless you've added custom native modules that directly deal with memory mapping or page-size-dependent operations

Is this Mandatory?

Yes. Google Play is making this a requirement for app updates. You would have received an email from Google Play if your app does not support 16 KB page size yet.

As the screenshot clearly shows, "From Nov 1, 2025, if your app updates do not support 16 KB memory page sizes, you won't be able to release these updates" for apps targeting Android 15+. This gives us a solid timeframe to get things ready.

What if You Don’t Upgrade Your App?

You could notice some serious issues if your app has native libraries that aren't ready for the 16 KB page size by the deadline. Here are a few:

• Crashes: This is the most serious. Your app might crash unexpectedly (often with a "segmentation fault") if it tries to access memory incorrectly due to old page size assumptions.

• Wasted Memory: If your code allocates memory in smaller chunks than 16 KB, it could end up using more memory than necessary, potentially slowing things down or hitting memory limits.

• Performance Hit: Instead of gaining speed, your app might actually run slower if its memory operations aren't aligned with the larger page size.

Essentially, your app might work fine today, but become unstable or inefficient on newer Android devices if its native components aren't updated.

How Does this Affect Hybrid Apps?

Generally, if you're building a standard hybrid app (React Native or Flutter app) without custom native modules, you're in a pretty good spot. The frameworks themselves, and the underlying runtimes (JavaScript engine for React Native, Dart VM for Flutter), usually handle memory management, abstracting away the page size.

However, if you've implemented custom native modules in C++ for performance-critical tasks or specific hardware interactions, then you do need to check those modules.

For the vast majority of standard React Native and Flutter apps, you likely won't need direct code changes related to page size, but always ensure you're using the latest SDK versions for your framework to benefit from any underlying platform updates.

What Would be the Code Change for This?

The biggest thing to avoid in your native code is making assumptions about memory page sizes. Instead of hardcoding 4096 (for 4 KB), always ask the operating system what its current page size is.

Steps to Take:

1. Audit Your Native Code: Search your .cpp, .c, and .h files for any direct use of 4096 or 4 KB in memory allocation, buffer sizing, or alignment calculations

2. Replace with sysconf(_SC_PAGESIZE) or getpagesize(): Update any fixed values to dynamically retrieve the actual page size.

3. Recompile with Latest NDK: Make sure you're building your native libraries with a recent Android NDK (r25 or newer is a good target). This ensures your toolchain is aware of the 16 KB page size and provides correct system definitions.

How to Verify if Your App is Upgraded to a 16 KB Page Size

You can verify if your app is upgraded by running extensive testing. However, here are the few more steps.

1. Check Your Test Device's Page Size:

   • Connect your Android 13+ test device (preferably a newer one like a Pixel) via ADB

   • Run adb shell getconf PAGE_SIZE

   • If it returns 16384, you're testing on a 16 KB page device! If it returns 4096, you'll need to find a different device to properly test for this change

   • Here’s an example screenshot from my device

     

2. Run Your App Extensively: Once you have a 16 KB page device, put your app through its paces. Try all features, especially those involving native code, heavy data loading, or complex operations.

3. Monitor for Crashes: Keep a close eye on your crash reporting tools (like Crashlytics). Specifically look for native crashes (SIGSEGV, SIGBUS) coming from Android 13+ devices, as these could be related to page size issues.

4. Memory Profiling: While less direct, if you suspect memory inefficiency in your native code, use Android Studio's Memory Profiler to see if allocations are unexpectedly large or if there's excessive memory usage.

Conclusion

In this blog, we learnt about page size in Android, and why and how to upgrade your app to support 16 KB page size. I hope you have a clear idea about 16 KB page size in Android. By being proactive now, you can avoid last-minute scrambling and ensure your apps continue to perform beautifully on the latest Android devices, well past the November 2025 deadline!

You can follow my Twitter/X account to receive the top AI news everyday. If you wish to learn more about mobile app development, subscribe to my email newsletter (https://5minslearn.gogosoon.com/) and follow me on social media.

I work as a Bluetooth software engineer on wearable devices like smart-glasses, and I’ve spent more time than I’d like to admit chasing down why these things break.

In this article, I’ll give you a peek behind the curtain: how Android’s Bluetooth stack actually works, why it sometimes feels unpredictable, and what you can do as a developer to make your apps or system more reliable.

Bluetooth in Plain English

At its core, Bluetooth is just a conversation between two devices. But it isn’t one simple line of communication – it’s multiple layers stacked on top of each other.

• The radio (Controller): Sends and receives the actual signals over the air medium.

• The software brain (Host stack): Decides whom to talk to and how, as well as if it wants to.

• Profiles: Define the purpose of the conversation – like streaming music or syncing health data.

• Protocols: Define how to talk to the other device.

There are two big “flavors” of bluetooth:

• Classic (BR/EDR): Used for things like headphones and car kits. Can lift more weight.

• Low Energy (LE): Used for fitness bands, beacons, and most wearables. Can sustain longer.

Most modern gadgets use both at once. That’s powerful, but it also opens the door for more things to go wrong.

Why Android Adds Its Own Quirks

On Android, Bluetooth isn’t just one neat package. It’s a chain of moving parts:

• Your app calls BluetoothAdapter.

• Those go into system services like AdapterService.

• Then into native code through JNI (Java Native Interface).

• Then into the chip vendor’s Bluetooth stack.

• Finally, it hits the radio hardware.

Every phone maker ships a slightly different Bluetooth chip and firmware. That means the exact same Bluetooth app might behave differently on a Samsung, a Pixel, or any other budget phone running Android.

The Real Problems Behind “It Just Disconnected”

Here are a few of the common headaches I see, explained simply:

Bonding issues (the “lost keys” problem)

When two Bluetooth devices pair, they exchange encryption keys (link keys for Classic, Long Term Keys for LE) and store them in non-volatile memory. These keys are what let the devices recognize each other later and reconnect securely without asking the user again.

A “mismatched memory” problem happens when one device’s stored keys don’t match the other’s anymore. This can be caused by:

• A firmware update or OS upgrade that wipes or regenerates keys.

• A factory reset or “forget device” on one side but not the other.

• Keys being corrupted or evicted by the system to free up storage.

From the user’s perspective, the device may still look paired (shows up in the Bluetooth menu), but connections mysteriously fail with errors like “Authentication Failed” or “Insufficient Encryption.” The only cure is usually to delete the device on both ends and re-pair, which feels ridiculous to non-technical users.

Timing mismatches

Bluetooth devices don’t just chat whenever they want, they agree on a connection interval – essentially a schedule for when each side will “wake up” and exchange packets. Think of it as two people agreeing to meet every 30 minutes at a café.

A mismatch happens when:

• The two sides negotiate different intervals but don’t fully agree (for example, one thinks it’s 30ms, the other 50ms).

• One side’s firmware update or configuration change alters its timing policy.

• Radio conditions cause one side to miss multiple scheduled check-ins, drifting the clocks apart.

• Power-saving logic (like a phone going into Doze mode) silently stretches out the interval.

This explains why a connection might work fine at first but start failing later: the devices initially synced on an interval, but then one side’s policy or behavior shifted. From the user’s perspective, it looks like audio stuttering, laggy input (on game controllers), or random disconnects after “it was working fine before.”

Unexpected disconnections

When a Bluetooth link ends, the radio layer (the controller) and the higher-level OS stack (the host) are supposed to exchange clear signals. The controller sends an HCI Disconnection Complete event (basically: “Goodbye, we’re done”). And the host should then update its internal state, clean up the GATT/ACL session, and be ready for reconnection.

But in practice, this doesn’t always line up:

• Sometimes the controller says goodbye cleanly, but the host stack doesn’t update its state properly. The app still “thinks” the connection is active, so reconnect attempts silently fail.

• Some platforms aggressively cache connection state (especially iOS). If the OS believes the connection is still valid, it won’t trigger a new connection attempt until you toggle Bluetooth or reboot.

• A race condition can occur if the disconnection event happens while another operation (for example, service discovery, bonding, or encryption setup) is in flight. The OS may get confused about what state the device is really in.

• On some devices, a fast reconnect attempt after a clean disconnection collides with internal cooldown timers. The controller ignores it, leaving the app waiting.

From the user’s perspective, the device looks “stuck.” The only way to recover is to toggle Bluetooth, restart the app, or power cycle the accessory, even though technically nothing “failed.”

How Developers Can Do Better

If you’re building a Bluetooth app, here are a few habits that save a lot of pain:

Check for bonded devices first

One of the most common causes of failed connections is mismatched bonding information: the phone and the accessory no longer share the same encryption keys. Even if the device appears in the UI, the OS may have lost its keys.

Before attempting a connection, always query the system’s bonded device list with BluetoothAdapter.getBondedDevices(). For example:

if (adapter.getBondedDevices().contains(targetDevice)) {
    targetDevice.connectGatt(context, false, gattCallback);
} else {
    showToast("Please re-pair this device to restore the connection.");
}

This ensures you only attempt secure connects to devices the OS still trusts. If the target device isn’t in the bonded list, you can give the user a clear instruction (“Please re-pair this device”) instead of leaving them with confusing connection errors.

Handle callbacks carefully

Another subtle pitfall is assuming that a STATE_CONNECTED event means a connection was successful. In reality, onConnectionStateChange() can report a connected state even when the underlying operation failed, the real result is in the status argument. To avoid chasing phantom connections, always check both status and newState:

if (status == BluetoothGatt.GATT_SUCCESS &&
    newState == BluetoothProfile.STATE_CONNECTED) {
    gatt.discoverServices();
} else {
    gatt.close();
}

This pattern prevents you from attempting service discovery on a dead connection and ensures stale sessions are closed promptly, leaving the stack ready for a clean retry.

Expect failures

Bluetooth connections fail all the time in the real world – devices drift out of range, interference spikes in the 2.4 GHz band, or the radio is simply busy. The worst thing an app can do is retry instantly in a tight loop, which drains the battery and makes the stack unstable.

A better approach is to implement exponential backoff like this:

long delay = (long) Math.min(250 * Math.pow(2, attempt), 30000);
new Handler(Looper.getMainLooper()).postDelayed(connectAction, delay);

This means your first retry happens quickly (~250 ms), but subsequent retries slow down (500 ms, 1 s, 2 s…), capped at a reasonable maximum. Backoff makes your app resilient without overwhelming the radio or the OS.

Use the right tools

Without visibility into what’s happening under the hood, connection problems look random. Tools like nRF Connect let you interactively scan, connect, and run GATT operations against your device, while Android’s Bluetooth HCI snoop log reveals the actual packets being exchanged. For example:

Settings.Secure.putInt(context.getContentResolver(), "bluetooth_hci_log", 1);

Once enabled, you can capture a logcat trace and confirm whether a failure is due to missing keys (Insufficient Authentication), a timing mismatch, or interference. Using these tools not only helps you debug your app, it also proves whether the issue lies in your code, the OS, or the accessory firmware.

Bigger Lessons

Working with Bluetooth taught me lessons that apply to engineering in general:

• Wireless is never perfect, so always build with recovery in mind.

• Logs and metrics aren’t optional. They’re your map through the chaos.

• The simplest solution usually survives best in the messy real world.

Conclusion

Bluetooth is messy because it’s a chain of hardware, firmware, and software all trying to cooperate. On Android, the variety of chips and vendors makes it even trickier.

But that doesn’t mean you’re helpless. By understanding how the layers work and designing your apps with retries, checks, and proper logging, you can make Bluetooth feel a lot less “weird” for your users.

The next time your earbuds misbehave, you’ll know – it’s not you. It’s just Bluetooth being Bluetooth.

⚡ This is the first of a number of articles I’m going to write on Bluetooth development. In the next one, we’ll dive deeper into how to build a secure Bluetooth Low Energy (BLE) GATT client and server on Android. Stay tuned!

First, we’ll turn your website into a Progressive Web App (PWA). Then we'll use a free command-line tool from Google called Bubblewrap to package that PWA into an Android app. Let’s get started.

Prerequisites

If you follow along with this tutorial, there are some prerequisites:

• Basic knowledge of web development

• Your site should be live to the public, and you’ll need to have access to its source code.

• We'll use npm to install the necessary tools, so make sure you have Node.js installed.

Note: This tutorial is based on a Vite project, but the final steps with Bubblewrap are the same for any web framework.

Table of Contents

1. What is a PWA?

2. What is Bubblewrap?

   • What is a TWA (Trusted Web Activity)?

   • How TWA Verifies Trust

3. Step 1 – Configure Your PWA in Vite

   • Create Your App Icons

   • Install the Vite PWA plugin.

   • Configure the Plugin

4. Step 2 – Create the Android App

   • Create a Build Folder

   • Install the Bubblewrap CLI

   • Initialize the Project

   • Let’s troubleshoot the init command.

5. Step 3 – Answer Bubblewrap Questions

6. Step 4 – Build the App

7. Step 5 – Setting Up TWA Validation

   • What is the .well-known folder?

   • What is delegate_permission/common.handle_all_urls?

8. Step 6 (Optional) – Customize the In-App Experience

9. Wrapping Up

What is a PWA?

PWA stands for Progressive Web Application, and its goal is to make your website look and feel just like a native app. If you’ve visited a website in your browser and seen an install icon that lets you download it to your phone or laptop, you've used a PWA.

But it’s not just about the look and feel. A PWA also has app-like features, such as working offline, sending push notifications, and more.

There are two main components of a PWA.

• The manifest file describes your app, such as its name, icons, start URL, and so on.

• A service worker is a background JavaScript file that acts as a proxy. The caching and push notifications are handled by a service file, which runs as a different thread apart from the main thread.

Without these two components, browsers won’t let users download the app locally.

The manifest file and the service worker are like a checklist for the browser. When you visit a website, the browser looks for both of these components. If they are present and correctly configured, the browser knows it's a true PWA and will show the "install" icon, allowing users to download the app locally. Without them, the browser just sees a regular website, and the option to install won't be available.

What is Bubblewrap?

Bubblewrap is a command-line tool made by Google that takes your PWA and turns it into an Android App using a Trusted Web Activity (TWA).

Bubblewrap simplifies the process of creating a TWA, turning a PWA's manifest file into an Android app package (APK or AAB).

What is a TWA (Trusted Web Activity)?

A Trusted Web Activity (TWA) is a modern Android feature that lets you display your live website full-screen inside an Android app. Basically, it runs the website on the browser, but it doesn’t show the browser address bar on the App. This helps it feel like a native app.

To unlock this full-screen feature, your app needs to be “Trusted“.

This is where the "secret handshake" comes in. Android needs to be sure that the person who built the app and the person who owns the website are the same. Without this proof of ownership, the TWA will run in a fallback mode and show the browser address bar at the top, ruining the native app feel.

How TWA Verifies Trust

This trust is verified using a system called Digital Asset Links. You place a special file on your website (we'll do this in the implementation part) that contains your app's unique digital fingerprint. When a user opens your app, the Android OS checks this file. If the fingerprints match, it grants your app "trusted" status, removes the address bar, and enables other features like deep linking.

You can check this relationship yourself using Google's official testing tool: Digital Asset Links Verifier.

Now that you understand the project and tools, let’s start building.

Step 1 – Configure Your PWA in Vite

The first step is to add the two main components for a PWA: the manifest file and service worker. This is what will allow the browser to recognize it as "installable."

This guide is based on a project built with Vite, which makes this process easy with a special plugin. If you're using a different tool, the concepts are the same, but you'll need to look up different resources about the specific steps for your environment.

Create Your App Icons

Before we touch any code, we need the icons for our app. Android requires specific sizes for the app's launcher icon (what you see on your home screen) and the splash screen (what you see when the app starts).

You'll need two main sizes: 192x192 pixels and 512x512 pixels. You can use this Favicon Generator to generate your logo in the respective sizes. You can upload your main logo, and it will generate all the necessary sizes for you.

Then just download the generated files and place the 192x192 and 512x512 files into the public folder of your project.

Install the Vite PWA plugin.

A PWA requires a manifest file and a service worker. We can create these manually, but this plugin automates that entire process. It will automatically generate a manifest.json and service-worker.js for you every time you build your project.

npm install vite-plugin-pwa -D

Configure the Plugin

In this step, we’ll use this plugin and configure our app's manifest. Edit the vite.config.ts file. This configuration will tell the plugin what to name your app, which icons to use, and so on.

In vite.config.ts:

export default defineConfig({
  plugins: [
    VitePWA({
      registerType: "autoUpdate",   
      manifest: {
        name: "your app name",
        short_name: "your app short name",
        description: "write any description",
        theme_color: "#0d1117",
        background_color: "#ffffff",
        display: "standalone",
        start_url: "/",
        icons: [
          {
            src: "/web-app-manifest-192x192.png",
            sizes: "192x192",
            type: "image/png",
          },
          {
            src: "/web-app-manifest-512x512.png",
            sizes: "512x512",
            type: "image/png",
          },
        ],
      },
    }),
  ]

Now, when you run npm run build, the plugin will automatically generate the manifest and service worker files for you. With that done, deploy the changes. Now your website is a PWA.

Step 2 – Create the Android App

Now that your website is a PWA, let’s use Bubblewrap to package it into an Android app.

Create a Build Folder

Create a dedicated folder for your Android project files. In your project's root, create a new folder. I'll call mine android.

project/
├── client/
├── server/
└── android/

Now navigate to the new folder that you created.

Install the Bubblewrap CLI

npm install -g @bubblewrap/cli

Initialize the Project

Next, run the init command. Bubblewrap will connect to your live website, read the manifest.webmanifest file that Vite created, and use that information to generate a basic Android project.

bubblewrap init --manifest=https://your-website-domain/manifest.webmanifest

Run the command, replacing your-website-domain with your actual URL:

Let’s troubleshoot the init command

As you run the init command, Bubblewrap will need two key software packages: the Java Development Kit (JDK) and the Android SDK. It will offer to install them for you.

JDK setup:

? Do you want Bubblewrap to install the JDK (recommended)?
  (Enter "No" to use your own JDK 17 installation) (Y/n)

In my case, when I let Bubblewrap install the JDK, the process downloaded the files but then failed at the "decompressing" step. If you face this same problem, don't worry! The fix is to install it manually.

• Say No to the prompt.

• Download the recommended version (usually JDK 17) from a source like Adoptium.

• Install it and set up your system's environment variables to include the JDK's bin path. If you’re not sure how to set environment variables, you can check out this site: Set Environment Variables.

• When Bubblewrap asks for the path, provide it directly, such as C:\java\jdk-17.0.16.8-hotspot.

Android SDK setup:

Once the JDK is set up successfully, the next step is to configure the Android SDK.

? Do you want Bubblewrap to install the Android SDK (recommended)?
  (Enter "No" to use your own Android SDK installation) (Y/n)

Since I didn't have the Android SDK, I let Bubblewrap handle this by selecting Yes. I didn't face any problems here.

If you face any problem in setting up on Android SDK, just set it up manually and give the path, just like the JDK setup.

Step 3 – Answer Bubblewrap Questions

After the SDK is set up, Bubblewrap will ask a bunch of questions to configure your app. This information is used to create the twa-manifest.json file, which is the blueprint for your App.

Domain: Press Enter (auto-filled from your manifest)

Application name: Your full app name

Application ID: (e.g, chat.yourapp.twa)

Display mode: standalone

Orientation: portrait

Status bar color: Press Enter (accepts default)

Splash screen color: Press Enter (accepts default)

Icon URL: Press Enter (accepts default)

Include support for Play Billing?: Type Y if your app uses Google Play in-app purchases. Otherwise, N

Request geolocation permission?: Type Y if your app needs location access. Otherwise, N

In these questions, the important part is the key store and the key.

First and Last names: Your full name

Organizational Unit: Developer or anything

Organization: Your organization name

Country (2-letter code): Your country code

Password for key store: Enter a new password

Password for key: Re-enter the same password

Note: These passwords for both the key store and key should be the same, or else it will throw an error. Refer to this issue: Bubblewrap Issue.

Step 4 – Build the App

bubblewrap build --universalApk

This command starts building your application. Here, the flag universalApk will produce the .apk and .abb. If you’re going to publish your application in the Play Store, upload the .abb file to the Play Store. For our testing, we need an APK file, so this flag universalApk will produce both files. If we didn't give this flag, it would only give us .abb.

Step 5 – Setting Up TWA Validation

Once the build is done, you’ll get the APK. Transfer it to your phone and test it. When you open the app, you’ll see the browser address bar. This is because we haven't set up the "trust" between your app and your website yet. Let's fix that now.

In your frontend project, go to the public folder, create a new folder called .well-known, and inside that, create a file called assetlinks.json.

frontend/
├── public/
    ├── .well-known/
        └── assetlinks.json

What is the .well-known folder?

A well-known folder is used to store files that define configurations for protocols, as it’s used for external sources to find the validation for your website. In our case, our app checks the well-known folder from our website and verifies the validation.

Paste the following into assetlinks.json:

[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "chat.yourapp.twa",
      "sha256_cert_fingerprints": [
       "your_sha256_fingerprint"
      ]
    }
  }
]

What is delegate_permission/common.handle_all_urls?

This is a special flag that opens all the links from the app instead of the domain. Simply put, it acts as a deeplink. After you install the app, if you click your website link from WhatsApp or from somewhere, it will open your app instead of opening in a browser, acting as a deeplink.

The package_name field should be the packageId, which you can get from your Android build folder in twa-manifest.json.

Now, get your fingerprints. Run the following command to do so:

keytool -list -v -keystore android.keystore -alias android

The alias name should be the value that you created. Once you enter this command, it’ll ask for the key store password. Enter that, and you’ll get your SHA256 fingerprint. Copy that and paste it into the assetslinks.json file in the sha256_cert_fingerprints array. Now push these changes to production. You can verify the validation in Digital Asset Links

That’s it! Now you can install the app and test it.

Step 6 (Optional) – Customize the In-App Experience

Now, additionally, there will be some cases where we want to show different content to users on the website vs the mobile app. Can we do that? Yes!

In your Android build folder, in twa-manifest.json, there will be a field called startUrl. If not, add it and add the value "startUrl": "/?twa=true". The startUrl is the entry point. I have a query parameter of value twa=true.

Run the build again with bubblewrap build --universalApk.

Now, if you open your app, it will open the app with the entry URL as yourwebsitedomain.com/?twa=true.

In your frontend:

const twaParam = queryParams.get("twa");

const [isTwa, setIsTwa] = useState<boolean>(() => {
   return localStorage.getItem("isTwa") === "true";
});

useEffect(() => {
  if (twaParam === "true") {
    localStorage.setItem("isTwa", "true"); // set the value to local storage
    setIsTwa(true);
  }
}, [twaParam]);

 {isTwa? (
    <Link to="/contact" className="underline hover:text-primary">
       Contact
    </Link> 
  ) : (
     <Link to="/download" className="underline hover:text-primary">
       Download App
      </Link>
  )}

In the code above, we check for the twa=true query parameter in the URL. If it's present, we save that information to local storage, and then we conditionally render the content for the user.

That's it. We have created an App.

If you want to change any name, colour, or splash screen, you can change it in twa-manifest.json and run the build again.

Wrapping Up

Bubblewrap is only for Android. If you want the app to support cross-platform, there are some other platforms, like Capacitor, which I’ll write about in another article.

By the way, you can check out the App that I made using Bubblewrap here: Stranger Talk.

If there are any mistakes or you have any questions, contact me on LinkedIn or Instagram.

Thank you for reading!

Google’s Accessibility Scanner on Google Play is a free app that offers developers, designers, and product leaders the ability to audit their app to find accessibility issues. The app is designed to highlight accessibility issues that might not meet the WCAG 2.1 Level AA standards.

Once installed, the Accessibility Scanner allows you to take screenshots or video recordings of your app, then highlights areas that may not meet accessibility requirements, like small touch targets, low color contrast, or missing content labels.

Here’s what we’ll cover:

1. How to Download and Enable the Accessibility Scanner

2. How to Use the Accessibility Scanner

   • How to Use the Snapshot Feature

   • How to Use the Record Feature

3. Why Use the Accessibility Scanner?

How to Download and Enable the Accessibility Scanner

In five quick steps, you can download the Accessibility App and enable it on your Android device.

1. Search “Accessibility Scanner” on Google Play Store and download it.

2. Find the downloaded app on your device and open it.

3. Turn on the Accessibility scanner by clicking on the “Turn on” button on the bottom right side of the page. This will take you to your Accessibility Settings.

4. In the Accessibility Setting page, click on the Accessibility Scanner button. This will take you to the Accessibility Scanner Settings.

5. Find Accessibility Scanner toggle and turn it on. (This will open a modal that asks if you allow “Accessibility Scanner” to have full control of your device, click Allow.

After step five, you will have a blue checkmark icon will appear on the right side of your screen (see image below). This floating icon gives you quick access to start scanning any screen for accessibility issues.

How to Use the Accessibility Scanner

To scan or record your app to find accessibility issues, tap the blue checkmark icon. You’ll see a few options after clicking on the blue checkmark:

• Record: Captures a short video of user interaction and generates a report of potential accessibility issues.

• Snapshot: Takes a static screenshot and flags issues found on that screen.

• Turn off: Turns the Accessibility Scanner off.

• Collapse: Collapses the options to show the initial blue checkmark.

You can choose between taking a single Snapshot or recording user flow using Record to evaluate multiple screens.

How to Use the Snapshot Feature

The snapshot button will take a snapshot of the page you are currently in and give you a result of accessibility issues that may be on the page. The accessibility issues will be highlighted in red boxes.

The image below is the result of taking a snapshot of the Facebook log in page. The accessibility scanner states that there are 10 accessibility suggestions on this page alone.

You can click on the highlighted area in order to get more details of the potential accessibility issue. For example, you can click on the red box that is highlighting the “Mobile number or email” form that’s in the image above. Once you click on the highlighted area, you will get additional information.

The image below is the result of clicking on the “Mobile number or email” form element. Accessibility Scanner is highlighting errors it found on this email form.

The first suggestion it gives is to fix the item label, because the item may not have a label readable by screen readers. The second issue it highlights is the Touch Target and suggests that the target should be larger. The final suggestion is the Unexposed Text, possible text detected: Mobile number or email.

Snapshots allow us to take screenshots of our pages and highlight accessibility issues.

How to Use the Record Feature

If you select to record, the Accessibility Scanner will take snapshots at intervals as you go through your app’s pages. To end the recording, tap the blue pause button (which replaces the original checkmark during recording).

Once you stop recording, Accessibility Scanner will give you the several snapshots and highlighted errors. The image below is the result of recording the Facebook log in page in less than a minute.

While recording, I navigated to other pages within the app. The recording gave 5 snapshots of the pages I was going through. You can see the snapshots on top of the page. In the image below, I am on screen one of five,. I can click to the other snapshots underneath the words, “Screen 1 of 5” and see issues for different snapshots taken during my recording. Similar to the snapshot accessibility audit, you can click on the red boxes and get more information on the errors.

Why Use the Accessibility Scanner?

The Accessibility Scanner is a valuable tool for teams throughout the app development lifecycle. Engineers can use it early in the process to scan the app locally, identify accessibility issues, and resolve them before release. During the QA phase, designers and product managers can use the scanner to audit user interfaces and flag potential accessibility concerns. Even after an app is in production, all teams can continue to use the scanner to monitor and improve accessibility.

But it’s important to note that the Accessibility Scanner is just one part of an accessibility strategy – it’s not a complete replacement for manual testing or audits. And it won’t catch all types of accessibility barriers – especially those that require keyboard navigation, screen reader testing, or cognitive usability reviews. But it is a simple and effective starting point for improving accessibility in Android apps.

You should use it alongside other tools, such as Android’s TalkBack for screen reader testing. Most importantly, real-world feedback from people who use assistive technologies is essential to identifying usability barriers that automated tools may miss.

With just a few taps, Accessibility Scanner helps surface issues that might otherwise be missed. It’s a free, lightweight, and essential tool for anyone building inclusive mobile experiences.

Thanks for Reading!

You should now know how to get started using the Accessibility Scanner to check your apps’ accessibility and make sure they’re usable by everyone.

We just posted a massive 60-hour Kotlin and Android Development course on the freeCodeCamp.org YouTube channel. This course will help you master modern Android practices. Alexandru Cristian developed this course. It’s packed with hands-on practice, ensuring you not only learn the theory but also apply it by building multiple real-world applications.

This is a thorough exploration of the Kotlin programming language and the Android development ecosystem. Here’s a glimpse of what you’ll learn:

Kotlin from the ground up

• Solidify your understanding of Kotlin syntax, variables, operators, control flow (loops, conditionals), and null safety.

  • Dive deep into Object-Oriented Programming (OOP) with Kotlin, covering classes, inheritance, interfaces, abstract classes, and data classes.

  • Master Kotlin Collections (lists, sets, maps) and powerful functions to manipulate them.

  • Explore advanced concepts like Generics, Lambda functions, and Kotlin Coroutines for efficient asynchronous programming.

  • Even touch upon SQL basics to understand data persistence.

Comprehensive android development

• Get started with Android Studio and understand the Android project structure.

  • Learn traditional UI development with XML, including various layouts (LinearLayout, RelativeLayout, ConstraintLayout) and UI widgets.

  • Master Android Activities and Fragments, their lifecycles, and how to navigate between screens using Intents and the modern Navigation Component.

  • Build dynamic lists with RecyclerView.

  • Understand and implement Material Design principles.

  • Work with data persistence using Room Database and connect to the cloud with Firebase Firestore.

  • Make network requests and handle APIs using Retrofit and parse JSON data.

  • Implement robust app architecture using MVVM (Model-View-ViewModel), LiveData, and potentially Dependency Injection.

  • Get an introduction to the future of Android UI with Jetpack Compose.

Theory is important, but practice is what makes a developer. Throughout this 60-hour course, you'll be building a portfolio of applications. The final project is an Uber clone that will have you implementing features like maps integration, user authentication, real-time location tracking, and more, demonstrating truly professional-grade development techniques.

Start learning today

Learning Kotlin and Android development opens doors to an exciting career in mobile technology. Android powers billions of devices worldwide, and skilled developers are in constant demand. Kotlin is a modern, concise, and powerful language officially supported by Google for Android development, making it an essential skill for today's app creators.

Watch the full course on the freeCodeCamp.org YouTube channel (60-hour watch).

At the time, there was no built-in composable to display tooltips and there were several alternative solutions circling online. The problem with those solutions was that once Jetpack Compose released newer versions, those solutions might break. So it wasn’t ideal and the community was left hoping that sometime in the future, support would be added for tooltips.

I’m glad to say that since version 1.1.0 of Compose Material 3, we now have built in tooltip support. 👏

While this in itself is great, more than a year has passed since that version was released. And with subsequent versions, the API related to tooltips changed drastically as well.

If you go over the changelog, you will see how the public and internal APIs have changed. So bear in mind, that when you read this article, things may have continued to change as everything related to Tooltips is still marked by the annotation ExperimentalMaterial3Api::class.

❗️ The version of material 3 used for this article is 1.2.1, which was released on March 6th, 2024

Tooltip Types

We now have support for two different types of tooltips:

1. Plain tooltip

2. Rich media tooltip

Plain Tooltip

You can use the first kind to provide information about an icon button that wouldn’t be clear otherwise. For example, you can use a plain tooltip to indicate to a user what the icon button represents.

To add a tooltip to your application, you use the TooltipBox composable. This composable takes several arguments:

fun TooltipBox(
    positionProvider: PopupPositionProvider,
    tooltip: @Composable TooltipScope.() -> Unit,
    state: TooltipState,
    modifier: Modifier = Modifier,
    focusable: Boolean = true,
    enableUserInput: Boolean = true,
    content: @Composable () -> Unit,
)

Some of these should be familiar to you if you have used Composables before. I’ll highlight the ones that have a specific use case here:

• positionProvider - Of PopupPositionProvider type, and is used to calculate the position of the tooltip.

• tooltip - This is where you can design the UI of how the tooltip will look like.

• state - This holds the state that is associated with a specific Tooltip instance. It exposes methods like showing/dismissing the tooltip and when instantiating an instance of one, you can declare if the tooltip should be persistent or not (meaning if it should keep displaying on the screen until a user performs a click action outside the tooltip).

• content - This is the UI that the tooltip will display above/below.

Here is an example of instantiating a BasicTooltipBox with all the relevant arguments filled in:

@OptIn(ExperimentalFoundationApi::class, ExperimentalMaterial3Api::class)
@Composable
fun BasicTooltip() {
    val tooltipPosition = TooltipDefaults.rememberPlainTooltipPositionProvider()
    val tooltipState = rememberBasicTooltipState(isPersistent = false)

    BasicTooltipBox(positionProvider = tooltipPosition,
        tooltip =  { Text("Hello World") } ,
        state = tooltipState) {
        IconButton(onClick = { }) {
            Icon(imageVector = Icons.Filled.Favorite, 
                 contentDescription = "Your icon's description")
        }
    }
}

Jetpack Compose has a built in class called TooltipDefaults. You can use this class to help you instantiate arguments that make up a TooltipBox. For instance, you could use TooltipDefaults.rememberPlainTooltipPositionProvider to correctly position the tooltip in relation to the anchor element.

Rich Tooltip

A rich media tooltip takes more space than a plain tooltip and can be used to provide more context about the functionality of an icon button. When the tooltip is shown, you can add buttons and links to it to provide further explanation or definitions.

It is instantiated in a similar way as a plain tooltip, inside of a TooltipBox, but you use the RichTooltip composable.

TooltipBox(positionProvider = tooltipPosition,
        tooltip = {
                  RichTooltip(
                      title = { Text("RichTooltip") },
                      caretSize = caretSize,
                      action = {
                          TextButton(onClick = {
                              scope.launch {
                                  tooltipState.dismiss()
                                  tooltipState.onDispose()
                              }
                          }) {
                              Text("Dismiss")
                          }
                      }
                  ) {
                        Text("This is where a description would go.")
                  }
        },
        state = tooltipState) {
        IconButton(onClick = {
            /* Icon button's click event */
        }) {
            Icon(imageVector = tooltipIcon,
                contentDescription = "Your icon's description",
                tint = iconColor)
        }
    }

A few things to notice about a Rich tooltip:

1. A Rich tooltip has support for a caret.

2. You can add an action (that is, a button) to the tooltip to give users an option to find out more information.

3. You can add logic to dismiss the tooltip.

Edge Cases

When you choose to mark your tooltip state as persistent, it means that once the user interacts with the UI that shows your tooltip, it will stay visible until the user presses anywhere else on the screen.

If you looked at the example of a Rich tooltip from above, you might have noticed that we have added a button to dismiss the tooltip once it’s clicked.

There is a problem that happens once a user presses that button. Since the dismiss action is performed on the tooltip, if a user wants to perform another long press on the UI item that invokes this tooltip, the tooltip won’t be shown again. This means that the state of the tooltip is persistent on it being dismissed. So, how do we go about and resolve this?

In order to “reset” the state of the tooltip, we have to call the onDispose method that is exposed through the tooltip state. Once we do that, the tooltip state is reset and the tooltip will be shown again when the user performs a long press on the UI item.

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun RichTooltip() {
    val tooltipPosition = TooltipDefaults.rememberRichTooltipPositionProvider()
    val tooltipState = rememberTooltipState(isPersistent = true)
    val scope = rememberCoroutineScope()

    TooltipBox(positionProvider = tooltipPosition,
        tooltip = {
                  RichTooltip(
                      title = { Text("RichTooltip") },
                      caretSize = TooltipDefaults.caretSize,
                      action = {
                          TextButton(onClick = {
                              scope.launch {
                                  tooltipState.dismiss()
                                  tooltipState.onDispose()  /// <---- HERE
                              }
                          }) {
                              Text("Dismiss")
                          }
                      }
                  ) {

                  }
        },
        state = tooltipState) {
        IconButton(onClick = {  }) {
            Icon(imageVector = Icons.Filled.Call, contentDescription = "Your icon's description")
        }
    }
}

Another scenario where the tooltip state does not reset is if instead of calling ourselves for the dismiss method per a user’s action, the user clicks outside of the tooltip, causing it to be dismissed. This calls the dismiss method behind the scenes and the tooltip state is set to dismissed. Long pressing on the UI element to see our tooltip again will result in nothing.

Our logic that calls the tooltip’s onDispose method does not get triggered, so how can we reset the tooltip’s state?

Currently, I haven’t been able to figure this out. It might be related to the tooltip’s MutatorMutex. Maybe with upcoming releases, there will be an API for this. I did notice that if other tooltips are present on the screen and they are pressed, this resets the previously clicked upon tooltip.

If you would like to see the code featured here, you can go to this GitHub repository

If you would like to see tooltips in an application, you can check it out here.

References

• Material3 Tooltip Overview

• Tooltip Defaults

• Tooltip Source Code

Update your Play Core Maven dependency to an Android 14 compatible version! Your current Play Core library is incompatible with targetSdkVersion 34 (Android 14), which introduces a backwards-incompatible change to broadcast receivers to improve user security. As a reminder, from August 31, Google Play requires all new app releases to target Android 14. Update to the latest Play Core library version dependency to avoid app crashes: https://developer.android.com/guide/playcore#playcore-migration

You may not be able to release future versions of your app with this SDK version to production or open testing.

Looks frightening, doesn’t it?

Don’t be so worried. It is actually easier than it looks.

What the Change is Actually About

Basically, Google stopped releasing new versions of the play core library back in early 2022.

The last version of play core library released

And from April 2022, they have broken down the original play core library into four separate libraries:

• Play Assets Delivery Library
• Play Feature Delivery Library
• Play In-App Reviews Library
• Play In-App Updates Library

Each library has its own functionality and responsibility.

Since the older core play library only supports up to a certain API level, you need to migrate your application to use the newer libraries that have support for the most recent API levels.

In essence, you need to figure out which functionality of the original core play library you are using and then download the correct part. For example, if you had logic to notify users when a newer version of your application was available, you need to take the Play In-App-Updates library.

We will be presenting two uses cases here:

• Native Android application
• Flutter application

Use Case – Native Android App

If you have a native Android application, whether it is written in Kotlin or Java, you need to do the following:

1. Open your application level build.gradle file
2. Most probably you will see under the dependencies block, this line:

implementation 'com.google.android.play:core-ktx:1.8.1'

3. You will need to remove it and replace it according to what you used in the previous core library

4. If you need to take the Play In-App-Updates library, then you need to add these to the dependencies block:

implementation 'com.google.android.play:app-update:2.1.0'
//Add the dependency below if you are using Kotlin in your application
implementation 'com.google.android.play:app-update-ktx:2.1.0'

5. Rebuild your application and see that everything works as it should.

✋ You might also need to change import statements from import com.google.android.play.core.tasks.*; to import com.google.android.gms.tasks.*;.

Use Case – Flutter Application

Since Flutter is a framework that caters to both Android and iOS, this scenario is a bit different from the one above. If you receive the warning to upgrade the core play library in your Flutter application, you need to have a look at the libraries you are using in your pubspec.yaml file:

dependencies:
  flutter:
    sdk: flutter
  ...
  in_app_update: ^3.0.0

As you can see above, the application depends on the in_app_update library, which has to do with notifying users when a newer version of the application is available. When we head over to in_app_update’s pub.dev changelog page, we can see that:

version 4.1.0 added the required support

So we need to update our pubspec.yaml file to use that version (at the very least).

dependencies:
  flutter:
    sdk: flutter
  ...
  in_app_update: ^4.1.0

Run Pub get and you should be good to go.

You may have come across multi-library projects in your line of work, or you may be looking into converting your library into sub-modules for better structure and organization. No matter the case, you should be well aware of what lies in front of you before diving in.

Writing your own library in Android is neat. You get a chance to write some code that can help other developers (or even yourself).

Since libraries can’t be a standalone project by themselves, they are usually always paired in a project with an application. This allows developing the library to be a simple process where you add a feature/fix a bug and then you can test it directly with the application you have in the project. Thus, simulating (in a local way) how a developer will integrate your library.

But, what if your library relies on another library you are developing?

If you are not aware of it, you should know that a library (read aar) cannot contain another local library within it. It can rely on libraries remotely (via dependencies), but not on something local.

This is not supported in Android, and while some solutions popped up during the years (FatAar), these didn’t always solve the problem and are not up to date. There is even a Google Issue Tracker requesting this feature that has been open for quite some time and is receiving plenty of attention from the community. But let’s identify which walls we can break and which we cannot.

Imagine your project hierarchy looks like this:

-- App
|
 -- OuterLib
   |
    --- InnerLib

So, since InnerLib can’t be part of your original project, where can it reside? And also how would you be able to work locally while developing features inside InnerLib?

We are going to answer these questions in this article.

Git Submodule

For most technical problems, there isn’t always just one solution. Usually, there are more, but each solution has its drawbacks. It's all a question of which drawbacks you are more comfortable living with at the end of the day.

To answer our first question, where can InnerLib reside, we have several options:

1. Make InnerLib a submodule of our original project
2. Make InnerLib a remote dependency of its own

If you are not aware of submodules in Git, Git’s documentation is a good place to familiarize yourself with them. Quoting from it (the first paragraph):

It often happens that while working on one project, you need to use another project from within it. 👉 Perhaps it’s a library that a third party developed or that you’re developing separately and using in multiple parent projects. 👈 A common issue arises in these scenarios: you want to be able to treat the two projects as separate yet still be able to use one from within the other.

This paragraph shows us that this is exactly our use case. Using a submodule has its benefits. All your code is in one place, is easy to manage, and is easy to develop locally.

But submodules have some weaknesses. One is the fact that you must always be aware of which branch your submodule is pointing to. Imagine a scenario where you are on a release branch in your main repository and your sub-module is on a feature branch. If you don’t notice, you release a version of your code with something that is not ready for production. Whoops.

Now think about this within a team of developers. One careless mistake can be costly.

If the first option sounds problematic for you, then hosting your library in another repository is your second choice. Setting up the repository is pretty simple, but how do you work locally now?

Working Locally

Now that we've gotten our project set up properly, we will probably have a line similar to this in our OuterLib build.gradle file:

dependencies {
  implementation 'url_to_remote_inner_lib_repository'
}

How can we make the development cycle efficient and easy to work with? If we develop some feature in InnerLib, how do we test things out in OuterLib? Or in our application?

One solution that might come up is to import our InnerLib locally to our OuterLib project, while having InnerLib .gitignored in our OuterLib project. You can do so easily by right clicking on the name of the project in the left hand side menu in Android Studio and going to New → Module.

How to import a module (Step 1)

Then in the window that opens up, you can choose the Import option at the bottom left:

How to import a module (Step 2)

That sounds easy and simple so far, but what’s the catch?

Each time you modify a file that belongs to InnerLib, the changes won’t be reflected inside InnerLib since it is ignored. So, each change you want to make has to happen inside of InnerLib and then you have to import it again inside OuterLib to see the changes.

This doesn’t seem right. There must be a better way of doing this.

With just a few lines in our settings.gradle file, we can make sure our files stay in sync when we make changes in InnerLib.

When we imported InnerLib into our project, Android Studio made a copy of InnerLib and cached it. That is why we needed to re-import the library for every change we made inside of it. We can tell Android Studio where to reference the files from using the projectDir attribute.

Our settings.gradle might look something like this:

include ':outerLib', ':innerLib', ':app'

To reference our InnerLib locally, we would have to change settings.gradle into this:

include ':outerLib', ':innerLib', ':app'
project('innerLib').projectDir = new File('PATH_TO_INNER_LIB')

Using this approach, our InnerLib files will be linked to our working directory, so every change we make will be reflected immediately.

But, we would like flexibility when working locally on OuterLib with a remote version of InnerLib. What we wrote above inside the settings.gradle file will only allow us to work locally and surely we don’t want to commit that as it is.

Maven Local

If the approach above doesn’t sit quite right with you, there is a different one you can take. Just like you would publish your library publicly with maven, you can do the same thing locally with maven local. Maven local is a set of repositories that sit locally on your machine.

Below are the paths for mavenLocal depending on the operating system of your machine:

• Mac → /Users/YOUR_USERNAME/.m2
• Linux → /home/YOUR_USERNAME/.m2
• Windows → C:\Users\YOUR_USERNAME.m2

In essence you can publish your library locally and then link to it in your project. Doing it this way, we can link our project to InnerLib.

In order to allow this configuration in our project, we need to do the following things:

1. Add mavenLocal() as a repository inside our repositories clause. This is to allow our project the ability to search for repositories locally

buildscript {
    repositories {
        mavenLocal()
    }
}

...

allprojects { 
    repositories { 
        mavenLocal() 
    }
}

2. Change our implementation line inside our dependencies clause to reference our InnerLib as if it we are referencing it remotely

3. To publish InnerLib locally, we will create a file called publishingLocally.gradle that will contain the following:

apply plugin: 'maven-publish' 

project.afterEvaluate {
    publishing { 
      publications {
            library(MavenPublication) { 
                    setGroupId groupId          //your library package
                    setArtifactId artifactId              
                    version versionName         //I.E. 1.0

                    artifact bundleDebugAar

                    pom.withXml { 
                        def dependenciesNode = asNode().appendNode('dependencies')
                        def dependencyNode = dependenciesNode.appendNode('dependency')
                        dependencyNode.appendNode('groupId', 'your_group_id')
                        dependencyNode.appendNode('artifactId', 'your_artificat_id')
                        dependencyNode.appendNode('version', 'your_version')
                    } 
                }
            }
        }
}

4. Inside your application level build.gradle file, add the line:

apply from: '/.publishingLocally.gradle

If this option seems a bit too good to be true, it is. While on one hand, we can develop things locally seamlessly just as if we were working with a remote library. On the other, if we make any change inside InnerLib while working locally, it is required to publish it locally again. While this isn’t a costly task, it does create a need to perform tedious tasks over and over.

A Solution for Working Locally and Remotely

We want to avoid the constant need to re-publish our InnerLib package whenever we make a change locally. We need to figure out a way to make our project be aware of those changes.

In the Working Locally section, we found out how to do that, but we had an issue with committing the settings.gradle file. To solve this problem so we can work both locally and remotely with our InnerLib, we will use a parameter we will define in our gradle.properties file.

The gradle.properties file is a place where you can store project level settings that configure your development environment. This helps make sure that all the developers on a team have a consistent development environment.

Some settings you might be familiar with that are found inside this file are AndroidX support (android.useAndroidX=true) or the JVM arguments (org.gradle.jvmargs=-Xmx1536m).

To help us solve our situation, we can add a parameter here to indicate whether we want to work locally or not. Something along the lines of:

workingLocally = false

This parameter will grant us the ability to distinguish between which settings we are working with, either locally or with production code. First, let’s alter what we have in our settings.gradle file by wrapping it in a condition that checks if our parameter is true:

include ':outerLib', ':innerLib', ':app'
if (workingLocally.booleanValue()) {
  project('innerLib').projectDir = new File('PATH_TO_INNER_LIB')
}

This way, we indicate to the project to get the files for our InnerLib locally from our machine.

Another place where we need to change our logic is in our build.gradle file. Here, instead of getting the code to our library remotely in our dependencies block, we can indicate whether we are depending on it locally or not.

dependencies {
   if (workingLocally.booleanValue()) {
      implementation 'innerLib'
   } else {
     implementation 'url_to_remote_repository'
  }
}

⚠️ Word of warning: You should never commit the gradle.properties file when working locally.

The journey was long and may have seemed quite exhausting. But now we have a full-proof setup for working locally and remotely on a multiple library project.

If you encounter any issues or would like to give your take on this, feel free to leave a comment.