Imported from njfdev/ncssm_hpr_2025_payload (.claude/skills/sensor-drivers/SKILL.md). Install upstream with npx skills add njfdev/ncssm_hpr_2025_payload --skill sensor-drivers. Copyright stays with the author.

Payload Sensor Drivers

Hardware Configuration

CRITICAL: Use the SCAN command to verify which I2C bus sensors are actually on. The ENS160 was initially assumed to be on I2C0 but scanning revealed it was on I2C1 with BMP390.

BMP390 - Barometric Pressure Sensor

Datasheet: Bosch BMP390

Specifications

• Pressure range: 300-1250 hPa
• Relative accuracy: ±3 Pa (~0.25m altitude)
• Absolute accuracy: ±0.40 hPa
• Temperature: -40 to +85°C (±0.5°C accuracy)
• Power: 3.2 µA @ 1Hz

I2C Address

• 0x76: SDO pin connected to GND
• 0x77: SDO pin connected to VDDIO (3.3V) ← Our configuration

Key Registers

Power Modes

• Sleep: No measurements (default after reset)
• Forced: Single measurement, then sleep
• Normal: Continuous measurements with standby

Initialization Sequence

const BMP390_ADDR: u8 = 0x77;
const CHIP_ID: u8 = 0x00;
const PWR_CTRL: u8 = 0x1B;
const OSR: u8 = 0x1C;
const ODR: u8 = 0x1D;

// 1. Read and verify chip ID (should be 0x60)
let mut id = [0u8];
i2c.write_read(BMP390_ADDR, &[CHIP_ID], &mut id).await?;
assert_eq!(id[0], 0x60);

// 2. Read calibration data (21 bytes from 0x31)
let mut calib = [0u8; 21];
i2c.write_read(BMP390_ADDR, &[0x31], &mut calib).await?;

// 3. Configure oversampling (x8 pressure, x1 temp)
i2c.write(BMP390_ADDR, &[OSR, 0b00000011]).await?;

// 4. Configure ODR (50 Hz = 0x02)
i2c.write(BMP390_ADDR, &[ODR, 0x02]).await?;

// 5. Enable pressure and temp, normal mode
// PWR_CTRL: press_en=1, temp_en=1, mode=normal(11)
i2c.write(BMP390_ADDR, &[PWR_CTRL, 0b00110011]).await?;

Reading Data

const DATA_0: u8 = 0x04;

// Read 6 bytes: pressure (3) + temperature (3)
let mut data = [0u8; 6];
i2c.write_read(BMP390_ADDR, &[DATA_0], &mut data).await?;

// Pressure: 24-bit unsigned (XLSB, LSB, MSB)
let press_raw = (data[2] as u32) << 16 | (data[1] as u32) << 8 | data[0] as u32;

// Temperature: 24-bit unsigned (XLSB, LSB, MSB)
let temp_raw = (data[5] as u32) << 16 | (data[4] as u32) << 8 | data[3] as u32;

// Apply compensation algorithm from datasheet using calibration data

ENS160 - Digital Metal-Oxide Multi-Gas Sensor

Datasheet: ScioSense ENS160

Specifications

• Air Quality Index (AQI): 1-5 scale
• Total VOC (TVOC): 0-65000 ppb
• Equivalent CO2 (eCO2): 400-65000 ppm
• Operating temperature: -40 to +85°C
• Warm-up time: 3 minutes (initial), then 1 second between readings

I2C Address

• 0x52: ADDR pin connected to GND
• 0x53: ADDR pin connected to VDDIO ← Our configuration

Note: The ENS160 also supports SPI mode. When using I2C, the CS pin must be held HIGH.

Key Registers

Operating Modes

• 0x00: Deep sleep (lowest power)
• 0x01: Idle (ready for commands)
• 0x02: Standard mode (1 second measurement interval) ← Use this

Status Register (0x20)

[3:2] VALIDITY: Data validity
      00 = Normal operation
      01 = Warm-up phase (data not ready)
      10 = Initial start-up phase
      11 = Invalid output
[1] NEWDAT: New data available
[0] NEWGPR: New GPR data available

Initialization Sequence

const ENS160_ADDR: u8 = 0x53;
const PART_ID: u8 = 0x00;
const OPMODE: u8 = 0x10;
const COMMAND: u8 = 0x12;

// 1. Read and verify part ID (should be 0x0160)
let mut id_buf = [0u8; 2];
i2c.write_read(ENS160_ADDR, &[PART_ID], &mut id_buf).await?;
let part_id = u16::from_le_bytes(id_buf);
assert_eq!(part_id, 0x0160);

// 2. Set to idle mode (required before configuration)
i2c.write(ENS160_ADDR, &[OPMODE, 0x01]).await?;
Timer::after_millis(10).await;

// 3. Clear GPR registers (command 0xCC)
i2c.write(ENS160_ADDR, &[COMMAND, 0xCC]).await?;
Timer::after_millis(10).await;

// 4. Set to standard operating mode
i2c.write(ENS160_ADDR, &[OPMODE, 0x02]).await?;
Timer::after_millis(50).await;

Reading Data

const DEVICE_STATUS: u8 = 0x20;
const DATA_AQI: u8 = 0x21;
const DATA_TVOC: u8 = 0x22;
const DATA_ECO2: u8 = 0x24;

// Check status first
let mut status = [0u8];
i2c.write_read(ENS160_ADDR, &[DEVICE_STATUS], &mut status).await?;

// Check validity bits [3:2]
let validity = (status[0] & 0x0C) >> 2;
if validity > 1 {
    // 0 = normal, 1 = warm-up, 2+ = not ready
    return Ok(()); // Skip reading, keep previous values
}

// Read AQI (1 byte)
let mut aqi_buf = [0u8];
i2c.write_read(ENS160_ADDR, &[DATA_AQI], &mut aqi_buf).await?;
let aqi = aqi_buf[0]; // 1-5 scale

// Read TVOC (2 bytes, little-endian)
let mut tvoc_buf = [0u8; 2];
i2c.write_read(ENS160_ADDR, &[DATA_TVOC], &mut tvoc_buf).await?;
let tvoc_ppb = u16::from_le_bytes(tvoc_buf);

// Read eCO2 (2 bytes, little-endian)
let mut eco2_buf = [0u8; 2];
i2c.write_read(ENS160_ADDR, &[DATA_ECO2], &mut eco2_buf).await?;
let eco2_ppm = u16::from_le_bytes(eco2_buf);

Temperature/Humidity Compensation

const TEMP_IN: u8 = 0x13;
const RH_IN: u8 = 0x15;

// Temperature in centidegrees (25.5°C = 2550)
// ENS160 expects: (T + 273.15) * 64
let temp_encoded = ((temp_centideg as u32 + 27315) * 64 / 100) as u16;
let bytes = temp_encoded.to_le_bytes();
i2c.write(ENS160_ADDR, &[TEMP_IN, bytes[0], bytes[1]]).await?;

// Humidity in percent * 100 (50.5% = 5050)
// ENS160 expects: RH * 512 / 100
let rh_encoded = (rh_centipercent as u32 * 512 / 10000) as u16;
let bytes = rh_encoded.to_le_bytes();
i2c.write(ENS160_ADDR, &[RH_IN, bytes[0], bytes[1]]).await?;

AQI Interpretation

Important Notes

1. Warm-up time: ENS160 needs 3+ minutes to provide valid readings after power-on
2. Read rate: Internal update rate is 1Hz in standard mode, so reading faster is pointless
3. Temperature compensation: Feed in ambient temperature for more accurate TVOC/eCO2
4. CS pin: Must be held HIGH for I2C mode (if using breakout board with SPI option)

LSM6DSOX - 6-Axis IMU (Accelerometer + Gyroscope)

Datasheet: ST LSM6DSOX

Specifications

• Accelerometer: ±2/±4/±8/±16 g
• Gyroscope: ±125/±250/±500/±1000/±2000 dps
• ODR: up to 6.66 kHz
• Power: 0.55 mA in high-performance mode

I2C Address

• 0x6A: SA0/SDO pin connected to GND ← Our configuration
• 0x6B: SA0/SDO pin connected to VDDIO

Key Registers

CTRL1_XL (Accelerometer Control)

[7:4] ODR_XL: Output data rate
      0000 = Power-down
      0001 = 12.5 Hz
      0010 = 26 Hz
      0011 = 52 Hz
      0100 = 104 Hz
      0101 = 208 Hz
      0110 = 416 Hz
      0111 = 833 Hz
      1000 = 1.66 kHz
      1001 = 3.33 kHz
      1010 = 6.66 kHz

[3:2] FS_XL: Full-scale selection
      00 = ±2 g
      01 = ±16 g
      10 = ±4 g
      11 = ±8 g

[1] LPF2_XL_EN: Low-pass filter enable
[0] (unused)

CTRL2_G (Gyroscope Control)

[7:4] ODR_G: Output data rate (same as accelerometer)

[3:2] FS_G: Full-scale selection
      00 = ±250 dps
      01 = ±500 dps
      10 = ±1000 dps
      11 = ±2000 dps

[1] FS_125: 125 dps full-scale (overrides FS_G if set)
[0] (unused)

Initialization Sequence

const LSM6DSOX_ADDR: u8 = 0x6A;
const WHO_AM_I: u8 = 0x0F;
const CTRL1_XL: u8 = 0x10;
const CTRL2_G: u8 = 0x11;
const CTRL3_C: u8 = 0x12;

// 1. Read and verify WHO_AM_I (should be 0x6C)
let mut who = [0u8];
i2c.write_read(LSM6DSOX_ADDR, &[WHO_AM_I], &mut who).await?;
assert_eq!(who[0], 0x6C);

// 2. Software reset
i2c.write(LSM6DSOX_ADDR, &[CTRL3_C, 0x01]).await?;
Timer::after_millis(10).await;

// 3. Configure accelerometer: 104 Hz, ±16g
// ODR=0100, FS=01 (±16g) -> 0b0100_0100 = 0x44
i2c.write(LSM6DSOX_ADDR, &[CTRL1_XL, 0x44]).await?;

// 4. Configure gyroscope: 104 Hz, ±2000 dps
// ODR=0100, FS=11 (±2000 dps) -> 0b0100_1100 = 0x4C
i2c.write(LSM6DSOX_ADDR, &[CTRL2_G, 0x4C]).await?;

Reading Data

const OUTX_L_G: u8 = 0x22;

// Read 12 bytes: gyro (6) + accel (6)
let mut data = [0u8; 12];
i2c.write_read(LSM6DSOX_ADDR, &[OUTX_L_G], &mut data).await?;

// Gyroscope (signed 16-bit, dps)
let gx = i16::from_le_bytes([data[0], data[1]]);
let gy = i16::from_le_bytes([data[2], data[3]]);
let gz = i16::from_le_bytes([data[4], data[5]]);

// Accelerometer (signed 16-bit, g)
let ax = i16::from_le_bytes([data[6], data[7]]);
let ay = i16::from_le_bytes([data[8], data[9]]);
let az = i16::from_le_bytes([data[10], data[11]]);

// Convert to physical units
// For ±16g: sensitivity = 0.488 mg/LSB
// For ±2000 dps: sensitivity = 70 mdps/LSB

LIS3MDL - 3-Axis Magnetometer

Datasheet: ST LIS3MDL

Specifications

• Range: ±4/±8/±12/±16 gauss
• ODR: up to 1000 Hz (ultra-high performance)
• Power: 270 µA @ 80 Hz

I2C Address

• 0x1C: SA1/SDO pin connected to GND ← Our configuration
• 0x1E: SA1/SDO pin connected to VDDIO

Key Registers

CTRL_REG1 (ODR and XY Performance)

[7] TEMP_EN: Temperature sensor enable
[6:5] OM: X/Y-axis operative mode
      00 = Low-power
      01 = Medium-performance
      10 = High-performance
      11 = Ultra-high performance

[4:2] DO: Output data rate
      000 = 0.625 Hz
      001 = 1.25 Hz
      010 = 2.5 Hz
      011 = 5 Hz
      100 = 10 Hz
      101 = 20 Hz
      110 = 40 Hz
      111 = 80 Hz

[1] FAST_ODR: Enable rates >80 Hz
[0] ST: Self-test enable

CTRL_REG2 (Full-Scale Selection)

[6:5] FS: Full-scale configuration
      00 = ±4 gauss
      01 = ±8 gauss
      10 = ±12 gauss
      11 = ±16 gauss

CTRL_REG3 (Operating Mode)

[1:0] MD: Operating mode
      00 = Continuous-conversion
      01 = Single-conversion
      10 = Power-down (default)
      11 = Power-down

Initialization Sequence

const LIS3MDL_ADDR: u8 = 0x1C;
const WHO_AM_I: u8 = 0x0F;
const CTRL_REG1: u8 = 0x20;
const CTRL_REG2: u8 = 0x21;
const CTRL_REG3: u8 = 0x22;
const CTRL_REG4: u8 = 0x23;

// 1. Read and verify WHO_AM_I (should be 0x3D)
let mut who = [0u8];
i2c.write_read(LIS3MDL_ADDR, &[WHO_AM_I], &mut who).await?;
assert_eq!(who[0], 0x3D);

// 2. Configure CTRL_REG1: temp enable, ultra-high perf XY, 80 Hz
// TEMP_EN=1, OM=11, DO=111 -> 0b1111_1100 = 0xFC
i2c.write(LIS3MDL_ADDR, &[CTRL_REG1, 0xFC]).await?;

// 3. Configure CTRL_REG2: ±4 gauss (default, 0x00)
i2c.write(LIS3MDL_ADDR, &[CTRL_REG2, 0x00]).await?;

// 4. Configure CTRL_REG3: continuous mode
i2c.write(LIS3MDL_ADDR, &[CTRL_REG3, 0x00]).await?;

// 5. Configure CTRL_REG4: ultra-high performance Z-axis
// OMZ=11 -> 0b0000_1100 = 0x0C
i2c.write(LIS3MDL_ADDR, &[CTRL_REG4, 0x0C]).await?;

Reading Data

const OUT_X_L: u8 = 0x28;

// Read 6 bytes (can also read with auto-increment: 0x28 | 0x80)
let mut data = [0u8; 6];
i2c.write_read(LIS3MDL_ADDR, &[OUT_X_L | 0x80], &mut data).await?;

// Magnetometer (signed 16-bit, gauss)
let mx = i16::from_le_bytes([data[0], data[1]]);
let my = i16::from_le_bytes([data[2], data[3]]);
let mz = i16::from_le_bytes([data[4], data[5]]);

// Convert to physical units
// For ±4 gauss: sensitivity = 6842 LSB/gauss

Embassy I2C Setup for RP2040

use embassy_rp::i2c::{I2c, Config, InterruptHandler};
use embassy_rp::bind_interrupts;
use embassy_rp::peripherals::{I2C0, I2C1};

bind_interrupts!(struct Irqs {
    I2C0_IRQ => InterruptHandler<I2C0>;
    I2C1_IRQ => InterruptHandler<I2C1>;
});

// I2C0 for IMU (LSM6DSOX + LIS3MDL): SDA=GP28, SCL=GP29
let mut config = Config::default();
config.frequency = 400_000; // 400 kHz Fast mode
let i2c0 = I2c::new_async(p.I2C0, p.PIN_29, p.PIN_28, Irqs, config);

// I2C1 for Barometer (BMP390) and Gas Sensor (ENS160): SDA=GP2, SCL=GP3
let i2c1 = I2c::new_async(p.I2C1, p.PIN_3, p.PIN_2, Irqs, config);

Note: Embassy I2C::new_async takes pins as (SCL, SDA) not (SDA, SCL).

I2C Bus Scanning

Use the SCAN command to discover devices on both I2C buses:

// Add to command handler
} else if cmd.starts_with(b"SCAN") {
    use embedded_hal_async::i2c::I2c as I2cTrait;

    let _ = class.write_packet(b"I2C0 scan:\r\n").await;
    for addr in 0x08u8..0x78u8 {
        let mut buf = [0u8; 1];
        if i2c0.read(addr, &mut buf).await.is_ok() {
            // Device found at addr
            let mut msg: heapless::String<16> = heapless::String::new();
            let _ = write!(msg, "  0x{:02X}\r\n", addr);
            let _ = class.write_packet(msg.as_bytes()).await;
        }
    }
    // Repeat for i2c1...
}

Expected output for our hardware:

I2C0 scan:
  0x1C    # LIS3MDL
  0x6A    # LSM6DSOX
I2C1 scan:
  0x53    # ENS160
  0x77    # BMP390

Sensitivity and Conversion

BMP390

Requires calibration coefficients from registers 0x31-0x45. See datasheet section 8.4 for compensation formulas.

LSM6DSOX

LIS3MDL

Troubleshooting

Sensor Not Responding

1. Check I2C address (measure SDO/SA0/SA1 pin voltage)
2. Verify pull-up resistors on SDA/SCL (2.2k-10k to 3.3V)
3. Check wiring: SDA to SDA, SCL to SCL
4. Reduce I2C frequency to 100kHz for debugging

Wrong WHO_AM_I Value

• 0xFF: No device responding (check address, wiring)
• 0x00: Device in reset or powered off
• Other: Wrong device or address conflict

No Data Updates

• Check power mode (devices start in power-down)
• Verify ODR is set (output data rate > 0)
• Check STATUS register for data ready flags

I2C Reads Hanging

If sensor reads hang after successful initialization:

1. Test sensors individually - add debug output between each sensor read to identify which one hangs
2. Check for I2C bus conflicts - multiple sensors on same bus can cause issues if one holds SDA/SCL low
3. Add small delays between operations - some sensors need settling time between init and first read
4. Verify async I2C trait is in scope - must use embedded_hal_async::i2c::I2c as I2cTrait; in each module

Debugging Pattern

When sensor reads aren't working, use this progressive debugging approach:

// Add debug output before/after each operation
let _ = class.write_packet(b"SENSOR_NAME...\r\n").await;
if sensor::read(&mut i2c, &mut data).await.is_err() {
    let _ = class.write_packet(b"SENSOR_NAME ERR\r\n").await;
}
let _ = class.write_packet(b"SENSOR_NAME DONE\r\n").await;

This reveals exactly which operation hangs - invaluable for I2C debugging.

Working Code Reference

The current pico_logger implementation in pico_logger/src/sensors/ provides working drivers for all three sensors. Key patterns:

1. Each sensor in its own module with init() and read() functions
2. I2C trait imported in each module: use embedded_hal_async::i2c::I2c as I2cTrait;
3. Error handling via Result - init returns error if WHO_AM_I doesn't match
4. Shared SensorData struct passed by mutable reference to reads