simple-max31865 1.0.0

Easy-to-use driver for the MAX31865 RTD to Digital converter (Raspberry Pi focus)
Documentation

simple-max31865

Crates.io↗ Docs.rs↗ License

An easy-to-use Raspberry Pi driver for the MAX31865 RTD to Digital converter

Documentation↗

Examples↗

Examples are in the examples directory from the root of the tree.

What works

  • Reading the raw value and the converted temperature value either in f64 or scaled integer forms.
  • Detecting and recovering from errors.
  • Setting the ohmic calibration value.
  • Interaction with the chip works well.
  • Reading temperatures and resistances from PT-100 sensors.
  • Fault detection and recovery.
  • Support for Raspberry Pi (via rppal crate).
  • Tested with Max31856 hardware from Playing With Fusion and an Adafruit clone board, both with a PT100 sensor.

TODO

See src/lib.rs for details.

Future: Testing/Mocking

  • Stub off hardware access by creating abstract implementations of Trait(s) and create minimal Mock unit tests (under a "mock" feature).
  • Create mock implementation of SPI and Pin abstractions (controlled by a "mock" feature).
  • Create "mock" hardware tests which exercise the APIs with mock feature.

Many other thoughts listed in the src/lib.rs file.

Quick Start

Raspberry Pi OS Configuration

  • You need a Raspberry Pi with a working Max31865 HAT attached with a known chip select pin.
  • Enable GPIO/SPI via raspi-config or your OS settings before running.

Add to Cargo.toml

[dependencies]
simple-max31865 = "1.0"

Basic Usage (Raspberry Pi)

use simple_max31865::{decode_fault_status, RTDReader, RTDLeads, FilterHz};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut max = RTDReader::new(24, RTDLeads::Three, FilterHz::Sixty)?; // CS pin 24, 3-wire PT100, 60Hz filter
    let temperature = max.get_temperature()?;
    println!("Temperature: {:.2}°C", temperature);
    let resistance = max.get_resistance()?;
    println!("Resistance: {:.2} Ω", resistance);

    match max.read_temp_100() {
        Ok(temp) => println!("Temperature: {:.2}°C", temp as f64 / 100.0),
        Err(e) => {
            if max.is_max_fault(&e) {
                let status = max.read_fault_status()?;
                println!("Fault: {:?}", decode_fault_status(status));  // Fixed: No ? needed
                let _ = max.clear_fault();
            }
            return Err(e.into());
        }
    }
    Ok(())
}

Configuration Options

The examples (e.g., ice_bath_test) support overriding defaults via CLI arguments or environment variables. This is useful for customizing the chip select pin, lead configuration, or filter without modifying code.

  • CLI Arguments (passed after --):

    • --cs-pin <u8>: GPIO pin for chip select (default: 24).
    • --leads <Two|Three|Four>: RTD lead configuration (default: "Three").
    • --filter <Fifty|Sixty>: Noise filter (default: "Sixty").

    Example:

    cargo run --example ice_bath_test -- --cs-pin 8 --leads Four --filter Fifty

  • Environment Variables (fallback if CLI not provided):

    • MAX31865_CS_PIN: GPIO pin for chip select (u8, e.g., "8").
    • MAX31865_LEADS: Lead configuration (e.g., "Four").
    • MAX31865_FILTER: Noise filter (e.g., "Fifty").

    Example:

    export MAX31865_CS_PIN=8
export MAX31865_LEADS=Four
export MAX31865_FILTER=Fifty
cargo run --example ice_bath_test

Precedence: CLI args > env vars > hardcoded defaults.

Running Hardware Tests

The hardware validation tests (e.g., in tests/100_ohm_test.rs) access shared SPI/GPIO resources and use the serial_test crate to run serially by default. No special flags are needed—just run them normally:

cargo test test_read_resistance_hardware -- --ignored

For the full suite of ignored tests:

cargo test -- --ignored

License

Licensed under either of

References

Credits and License

The simple-max31865 crate is derived from version 1.0.0 of the rs-max31865↗ crate by Rudi Horn and Emeric Martineau, with significant modifications:

  • Greatly simplified, opaque API hiding hardware details.
  • Added Raspberry Pi support via rppal.
  • Floating-point temperature and resistance reads.

Some original code snippets (e.g., register configs) and temperature conversion etc are reused under the MIT/Apache-2.0 license. See the original repo for their contributions.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.