eldruin / ads1x1x-rs / 11962679483

coverage: 81.739% (-1.1%) from 82.819%
11962679483

Pull #32

github

web-flow 
Merge a20bff9e8 into d3af2b607
Pull Request #32: Improve documentation.

188 of 230 relevant lines covered (81.74%)

3.01 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

25.0
/src/lib.rs
1 
//! This is a platform-agnostic Rust driver for the ADS1013, ADS1014, ADS1015,
2 
//! ADS1113, ADS1114, and ADS1115 ultra-small, low-power
3 
//! analog-to-digital converters (ADC), based on the [`embedded-hal`] traits.
4 
//!
5 
//! [`embedded-hal`]: https://github.com/rust-embedded/embedded-hal
6 
//!
7 
//! This driver allows you to:
8 
//! - Set the operating mode to one-shot or continuous. See: [`into_continuous()`].
9 
//! - Make a measurement in one-shot mode. See: [`read()`][read_os].
10 
//! - Start continuous conversion mode. See: [`start()`].
11 
//! - Read the last measurement made in continuous conversion mode. See: [`read()`][read_cont].
12 
//! - Set the data rate. See: [`set_data_rate()`].
13 
//! - Set the full-scale range (gain amplifier). See [`set_full_scale_range()`].
14 
//! - Read whether a measurement is in progress. See: [`is_measurement_in_progress()`].
15 
//! - Set the ALERT/RDY pin to be used as conversion-ready pin. See: [`use_alert_rdy_pin_as_ready()`].
16 
//! - Comparator:
17 
//!     - Set the low and high thresholds. See: [`set_high_threshold_raw()`].
18 
//!     - Set the comparator mode. See: [`set_comparator_mode()`].
19 
//!     - Set the comparator polarity. See: [`set_comparator_polarity()`].
20 
//!     - Set the comparator latching. See: [`set_comparator_latching()`].
21 
//!     - Set the comparator queue. See: [`set_comparator_queue()`].
22 
//!     - Disable the comparator. See: [`disable_comparator()`].
23 
//!
24 
//! [`into_continuous()`]: struct.Ads1x1x.html#method.into_continuous
25 
//! [read_os]: struct.Ads1x1x.html#method.read-1
26 
//! [`start()`]: struct.Ads1x1x.html#method.start
27 
//! [read_cont]: struct.Ads1x1x.html#method.read
28 
//! [`set_data_rate()`]: struct.Ads1x1x.html#method.set_data_rate
29 
//! [`set_full_scale_range()`]: struct.Ads1x1x.html#method.set_full_scale_range
30 
//! [`is_measurement_in_progress()`]: struct.Ads1x1x.html#method.is_measurement_in_progress
31 
//! [`set_high_threshold_raw()`]: struct.Ads1x1x.html#method.set_high_threshold_raw
32 
//! [`set_comparator_mode()`]: struct.Ads1x1x.html#method.set_comparator_mode
33 
//! [`set_comparator_polarity()`]: struct.Ads1x1x.html#method.set_comparator_polarity
34 
//! [`set_comparator_latching()`]: struct.Ads1x1x.html#method.set_comparator_latching
35 
//! [`set_comparator_queue()`]: struct.Ads1x1x.html#method.set_comparator_queue
36 
//! [`disable_comparator()`]: struct.Ads1x1x.html#method.disable_comparator
37 
//! [`use_alert_rdy_pin_as_ready()`]: struct.Ads1x1x.html#method.use_alert_rdy_pin_as_ready
38 
//!
39 
//! # The devices
40 
//!
41 
//! The devices are precision, low power, 12/16-bit analog-to-digital
42 
//! converters (ADC) that provide all features necessary to measure the most
43 
//! common sensor signals in an ultra-small package. Depending on the device,
44 
//! these  integrate a programmable gain amplifier (PGA), voltage reference,
45 
//! oscillator and high-accuracy temperature sensor.
46 
//!
47 
//! The devices can perform conversions at data rates up to 3300 samples per
48 
//! second (SPS). The PGA offers input ranges from ±256 mV to ±6.144 V,
49 
//! allowing both large and small signals to be measured with high resolution.
50 
//! An input multiplexer (MUX) allows to measure two differential or four
51 
//! single-ended inputs. The high-accuracy temperature sensor can be used for
52 
//! system-level temperature monitoring or cold-junction compensation for
53 
//! thermocouples.
54 
//!
55 
//! The devices operate either in continuous-conversion mode, or in a
56 
//! single-shot mode that automatically powers down after a conversion.
57 
//! Single-shot mode significantly reduces current consumption during idle
58 
//! periods. Data is transferred through I²C.
59 
//!
60 
//! Here is a comparison of the caracteristics of the devices:
61 
//!
62 
//! | Device  | Resolution | Sample Rate  | Channels | Multi-channel | Features        |
63 
//! |---------|------------|--------------|----------|---------------|-----------------|
64 
//! | ADS1013 | 12-bit     | Max 3300 SPS | 1        | N/A           |                 |
65 
//! | ADS1014 | 12-bit     | Max 3300 SPS | 1        | N/A           | Comparator, PGA |
66 
//! | ADS1015 | 12-bit     | Max 3300 SPS | 4        | Multiplexed   | Comparator, PGA |
67 
//! | ADS1113 | 16-bit     | Max 860 SPS  | 1        | N/A           |                 |
68 
//! | ADS1114 | 16-bit     | Max 860 SPS  | 1        | N/A           | Comparator, PGA |
69 
//! | ADS1115 | 16-bit     | Max 860 SPS  | 4        | Multiplexed   | Comparator, PGA |
70 
//!
71 
//! Datasheets:
72 
//! - [ADS101x](http://www.ti.com/lit/ds/symlink/ads1015.pdf)
73 
//! - [ADS111x](http://www.ti.com/lit/ds/symlink/ads1115.pdf)
74 
//!
75 
//! # Examples
76 
//!
77 
//! To use this driver, import this crate and an `embedded_hal` implementation,
78 
//! then instantiate the appropriate device.
79 
//! In the following examples an instance of the device ADS1013 will be created.
80 
//!
81 
//! Please find additional examples using hardware in this repository: [driver-examples]
82 
//!
83 
//! [driver-examples]: https://github.com/eldruin/driver-examples
84 
//!
85 
//! ## Creating a Driver Instance for an ADS1013
86 
//!
87 
//! ```no_run
88 
//! use linux_embedded_hal::I2cdev;
89 
//! use ads1x1x::{Ads1x1x, TargetAddr};
90 
//!
91 
//! let dev = I2cdev::new("/dev/i2c-1").unwrap();
92 
//! let adc = Ads1x1x::new_ads1013(dev, TargetAddr::default());
93 
//! // do something...
94 
//!
95 
//! // get the I2C device back
96 
//! let dev = adc.destroy_ads1013();
97 
//! ```
98 
//!
99 
//! ### Creating a driver instance for an ADS1013 with the ADDR pin connected to SDA.
100 
//!
101 
//! ```no_run
102 
//! use linux_embedded_hal::I2cdev;
103 
//! use ads1x1x::{Ads1x1x, TargetAddr};
104 
//!
105 
//! let dev = I2cdev::new("/dev/i2c-1").unwrap();
106 
//! let adc = Ads1x1x::new_ads1013(dev, TargetAddr::Sda);
107 
//! ```
108 
//!
109 
//! ## Taking a One-Shot Measurement
110 
//!
111 
//! ```no_run
112 
//! use ads1x1x::{channel, Ads1x1x, TargetAddr};
113 
//! use linux_embedded_hal::I2cdev;
114 
//! use nb::block;
115 
//!
116 
//! let dev = I2cdev::new("/dev/i2c-1").unwrap();
117 
//! let mut adc = Ads1x1x::new_ads1013(dev, TargetAddr::default());
118 
//! let measurement = block!(adc.read(channel::DifferentialA0A1)).unwrap();
119 
//! println!("Measurement: {}", measurement);
120 
//! let _dev = adc.destroy_ads1013(); // get I2C device back
121 
//! ```
122 
//!
123 
//! ## Changing to Continuous Conversion Mode and Reading the Last Measurement
124 
//!
125 
//! Changing the mode may fail in case there was a communication error.
126 
//! In this case, you can retrieve the unchanged device from the error type.
127 
//!
128 
//! ```no_run
129 
//! use linux_embedded_hal::I2cdev;
130 
//! use ads1x1x::{Ads1x1x, ModeChangeError, TargetAddr};
131 
//!
132 
//! let dev = I2cdev::new("/dev/i2c-1").unwrap();
133 
//! let adc = Ads1x1x::new_ads1013(dev, TargetAddr::default());
134 
//! match adc.into_continuous() {
135 
//!     Err(ModeChangeError::I2C(e, adc)) => /* mode change failed handling */ panic!(),
136 
//!     Ok(mut adc) => {
137 
//!         let measurement = adc.read().unwrap();
138 
//!         // ...
139 
//!     }
140 
//! }
141 
//! ```
142 
//!
143 
//!
144 
//! ## Setting the Data Rate
145 
//! For 12-bit devices, the available data rates are given by `DataRate12Bit`.
146 
//! For 16-bit devices, the available data rates are given by `DataRate16Bit`.
147 
//!
148 
//! ```no_run
149 
//! use linux_embedded_hal::I2cdev;
150 
//! use ads1x1x::{Ads1x1x, DataRate16Bit, TargetAddr};
151 
//!
152 
//! let dev = I2cdev::new("/dev/i2c-1").unwrap();
153 
//! let mut adc = Ads1x1x::new_ads1115(dev, TargetAddr::default());
154 
//! adc.set_data_rate(DataRate16Bit::Sps860).unwrap();
155 
//! ```
156 
//!
157 
//! ## Configuring the Comparator
158 
//!
159 
//! Configure the comparator to assert when the voltage drops below -1.5V
160 
//! or goes above 1.5V in at least two consecutive conversions. Then the
161 
//! ALERT/RDY pin will be set high and it will be kept so until the
162 
//! measurement is read or an appropriate SMBus alert response is sent by
163 
//! the controller.
164 
//!
165 
//! ```no_run
166 
//! use linux_embedded_hal::I2cdev;
167 
//! use ads1x1x::{
168 
//!     Ads1x1x, TargetAddr, ComparatorQueue, ComparatorPolarity,
169 
//!     ComparatorMode, ComparatorLatching, FullScaleRange
170 
//! };
171 
//!
172 
//! let dev = I2cdev::new("/dev/i2c-1").unwrap();
173 
//! let address = TargetAddr::default();
174 
//! let mut adc = Ads1x1x::new_ads1015(dev, address);
175 
//! adc.set_comparator_queue(ComparatorQueue::Two).unwrap();
176 
//! adc.set_comparator_polarity(ComparatorPolarity::ActiveHigh).unwrap();
177 
//! adc.set_comparator_mode(ComparatorMode::Window).unwrap();
178 
//! adc.set_full_scale_range(FullScaleRange::Within2_048V).unwrap();
179 
//! adc.set_low_threshold_raw(-1500).unwrap();
180 
//! adc.set_high_threshold_raw(1500).unwrap();
181 
//! adc.set_comparator_latching(ComparatorLatching::Latching).unwrap();
182 
//! ```
183 
#![deny(unsafe_code)]
184 
#![deny(missing_docs)]
185 
#![no_std]
186 









187



struct Register;










188



impl Register {




×







189



    const CONVERSION: u8 = 0x00;










190



    const CONFIG: u8 = 0x01;










191



    const LOW_TH: u8 = 0x02;










192



    const HIGH_TH: u8 = 0x03;










193



}










194












195



struct BitFlags;










196



impl BitFlags {










197



    const OS: u16 = 0b1000_0000_0000_0000;




5✔





198



    const MUX2: u16 = 0b0100_0000_0000_0000;










199



    const MUX1: u16 = 0b0010_0000_0000_0000;










200



    const MUX0: u16 = 0b0001_0000_0000_0000;










201



    const PGA2: u16 = 0b0000_1000_0000_0000;










202



    const PGA1: u16 = 0b0000_0100_0000_0000;










203



    const PGA0: u16 = 0b0000_0010_0000_0000;










204



    const OP_MODE: u16 = 0b0000_0001_0000_0000;










205



    const DR2: u16 = 0b0000_0000_1000_0000;










206



    const DR1: u16 = 0b0000_0000_0100_0000;




5✔





207



    const DR0: u16 = 0b0000_0000_0010_0000;










208



    const COMP_MODE: u16 = 0b0000_0000_0001_0000;










209



    const COMP_POL: u16 = 0b0000_0000_0000_1000;










210



    const COMP_LAT: u16 = 0b0000_0000_0000_0100;










211



    const COMP_QUE1: u16 = 0b0000_0000_0000_0010;










212



    const COMP_QUE0: u16 = 0b0000_0000_0000_0001;










213



}










214












215



pub mod channel;










216



pub use channel::ChannelId;










217



mod construction;










218



mod conversion;










219



pub use crate::conversion::{ConvertMeasurement, ConvertThreshold};










220



mod devices;










221



#[doc(hidden)]










222



pub mod ic;










223



mod types;










224



use crate::types::Config;










225



pub use crate::types::{










226



    mode, Ads1x1x, ComparatorLatching, ComparatorMode, ComparatorPolarity, ComparatorQueue,










227



    DataRate12Bit, DataRate16Bit, Error, FullScaleRange, ModeChangeError, TargetAddr,










228



};










229












230



mod private {










231



    use super::{ic, Ads1x1x};










232



    pub trait Sealed {}










233












234



    impl<I2C, IC, CONV, MODE> Sealed for Ads1x1x<I2C, IC, CONV, MODE> {}




×







235












236



    impl Sealed for ic::Resolution12Bit {}




×







237



    impl Sealed for ic::Resolution16Bit {}










238












239



    impl Sealed for ic::Ads1013 {}




×







240



    impl Sealed for ic::Ads1113 {}










241



    impl Sealed for ic::Ads1014 {}










242



    impl Sealed for ic::Ads1114 {}




×







243



    impl Sealed for ic::Ads1015 {}




×







244



    impl Sealed for ic::Ads1115 {}










245



}
























    

  • 

    •