pamoja_radios/

sx1302.rs

//! Semtech SX1302 and SX1303 concentrators.
//!
//! A transceiver listens to one channel at a time. A concentrator listens to eight at once,
//! across every spreading factor, which is what separates a gateway from a node. That is also
//! why it is driven differently: the SX126x and SX127x take commands, while this chip is a
//! map of registers, most of them a few bits inside a byte shared with their neighbors.
//!
//! Nothing works until two microcontrollers inside the chip are given firmware. The gain
//! control one sets the front end, the arbiter shares the radios between the receivers, and
//! both come up empty, so a concentrator that has been powered but not loaded reports a
//! healthy version register and hears nothing at all.
//!
//! This module carries that as data:
//!
//! - [`spi`] - the transfers the chip answers, byte for byte, and how a long write is split.
//! - [`register`] - where the blocks are and which bits inside a byte each register owns.
//! - [`chip`] - the version that says a board is answering, and the part number that says
//!   whether it is an SX1302 or an SX1303.
//! - [`channel`] - the frequencies the receivers listen on, the spreading factors they
//!   look for, and the order all of that is set in.
//! - [`firmware`] - the order the two microcontrollers are loaded in, and what to check
//!   afterwards.
//! - [`mcu`] - configuring those two microcontrollers once they are loaded, which is
//!   the other half of bringing one up.
//! - [`rx`] - the packets the receive buffer holds, and what the receiver made of each.
//! - [`tx`] - where a payload is written, how far ahead of its window a send starts, and
//!   the three ways a transmission is triggered.
//! - [`lbt`] - the commands for the SX1261 beside the concentrator, which listens to a
//!   channel before the gateway is allowed to talk on it.
//! - [`sx1261`] - bringing that radio up, which has to happen before those commands
//!   mean anything to it.
//! - [`sx1250`] - the front ends the concentrator listens through, which are what a
//!   carrier is tuned to, and the order one is brought up in.
//! - [`timestamp`] - the counter packets are stamped against and receive windows are
//!   measured from, and how it is widened past a rollover.
//! - [`bridge`] - the messages that carry all of the above through the microcontroller on
//!   a USB card, which does the SPI on the host's behalf.
//!
//! With the `embedded-hal` feature, the [`Sx1302`] driver walks all of that against a real
//! bus: it resets the board, reads the version, resets the front ends, and gives each
//! microcontroller its firmware.
//!
//! None of it opens a bus, so a frame can be checked against the reference implementation,
//! or against a capture from a working gateway, with no hardware present.
//!
//! The register map, the transfer framing, and the load sequence follow Semtech's
//! `sx1302_hal`, which is BSD 3-Clause. The notice is on the
//! [notices page](https://pamoja.molex.cloud/docs/about/notices.html).
//!
//! # Examples
//!
//! Asking a board what it is, without a bus in sight.
//!
//! ```
//! use pamoja_radios::sx1302::{chip, register, spi};
//!
//! // The version register is read like any other: the target, the register's address
//! // most significant byte first, a dummy byte, and the byte the chip answers in.
//! let version = register::COMMON_VERSION.address;
//! let [high, low] = version.to_be_bytes();
//! let asked = spi::read(spi::TARGET_CONCENTRATOR, version);
//! assert_eq!(asked, [spi::TARGET_CONCENTRATOR, high, low, 0, 0]);
//!
//! // A concentrator that is powered and wired the right way round answers with one value.
//! assert!(chip::answers(0x10));
//! assert!(!chip::answers(0x00));
//!
//! // The part number takes two transfers, because it lives in one-time programmable memory.
//! let [select, read] = chip::identify();
//! assert_eq!(select, chip::Step::Write(register::OTP_BYTE_ADDR, 0xd0));
//! assert_eq!(read, chip::Step::Read(register::OTP_RD_DATA));
//!
//! assert_eq!(chip::Model::of(0x03), chip::Model::Sx1303);
//! ```

pub mod bridge;
pub mod channel;
pub mod chip;
pub mod firmware;
pub mod lbt;
pub mod mcu;
pub mod register;
pub mod rx;
pub mod spi;
pub mod sx1250;
pub mod sx1261;
pub mod timestamp;
pub mod tx;
#[cfg(feature = "std")]
pub mod usb;

#[cfg(feature = "embedded-hal")]
mod driver;
#[cfg(feature = "embedded-hal")]
mod listener;

#[cfg(feature = "embedded-hal")]
pub use driver::{
    ConcentratorError, Sx1302, ABORT_POLLS, RADIO_CALIBRATE_US, RADIO_RESET_HOLD_US,
    RADIO_RESET_SETTLE_US, RESET_HOLD_US,
};
#[cfg(feature = "embedded-hal")]
pub use listener::{ListenerError, Sx1261, COMMAND_WAIT_US, LISTENER_RESET_US};