pamoja_lorawan/

lib.rs

#![cfg_attr(not(test), no_std)]

//! LoRaWAN 1.0.x MAC framing for the pamoja SDK.
//!
//! LoRaWAN is how a low-power node reaches a network kilometers away over a license-free
//! radio, which is why it is the SDK's first-class answer for rural and remote reach. The
//! [`pamoja-lora`](https://docs.rs/pamoja-lora) crate gives the link budget, the exact
//! time a transmission spends on air; this crate gives the bytes that go in it: the
//! secured LoRaWAN frame.
//!
//! A LoRaWAN frame is not just a payload with an address. The standard wraps every frame
//! in two cryptographic guarantees, because a long-range public-band link is wide open: a
//! message integrity code keyed to the network proves the frame is authentic and intact,
//! and the payload is encrypted to the application so only its owner can read it. This
//! crate builds and verifies exactly that, with no radio and no allocation:
//!
//! - [`Session`] - an activated device's address and session keys. It [encodes](Session::encode_uplink)
//!   an uplink or downlink data frame, encrypting the payload and appending the MIC, and
//!   [decodes](Session::decode) one received, verifying the MIC before decrypting.
//! - [`Uplink`] and [`Downlink`] - the data frame to send, built up from the fields a
//!   sender sets (confirmed, adaptive data rate, acknowledgment, frame options).
//! - [`RxData`] - a decoded frame: its header fields and its recovered payload.
//! - [`Device`] - the root credentials for over-the-air activation: it builds the
//!   join-request a device broadcasts and turns the network's join-accept into a ready
//!   [`Session`], deriving the session keys the spec prescribes.
//! - [`JoinRequest`] and [`JoinGrant`] - the other half of that exchange, so a deployment
//!   can run its own network instead of joining someone else's: verify the request a
//!   device sent, then grant it an address and sign the reply. Both sides derive the same
//!   session keys from the same nonces, with no key ever on the air.
//! - [`FrameHeader`] - what a frame says about itself before any key is involved: its
//!   message type, the device address, and the counter. A receiver holding many sessions
//!   reads this first to find the one a frame belongs to, then decodes.
//! - [`CfList`] - the channel list a join accept may end with, in either of the two forms the
//!   regional parameters define.
//! - [`defaults`] - the receive delays, frame counter gap and ADR counts every region
//!   shares, and [`adr`] and [`mac`] for keeping a device reachable and configuring it.
//! - [`device`] - a Class A end device with no radio: it joins, picks a channel and data rate
//!   for each uplink, says when to listen, reads what the network sends back and does what
//!   its MAC commands ask, following the [`Version`] of the link layer it is given.
//!
//! The cryptography is the LoRaWAN construction over AES-128: an AES-CMAC MIC and an
//! AES keystream for the payload, with the device address and frame counter folded into
//! both so a frame cannot be lifted out of its place in the stream. The radio itself is
//! `pamoja-radios`' part, so everything here runs the same on a microcontroller, on a
//! gateway, and in a test with no hardware at all.
//!
//! # Examples
//!
//! ```
//! use pamoja_lorawan::{Session, Uplink};
//!
//! // A node activated with a device address and its two session keys.
//! let session = Session::new(0x2601_1BDA, [0x2B; 16], [0x99; 16]);
//!
//! // Encode a confirmed uplink reading; the payload is encrypted and the MIC appended.
//! let frame = session
//!     .encode_uplink(&Uplink::new(42, 1, b"temp=4.8").confirmed())
//!     .unwrap();
//!
//! // The network, holding the same session, verifies and decrypts it.
//! let rx = session.decode(frame.as_bytes(), 42).unwrap();
//! assert!(rx.confirmed());
//! assert_eq!(rx.payload(), b"temp=4.8");
//! ```

pub mod adr;
mod cflist;
mod crypto;
pub mod defaults;
pub mod device;
mod error;
mod frame;
mod header;
mod hex;
mod join;
pub mod mac;
mod network;
pub mod packages;
pub mod relay;
mod session;
mod version;

pub use adr::Backoff;
pub use cflist::{CfList, CfListKind, CFLIST_FREQUENCIES, CFLIST_LEN, CFLIST_MASK_GROUPS};
pub use error::LorawanError;
pub use frame::{Direction, PhyPayload, MAX_FRAME, MAX_PAYLOAD};
pub use header::{FrameHeader, MessageType};
pub use hex::parse_hex;
pub use join::{Device, JoinAccept};
pub use mac::{MacCommand, MacCommands};
pub use network::{JoinGrant, JoinRequest};
pub use session::{Downlink, RxData, Session, Uplink};
pub use version::Version;