Document Flipper Zero BLE RPC recipe over the GATT tools

[Miyamura80]

Summary

Docs-only. Adds a Flipper Zero over BLE worked example to README.md (plus a pointer in CLAUDE.md) that maps the real Flipper serial BLE-RPC sequence onto the bt_* GATT tools shipped in #31 — no module code changes were needed.

The recipe covers: pair/connect → bt_gatt_request_mtu 517 → subscribe RX …61fe indicate + status …64fe notify → write 01000000 session-activation to …64fe → bt_gatt_write_wait the app_start/NFC protobuf to TX …62fe → poll RX decode:"length_delimited" → storage_read /ext/nfc/.... It uses the authoritative service 8fe5b3d5-2e7f-4a98-2a48-7acc60fe0000 and characteristic UUIDs from real-device testing (Pixel 6 ↔ Flipper 80:E1:27:66:36:CB), and prominently states the two gotchas: (1) never send the USB-only start_rpc_session string over BLE, (2) the official Flipper app must be disconnected (single BLE client). It also notes the module is protocol-agnostic — the calling agent encodes/decodes PB.Main.

I also replaced the earlier inline Flipper snippet, whose UUIDs and RX/TX mapping disagreed with real-device testing, with a pointer to the new authoritative section.

Verification of #31's tools (all pass — no code gap)

1. Indicate + notify subscribe. AndroidBluetoothSource.doSubscribe resolves mode: indicate → checks PROPERTY_INDICATE and writes ENABLE_INDICATION_VALUE (CCCD 0x0002); notify → ENABLE_NOTIFICATION_VALUE (0x0001); auto → prefers indicate when advertised, else notify. Exactly the RX …61fe (indicate) + …63fe/…64fe (notify) split. Pass.
2. Concurrent per-characteristic queues. GattConnection.subscriptions is a ConcurrentHashMap<subKey, Subscription>, each Subscription owning its own ArrayBlockingQueue; onCharacteristicChanged routes by subKey(characteristic). RX indicate + two notify chars each get an independent queue on one connection. Pass.
3. Connection pinned; exact-bytes write. gattConnections is keyed by address and held in a single long-lived source instance; subscribe/write/poll all reuse the one live BluetoothGatt. gattWrite sends exactly the caller's value (test gattWriteSucceeds asserts 01ff → [0x01,0xff]); gattWriteWait passes the raw value straight through. No start_rpc_session or implicit framing anywhere in the repo (grep: 0 hits). Pass.
4. length_delimited reassembly across notifications. Subscription.reassemble keeps a persistent reassembly buffer, concatenates event values, runs parseLengthDelimited (varint LEB128 length + payload), and carries the incomplete remainder to the next call — so PB.Main frames spanning several indications come back whole. Covered by lengthDelimitedReassemblyAcrossTwoEventsYieldsOneFrame and parseLengthDelimitedBuffersIncompleteRemainder. Pass.
5. write_wait expresses "write, collect until reply completes". gattWriteWait auto-subscribes RX, clears stale events, writes TX, then collectUntil bounded by idle_timeout_ms / max_bytes / overall timeout_ms. The module correctly can't know protobuf has_next, so the agent bounds collection with idle_timeout/max_bytes and repeats poll until has_next = 0 — documented in the recipe. Pass.

Conclusion: #31 already provides the full subscribe/notify/indicate/write-wait capability for the Flipper BLE RPC sequence. No code change was warranted; this PR is documentation only.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NgN7YdfLT41kWnWqe1MPZa

---

Generated by Claude Code

---

Summary by cubic

Adds a real-device-tested Flipper Zero over BLE worked example to README.md, with a pointer in CLAUDE.md. It replaces the earlier inline snippet, whose UUIDs and RX/TX mapping disagreed with real-device testing, and requires no module code changes — the existing bt_* GATT tools already support the full sequence.

Recipe coverage

• Walks through pair/connect, MTU 517, subscribe RX (indicate) + status (notify), session activation write (01000000), protobuf writes to TX, and length_delimited polling.
• Calls out the two gotchas: never send the USB-only start_rpc_session string over BLE, and the official Flipper app must be disconnected (single BLE client).

^{Written for commit 69a1fb9. Summary will update on new commits.}

[qodo-code-review]

ⓘ Qodo reviews are paused because the subscription is no longer active. Ask your workspace admin to reactivate the subscription to resume reviews. Manage billing