path: root/src/lib.rs

//! This is a platform-agnostic Rust driver for the ADS1013, ADS1014, ADS1015,
//! ADS1113, ADS1114, ADS1115, ADS1018 and ADS1118 ultra-small, low-power
//! analog-to-digital converters (ADC), based on the [`embedded-hal`] traits.
//!
//! [`embedded-hal`]: https://github.com/rust-embedded/embedded-hal
//!
//! This driver allows you to:
//! - Set the operating mode to one-shot or continuous. See: [`into_continuous()`].
//! - Make a measurement in one-shot mode. See: [`read()`].
//! - Set the data rate. See: [`set_data_rate()`].
//! - Set the low and high thresholds. See: [`set_high_threshold()`].
//! - Set the comparator mode. See: [`set_comparator_mode()`].
//! - Set the comparator polarity. See: [`set_comparator_polarity()`].
//!
//! [`into_continuous()`]: struct.Ads1x1x.html#method.into_continuous
//! [`read()`]: struct.Ads1x1x.html#method.read
//! [`set_data_rate()`]: struct.Ads1x1x.html#method.set_data_rate
//! [`set_high_threshold()`]: struct.Ads1x1x.html#method.set_high_threshold
//! [`set_comparator_mode()`]: struct.Ads1x1x.html#method.set_comparator_mode
//! [`set_comparator_polarity()`]: struct.Ads1x1x.html#method.set_comparator_polarity
//!
//! ## The devices
//!
//! The devices are precision, low power, 12/16-bit analog-to-digital
//! converters (ADC) that provide all features necessary to measure the most
//! common sensor signals in an ultra-small package. Depending on the device,
//! these  integrate a programmable gain amplifier (PGA), voltage reference,
//! oscillator and high-accuracy temperature sensor.
//!
//! The devices can perform conversions at data rates up to 3300 samples per
//! second (SPS). The PGA offers input ranges from ±256 mV to ±6.144 V,
//! allowing both large and small signals to be measured with high resolution.
//! An input multiplexer (MUX) allows to measure two differential or four
//! single-ended inputs. The high-accuracy temperature sensor can be used for
//! system-level temperature monitoring or cold-junction compensation for
//! thermocouples.
//!
//! The devices operate either in continuous-conversion mode, or in a
//! single-shot mode that automatically powers down after a conversion.
//! Single-shot mode significantly reduces current consumption during idle
//! periods. Data are transferred through a I2C or SPI.
//!
//! Here is a comparison of the caracteristics of the devices:
//!
//! | Device  | Resolution | Sample Rate  | Channels | Interface | Multi-channel | Features                     |
//! |---------|------------|--------------|----------|-----------|---------------|------------------------------|
//! | ADS1013 | 12-bit     | Max 3300 SPS | 1        | I2C       | N/A           |                              |
//! | ADS1014 | 12-bit     | Max 3300 SPS | 1        | I2C       | N/A           | Comparator, PGA              |
//! | ADS1015 | 12-bit     | Max 3300 SPS | 4        | I2C       | Multiplexed   | Comparator, PGA              |
//! | ADS1018 | 12-bit     | Max 3300 SPS | 4        | SPI       | Multiplexed   | Comparator, PGA, Temp sensor |
//! | ADS1113 | 16-bit     | Max 860 SPS  | 1        | I2C       | N/A           |                              |
//! | ADS1114 | 16-bit     | Max 860 SPS  | 1        | I2C       | N/A           | Comparator, PGA              |
//! | ADS1115 | 16-bit     | Max 860 SPS  | 4        | I2C       | Multiplexed   | Comparator, PGA              |
//! | ADS1118 | 16-bit     | Max 860 SPS  | 4        | SPI       | Multiplexed   | Comparator, PGA, Temp sensor |
//!
//! Datasheets:
//! - [ADS101x](http://www.ti.com/lit/ds/symlink/ads1015.pdf)
//! - [ADS1018](http://www.ti.com/lit/ds/symlink/ads1018.pdf)
//! - [ADS111x](http://www.ti.com/lit/ds/symlink/ads1115.pdf)
//! - [ADS1118](http://www.ti.com/lit/ds/symlink/ads1118.pdf)
//!
//! ## Usage examples (see also examples folder)
//!
//! To use this driver, import this crate and an `embedded_hal` implementation,
//! then instantiate the appropriate device.
//! In the following examples an instance of the device ADS1013 will be created
//! as an example. Other devices can be created with similar methods like:
//! `Ads1x1x::new_ads1114(...)`.
//!
//! ### Create a driver instance for the ADS1013
//!
//! ```no_run
//! extern crate linux_embedded_hal as hal;
//! extern crate ads1x1x;
//! use ads1x1x::{ Ads1x1x, SlaveAddr };
//!
//! # fn main() {
//! let dev = hal::I2cdev::new("/dev/i2c-1").unwrap();
//! let address = SlaveAddr::default();
//! let rtc = Ads1x1x::new_ads1013(dev, address);
//! // do something...
//!
//! // get the I2C device back
//! let dev = rtc.destroy_ads1013();
//! # }
//! ```
//!
//! ### Create a driver instance for the ADS1013 with an alternative address
//!
//! ```no_run
//! extern crate linux_embedded_hal as hal;
//! extern crate ads1x1x;
//! use ads1x1x::{ Ads1x1x, SlaveAddr };
//!
//! # fn main() {
//! let dev = hal::I2cdev::new("/dev/i2c-1").unwrap();
//! let (a1, a0) = (true, false);
//! let address = SlaveAddr::Alternative(a1, a0);
//! let rtc = Ads1x1x::new_ads1013(dev, address);
//! # }
//! ```

#![deny(unsafe_code)]
#![deny(missing_docs)]
#![deny(warnings)]
#![no_std]

extern crate nb;
extern crate embedded_hal as hal;
use core::marker::PhantomData;

/// All possible errors in this crate
#[derive(Debug)]
pub enum Error<E> {
    /// I²C/SPI bus error
    Comm(E),
    /// Invalid input data provided
    InvalidInputData
}

const DEVICE_BASE_ADDRESS : u8 = 0b100_1000;

/// Mode marker types
pub mod mode {
    /// One-shot operating mode / power-down state (default)
    pub struct OneShot(());

    /// Continuous conversion mode
    pub struct Continuous(());
}

/// Data rate
#[derive(Debug, Clone, PartialEq)]
pub enum DataRate {
    /// 128 SPS
    Sps128,
    /// 250 SPS
    Sps250,
    /// 490 SPS
    Sps490,
    /// 920 SPS
    Sps920,
    /// 1600 SPS (default)
    Sps1600,
    /// 2400 SPS
    Sps2400,
    /// 3300 SPS
    Sps3300
}

/// Comparator mode (only for ADS1x14, ADS1x15)
#[derive(Debug, Clone, PartialEq)]
pub enum ComparatorMode {
    /// Traditional comparator (default)
    ///
    /// In this mode the ALERT/RDY pin asserts (according to selected active
    /// polarity) when the conversion data exceeds the limit set as *high*
    /// threshold and remains active until the conversion data falls below the
    /// value set as *low* threshold.
    Traditional,
    /// Window comparator
    ///
    /// In this mode the ALERT/RDY pin asserts (according to selected active
    /// polarity) when the conversion data exceeds the value set as *high*
    /// threshold or goes below the value set as *low* temperature threshold.
    Window
}

/// Comparator polarity (only for ADS1x14, ADS1x15)
#[derive(Debug, Clone, PartialEq)]
pub enum ComparatorPolarity {
    /// Active low (default)
    ActiveLow,
    /// Active high
    ActiveHigh
}

/// Possible slave addresses
#[derive(Debug, Clone)]
pub enum SlaveAddr {
    /// Default slave address
    Default,
    /// Alternative slave address providing bit values for A1 and A0
    Alternative(bool, bool)
}

impl Default for SlaveAddr {
    /// Default slave address
    fn default() -> Self {
        SlaveAddr::Default
    }
}

impl SlaveAddr {
    fn addr(self, default: u8) -> u8 {
        match self {
            SlaveAddr::Default => default,
            SlaveAddr::Alternative(a1, a0) => default           |
                                              ((a1 as u8) << 1) |
                                                a0 as u8
        }
    }
}

struct Register;

impl Register {
    const CONVERSION : u8 = 0x00;
    const CONFIG     : u8 = 0x01;
    const LOW_TH     : u8 = 0x02;
    const HIGH_TH    : u8 = 0x03;
}

struct BitFlags;
impl BitFlags {
    const OP_MODE      : u16 = 0b0000_0001_0000_0000;
    const OS           : u16 = 0b1000_0000_0000_0000;
    const DR2          : u16 = 0b0000_0000_1000_0000;
    const DR1          : u16 = 0b0000_0000_0100_0000;
    const DR0          : u16 = 0b0000_0000_0010_0000;
    const COMP_MODE    : u16 = 0b0000_0000_0001_0000;
    const COMP_POL     : u16 = 0b0000_0000_0000_1000;
}


#[derive(Debug, Clone)]
struct Config {
    bits: u16
}

impl Config {
    fn is_high(&self, mask : u16) -> bool {
        (self.bits & mask) != 0
    }

    fn with_high(&self, mask: u16) -> Self {
        Config { bits: self.bits | mask }
    }
    fn with_low(&self, mask: u16) -> Self {
        Config { bits: self.bits & !mask }
    }
}

impl Default for Config {
    fn default() -> Self {
        Config { bits: 0x8583 }
    }
}

/// ADS1x1x ADC driver
#[derive(Debug, Default)]
pub struct Ads1x1x<DI, IC, MODE> {
    iface: DI,
    config: Config,
    a_conversion_was_started: bool,
    _ic: PhantomData<IC>,
    _mode: PhantomData<MODE>
}

#[doc(hidden)]
pub mod interface;
mod devices;
pub use devices::ic;
pub use devices::channel;

mod private {
    use super::{ devices::ic, interface };
    pub trait Sealed {}

    impl<I2C> Sealed for interface::I2cInterface<I2C> {}
    impl<SPI, CS> Sealed for interface::SpiInterface<SPI, CS> {}

    impl Sealed for ic::Ads1013 {}
    impl Sealed for ic::Ads1113 {}
    impl Sealed for ic::Ads1014 {}
    impl Sealed for ic::Ads1114 {}
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn can_get_default_address() {
        let addr = SlaveAddr::default();
        assert_eq!(DEVICE_BASE_ADDRESS, addr.addr(DEVICE_BASE_ADDRESS));
    }

    #[test]
    fn can_generate_alternative_addresses() {
        assert_eq!(0b100_1000, SlaveAddr::Alternative(false, false).addr(DEVICE_BASE_ADDRESS));
        assert_eq!(0b100_1001, SlaveAddr::Alternative(false,  true).addr(DEVICE_BASE_ADDRESS));
        assert_eq!(0b100_1010, SlaveAddr::Alternative(true, false).addr(DEVICE_BASE_ADDRESS));
        assert_eq!(0b100_1011, SlaveAddr::Alternative(true,  true).addr(DEVICE_BASE_ADDRESS));
    }
}