ble

BLEA

Use BLEA for local BLE work. Prefer BLEA MCP tools when available; otherwise run the equivalent ble CLI command with JSON output.

Environment boundary

First determine whether the current Agent host has BLEA MCP tools or the ble runtime and native Bluetooth access. A hosted Agent cannot access the Bluetooth adapter on the user's computer merely because this Skill is installed. In that environment, analyze uploaded .blea.jsonl evidence, explain or prepare commands for a local host, and clearly label them as not executed. Do not claim a scan, connection, read, notification, or write occurred without the corresponding structured result.

When uploaded evidence is available but the BLEA runtime is not, parse the JSONL as structured JSON records, require a final complete summary before treating it as a complete capture, and report only the recorded advertisement, profile, read, notification, error, and cleanup evidence. Do not turn missing records into successful observations. Live operations require a local Agent host, the BLEA Python runtime, operating-system Bluetooth permission, and a supported adapter.

Diagnostic sequence

1. Run ble_doctor or ble doctor --json when adapter availability is unknown.
2. Scan and preserve the returned identifier, names, RSSI, advertised services, and raw advertising evidence.
3. Select by exact identifier. Use an exact name only when one observed device has that name.
4. Inspect the GATT profile before choosing characteristics.
5. For event discovery, use bounded ble_observe/ble observe before writing; omit characteristics to observe all notify/indicate traits from the discovered profile.
6. When probing, continue with next_read_offset until it is null. ok=true means the page ran; it does not mean every characteristic read succeeded. Aggregate read_page.success_count, failure_count, and failure_reasons across pages, and preserve both successful reads and per-characteristic failures.
7. Prefer reads and bounded observation before considering a write. Treat a silent observation window as evidence only for that window, not proof that a characteristic never emits events.
8. After the initial diagnosis, save a portable evidence package with ble_capture or ble capture. Use the exact resolved identifier, choose an explicit .blea.jsonl output path, and set --redact-identifiers when the package will leave the workstation. Capture is read-only: it records advertisements, the GATT profile, bounded readable-characteristic results, bounded notifications, operation errors, and a final integrity summary. It never writes, pairs, or changes configuration. Keep the file as the authoritative artifact and report its path plus summary status to the user.
9. Compare before/after captures offline with ble_diff or ble diff. Keep the default identity guard for normal comparisons and use allow_different_devices only for an intentional cross-device comparison. Treat the 5 dBm RSSI tolerance as noise control; use strict RSSI only when exact signal samples matter. Diff never scans, connects, pairs, subscribes, or writes.
10. Reproduce captured behavior offline with ble_replay or ble replay. Use instant timing for Agent debugging and CI. Treat replay_miss as absent evidence, not device behavior, and do not infer a successful subscription from a notify property alone. Replay never accesses a physical adapter and never sends or simulates writes.
11. When one authorized write is expected to trigger notifications, use ble_exchange or ble_session_exchange. These operations establish the subscription before writing and collect the response atomically; do not run standalone session subscribe and write tools concurrently.
12. Close the exact stateful MCP session once when the task is complete. Use ble_session_list when cleanup is uncertain. Use ble_session_close_all only when a session ID is unknown, an explicit close failed, or leaked state must be recovered; do not call it after a successful close.