Hardening a Cross-Platform BLE Stack

The first fix

My first upstream contribution, PR #217, added exception handling to the Windows connection and notification callbacks. If WinRT now throws there, the plugin cleans up the affected connection state and reports the failure through the existing Dart connection callback instead of taking down the process.

I manually reproduced the failure and checked that the application could reconnect afterward, then submitted the fix upstream. It used the existing connection callback, so the public Dart API did not need to change.

Why Dart exception handling was not enough

A try and catch in Dart only helps if the failure crosses the platform boundary. These exceptions were thrown inside native asynchronous operations and event callbacks. The Windows process was already gone before Flutter could react.

Once the process stayed alive, I could investigate what a badly timed disconnect or reconnect did to the connection state.

One connection, several asynchronous owners

As I continued testing the Windows implementation, I found that Flutter method handlers, WinRT callbacks, and asynchronous GATT operations could all touch the same connection state during disconnect or cleanup. An operation started by an old connection could even finish after a new connection had replaced it.

Native objects had to stay alive for as long as an operation used them. Work belonging to an old connection also had to lose the right to change the new one, even if it finished successfully.

Hardening ownership and stale operations

My next contribution, PR #278, added synchronized ownership of the connected-device state and a generation number for connection attempts. Every new attempt advances that number. Callbacks and asynchronous completions can then check whether they still belong to the current connection before changing anything.

I manually checked scanning, connection, service discovery, reads and writes, notification changes, and disconnects against a physical BLE device. The ownership and cleanup changes below also went through the HIL fixture once it was available. WinRT completion handling needed care too: an operation could finish successfully after its connection had already been replaced.

• Shared ownership for native connection state used by in-flight work
• Connection generations that invalidate superseded attempts and callbacks
• Synchronized installation, lookup, replacement, and removal of devices
• Cleanup ordered around handlers, subscriptions, services, and native devices
• Notification changes committed only after the native operation succeeds

Connecting the application, library, and fixture

Building the fixture also meant repeatedly changing firmware, flashing the board, and running host-side tests. I realized agents could coordinate that work. They could implement a scenario, build and flash the Zephyr firmware, run the Flutter test, inspect the failure, and repeat after a correction. I could investigate more edge cases without manually carrying every change through that cycle.

I gave the agents context from three repositories: the SSP application, Universal BLE, and the Zephyr fixture firmware. This is usually called context engineering. In this case, it let a host-side test be checked against the firmware command it used, the native code it exercised, and the recovery behavior the application needed.

Different agents for different parts

I split the agent work by concern. One agent could stay inside Zephyr and the fault protocol, another could work on the Flutter integration tests, while another reviewed C++ ownership, WinRT completion, and teardown. Separate verification work then checked what came back.

Independent tasks could run in parallel, with their findings returning to one coordinating thread before the next decision. I defined the architecture, decided what could be delegated safely, connected the results, and rejected changes that did not match the physical system.

Checking that a test exercises the fix

I organized that work into an agentic loop, sometimes called loop engineering. Each cycle started with a concrete failure scenario. The agents worked on the matching host test and peripheral behavior, built and flashed the fixture, ran the test, and used the result to correct the implementation or the test itself.

The same loop checked the hardening. I would remove or bypass a fix and have the scenario run again. If it stayed green, I needed to find out why it had missed the missing protection. Once it failed for the expected reason, I restored or improved the fix and checked that the test passed, including a follow-up read, write, reconnect, or resubscription.

My implementation and review responsibilities

I used AI heavily here. Flutter integration testing was new to me, so the agents handled much of the detailed host-side implementation. They also produced the first version of the Zephyr fixture firmware and automated parts of the build and flash process. I reviewed, corrected, and improved the firmware work because embedded software, BLE, and Zephyr are the areas where I already knew what good looked like.

I defined the fault model, the system boundaries, what counted as a correct result, how recovery should behave, and how the three repositories fit together. I also checked whether an implemented fault represented the failure class under investigation and whether its passing test was meaningful.

Extending the loop to native Windows tests

The same approach later supported native Windows tests and startup-close reproduction, alongside the HIL and fault-injection runs. That mattered when shutdown testing reached a failure during Bluetooth initialization.

GATT objects and the first notification

Running faults repeatedly through the fixture exposed more Windows problems. Those fixes became PR #284. In-flight reads, writes, discovery, and descriptor operations needed to retain their native GATT objects. Service changes also needed to refresh the GATT map safely and restore handlers for existing subscriptions.

One example was the first notification: the peripheral could send its first notification while the Client Characteristic Configuration (CCC) descriptor write was still completing. Windows registered the handler too late and lost that value. I moved registration before the enable write, with rollback if the write failed. The same PR corrected descriptor return values and copied notification payloads when their underlying buffer also contained platform-message bytes.

Queued callbacks and plugin shutdown

Connection events also needed their generation checked when delivered on the UI thread. Checking only when an event was queued still allowed an old disconnect event to arrive after a newer connection had started. I added a reconnect test that swept short delays around a pending disconnect callback.

For shutdown, a callback tracker stopped new work from entering and kept plugin state alive until callbacks already running had finished. The drain dispatched COM continuations and Windows messages so work waiting for the UI thread could finish. The baseline and fault-injection suites passed with that drain in place. Later, closing the application during startup exposed a different shutdown failure.

Radio initialization during shutdown

PR #319 addressed a crash when the app closed while Radio::GetRadiosAsync() was pending. Initialization held a lease on the general callback tracker. Shutdown pumped UI messages while waiting for its continuation, and those messages could enter Flutter after engine teardown had begun.

For this fix, Codex (GPT 6.1 Sol) handled implementation and test execution entirely. Initialization was separated from that tracker and given a WinRT completion handler. Pending radio enumeration no longer holds a lease. Only its short completion and UI publication are tracked, late work is ignored after shutdown starts, and an already-entered initialization completion drains without pumping application messages. The cross-thread notification window handle is atomic too.

Reproducing the close in the real runner

Before the fix, every startup-close reproduction run crashed with 0xC000041D. Afterward, repeated runs in both Debug and Release exited cleanly when closed during the first two seconds of startup.

Verification covered native tests, startup-close reproduction, and the Windows HIL and fault-injection runs. A native test checks the initialization lifetime protocol with a controlled WinRT operation. Using the general callback tracker as a countercheck fails its message-preservation assertion. A separate script exercises startup and close in the actual Flutter runner.