// Per-repo skill for the Peat BLE mesh transport — multi-platform Rust crate (Linux/macOS/iOS/Android/ESP32) plus an Android AAR via UniFFI.
| 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 SKILLpeat-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.
src/ (transport, peer, platform, codec)android/ (Gradle/Kotlin AAR build)uniffi-bindgen/ or anything that affects generated bindingsCargo.tomldocs/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).In scope:
src/platform/)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 feature) and the Android AAR buildCargo.tomlOut of scope (route elsewhere):
peat-mesh/SKILL.mdpeat-atak-plugin/SKILL.mdpeat/peat-protocol or peat/peat-transport (workspace subcrates of the peat repo) insteadpeat/SKILL.md (ecosystem) if accessible. Read this file. Read CONTRIBUTING.md for the per-platform build matrix. git status, git log -10.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.main referencing the issue. Single concern per PR — squash-merge applies, so the PR title becomes the merge commit subject.A session in this repo is not done until each of these produces evidence:
cargo fmt --check exits 0cargo clippy -- -D warnings exits 0cargo test exits 0 on the host platformcargo build --features <flag> for each affected platform feature (linux, macos, ios, android, esp32, windows) — and cargo test --features <flag> where the feature gates test code pathscargo test --features translator-codeccd android && ./gradlew assembleRelease succeeds"Seems right" or "the diff looks correct" is never sufficient.
| 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. |
src/platform/<os>/. Shared code must compile on every supported platform feature.peat-mesh or peat-protocol../gradlew assembleRelease.--no-verify to skip pre-commit hooks.Add an entry each time a session produces output that needed correction. One line per gotcha plus a Why: line.
peat/SKILL.md (sibling repo)CONTRIBUTING.mdpeat-btle-quickstart-guide.mdpeat-btle-m5stack-samsung-test-plan.mdpeat-btle-implementation-kickstart.mdCross.tomldocs/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.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 commitsLast updated: 2026-05-05 Maintained by: Kit Plummer, VP Data and Autonomy, Defense Unicorns