BLEA

<!-- mcp-name: io.github.Nitmi/blea -->

BLEA — Bluetooth Low Energy Automation — is a universal Agent Plugin for safe, deterministic BLE work. It gives AI agents a portable Skill, a machine-readable CLI, a local MCP server, guarded automation, and offline evidence capture, diff, and replay.

The project is designed for the BLE work agents repeatedly need: checking OS Bluetooth access, finding the right nearby device, discovering GATT services, preserving and comparing raw byte evidence, reading and subscribing before changing state, and making writes only after explicit authorization.

| Surface | Role | | --- | --- | | Agent Plugin 1.0.0 | Packages the portable identity, Skill, and MCP declaration. | | Agent Skill | Teaches agents the BLE workflow, safety boundaries, and recovery rules. | | CLI | Emits deterministic JSON/JSONL for scripts, terminals, and any agent with shell access. | | MCP | Exposes the same runtime as local, structured tools with managed BLE sessions. |

The ble executable is the shared runtime. Regular subcommands use the CLI surface; ble mcp starts the stdio MCP server. The MCP protocol is therefore a first-class interface, not a second tool hidden inside an unrelated CLI product.

Install

BLEA requires Python 3.10 or newer. Bluetooth access is provided by the operating system through Bleak.

Quick install with an Agent prompt

Give this prompt to an Agent with shell access:

Read https://github.com/Nitmi/blea and follow its README to install BLEA for me.

For manual installation, use the detailed paths below.

Install the latest published Python runtime from PyPI:

uv tool install blea
ble --help

For Codex, install the public Git marketplace package after the runtime:

codex plugin marketplace add Nitmi/blea
codex plugin add blea@blea

To install only the portable Agent Skill with the Skills CLI:

npx skills add Nitmi/blea --skill ble

For OpenClaw, install the same portable Skill from its public ClawHub listing:

openclaw skills install @nitmi/blea
# Or use the registry CLI directly:
clawhub install @nitmi/blea

The Skill teaches the workflow and safety policy; it does not install the Python runtime. Install blea from PyPI as shown above before asking an agent to access live Bluetooth hardware or start the local MCP server. The source Skill is skills/ble/SKILL.md, and the public ClawHub release is @nitmi/blea.

Start a new Agent task after installation. The marketplace package supplies the BLE Skill and MCP declaration; it does not install the Python runtime or operating-system Bluetooth permissions. See docs/installation.md for the release-tag, legacy 0.6.0 bridge, and update procedure.

From a checkout, install the command runtime directly from the working tree:

uv tool install --editable .
ble --version

For repository development:

uv sync --extra dev
uv run ble --help

Standalone Windows release

Starting with 0.6.5, each release includes blea-<version>-windows-x86_64.zip with a single-file ble.exe and a manifest binding its SHA-256, version, target, and source commit. Python is not required at runtime. The tag workflow builds twice on one GitHub-hosted Windows runner, rejects unequal ZIP hashes, runs ble --version and an adapter-free evidence replay, and creates GitHub artifact provenance. It does not run doctor, scan, or access Bluetooth hardware.

Verify the archive before use:

gh attestation verify blea-0.6.5-windows-x86_64.zip `
  --repo Nitmi/blea `
  --source-ref refs/tags/v0.6.5 `
  --signer-workflow Nitmi/blea/.github/workflows/binary-release.yml `
  --deny-self-hosted-runners

Attestation proves repository build provenance; it is not Windows Authenticode signing and does not prove a Bluetooth adapter, peripheral, or firmware identity.

The Python runtime and Agent Plugin are two related installation units: PyPI installs the ble executable, while an Agent Plugins 1.0.0 client loads this repository directory to discover plugin.json, mcp.json, and skills/ble. Install the runtime first so the plugin's local stdio MCP server can find ble on PATH. See docs/installation.md for source, plugin, update, permissions, and verification paths.

CLI

ble doctor --json
ble scan --timeout 8 --json
ble inspect --device "id:AA:BB:CC:DD:EE:FF" --json
ble probe --device "id:AA:BB:CC:DD:EE:FF" --max-reads 16 --json
ble probe --device "id:AA:BB:CC:DD:EE:FF" --max-reads 16 --read-offset 16 --json
ble read --device "id:AA:BB:CC:DD:EE:FF" --characteristic 2a19 --json
ble subscribe --device "id:AA:BB:CC:DD:EE:FF" --characteristic 2a37 --duration 15 --jsonl
ble observe --device "id:AA:BB:CC:DD:EE:FF" --duration 10 --jsonl
ble diff before.blea.jsonl after.blea.jsonl --json
ble replay capture.blea.jsonl inspect --json
ble replay capture.blea.jsonl read --characteristic 2a19 --json
ble exchange \
  --device "id:AA:BB:CC:DD:EE:FF" \
  --write-characteristic 12345678-1234-1234-1234-1234567890ab \
  --notify-characteristic 87654321-4321-4321-4321-ba0987654321 \
  --text ping --duration 5 --allow-write \
  --confirm-device "AA:BB:CC:DD:EE:FF" --jsonl

Device names are accepted only when exactly one observed device has that name. Prefer the platform identifier returned by scan; on macOS this is normally a UUID rather than a MAC address.

Every binary value includes length, hex, base64, and replacement-safe UTF-8 representations. JSON errors use stable reasons and exit codes suitable for agent recovery.

probe is paginated. Follow next_read_offset until it is null. Page counts and characteristic-level failures live under read_page; ok=true means the page executed, while read_page.has_failures tells you whether any characteristic failed. Every result includes a small profile_summary. The CLI includes the full GATT profile by default and supports --no-include-profile; the MCP tool omits it by default to keep repeated pages compact.

Connection commands report timeout_scope=per_backend_operation. Their timeout applies separately to discovery, connection, and each GATT operation, rather than bounding the total command time. GATT entries include uuid_namespace. BLEA reports library descriptions only for canonical Bluetooth Base UUIDs, avoiding false standard names inferred from the leading bytes of custom 128-bit UUIDs.

observe discovers notify/indicate characteristics and watches them over one connection for a bounded duration. Omit --characteristic to select all event-capable traits, or repeat it for explicit selection. The result separates subscription failures, cleanup failures, and notification events; a quiet window is evidence only for that sample window.

Save a complete read-only evidence package after diagnosis:

ble capture \
  --device "id:AA:BB:CC:DD:EE:FF" \
  --output capture.blea.jsonl \
  --max-reads 128 \
  --observe-duration 10 \
  --redact-identifiers \
  --json

capture records the advertisement, normalized GATT profile, each readable-characteristic result, bounded notifications, operation errors, and a validated final summary. It performs no writes, pairing, or configuration changes and replaces the destination only after an atomic close. The JSONL file is the authoritative artifact; the command's JSON result is a compact summary. The Evidence Format v1 contract and deterministic validator live in docs/evidence-format-v1.md.

Compare two complete evidence packages without a Bluetooth adapter or device:

ble diff before.blea.jsonl after.blea.jsonl --json
ble diff before.blea.jsonl after.blea.jsonl --fail-on-change --json

diff validates both Evidence Format v1 inputs, projects them into stable BLE semantics, and emits sorted JSON Pointer changes. It ignores capture IDs, timestamps, runtime metadata, sampling duration, and RSSI movement within 5 dBm by default. Use --strict-rssi for exact RSSI comparison. Device identifiers must match unless an intentional cross-device comparison uses --allow-different-devices. Binary payloads are atomic changes, so one changed value does not produce separate Hex, Base64, and UTF-8 noise. A normal difference exits successfully; --fail-on-change returns code 3 after printing the complete result for CI. The contract lives in docs/diff-format-v1.md.

Replay a complete evidence package without a Bluetooth adapter or physical device:

ble replay capture.blea.jsonl inspect --json
ble replay capture.blea.jsonl probe --max-reads 32 --json
ble replay capture.blea.jsonl read --characteristic 2a19 --json
ble replay capture.blea.jsonl observe --duration 10 --jsonl
ble replay capture.blea.jsonl run examples/replay-read-only.yaml --json

Replay reconstructs advertisements, GATT, reads, captured failures, subscription outcomes, and the notification timeline through the same read-only backend interfaces used for live devices. The default --speed 0 mode is immediate and deterministic; place a positive --speed before the operation to preserve recorded notification gaps at that multiplier. Missing observations return the stable replay_miss reason instead of an invented value or success. Replay never accesses a real adapter and never sends or simulates writes or exchanges. The full contract lives in docs/replay-format-v1.md.

Guarded writes

A write requires both --allow-write and an exact confirmation of the resolved identifier:

ble write \
  --device "id:AA:BB:CC:DD:EE:FF" \
  --characteristic 12345678-1234-1234-1234-1234567890ab \
  --hex 01 \
  --allow-write \
  --confirm-device "AA:BB:CC:DD:EE:FF" \
  --read-back \
  --json

YAML writes and exchanges add two more guards: the workflow must enable writes and each state-changing step must declare dangerous: true plus successful prerequisite steps. The policy must also carry an exact confirm_device identifier. See examples/guarded-write.yaml and examples/esp32-burst-exchange.yaml.

For protocols where a write triggers notifications, use exchange. It enables the notification subscription before performing the guarded write, then collects events for a bounded duration. The write and notify characteristics may be the same or different. This avoids the race created by launching standalone session subscribe and write operations concurrently.

For repeatable checks, an exchange step can assert the exact notification count, UTF-8 or Hex content, the final notification, and subscription cleanup. Run a guarded YAML workflow with the independent invocation gate:

ble run examples/esp32-burst-exchange.yaml --allow-write --json

Replace the example's device identifier and confirmation with the exact value returned by a fresh scan before running it.

MCP and Agent Plugin

Start the local stdio server directly:

ble mcp

The MCP surface includes one-shot tools, the offline ble_diff comparator, the offline ble_replay runner, and stateful session tools. Sessions let an agent connect once,