Crate donglora_protocol 

DongLoRa Protocol v2 — wire types, framing, and codecs.

This crate is the normative Rust implementation of the protocol defined in PROTOCOL.md. It is no_std and alloc-free: every container is fixed-capacity (heapless::Vec) and every fallible operation returns a typed error — no panics, no unwraps, no unsafe.

Layout

• frame — wire-level COBS + CRC framing. encode_frame turns a (type_id, tag, payload) tuple into a complete wire-ready byte slice; FrameDecoder accumulates inbound bytes and emits FrameResult values as frames arrive.
• commands — host-to-device command enum and type_id constants.
• events — device-to-host message enum (OK / ERR / RX / TX_DONE) and its sub-shapes.
• modulation — per-modulation parameter structs for SET_CONFIG (LoRa, FSK/GFSK, LR-FHSS, FLRC).
• info — GET_INFO response payload, including capability bits.
• errors — wire-level error codes (ErrorCode).
• chip_id — RadioChipId enum.
• crc — CRC-16/CCITT-FALSE implementation.

Typical encode

use donglora_protocol::{encode_frame, Command, commands::TYPE_PING, MAX_WIRE_FRAME};

let cmd = Command::Ping;
let mut payload_buf = [0u8; 4];
let payload_len = cmd.encode_payload(&mut payload_buf).unwrap();

let mut wire = [0u8; MAX_WIRE_FRAME];
let wire_len = encode_frame(cmd.type_id(), 1, &payload_buf[..payload_len], &mut wire).unwrap();
// wire[..wire_len] is ready to transmit.

Typical decode

use donglora_protocol::{Command, FrameDecoder, FrameResult};

let mut decoder = FrameDecoder::new();
let incoming_bytes: &[u8] = &[];
decoder.feed(incoming_bytes, |res| match res {
    FrameResult::Ok { type_id, tag, payload } => {
        match Command::parse(type_id, payload) {
            Ok(cmd) => { /* dispatch cmd with tag */ }
            Err(_e) => { /* respond ERR(EUNKNOWN_CMD) with echoed tag */ }
        }
    }
    FrameResult::Err(_e) => { /* emit async ERR(EFRAME) */ }
});

Re-exports

pub use chip_id::RadioChipId;

pub use commands::Command;

pub use commands::TxFlags;

pub use errors::ErrorCode;

pub use events::DeviceMessage;

pub use events::OkPayload;

pub use events::Owner;

pub use events::RxOrigin;

pub use events::RxPayload;

pub use events::SetConfigResult;

pub use events::SetConfigResultCode;

pub use events::TxDonePayload;

pub use events::TxResult;

pub use frame::FrameDecoder;

pub use frame::FrameResult;

pub use frame::encode_frame;

pub use info::Info;

pub use info::cap;

pub use modulation::FlrcBitrate;

pub use modulation::FlrcBt;

pub use modulation::FlrcCodingRate;

pub use modulation::FlrcConfig;

pub use modulation::FlrcPreambleLen;

pub use modulation::FskConfig;

pub use modulation::LoRaBandwidth;

pub use modulation::LoRaCodingRate;

pub use modulation::LoRaConfig;

pub use modulation::LoRaHeaderMode;

pub use modulation::LrFhssBandwidth;

pub use modulation::LrFhssCodingRate;

pub use modulation::LrFhssConfig;

pub use modulation::LrFhssGrid;

pub use modulation::Modulation;

pub use modulation::ModulationId;

Modules

chip_id

Radio chip identifier enum from PROTOCOL.md §8.

commands

Host-to-device commands (PROTOCOL.md §6).

crc

CRC-16/CCITT-FALSE — the wire-level integrity check used by DongLoRa Protocol.

errors

Error codes carried in ERR frames (PROTOCOL.md §7).

events

Device-to-host messages (PROTOCOL.md §6.7–6.10).

frame

DongLoRa Protocol frame format and streaming decoder (PROTOCOL.md §2).

info

GET_INFO response payload (PROTOCOL.md §6.2).

modulation

Per-modulation parameter structs for SET_CONFIG (PROTOCOL.md §10).

Enums

CommandEncodeError

Errors from encoding a Command payload.

CommandParseError

Errors from parsing a Command payload.

DeviceMessageEncodeError

Errors from encoding a device-message payload.

DeviceMessageParseError

Errors from parsing a device-message payload.

FrameDecodeError

Errors returned from the frame decoder.

FrameEncodeError

Errors returned from encode_frame.

InfoParseError

Errors from Info encode/decode.

ModulationEncodeError

Errors from modulation param encoding.

ModulationParseError

Errors from modulation param parsing.

Constants

FRAME_HEADER_SIZE

Byte count of the pre-CRC, pre-COBS frame header: type(1) + tag(2).

FRAME_TRAILER_SIZE

Byte count of the frame trailer (CRC16).

MAX_COBS_OVERHEAD

COBS encoding overhead upper bound: ceil(n/254) + 1 bytes added around a run of n bytes. For MAX_PRE_COBS_FRAME = 280 this is 3.

MAX_MCU_UID_LEN

Maximum GET_INFO.mcu_uid length (PROTOCOL.md §6.2).

MAX_OK_PAYLOAD

Maximum OK payload size across all shapes. Info is the worst case: GET_INFO’s 37-byte fixed prefix plus both maximum UIDs (32 + 16).

MAX_OTA_PAYLOAD

Maximum over-the-air packet payload (bytes). The spec allows this to be chip-dependent via GET_INFO.max_payload_bytes; 255 is the ceiling for all currently-supported Semtech silicon.

MAX_PAYLOAD_FIELD

Maximum payload-field size in any DongLoRa Protocol frame. This is the OTA limit plus the 20-byte RX metadata prefix: type + tag + this + crc gives the overall frame budget.

MAX_PRE_COBS_FRAME

Maximum pre-COBS frame size: header + max payload + trailer.

MAX_RADIO_UID_LEN

Maximum GET_INFO.radio_uid length (PROTOCOL.md §6.2).

MAX_SETCONFIG_OK_PAYLOAD

Maximum OK payload size for SET_CONFIG: result(1) + owner(1) + modulation_id(1) + max params(24 for FSK with 8-byte sync word).

MAX_SYNC_WORD_LEN

Maximum FSK/GFSK sync-word length (PROTOCOL.md §10.2).

MAX_WIRE_FRAME

Maximum on-wire frame size: pre-COBS size + COBS overhead + 1 for the trailing 0x00 sentinel. Buffer sizes of this value (or more) guarantee no encode-side overflow across any valid frame.