Add configuration register

.gitignore

@@ -1,4 +1,4 @@
-
 /target/
 **/*.rs.bk
 Cargo.lock
+.idea

Cargo.toml

@@ -1,17 +1,62 @@
 [package]
 name = "ina219"
 description = "INA219 current/power monitor driver"
-version = "0.1.0"
+edition = "2021"
+version = "0.2.0"
 keywords = ["ina219", "driver", "i2c", "current", "no_std"]
 repository = "https://github.com/scttnlsn/ina219"
-authors = ["Scott Nelson <scott@scottnelson.co>"]
+authors = ["Scott Nelson <scott@scottnelson.co>", "Tamme Dittrich <tamme@tweedegolf.com>"]
 license = "MIT/Apache-2.0"
 
+[features]
+default = ["sync", "async", "paranoid"]
+
+# Provide a blocking driver implementation
+sync = ["dep:embedded-hal"]
+
+# Provide an async driver implementation
+async = ["dep:embedded-hal-async"]
+
+
+# Use the standard library and impl std::error::Error on all error types
+std = []
+
+# Perform checks to see if the INA219 reacts as expected such as:
+# - All measurements are in the configured ranges
+# - We can read back the configuration we have written without any changes
+#
+# This does cause some overhead such as memorizing the last written configuration and performing more actions on the
+# bus. So it can be disabled by setting `default-features = false`.
+paranoid = []
+
+# When using a raspberry pi and the I2C transaction an operation not supported error is raised. This feature replaces
+# the usage of a single transaction with multiple write_read operations.
+no_transaction = []
+
+[[example]]
+name = "calibration"
+required-features = ["sync", "std", "no_transaction"]
+
+[[example]]
+name = "custom-calibration"
+required-features = ["sync", "std", "no_transaction"]
+
+[[example]]
+name = "full-config"
+required-features = ["sync", "std", "no_transaction"]
+
+[[example]]
+name = "minimal"
+required-features = ["sync", "std", "no_transaction"]
+
+[[example]]
+name = "triggered"
+required-features = ["sync", "std", "no_transaction"]
 
 [dependencies]
-byteorder = {version = "1.2.1", default-features = false}
-embedded-hal = "0.2"
+embedded-hal = { version = "1.0.0", optional = true }
+embedded-hal-async = { version = "1.0.0", optional = true }
 
 [dev-dependencies]
-linux-embedded-hal = "0.2"
-embedded-hal-mock = "0.4"
+linux-embedded-hal = "0.4.0"
+embedded-hal-mock = { version = "0.10.0", default-features = false, features = ["eh1"] }

README.md

@@ -1,36 +1,28 @@
 # ina219
 
-[![Travis CI Status](https://travis-ci.org/scttnlsn/ina219.svg?branch=master)](https://travis-ci.org/scttnlsn/ina219)
 [![crates.io](https://img.shields.io/crates/v/ina219.svg)](https://crates.io/crates/ina219)
 
-[INA219](http://www.ti.com/product/INA219) current/power monitor driver for Rust
+Blocking and async driver for the [INA219](http://www.ti.com/product/INA219) current/power monitor by Texas Instruments.
 
-## Example
 
-```rust
-extern crate ina219;
-extern crate linux_embedded_hal as hal;
 
-use hal::I2cdev;
-use ina219::{INA219, INA219_ADDR};
+## Features
+This crate has the following feature flags (default features in bold):
 
-fn main() {
-    let device = I2cdev::new("/dev/i2c-1").unwrap();
-    let mut ina = INA219::new(device, INA219_ADDR);
+| Name           | Description                                                            |
+|----------------|------------------------------------------------------------------------|
+| **sync**       | Provide a blocking driver implementation                               |
+| **async**      | Provide an async driver implementation                                 |
+| **paranoid**   | Perform extra checks                                                   |
+| no_transaction | Disable use of transactions and perform individual system calls        |
+| std            | Use the standard library and impl std::error::Error on all error types |
 
-    ina.calibrate(0x0100).unwrap();
+For more detailed descriptions see [Cargo.toml](Cargo.toml).
 
-    let voltage = ina.voltage().unwrap();
-    println!("bus voltage: {:?}", voltage);
+## Calibration
+This driver includes ways to use the calibration feature of the INA219. However, the errors introduced by the 
+calculations can be unintuitive. So it can make sense to just compute the current and power in software.
 
-    let shunt_voltage = ina.shunt_voltage().unwrap();
-    println!("shunt voltage: {:?}", shunt_voltage);
-
-    let current = ina.current().unwrap();
-    println!("current: {:?}", current);
-
-    let power = ina.power().unwrap();
-    println!("power: {:?}", power);
-}
-
-```
+## Examples
+The [examples](examples/) folder contains code that demonstrates how this driver can be used. They were tested on a
+Raspberry Pi with an INA219 that was configured for address 0x42.

build.rs

@@ -0,0 +1,21 @@
+use std::env;
+use std::fs::File;
+use std::io::Write;
+use std::path::PathBuf;
+
+fn main() -> std::io::Result<()> {
+    // Produce an sync version from the async one
+    println!("cargo:rerun-if-changed=src/async.rs");
+    let asynced = std::fs::read_to_string("src/async.rs")?;
+
+    let asynced = asynced.replace("embedded_hal_async", "embedded_hal");
+    let asynced = asynced.replace("async", "");
+    let asynced = asynced.replace(".await", "");
+
+    let mut out_path = PathBuf::from(env::var("OUT_DIR").unwrap());
+    out_path.push("de-asynced.rs");
+
+    File::create(out_path)?.write_all(asynced.as_bytes())?;
+
+    Ok(())
+}

examples/calibration.rs

@@ -0,0 +1,28 @@
+use ina219::address::Address;
+use ina219::calibration::{IntCalibration, MicroAmpere};
+use ina219::SyncIna219;
+use linux_embedded_hal::I2cdev;
+use std::error::Error;
+
+fn main() -> Result<(), Box<dyn Error>> {
+    // Resolution of 1A, and a shunt of 1mOhm
+    let calib = IntCalibration::new(MicroAmpere(1_000_000), 1_000).unwrap();
+
+    let device = I2cdev::new("/dev/i2c-1")?;
+    let mut ina = SyncIna219::new_calibrated(device, Address::from_byte(0x42)?, calib)?;
+
+    let measurement = ina.next_measurement()?.expect("A measurement is ready");
+
+    println!("{:#?}", measurement);
+
+    let err = (measurement.current.0 / 1_000_000)
+        - i64::from(measurement.shunt_voltage.shunt_voltage_mv());
+    assert!(err.abs() < 10);
+
+    let err = (measurement.power.0 / 1_000_000).abs_diff(
+        measurement.current.0 / 1_000_000 * i64::from(measurement.bus_voltage.voltage_mv() / 1000),
+    );
+    assert!(err < 100);
+
+    Ok(())
+}

examples/custom-calibration.rs

@@ -0,0 +1,78 @@
+use ina219::address::Address;
+use ina219::calibration::Calibration;
+use ina219::measurements::{CurrentRegister, PowerRegister};
+use ina219::SyncIna219;
+use linux_embedded_hal::I2cdev;
+use std::error::Error;
+
+struct MyCalib;
+
+impl MyCalib {
+    const R_OHM: f32 = 0.001; // 1mOhm
+    const CURRENT_LSB: f32 = 1.0; // 1A
+
+    fn new() -> Self {
+        Self
+    }
+}
+
+impl Calibration for MyCalib {
+    type Current = u16; // in A
+    type Power = u16; // in W
+
+    fn register_bits(&self) -> u16 {
+        (0.04096 / (Self::CURRENT_LSB * Self::R_OHM)) as u16
+    }
+
+    fn current_from_register(&self, reg: CurrentRegister) -> Self::Current {
+        reg.0
+    }
+
+    fn power_from_register(&self, reg: PowerRegister) -> Self::Power {
+        reg.0 * 20
+    }
+}
+
+fn main() -> Result<(), Box<dyn Error>> {
+    let device = I2cdev::new("/dev/i2c-1")?;
+    let mut ina = SyncIna219::new_calibrated(device, Address::from_byte(0x42)?, MyCalib::new())?;
+
+    let measurements = ina.next_measurement()?.expect("Measurement is done");
+
+    println!("{:#?}", measurements);
+
+    // NOTE: The calibration can introduce quite a bit of error, we allow for 10% for testing
+
+    let shunt = measurements.shunt_voltage.shunt_voltage_mv() as u16;
+    let err = shunt / 10;
+    let plausible_currents = (shunt - err)..(shunt + err);
+    assert!(plausible_currents.contains(&measurements.current));
+
+    let expected_power = measurements.current * (measurements.bus_voltage.voltage_mv() / 1000);
+    let err = expected_power / 10;
+    let plausible_power = (expected_power - err)..(expected_power + err);
+    assert!(plausible_power.contains(&measurements.power));
+
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use ina219::calibration::simulate;
+    use ina219::measurements::{BusVoltage, ShuntVoltage};
+
+    #[test]
+    fn does_not_overflow() {
+        // Worst case is we get 16A at 20V over our 1mOhm resistor
+
+        let bus = BusVoltage::from_mv(20_000); // 20V = 20_000mV
+        let shunt = ShuntVoltage::from_10uv(16_000 / 10); // 0.001 Ohm * 16A = 0.016V = 16_000µV
+        assert_eq!(shunt.shunt_voltage_uv(), 16_000);
+
+        let measurements = simulate(&MyCalib, bus, shunt).expect("Does not overflow");
+
+        assert!((15..17).contains(&measurements.current)); // Calculation does include some error
+        assert_eq!(measurements.power, measurements.current * 20);
+    }
+}

examples/full-config.rs

@@ -0,0 +1,46 @@
+use ina219::address::Address;
+use ina219::configuration::{
+    BusVoltageRange, Configuration, MeasuredSignals, OperatingMode, Reset, Resolution,
+    ShuntVoltageRange,
+};
+use ina219::SyncIna219;
+use linux_embedded_hal::I2cdev;
+use std::error::Error;
+use std::time::Duration;
+
+fn main() -> Result<(), Box<dyn Error>> {
+    let device = I2cdev::new("/dev/i2c-1")?;
+    let mut ina = SyncIna219::new(device, Address::from_byte(0x42)?)?;
+
+    ina.set_configuration(Configuration {
+        // Be extra precise, but take some extra time
+        bus_resolution: Resolution::Avg128,
+        shunt_resolution: Resolution::Avg128,
+
+        // We only care about low voltage bus and shunt, values larger are truncated to the max
+        bus_voltage_range: BusVoltageRange::Fsr16v,
+        shunt_voltage_range: ShuntVoltageRange::Fsr40mv,
+
+        // Measure both signals continuously (default)
+        operating_mode: OperatingMode::Continous(MeasuredSignals::ShutAndBusVoltage),
+
+        // Do not perform a reset
+        reset: Reset::Run,
+    })?;
+
+    // Wait for the for measurement to be done
+    let conversion_time: Duration = ina.configuration()?.conversion_time().unwrap();
+    std::thread::sleep(conversion_time);
+
+    let measurements = ina.next_measurement()?.expect("Conversion is done now");
+    println!(
+        "Bus:   {:.2}  V",
+        measurements.bus_voltage.voltage_mv() as f32 / 1000.0
+    );
+    println!(
+        "Shunt: {:.2} mV",
+        measurements.shunt_voltage.shunt_voltage_mv() as f32
+    );
+
+    Ok(())
+}

examples/minimal.rs

@@ -0,0 +1,17 @@
+use ina219::address::Address;
+use ina219::SyncIna219;
+use linux_embedded_hal::I2cdev;
+use std::error::Error;
+
+fn main() -> Result<(), Box<dyn Error>> {
+    let device = I2cdev::new("/dev/i2c-1")?;
+    let mut ina = SyncIna219::new(device, Address::from_byte(0x42)?)?;
+
+    // Wait until a result is ready
+    std::thread::sleep(ina.configuration()?.conversion_time().unwrap());
+
+    println!("Bus Voltage: {}", ina.bus_voltage()?);
+    println!("Shunt Voltage: {}", ina.shunt_voltage()?);
+
+    Ok(())
+}

examples/triggered.rs

@@ -0,0 +1,43 @@
+use ina219::address::Address;
+use ina219::configuration::{Configuration, MeasuredSignals, OperatingMode};
+use ina219::SyncIna219;
+use linux_embedded_hal::I2cdev;
+use std::error::Error;
+use std::time::Duration;
+
+fn main() -> Result<(), Box<dyn Error>> {
+    let device = I2cdev::new("/dev/i2c-1")?;
+    let mut ina = SyncIna219::new(device, Address::from_byte(0x42)?)?;
+
+    ina.set_configuration(Configuration {
+        // Only measure if we kindly ask
+        operating_mode: OperatingMode::Triggered(MeasuredSignals::ShutAndBusVoltage),
+        ..Configuration::default()
+    })?;
+
+    // Wait for the for measurement to be done
+    let conversion_time: Duration = ina.configuration()?.conversion_time().unwrap();
+    std::thread::sleep(conversion_time);
+
+    // Writing the configuration started the first measurement
+    let measurements = ina.next_measurement()?;
+    println!("After configuration: {:?}", measurements);
+    assert!(measurements.is_some());
+
+    // If we wait and check again there will be no new data
+    std::thread::sleep(conversion_time);
+    let measurements = ina.next_measurement()?;
+    println!("After no trigger: {:?}", measurements);
+    assert!(measurements.is_none());
+
+    // But we can start a new conversion using a trigger
+    ina.trigger()?;
+
+    std::thread::sleep(conversion_time);
+
+    let measurements = ina.next_measurement()?;
+    println!("After trigger: {:?}", measurements);
+    assert!(measurements.is_some());
+
+    Ok(())
+}