lora

no_std Rust driver for LoRa radio modules based on the SX1278 chip. It provides SPI-based control for transmission and reception with configurable operating modes, optional payload compression, and cooperative TX cancellation.

Features

• no_std — Suitable for embedded targets without the standard library.
• SX1278 support — Register-level driver for frequency, modem config, FIFO, and IRQ handling.
• Operating modes — Transmitter, Receiver, Transceiver, Manual, and ReceiverSingle.
• Deep sleep — deep_sleep() and wake_from_deep_sleep() for minimal chip power consumption (~0.2 µA).
• TX/RX — Blocking send() and receive() with configurable timeouts; RSSI and SNR in receive results.
• Compression — Payload compression/decompression (via the tools crate) for smaller over-the-air packets.
• Cooperative cancellation — Optional atomic flag to cancel an ongoing transmission from another task or IRQ.
• DIO0 IRQ — Optional binding of an atomic flag for TX_DONE/RX_DONE to integrate with your GPIO interrupt handler.

Cargo features

Feature	Description
sx1278	Enables the SX1278 controller and public API.
test-support	Enables embedded-hal-mock for unit tests.

Enable at least sx1278 for normal use:

[dependencies]
lora = { version = "0.1", registry = "forgejo", features = ["sx1278"] }

For publishing or depending from a Forgejo registry, add the forgejo registry and the tools dependency as in this crate’s Cargo.toml.

Usage example

use embedded_hal::delay::DelayNs;
use embedded_hal::digital::OutputPin;
use embedded_hal::spi::SpiBus;
use lora::sx1278::{Controller, Mode};

// SPI, NSS, and RST are your embedded_hal implementations (owned by the controller).
let mut controller = Controller::new(spi, nss, rst, &mut delay, Mode::Transceiver)?;
controller.set_frequency(433_000_000, &mut delay); // 433 MHz

// Send a message (blocking until TX_DONE or timeout).
controller.send(&message[..], &mut delay)?;

// Receive into a buffer (blocking until RX_DONE or timeout).
let result = controller.receive(&mut buffer[..], &mut delay)?;
// result.size, result.rssi (dBm), result.snr (dB)

// Put the radio in deep sleep when idle (configuration is retained).
controller.deep_sleep(&mut delay);

// send(), receive(), and handle_dio0_irq() wake the chip automatically.
// Call wake_from_deep_sleep() only if you need RX active before the next operation.
controller.wake_from_deep_sleep(&mut delay);

Project structure

lora/
├── src/
│   ├── lib.rs           # Crate root; re-exports error and sx1278
│   ├── error/           # LoRaError and error types
│   │   ├── mod.rs
│   │   └── model.rs
│   └── sx1278/          # SX1278 driver (feature-gated)
│       ├── mod.rs       # Controller, Mode, ReceiveResult, TxTimeoutConfig
│       ├── registers.rs # Register addresses, modes, IRQ masks, constants
│       └── tests/       # Unit tests (send, receive, set_frequency, set_mode, version, etc.)
├── scripts/
│   └── test.sh          # Runs cargo test with sx1278 feature
├── Cargo.toml
├── LICENSE
└── README.md

Dependencies

• embedded-hal 1.x — SPI, delay, and output pin traits.
• ufmt — Optional formatting in no_std.
• tools (Forgejo registry) — Register read/write and compression; requires registry = "forgejo" and a configured Forgejo Cargo registry.
• lzss — Used for compression (default-features = false).

Building and testing

# Build with SX1278 support
cargo build --features sx1278

# Run tests (uses embedded-hal-mock)
cargo test --features sx1278

# Or use the project script
./scripts/test.sh

Status

• Version: 0.1.0
• Driver: SX1278 register interface, init, send, receive, set_frequency, set_mode, read_version.
• Tests: Unit tests for init, send (including timeout and cancellation), receive (including CRC and buffer size), set_frequency, set_mode, and version read.

License

Personal Use Only — Non-Commercial. See LICENSE for full terms and disclaimers. Commercial use requires written permission from the copyright holder.