shiny-bluetoothle

# Shiny BluetoothLE (Client/Central) ## When to Use This Skill Use this skill when the user needs to: - Scan for BLE peripherals - Connect to and communicate with BLE devices - Read, write, or subscribe to GATT characteristics - Read or write GATT descriptors - Implement managed scans with automatic peripheral list management - Request MTU changes, pair with devices, or perform reliable write transactions - Read standard BLE services (device information, battery, heart rate) - Work with BLE advertisement data - Open L2CAP CoC channels to a peripheral that has published a PSM - Upload or download files over L2CAP with percent-complete / throughput / ETA metrics Do NOT use this skill for BLE hosting/peripheral mode (advertising, GATT server). That is a separate library (`Shiny.BluetoothLE.Hosting`). ## Library Overview - **NuGet Package**: `Shiny.BluetoothLE` (Android, iOS/tvOS/macOS, Windows), `Shiny.BluetoothLE.Linux` (Linux via BlueZ), `Shiny.BluetoothLE.Blazor` (Blazor WebAssembly via Web Bluetooth API) - **Primary Namespace**: `Shiny.BluetoothLE` - **Managed Scan Namespace**: `Shiny.BluetoothLE.Managed` - **Platforms**: Android, iOS/tvOS/macOS (Apple), Windows, Linux (BlueZ), WebAssembly (Web Bluetooth) ### tvOS tvOS runs the same CoreBluetooth central implementation as iOS — scanning, connecting, GATT and L2CAP are identical and there is **no tvOS-specific code to write**. Two Apple limits to encode in any guidance you generate: - **No background Bluetooth.** tvOS has no `bluetooth-central` background mode. Scans and connections end when the app suspends, and setting `AppleBleConfiguration.RestoreIdentifier` accomplishes nothing — do not suggest it for tvOS. - **No peripheral role.** `Shiny.BluetoothLE.Hosting` has no tvOS target; `CBMutableService`/`CBMutableCharacteristic` carry no constructors there. If asked to build a GATT server on tvOS, say it is not possible rather than producing code that cannot compile. Also worth mentioning when relevant: the Siri Remote is itself a BLE device, so an Apple TV has fewer simultaneous connections to spare than an iPhone. ### Blazor WebAssembly / Web Bluetooth caveats The Blazor implementation is built on the browser's Web Bluetooth API and inherits its limitations: - **User-gesture gated.** Scans must be kicked off from a click handler. The browser shows a native chooser and Shiny only sees the peripheral(s) the user explicitly selects — there is no ambient/background scanning and no manufacturer data. - **HTTPS or `http://localhost` required.** The API is unavailable on plain `http://`. - **No background operation.** Scanning and connections stop when the tab is backgrounded or closed. - **Browser support is Chromium-only and requires enabling in some cases.** When generating setup instructions or troubleshooting guidance, note the following: - **Chrome / Edge / Brave / Opera (desktop)**: enabled by default on Windows, macOS, Linux, ChromeOS. Fallback: `chrome://flags/#enable-web-bluetooth` (or `edge://flags`, etc.) → *Enabled* → restart. Linux also needs `experimental-web-platform-features` on and BlueZ 5.43+. - **Chrome / Edge (Android)**: Android 6.0+. OS location services must be on for the chooser prompt to appear. - **Samsung Internet**: enable `internet://flags` → *Web Bluetooth*. - **Safari (macOS / iOS / iPadOS)**: not supported. On iOS/iPadOS suggest third-party WKWebView-based browsers *Bluefy* or *WebBLE*. Stock macOS Safari has no workaround. - **Firefox**: not supported on any platform. ## Setup Register in your `MauiProgram.cs` or host builder: ```csharp // Basic registration services.AddBluetoothLE(); // With a delegate for background events (adapter state changes, peripheral connections) services.AddBluetoothLE<MyBleDelegate>(); // iOS/macOS only - with Apple-specific configuration services.AddBluetoothLE<MyBleDelegate>(new AppleBleConfiguration( ShowPowerAlert: true, RestoreIdentifier: "my-ble-app" )); ``` The delegate class: ```csharp public class MyBleDelegate : BleDelegate { public override Task OnAdapterStateChanged(AccessState state) { // Handle adapter state changes (foreground or background) return Task.CompletedTask; } public override Task OnPeripheralStateChanged(IPeripheral peripheral) { // Handle peripheral connection state changes (foreground or background) return Task.CompletedTask; } } ``` ### Android Manifest (required for scanning) Add the BLE permissions to `Platforms/Android/AndroidManifest.xml`. **Critical:** on Android 12+ (API 31+) Shiny requests only `BLUETOOTH_SCAN` / `BLUETOOTH_CONNECT` at runtime — it does NOT request `ACCESS_FINE_LOCATION`. If you declare `BLUETOOTH_SCAN` *without* the `neverForLocation` flag, Android silently withholds **all** scan results unless fine location is also granted, so scans appear to return nothing. Unless your app actually derives physical location from BLE, always add `neverForLocation`: ```xml <!-- Android 12+ --> <uses-permission android:name="android.permission.BLUETOOTH_SCAN" android:usesPermissionFlags="neverForLocation" /> <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" /> <!-- Android 11 and below --> <uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" /> <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" /> <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" android:maxSdkVersion="30" /> ``` If you DO use BLE to infer location, omit `neverForLocation` and also request/grant `ACCESS_FINE_LOCATION` at runtime. Scans discover both legacy and Bluetooth 5 extended advertisements automatically (when the chipset supports extended advertising); legacy advertisements that virtually all peripherals send are always included. To force a legacy-only scan, use `new AndroidScanConfig(IncludeExtendedAdvertisements: false)`. ## Code Generation Instructions When generating BLE client code, follow these conventions: 1. **Always request access before scanning**: Call `IBleManager.RequestAccess()` or `RequestAccessAsync()` and verify `AccessState.Available` before starting a scan - it is how a denied permission or a switched-off adapter reaches the user. It is no longer load-bearing for the scan itself: as of 5.6 a `Scan()` issued before the Apple central has finished powering on is parked and started automatically (see #12), rather than being silently dropped. 2. **Use reactive (IObservable) APIs as the primary pattern**: The library is built on System.Reactive. Use the `Async` extension methods only when you need Task-based patterns. 3. **Dispose scan subscriptions**: Only one scan can be active at a time. Always dispose the scan subscription or call `StopScan()` when done - either one releases the slot. Never track "am I scanning" with your own flag; read `IBleManager.IsScanning`, which reports whether the *native* scan is running (it is `false` while a scan is parked waiting on the adapter). 4. **Use string-based UUIDs for services and characteristics**: The API uses string UUIDs throughout (e.g., `"180D"` or `"0000180d-0000-1000-8000-00805f9b34fb"`). 5. **Prefer `ConnectAsync` for simple connection flows**: It handles waiting for the connected state and has a default 30-second timeout. 6. **Always call `CancelConnection()` or `DisconnectAsync()` when done**: Connections are not automatically cleaned up. 7. **Use `IManagedScan` for UI-bound scanning**: It provides an `INotifyReadOnlyCollection` that works with MVVM bindings and handles peripheral deduplication, buffering, and stale removal. 8. **Feature detection via interface checks**: Optional capabilities (MTU request, pairing, reliable transactions) use feature interfaces. Always use the `Try*` or `Can*` extension methods rather than casting directly. 8a. **`IPeripheral.Mtu` is the usable payload, not the ATT MTU**: It is already the negotiated ATT MTU minus the 3-byte ATT header (`BleConstants.AttHeaderSize`), so fragment writes to `peripheral.Mtu` directly — never write `peripheral.Mtu - 3`. The units are asymmetric across a single call: `TryRequestMtu(512)` passes 512 as an ATT MTU to the platform but emits `509`, the payload. When handing a value to an API that genuinely wants an ATT MTU, add the header back with `peripheral.Mtu + BleConstants.AttHeaderSize`. 9. **Handle `BleException` and `BleOperationException`**: GATT operations can throw these. `BleOperationException` includes a `GattStatusCode`. An in-flight operation that is interrupted by a disconnect faults with a `BleException` rather than hanging, so always have an `onError` handler (or `catch`) on read/write/discovery calls — with auto-reconnect enabled, retry once the peripheral reports `Connected` again. 10. **Connection auto-reconnect**: `ConnectionConfig.AutoConnect = true` (default) reconnects the peripheral after a dropped link or a power cycle on every platform — never write your own `WhenDisconnected().Subscribe(_ => peripheral.Connect())` loop on top of it, the two fight each other. Set `AutoConnect = false` for a faster initial connection when you intend to own reconnecting. `CancelConnection()` disposes the auto-reconnect, so a deliberate disconnect stays disconnected; call `Connect()` again to re-arm it. Auto-reconnect restores the *link* only — re-run per-connection setup (MTU request, authentication handshake, reading a config characteristic) from `WhenConnected()`, not once after the first `ConnectAsync()`. 11. **The user toggling Bluetooth off/on is handled for you (5.6+, iOS/Mac Catalyst/macOS/Android)**: Do not re-implement it on those platforms. Neither OS reports the resulting drop per peripheral, so Shiny watches the adapter and, on power-down, runs the full disconnect teardown on every connected peripheral — `WhenStatusChanged()` emits `Disconnected` (agreeing with `IPeripheral.Status`, which reads the platform live), notifiers are cleared, in-flight operations fault with `BleException`, and on Android the GATT client is closed and service discovery re-armed. On power-up, every peripheral connected with `AutoConnect: true` is reconnected. Never write a `Connect()` call in `IBleDelegate.OnAdapterStateChanged(AccessState.Available)` for an `AutoConnect: true` peripheral — that is the pre-5.6 workaround and it now races Shiny's own reconnect. A `Connect()` issued while the adapter is off is parked and replayed when it returns rather than silently no-oping, so an explicit connect from that handler is safe but redundant. If you own reconnecting (`AutoConnect = false`), gate your `WhenDisconnected()` handler on the adapter being available, since you will now get a `Disconnected` on power-down. Starting a `Scan()` while a peripheral is waiting to reconnect is safe - the scan's cache prune skips peripherals with an armed auto-reconnect or a parked connect. Windows needs none of this (its `ConnectionStatusChanged` fires on a radio power-down by itself); on Linux (BlueZ) and Blazor the adapter cycle is *not* tracked, so there you still handle it yourself. 12. **Never build your own "wait for the adapter, then scan" wrapper on Apple (5.6+)**: `Scan()` parks itself. A `CBCentralManager` reports `Unknown` for a moment after construction — and `IBleManager` builds it lazily, so on a cold start that moment *is* the `Scan()` call — and CoreBluetooth silently discards any scan issued below `PoweredOn`. Shiny holds the request and issues it the instant the central powers on, and re-issues it after an adapter power cycle. Do not write `RequestAccess().Where(x => x == AccessState.Available).SelectMany(_ => Scan())`, do not retry `Scan()` on a timer, and do not call `Scan()` from `IBleDelegate.OnAdapterStateChanged` — all three now race Shiny's own replay and will throw `There is already an existing scan`. Applies to iOS, tvOS, Mac Catalyst and macOS; Android and Windows never had the problem. ## L2CAP Channels Some platforms support L2CAP Connection-Oriented Channels for streaming data without going through GATT. This is exposed as an optional capability — `ICanL2Cap` — on the platform `Peripheral` types. ### Feature detection ```csharp using Shiny.BluetoothLE; if (peripheral.IsL2CapAvailable()) { // Backend supports L2CAP } ``` ### Opening a channel ```csharp // Safe variant — returns an empty observable on unsupported platforms peripheral .TryOpenL2CapChannel(psm: 0x0083, secure: false) .Subscribe(channel => { /* ... */ }); // Direct access when the cast succeeds if (peripheral is ICanL2Cap l2cap) { l2cap.OpenL2CapChannel(psm: 0x0083, secure: false).Subscribe(channel => { // channel.Psm — the PSM the channel was opened on // channel.Identifier — the remote peer identifier // channel.DataReceived — IObservable<byte[]> of incoming bytes // channel.Write(bytes) — IObservable<Unit> that completes when bytes are queued }); } ``` `L2CapChannel` implements `IDisposable` — dispose it to close the underlying streams (Apple) or socket (Android). ### Reading and writing ```csharp using System.Reactive.Threading.Tasks; channel.DataReceived.Subscribe( payload => Console.WriteLine($"<- {payload.Length} bytes"), ex => Console.WriteLine($"Channel error: {ex.Message}"), () => Console.WriteLine("Remote closed the channel") ); await channel.Write(payload).ToTask(); ``` `DataReceived` is hot, emits right-sized byte arrays per read, completes on remote close, and surfaces I/O errors via `OnError`. ### Platform notes - **iOS / Mac Catalyst / macOS**: `CBPeripheral.OpenL2CapChannel`. The `secure` flag is ignored — security is set by how the peripheral published the channel. - **Android**: `BluetoothDevice.CreateL2capChannel` / `CreateInsecureL2capChannel`. Requires API 29+. Throws `InvalidOperationException` on older versions. - **Windows / Linux / Blazor**: not currently supported (`IsL2CapAvailable()` returns false). ### File Transfer (upload & download) Prefer these over hand-rolling a protocol on `DataReceived`/`Write`. The peripheral must be serving with `IBleHostingManager.OpenL2CapFileServer(...)` (or its own `ReadFileRequest` loop) — see the `shiny-ble-hosting` skill. The one-liners on `IPeripheral` open a channel, run the transfer, and close it again: ```csharp using Shiny.BluetoothLE; var result = await peripheral.UploadFile( psm: 0x0083, localFilePath: "/path/to/file.bin", remoteFileName: "file.bin", // optional, defaults to the local file name secure: false, onProgress: p => Console.WriteLine( $"{p.PercentComplete:P0} ({p.BytesTransferred}/{p.BytesToTransfer}) " + $"{p.BytesPerSecond / 1024} KB/s, ETA {p.EstimatedTimeRemaining}" ), cancellationToken: ct ); // result.BytesTransferred / result.Elapsed / result.BytesPerSecond (average for the whole transfer) await peripheral.DownloadFile( psm: 0x0083, remoteFileName: "firmware.bin", localFilePath: "/local/firmware.bin", onProgress: p => Console.WriteLine($"{p.PercentComplete:P0}") ); ``` Rx flavours emit progress and complete when the transfer finishes — disposing the subscription cancels it: ```csharp peripheral .DownloadFileWithProgress(0x0083, "firmware.bin", "/local/firmware.bin") .Subscribe(p => this.Percent = p.PercentComplete); ``` To move several files over **one** channel, open it yourself and use the `L2CapChannel` extensions: ```csharp using var channel = await peripheral.OpenL2CapChannelAsync(psm: 0x0083, secure: false); await channel.UploadFile("/path/a.bin", onProgress: OnProgress); await channel.DownloadFile("b.bin", "/local/b.bin", onProgress: OnProgress); ``` Tuning is via `L2CapTransferOptions` (`BufferSize`, `ProgressInterval`, `IdleTimeout`). **Progress metrics** are `TransferProgress` — identical in shape to `Shiny.Net.Http.TransferProgress`: `PercentComplete`, `BytesPerSecond`, `BytesTransferred`, `BytesToTransfer`, `EstimatedTimeRemaining`, `IsDeterministic`. Because the peer agrees the exact byte count up front, percent complete and ETA are always real (never `-1`) on both ends. Emissions fire on `ProgressInterval` (default 2s) plus a final 100% emission carrying the average throughput. **Failures**: a refusal from the peer surfaces as `L2CapTransferException` with an `Error` code (`NotFound`, `NotPermitted`, `TooLarge`, `IoError`, `ProtocolError`, `Cancelled`). Refusals leave the channel usable for the next request; a transfer that dies mid-body does not — close the channel and open a new one. A failed download never leaves a partial local file behind. **Raw streaming**: `channel.SendFile(...)` is the protocol-less primitive — it just pushes bytes with progress and no handshake, so the receiver must already know the length and framing. Use `UploadFile` unless you are talking to a non-Shiny peer. - A `Stream` overload exists for non-file sources. Pass `totalBytes` to enable percent / ETA; pass `null` and `IsDeterministic` will be false, `PercentComplete` returns `-1`, `EstimatedTimeRemaining` returns `TimeSpan.Zero`. ## Namespace Ambiguities - **`IPeripheral`**: Both `Shiny.BluetoothLE` and `Shiny.BluetoothLE.Hosting` define an `IPeripheral` interface. If both packages are referenced, do NOT add `Shiny.BluetoothLE.Hosting` as a global using. Use file-level `using` or FQN (`Shiny.BluetoothLE.IPeripheral`) to disambiguate. - **`DeviceInfo`**: `Shiny.BluetoothLE` has a `DeviceInfo` class that conflicts with `Microsoft.Maui.Devices.DeviceInfo` in MAUI apps. Use FQN when needed. ## Best Practices - Use `ScanConfig` with `ServiceUuids` to filter scans, especially on iOS where background scanning requires a service UUID filter. - For Android, consider `AndroidScanConfig` for scan mode and batching options. - For Android, consider `AndroidConnectionConfig` for connection priority settings. - Always check `CharacteristicProperties` before attempting read/write/notify operations using the convenience extensions (`CanRead()`, `CanWrite()`, `CanNotify()`, etc.).