ESP32#

rustup target add riscv32imc-unknown-none-elf
cargo install espflash

use esp_hal::i2c::master::{Config, I2c};
use esp_println::println;
use pamoja_sensors::bme280::{Bme280, I2C_ADDRESS_PRIMARY};

#[main]
fn main() -> ! {
    let peripherals = esp_hal::init(esp_hal::Config::default());

    // The core's own types hold an owned topic and payload, so the binary carries a heap;
    // the driver itself never allocates.
    esp_alloc::heap_allocator!(size: 8 * 1024);

    // The chip routes I2C0 to any two pins; GPIO6 and GPIO7 are the pair the XIAO ESP32C3
    // labels D4 and D5. The default configuration is the 100 kHz standard mode.
    let i2c = I2c::new(peripherals.I2C0, Config::default())
        .expect("a valid I2C configuration")
        .with_sda(peripherals.GPIO6)
        .with_scl(peripherals.GPIO7);

    let mut sensor = Bme280::i2c(i2c, I2C_ADDRESS_PRIMARY, Delay);
    sensor.init().expect("the BME280 answers on I2C0");

    loop {
        let measurement = sensor.measure().expect("a measurement");
        println!(
            "{:.2} C, {:.2} hPa, {:.2} % humidity",
            measurement.celsius(),
            measurement.hectopascals(),
            measurement.relative_humidity_percent()
        );
        Delay.delay_ms(2000);
    }
}

cd examples/boards/esp32c3
cargo run --release

use esp_hal::gpio::{Input, InputConfig, Level, Output, OutputConfig, Pull};
use esp_hal::i2c::master::{Config, I2c};
use esp_println::println;
use pamoja_gpio::pin::Polarity;
use pamoja_gpio::switch::{Contact, Switch};
use pamoja_kit::{Debounce, Thermostat};
use pamoja_sensors::bme280::{Bme280, I2C_ADDRESS_PRIMARY};

/// Hold this temperature, switching a heater on half a degree below it and off half a
/// degree above. The deadband is what stops a relay chattering at the threshold.
const SETPOINT_C: f32 = 21.0;
const DEADBAND_C: f32 = 0.5;

#[main]
fn main() -> ! {
    let peripherals = esp_hal::init(esp_hal::Config::default());

    // The core's own types hold an owned topic and payload, so the binary carries a heap;
    // the driver and the control math never allocate.
    esp_alloc::heap_allocator!(size: 8 * 1024);

    // The chip's GPIO matrix routes I2C0 to any two pins.
    let i2c = I2c::new(peripherals.I2C0, Config::default())
        .expect("a valid I2C configuration")
        .with_sda(peripherals.GPIO6)
        .with_scl(peripherals.GPIO7);
    let mut sensor = Bme280::i2c(i2c, I2C_ADDRESS_PRIMARY, Delay);
    sensor.init().expect("the BME280 answers on I2C0");

    // The relay. Its initial level is what the pin drives the instant it is configured,
    // so starting it at the resting level is what keeps a heater off through boot. Most
    // relay boards energize on a low input, which `ActiveLow` states once here.
    let relay = Output::new(peripherals.GPIO10, Level::High, OutputConfig::default());
    let mut heater = Switch::new(relay, Polarity::ActiveLow);

    // The button, wired to ground, so the chip's own pull-up holds the line high until it
    // is pressed. Without that pull the line floats and reads as noise.
    let pin = Input::new(peripherals.GPIO3, InputConfig::default().with_pull(Pull::Up));
    let mut button = Contact::new(pin, Polarity::ActiveLow);
    let mut settled = Debounce::new(4, false);

    // The decision. A heating thermostat switches on below the band and off above it.
    let mut control = Thermostat::heating(SETPOINT_C, DEADBAND_C);
    let mut override_on = false;
    let mut was_pressed = false;

    loop {
        // The button is polled every 50 ms for the second between measurements, so a
        // press is caught rather than missed while the sensor is being read.
        for _ in 0..20 {
            let pressed = settled.update(button.is_asserted().unwrap_or(false));
            if pressed && !was_pressed {
                override_on = !override_on;
                println!("override {}", if override_on { "on" } else { "off" });
            }
            was_pressed = pressed;
            Delay.delay_ms(50);
        }

        let measurement = sensor.measure().expect("a measurement");
        let celsius = measurement.celsius();

        // The thermostat is fed every reading, so its deadband keeps working even while
        // the override holds the relay; releasing it resumes mid-cycle, not from cold.
        let wanted = control.update(celsius);
        let on = wanted || override_on;
        heater.set(on).expect("the relay line takes it");

        println!(
            "{celsius:.2} C, {:.1} % humidity, heater {}{}",
            measurement.relative_humidity_percent(),
            if on { "on" } else { "off" },
            if override_on { " (override)" } else { "" }
        );
    }
}

cargo run --release --bin thermostat

use embedded_hal_bus::spi::ExclusiveDevice;
use esp_hal::gpio::{Level, Output, OutputConfig};
use esp_hal::spi::master::{Config, Spi};
use esp_hal::spi::Mode;
use esp_hal::time::Rate;
use esp_println::println;
use pamoja_lora::LinkSettings;
use pamoja_radios::duty::DutyCycle;
use pamoja_radios::sx127x::config::{PaOutput, TxPower};
use pamoja_radios::sx127x::{Board, RadioConfig, Reception, Sx127x};

/// The channel this node uses, what it sends at, and the share of time it may hold the band.
const FREQUENCY_HZ: u32 = 868_100_000;
const OUTPUT_DBM: i8 = 14;
const DUTY_CYCLE_PERMILLE: u32 = 10;

/// How long the radio listens before it looks at its duty-cycle budget again, in microseconds.
const LISTEN_US: u64 = 10_000_000;

#[main]
fn main() -> ! {
    let peripherals = esp_hal::init(esp_hal::Config::default());

    // The chip's GPIO matrix routes SPI2 to any pins, so the six above are chosen for being
    // free rather than for being an SPI block. Two megahertz is well under what the radio
    // accepts and is what the reference drivers use.
    let bus = Spi::new(
        peripherals.SPI2,
        Config::default()
            .with_frequency(Rate::from_mhz(2))
            .with_mode(Mode::_0),
    )
    .expect("a valid SPI configuration")
    .with_sck(peripherals.GPIO4)
    .with_mosi(peripherals.GPIO5)
    .with_miso(peripherals.GPIO6);

    // The chip select is a plain output the bus drives around each transaction, resting high
    // so the radio ignores the bus until a transaction starts.
    let cs = Output::new(peripherals.GPIO7, Level::High, OutputConfig::default());
    let device = ExclusiveDevice::new(bus, cs, Delay).expect("the chip select takes a level");

    // An RFM95W wires the SX1276's PA_BOOST output to its antenna and clocks it from a
    // crystal, which is what the board description says here.
    let reset = Output::new(peripherals.GPIO10, Level::High, OutputConfig::default());
    let mut radio = Sx127x::new(device, reset, Delay, Board::new(PaOutput::PaBoost));
    radio.init().expect("the RFM95W answers on SPI2");

    // SF9 at 125 kHz, which is DR3 in the European plan, at 14 dBm on PA_BOOST.
    let link = LinkSettings::new(9, 125_000);
    let power = TxPower::for_output(PaOutput::PaBoost, OUTPUT_DBM);
    radio
        .configure(RadioConfig::new(FREQUENCY_HZ, link, power))
        .expect("the chip takes the settings");
    println!("beacon on {FREQUENCY_HZ} Hz at SF9, {OUTPUT_DBM} dBm");

    // Each frame buys silence in proportion to its airtime, and the guard says when the next
    // one may go out, counted on the chip's own microsecond timer.
    let mut duty = DutyCycle::new(DUTY_CYCLE_PERMILLE);
    let mut buffer = [0u8; 255];
    let mut reading = 0u32;

    loop {
        match radio.receive(&mut buffer, LISTEN_US) {
            Ok(Reception::Frame { len, status }) => {
                let heard = core::str::from_utf8(&buffer[..len]).unwrap_or("(not text)");
                println!(
                    "heard  {heard} at {} dBm, SNR {} dB",
                    status.rssi_dbm.round_db(),
                    status.snr_db.round_db()
                );
            }
            Ok(Reception::Corrupt) => println!("heard  a frame whose CRC failed"),
            Ok(Reception::Timeout) => {}
            Err(_) => println!("the radio stopped answering"),
        }

        let now_us = Instant::now().duration_since_epoch().as_micros();
        if duty.ready(now_us) {
            let mut frame = [0u8; 32];
            let len = beacon(&mut frame, reading);
            match radio.transmit(&frame[..len]) {
                Ok(airtime_us) => {
                    duty.transmitted(now_us, &link, len);
                    println!("sent   reading {reading} in {airtime_us} us on air");
                    reading += 1;
                }
                Err(_) => println!("the frame did not go out"),
            }
        }
    }
}

/// Writes a beacon into a buffer without allocating, and returns its length.
fn beacon(frame: &mut [u8; 32], reading: u32) -> usize {
    use core::fmt::Write;

    let mut cursor = Cursor { frame, len: 0 };
    let _ = write!(cursor, "esp32 reading {reading}");
    cursor.len
}

/// A writer over a fixed buffer, so a `no_std` node can format a frame.
struct Cursor<'a> {
    frame: &'a mut [u8; 32],
    len: usize,
}

impl core::fmt::Write for Cursor<'_> {
    fn write_str(&mut self, text: &str) -> core::fmt::Result {
        for byte in text.as_bytes() {
            if self.len == self.frame.len() {
                return Err(core::fmt::Error);
            }
            self.frame[self.len] = *byte;
            self.len += 1;
        }
        Ok(())
    }
}

cargo run --release --bin radio

export LORAWAN_DEV_EUI=1111111111111111
export LORAWAN_JOIN_EUI=2222222222222222
export LORAWAN_APP_KEY=33333333333333333333333333333333

use embedded_hal_bus::spi::ExclusiveDevice;
use esp_hal::gpio::{Level, Output, OutputConfig};
use esp_hal::i2c::master::{Config as I2cConfig, I2c};
use esp_hal::spi::master::{Config as SpiConfig, Spi};
use esp_hal::spi::Mode;
use esp_hal::time::Rate;
use esp_println::println;
use pamoja_lora::region::Region;
use pamoja_lorawan::device::{DeviceError, EndDevice, Settings};
use pamoja_lorawan::{parse_hex, Device, Version};
use pamoja_radios::lorawan::{Node, NodeError, Timer};
use pamoja_radios::sx127x::config::PaOutput;
use pamoja_radios::sx127x::{Board, Sx127x};
use pamoja_sensors::bme280::{Bme280, Measurement, I2C_ADDRESS_PRIMARY};

/// Who the device is to its network, and the root key it shares with it, read from the build
/// environment so that no key is kept in the source. A missing or malformed value stops the
/// build.
const DEV_EUI: [u8; 8] = from_build(env!("LORAWAN_DEV_EUI", "set LORAWAN_DEV_EUI in hex"));
const JOIN_EUI: [u8; 8] = from_build(env!("LORAWAN_JOIN_EUI", "set LORAWAN_JOIN_EUI in hex"));
const APP_KEY: [u8; 16] = from_build(env!("LORAWAN_APP_KEY", "set LORAWAN_APP_KEY in hex"));

/// Reads an identifier or key given in hexadecimal when the program was built.
const fn from_build<const N: usize>(hex: &str) -> [u8; N] {
    match parse_hex(hex) {
        Some(bytes) => bytes,
        None => panic!("an identifier or key takes two hex digits a byte"),
    }
}

/// The application port readings go out on, and how long to wait between them.
const PORT: u8 = 2;
const INTERVAL_US: u64 = 5 * 60 * 1_000_000;

#[main]
fn main() -> ! {
    let peripherals = esp_hal::init(esp_hal::Config::default());

    // The core's own types hold an owned topic and payload, so the binary carries a heap;
    // neither driver, the device, nor the node allocates.
    esp_alloc::heap_allocator!(size: 8 * 1024);

    let i2c = I2c::new(peripherals.I2C0, I2cConfig::default())
        .expect("a valid I2C configuration")
        .with_sda(peripherals.GPIO6)
        .with_scl(peripherals.GPIO7);
    let mut sensor = Bme280::i2c(i2c, I2C_ADDRESS_PRIMARY, Delay);
    sensor.init().expect("the BME280 answers on I2C0");

    let bus = Spi::new(
        peripherals.SPI2,
        SpiConfig::default()
            .with_frequency(Rate::from_mhz(2))
            .with_mode(Mode::_0),
    )
    .expect("a valid SPI configuration")
    .with_sck(peripherals.GPIO4)
    .with_mosi(peripherals.GPIO5)
    .with_miso(peripherals.GPIO3);
    let cs = Output::new(peripherals.GPIO10, Level::High, OutputConfig::default());
    let device = ExclusiveDevice::new(bus, cs, Delay).expect("the chip select takes a level");
    let reset = Output::new(peripherals.GPIO20, Level::High, OutputConfig::default());
    let mut radio = Sx127x::new(device, reset, Delay, Board::new(PaOutput::PaBoost));
    radio.init().expect("the RFM95W answers on SPI2");

    // The chip has no entropy of its own without its Wi-Fi radio running, so the node takes it
    // from the LoRa receiver's noise, as LoRaWAN 1.0.3 suggests for the join nonce. The network
    // registration says 1.0.3, whose nonce is random rather than a stored count.
    let seed = radio.random().expect("the RFM95W listens");
    let (min_dbm, max_dbm) = PaOutput::PaBoost.range_dbm();
    let settings = Settings::new(min_dbm, max_dbm)
        .with_version(Version::V1_0_3)
        .with_seed(seed);
    let credentials = Device::new(DEV_EUI, JOIN_EUI, APP_KEY);
    let device = EndDevice::new(Region::Eu868.plan(), credentials, settings)
        .expect("EU868 fits a device's channel table");

    // The node sends, opens both receive windows on time, and sees each uplink through its
    // repeats. The clock and the delay it times them with are the chip's own timer.
    let clock = Timer::new(|| Instant::now().duration_since_epoch().as_micros(), Delay);
    let mut node = Node::new(device, radio, clock);

    while !node.device().is_joined() {
        let nonce = node.radio_mut().random().map_or(0, |noise| noise as u16);
        match node.join(nonce) {
            Ok(true) => println!("joined as {:08X}", node.device().dev_addr().unwrap_or(0)),
            Ok(false) => println!("no join accept yet"),
            Err(NodeError::Device(DeviceError::Wait { until_us })) => node.wait_until(until_us),
            Err(error) => println!("join failed: {error}"),
        }
    }

    loop {
        let started = Instant::now().duration_since_epoch().as_micros();
        match sensor.measure() {
            Ok(measurement) => {
                let payload = encode(&measurement);
                match node.send(PORT, &payload, false) {
                    Ok(report) => {
                        println!(
                            "sent {:.2} C, {:.2} hPa, {:.2} % as uplink {} ({} transmissions)",
                            measurement.celsius(),
                            measurement.hectopascals(),
                            measurement.relative_humidity_percent(),
                            node.device().fcnt_up() - 1,
                            report.transmissions,
                        );
                        if let Some(delivery) = report.delivery {
                            println!(
                                "heard {} bytes on port {:?}",
                                delivery.payload().len(),
                                delivery.port()
                            );
                        }
                    }
                    Err(NodeError::Device(DeviceError::Wait { until_us })) => {
                        node.wait_until(until_us);
                        continue;
                    }
                    Err(error) => println!("the uplink failed: {error}"),
                }
            }
            Err(_) => println!("the BME280 did not answer"),
        }
        node.wait_until(started + INTERVAL_US);
    }
}

/// Packs a reading into seven bytes, most significant first: the temperature in hundredths
/// of a degree as a signed 16-bit value, the relative humidity in hundredths of a percent as
/// an unsigned 16-bit value, and the pressure in pascals in 24 bits.
fn encode(measurement: &Measurement) -> [u8; 7] {
    let celsius = hundredths(measurement.celsius()) as i16;
    let humidity = hundredths(measurement.relative_humidity_percent()) as u16;
    let pascals = measurement.pascals().min(0x00FF_FFFF);

    let mut payload = [0u8; 7];
    payload[..2].copy_from_slice(&celsius.to_be_bytes());
    payload[2..4].copy_from_slice(&humidity.to_be_bytes());
    payload[4..].copy_from_slice(&pascals.to_be_bytes()[1..]);
    payload
}

/// A value in hundredths, rounded to the nearest one.
fn hundredths(value: f32) -> i32 {
    let scaled = value * 100.0;
    if scaled >= 0.0 {
        (scaled + 0.5) as i32
    } else {
        (scaled - 0.5) as i32
    }
}

cargo run --release --bin lorawan