| name | peat-btle |
| description | Per-repo skill for the Peat BLE mesh transport — multi-platform Rust crate (Linux/macOS/iOS/Android/ESP32) plus an Android AAR via UniFFI. |
| when_to_use | Editing files under peat-btle/, reviewing peat-btle PRs, debugging BLE advertise/scan/GATT/peripheral issues, working on M5Stack/ESP32 firmware integration, or working on ADR slices that touch the BLE transport. |
| verifies_with | cargo fmt --check, cargo clippy -- -D warnings, cargo test (host platform), plus per-platform feature builds for any flag whose paths the change touches. |
peat-btle SKILL
peat-btle is the Bluetooth Low Energy transport for the Peat Protocol. It implements a Transport-shaped surface plus the wire codec primitives (typed BLE structs, *_to_* JSON projections, 0xB6 framing) that other peat-* code can plug into for BLE-based peer connectivity. peat-btle has zero peat-mesh dep as of 0.4.0 (ADR-059 Amendment 4 Slice 4.b deleted the back-edge); peat-mesh's bluetooth feature wraps these primitives with its own Translator trait impl in peat-mesh's tree. The crate is multi-platform: Linux uses bluer (BlueZ), macOS/iOS use objc2-core-bluetooth, Android uses UniFFI bindings consumed by the ATAK plugin, ESP32 uses NimBLE. The translator-codec feature is what consumers (peat-mesh-using hosts and standalone embedded callers like M5Stack Core2 / Bitchat-style sensors) enable to get the wire codec.
When this skill applies
- Editing any file under
src/ (transport, peer, platform, codec)
- Editing
android/ (Gradle/Kotlin AAR build)
- Editing
uniffi-bindgen/ or anything that affects generated bindings
- Touching the feature-flag matrix in
Cargo.toml
- Working on M5Stack / ESP32 firmware that pins this crate
- Working on an active slice of any local ADR (
docs/adr/) or any ecosystem ADR that lands here. Recent ecosystem slices touching this repo: ADR-032 (pluggable transport), ADR-039 (BLE refinements), ADR-049 (security primitives), ADR-059 (translator / cross-transport bridging) — these live in peat/docs/adr/ (sibling repo). Local ADRs cover peat-btle's internal architecture (trust model, provisioning, document registry).
Scope
In scope:
- BLE transport implementations and the platform adapter layer (
src/platform/)
- Peer state, advertisement, scan, GATT
- BleTranslator wire codec (
translator-codec feature) — the typed BLE structs, JSON projection helpers, and 0xB6 framing. peat-mesh's Translator-trait integration on top of these primitives lives in peat-mesh's tree (Slice 4.a), not here.
- UniFFI surface (
uniffi feature) and the Android AAR build
- Feature-flag wiring in
Cargo.toml
Out of scope (route elsewhere):
- Mesh routing / topology / discovery / sync →
peat-mesh/SKILL.md
- ATAK plugin lifecycle / Android UI →
peat-atak-plugin/SKILL.md
- Top-level shared types/traits — consider whether the change belongs in
peat/peat-protocol or peat/peat-transport (workspace subcrates of the peat repo) instead
Workflow
- Orient. Read
peat/SKILL.md (ecosystem) if accessible. Read this file. Read CONTRIBUTING.md for the per-platform build matrix. git status, git log -10.
- Locate the spec. Confirm the task has a GitHub issue with Context / Scope / Acceptance / Constraints / Dependencies. If not, stop and ask the user.
- Plan. Produce a 1–5 step plan. Cross-check against ecosystem hard invariants (transport agnosticism, FFI direction, dependency direction) and the scope guards below. If the change is architectural, reference the relevant ecosystem ADR.
- Implement. Branch from
main per the trunk-based convention. Vertical slices, one concern per commit. Match existing module boundaries — keep platform-specific code under src/platform/<os>/ and not in shared code paths.
- Verify. Run every command in the verification checklist below. Capture output.
- Hand off. Open PR against
main referencing the issue. Single concern per PR — squash-merge applies, so the PR title becomes the merge commit subject.
Verification (exit criteria)
A session in this repo is not done until each of these produces evidence:
"Seems right" or "the diff looks correct" is never sufficient.
Anti-rationalization
| Excuse | Rebuttal |
|---|
| "This change is too small to need a test." | If it's worth changing, it's worth one assertion. Add the test. |
| "I'll fix the clippy warning later." | The CI gate is -D warnings. There is no later. Fix it before commit. |
| "I only changed shared code; the per-platform builds will pass." | BLE platform code interacts non-obviously with feature flags and target dependencies. Build each affected platform locally. |
| "I'll regenerate the UniFFI bindings in a follow-up." | Stale bindings break the ATAK plugin's AAR consumption and the Android CI gate. Regenerate and commit in the same PR. |
"I'll bump the version to drop the -rc suffix to clean up." | peat-btle is in an active RC cycle and downstream M5Stack/ESP32 firmware pins specific RCs (see the peat repo's "M5Stack peat-btle dep gate" CI check). Don't bump versions casually. |
| "Cargo.lock churn is noise." | peat-btle commits Cargo.lock because downstream consumers pin against this crate's resolved deps. Lockfile changes ride along with version bumps; don't strip them. |
| "Transport-level retry can live in peat-mesh's adapter — same trait." | peat-btle is the transport adapter for BLE. Retry semantics specific to BLE link characteristics (advertise window, GATT timeouts, paired-vs-unpaired) belong here, not in peat-mesh. |
"Re-introduce the mesh-translator feature so peat-btle can host the Translator impl directly." | Don't. ADR-059 Amendment 4 Slice 4.b deleted that feature precisely to break the peat-mesh ⇄ peat-btle cycle. peat-mesh's tree is the home for Translator impls now. |
Scope guards
- Touch only files the issue/user asked you to touch.
- Do not edit other peat-* repos. Cross-repo work goes in a separate PR in that repo, linked through a tracking issue.
- Keep platform-specific code under
src/platform/<os>/. Shared code must compile on every supported platform feature.
- Do not bleed app-layer logic (mesh sync, document state, broker concerns) into BLE transport — those belong in
peat-mesh or peat-protocol.
- Do not break the Android AAR build silently. If you touch the UniFFI surface, regenerate bindings and run
./gradlew assembleRelease.
- Do not configure git to bypass GPG signing or use
--no-verify to skip pre-commit hooks.
Gotchas
Add an entry each time a session produces output that needed correction. One line per gotcha plus a Why: line.
References (read on demand, not by default)
- Ecosystem invariants:
peat/SKILL.md (sibling repo)
- Build matrix and feature flags:
CONTRIBUTING.md
- Quickstart guide:
peat-btle-quickstart-guide.md
- M5Stack/Samsung integration test plan:
peat-btle-m5stack-samsung-test-plan.md
- Implementation kickstart:
peat-btle-implementation-kickstart.md
- Cross-compilation:
Cross.toml
- Local ADR index:
docs/adr/ — covers peat-btle's internal architecture (trust, provisioning, document registry). Numbering is inconsistent across the existing files (001-, 03-, 04-, ADR-001-, etc.) — match the existing convention if adding new ones, or normalize as a separate cleanup PR.
- Ecosystem ADR index:
peat/docs/adr/ (sibling repo) — ADR-032 (pluggable transport), ADR-039 (BLE refinements), ADR-049 (security primitives), ADR-059 (translator / cross-transport bridging) and others; cited in this repo's Cargo.toml comments and recent commits
- Repo: https://github.com/defenseunicorns/peat-btle
Last updated: 2026-05-05
Maintained by: Kit Plummer, VP Data and Autonomy, Defense Unicorns
