swaits
e2ac01f0cb
CI / Test (all-features) (push) Canceled after 0s
CI / Test (default) (push) Canceled after 0s
CI / Test (no-default-features) (push) Canceled after 0s
CI / Clippy (all-features) (push) Canceled after 0s
CI / Clippy (default) (push) Canceled after 0s
CI / Clippy (no-default-features) (push) Canceled after 0s
CI / Format (push) Canceled after 0s
CI / Doc (push) Canceled after 0s
CI / Cargo Deny (push) Canceled after 0s
CI / Miri (push) Canceled after 0s
CI / Fuzz (60s per target) (push) Canceled after 0s
CI / Mutants (default) (push) Canceled after 0s
CI / Mutants (no-default-features) (push) Canceled after 0s
Rewrites remaining github.com / git.sr.ht references to git.swaits.com, translating GitHub URL shapes to Gitea's (/blob/<ref>/ -> /src/branch/<ref>/, /tree/<tag> -> /src/tag/<tag>, /actions/workflows/X -> /actions?workflow=X, /edit/ -> /_edit/). Left pointing at GitHub on purpose: pull-request links (PRs were not migrated) and GitHub-only surfaces Gitea lacks (security advisories, discussions).
69 lines
2.6 KiB
Markdown
69 lines
2.6 KiB
Markdown
# donglora-protocol
|
|
|
|
[](https://git.swaits.com/donglora/protocol-rs/actions?workflow=ci.yml)
|
|
[](https://crates.io/crates/donglora-protocol)
|
|
[](https://docs.rs/donglora-protocol)
|
|
|
|
Wire protocol types and COBS framing for [DongLoRa], shared between the
|
|
firmware and host crates (`client-rs`, `mux-rs`, `bridge`). `no_std`,
|
|
zero-alloc, fixed-width little-endian. See [`PROTOCOL.md`][protocol-md]
|
|
in this repo for the normative DongLoRa Protocol v2 specification.
|
|
|
|
[DongLoRa]: https://git.swaits.com/donglora
|
|
[protocol-md]: https://git.swaits.com/donglora/protocol-rs/src/branch/main/PROTOCOL.md
|
|
|
|
## Install
|
|
|
|
```toml
|
|
# Embedded / firmware (defmt::Format derives on by default):
|
|
donglora-protocol = "1"
|
|
|
|
# Host (no defmt):
|
|
donglora-protocol = { version = "1", default-features = false }
|
|
```
|
|
|
|
## Layout
|
|
|
|
- `src/frame.rs`: `FrameDecoder` (streaming COBS + CRC decoder) and
|
|
`encode_frame(type_id, tag, payload, out)`.
|
|
- `src/commands.rs`: host-to-device `Command` enum, `type_id`
|
|
constants, and `TxFlags`.
|
|
- `src/events.rs`: device-to-host `DeviceMessage` (OK / ERR / RX /
|
|
TX_DONE), with the `OkPayload`, `SetConfigResult`, `RxPayload`,
|
|
`RxOrigin`, and `TxDonePayload` sub-shapes.
|
|
- `src/modulation.rs`: `Modulation` enum (LoRa, FSK/GFSK, LR-FHSS,
|
|
FLRC) and their typed parameter structs.
|
|
- `src/info.rs`: `GET_INFO` response payload + capability bitmap
|
|
helpers.
|
|
- `src/errors.rs`: wire-level `ErrorCode` enum.
|
|
- `src/chip_id.rs`: `RadioChipId` enum.
|
|
- `src/crc.rs`: CRC-16/CCITT-FALSE helper.
|
|
|
|
## Features
|
|
|
|
| Feature | Default | What it does |
|
|
|---------|---------|--------------|
|
|
| `defmt` | yes | Derive `defmt::Format` on public enums. |
|
|
| `std` | no | Enable `Debug`-based niceties for host-side fuzz / proptest. |
|
|
|
|
## Testing
|
|
|
|
The crate ships its own quality gate via `just test`:
|
|
|
|
| Gate | What runs |
|
|
|------|-----------|
|
|
| `test-unit` | nextest across all feature permutations + doc tests |
|
|
| `test-clippy` | `-D warnings` across all feature permutations |
|
|
| `test-fmt` | `cargo fmt -- --check` |
|
|
| `test-doc` | `cargo doc --no-deps --all-features` |
|
|
| `test-deny` | `cargo deny check` |
|
|
| `test-fuzz` | 60 s on each of 5 cargo-fuzz targets (nightly) |
|
|
| `test-miri` | miri on lib + vector tests, both feature shapes (nightly) |
|
|
| `test-mutants` | cargo-mutants under both feature configurations |
|
|
|
|
The proptest suite alone exercises ~1.13M test cases per run.
|
|
|
|
## License
|
|
|
|
MIT — see [`LICENSE`](LICENSE).
|