From 85420dc6738eb9f7e39e1bcab7abbad344445633 Mon Sep 17 00:00:00 2001 From: Stephen Waits Date: Wed, 22 Apr 2026 09:18:36 -0600 Subject: [PATCH] chore: release 1.0.0 --- CHANGELOG.md | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++ Cargo.toml | 2 +- README.md | 29 +++++++++++++++++++--------- 3 files changed, 75 insertions(+), 10 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 96d1a74..38c6df4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,60 @@ All notable changes to this crate are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres to [Semantic Versioning](https://semver.org/). +## 1.0.0 — 2026-04-22 + +The 1.0 wire-format rewrite. Every message shape, tag-correlation +rule, and field layout is re-specified in the new normative +`PROTOCOL.md` and is incompatible with the 0.1.x line. + +### Breaking + +- **DongLoRa Protocol v2 wire format.** Every `type_id`, tag-correlation + rule, and field layout is redefined in `PROTOCOL.md` §2 through §16. + No byte compatibility with 0.1.x. +- **Module split.** The single-file `lib.rs` is replaced with dedicated + modules: `frame`, `commands`, `events`, `errors`, `modulation`, + `info`, `crc`, `chip_id`. Re-exports at the crate root preserve the + short-form imports (`Command`, `ErrorCode`, etc.), but full paths to + the old `framing` module and `Response` / `RadioConfig` / `Bandwidth` + types no longer resolve. +- **Framing replaced.** `src/framing.rs` is gone. The new + `frame::FrameDecoder` streams inbound bytes and yields + `FrameResult::Ok { type_id, tag, payload }` on each COBS-delimited, + CRC-verified frame. Encoding moves to `encode_frame(type_id, tag, + payload, out)`. +- **`Modulation` replaces `RadioConfig` + `Bandwidth`.** New enum + covering LoRa, FSK/GFSK, LR-FHSS, and FLRC, each with its own typed + parameter struct. +- **New response shapes.** `OkPayload`, `SetConfigResult`, + `TxDonePayload`, `RxPayload`, `RxOrigin`, and `TxFlags` model the + richer response surface required by v2. + +### Added + +- `PROTOCOL.md`: the normative specification of DongLoRa Protocol v2, + including wire examples, error taxonomy, state machine, and + multi-client semantics (§13). +- `RadioChipId` enum for `GET_INFO` chip identification. +- CRC-16/CCITT-FALSE helper (`crc`) exposed for integrity checks on + arbitrary payload slices. +- `cap` bitflag helpers on the `Info` struct for decoding capability + bitmaps. + +### Changed + +- Fuzz corpus rewritten: `decoder_feed`, `frame_roundtrip`, + `lora_config_roundtrip`, `parse_command`, `parse_device_message` + replace the 0.1 `cobs_*` and `command_roundtrip` targets. +- Proptest suite and mutation-killer set expanded to cover the new + wire shape. +- Canonical-byte vectors rewritten against `PROTOCOL.md` §C. + +### CI + +- Workflow now runs on pushes to `dev` in addition to `main`. +- Fuzz jobs pinned to `x86_64-unknown-linux-gnu` for reproducibility. + ## 0.1.0 — 2026-04-13 Initial release. The DongLoRa wire-protocol types and COBS framing, diff --git a/Cargo.toml b/Cargo.toml index 6c8ac6b..25ae572 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "donglora-protocol" -version = "0.1.0" +version = "1.0.0" edition = "2024" rust-version = "1.85" authors = ["Stephen Waits "] diff --git a/README.md b/README.md index ae1db6e..4e52027 100644 --- a/README.md +++ b/README.md @@ -6,27 +6,38 @@ 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 the firmware repo's -[`PROTOCOL.md`][protocol-md] for the full spec. +zero-alloc, fixed-width little-endian. See [`PROTOCOL.md`][protocol-md] +in this repo for the normative DongLoRa Protocol v2 specification. [DongLoRa]: https://github.com/donglora -[protocol-md]: https://github.com/donglora/firmware/blob/main/PROTOCOL.md +[protocol-md]: https://github.com/donglora/protocol/blob/main/PROTOCOL.md ## Install ```toml # Embedded / firmware (defmt::Format derives on by default): -donglora-protocol = "0.1" +donglora-protocol = "1" # Host (no defmt): -donglora-protocol = { version = "0.1", default-features = false } +donglora-protocol = { version = "1", default-features = false } ``` ## Layout -- `src/lib.rs` — `Command`, `Response`, `RadioConfig`, `Bandwidth`, - `ErrorCode` plus constants and validation/resolve helpers. -- `src/framing.rs` — `CobsDecoder` (streaming) and `cobs_encode_response`. +- `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 @@ -46,7 +57,7 @@ The crate ships its own quality gate via `just test`: | `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 7 cargo-fuzz targets (nightly) | +| `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 |