diff options
author | Markus Reiter <me@reitermark.us> | 2024-11-23 22:49:30 +0100 |
---|---|---|
committer | GitHub <noreply@github.com> | 2024-11-23 22:49:30 +0100 |
commit | 0edd5527161809dfbc0c76e39c462e3a4f00beb7 (patch) | |
tree | bb55dd2015752ce100d21682a5f452b9f5c4d208 | |
parent | d3af2b6074e8698b8b83f79758e23070a8b80002 (diff) | |
download | ads1x1x-async-0edd5527161809dfbc0c76e39c462e3a4f00beb7.tar.gz ads1x1x-async-0edd5527161809dfbc0c76e39c462e3a4f00beb7.tar.xz ads1x1x-async-0edd5527161809dfbc0c76e39c462e3a4f00beb7.zip |
Improve documentation. (#32)
* Use `non_exhaustive`.
* Improve docs.
-rw-r--r-- | CHANGELOG.md | 2 | ||||
-rw-r--r-- | README.md | 5 | ||||
-rw-r--r-- | src/channel.rs | 3 | ||||
-rw-r--r-- | src/devices/common.rs | 4 | ||||
-rw-r--r-- | src/devices/features/mod.rs | 3 | ||||
-rw-r--r-- | src/devices/features/tier1.rs | 6 | ||||
-rw-r--r-- | src/devices/features/tier2.rs | 54 | ||||
-rw-r--r-- | src/devices/mode/continuous.rs | 8 | ||||
-rw-r--r-- | src/devices/mode/mod.rs | 2 | ||||
-rw-r--r-- | src/devices/mode/oneshot.rs | 13 | ||||
-rw-r--r-- | src/ic.rs | 6 | ||||
-rw-r--r-- | src/lib.rs | 28 | ||||
-rw-r--r-- | src/types.rs | 14 |
13 files changed, 75 insertions, 73 deletions
diff --git a/CHANGELOG.md b/CHANGELOG.md index 788abc2..28f41cc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -49,7 +49,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. When changing into continuous mode the measurements are started and to stop one can simply change into one-shot mode. (This is how the hardware does it anyway). The one-shot mode is not affected. - When changing the mode an I2C communication error can occur but the unchanged device + When changing the mode an I²C communication error can occur but the unchanged device can now be retrieved. ## [0.1.0] - 2018-11-21 @@ -48,7 +48,7 @@ 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 is transferred through I2C. +periods. Data is transferred through I²C. Here is a comparison of the caracteristics of the devices: @@ -70,8 +70,7 @@ Datasheets: 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(...)`. +as an example. Please find additional examples using hardware in this repository: [driver-examples] diff --git a/src/channel.rs b/src/channel.rs index 4b7555e..4d6e028 100644 --- a/src/channel.rs +++ b/src/channel.rs @@ -1,4 +1,5 @@ -//! ADC input channels +//! ADC input channels. + use crate::{ic, Ads1x1x, BitFlags as BF, Config}; use private::ChannelSelection; diff --git a/src/devices/common.rs b/src/devices/common.rs index 53cb050..66a6d97 100644 --- a/src/devices/common.rs +++ b/src/devices/common.rs @@ -1,4 +1,4 @@ -//! Common functions +//! Common functions. use crate::{devices::OperatingMode, Ads1x1x, BitFlags, Config, Error, Register}; @@ -30,7 +30,7 @@ where Ok(()) } - /// Read whether a measurement is currently in progress. + /// Checks whether a measurement is currently in progress. pub fn is_measurement_in_progress(&mut self) -> Result<bool, Error<E>> { let config = Config { bits: self.read_register(Register::CONFIG)?, diff --git a/src/devices/features/mod.rs b/src/devices/features/mod.rs index c24b7b4..e64f25a 100644 --- a/src/devices/features/mod.rs +++ b/src/devices/features/mod.rs @@ -1,5 +1,4 @@ -//! Implementation of IC features separated in tiers depending on the hardware -//! support. +//! Implementation of IC features separated in tiers depending on the hardware support. mod tier1; mod tier2; diff --git a/src/devices/features/tier1.rs b/src/devices/features/tier1.rs index c6aa8cd..3a8beb9 100644 --- a/src/devices/features/tier1.rs +++ b/src/devices/features/tier1.rs @@ -1,4 +1,4 @@ -//! Common functions +//! Features supported on all ADS1x1x devices. use crate::{ic, Ads1x1x, BitFlags as BF, DataRate12Bit, DataRate16Bit, Error, Register}; @@ -6,7 +6,7 @@ impl<I2C, IC, MODE, E> Ads1x1x<I2C, IC, ic::Resolution12Bit, MODE> where I2C: embedded_hal::i2c::I2c<Error = E>, { - /// Set data rate + /// Sets the data rate. pub fn set_data_rate(&mut self, rate: DataRate12Bit) -> Result<(), Error<E>> { use crate::DataRate12Bit as DR; let cfg = self.config.clone(); @@ -29,7 +29,7 @@ impl<I2C, IC, MODE, E> Ads1x1x<I2C, IC, ic::Resolution16Bit, MODE> where I2C: embedded_hal::i2c::I2c<Error = E>, { - /// Set data rate + /// Sets the data rate. pub fn set_data_rate(&mut self, rate: DataRate16Bit) -> Result<(), Error<E>> { use crate::DataRate16Bit as DR; let cfg = self.config.clone(); diff --git a/src/devices/features/tier2.rs b/src/devices/features/tier2.rs index 5f25b41..fe36a72 100644 --- a/src/devices/features/tier2.rs +++ b/src/devices/features/tier2.rs @@ -1,6 +1,4 @@ -//! Tier 2 features. -//! -//! These are the features included only in ADS1x14, ADS1x15 +//! Features only supported by ADS1x14 and ADS1x15 devices. use crate::{ conversion, ic, Ads1x1x, BitFlags as BF, ComparatorLatching, ComparatorMode, @@ -13,9 +11,9 @@ where IC: ic::Tier2Features, CONV: conversion::ConvertThreshold<E>, { - /// Set the input voltage measurable range + /// Sets the input voltage measurable range. /// - /// This configures the programmable gain amplifier and determines the measurable input voltage range. + /// This configures the programmable gain amplifier (PGA) and determines the measurable input voltage range. pub fn set_full_scale_range(&mut self, range: FullScaleRange) -> Result<(), Error<E>> { use crate::FullScaleRange as FSR; let cfg = self.config.clone(); @@ -47,29 +45,31 @@ where Ok(()) } - /// Set raw comparator lower threshold + /// Sets the raw comparator lower threshold. + /// + /// The voltage that these values correspond to must be calculated using the + /// full-scale range ([`FullScaleRange`]) selected. /// /// The input value must be within `[2047..-2048]` for 12-bit devices (`ADS101x`) - /// and within `[32767..-32768]` for 16-bit devices (`ADS111x`). The voltage that - /// these values correspond to must be calculated using the full-scale range - /// selected. See [`FullScaleRange`](enum.FullScaleRange.html). + /// and within `[32767..-32768]` for 16-bit devices (`ADS111x`). pub fn set_low_threshold_raw(&mut self, value: i16) -> Result<(), Error<E>> { let register_value = CONV::convert_threshold(value)?; self.write_register(Register::LOW_TH, register_value) } - /// Set raw comparator upper threshold + /// Sets the raw comparator upper threshold. + /// + /// The voltage that these values correspond to must be calculated using the + /// full-scale range ([`FullScaleRange`]) selected. /// /// The input value must be within `[2047..-2048]` for 12-bit devices (`ADS101x`) - /// and within `[32767..-32768]` for 16-bit devices (`ADS111x`). The voltage that - /// these values correspond to must be calculated using the full-scale range - /// selected. See [`FullScaleRange`](enum.FullScaleRange.html). + /// and within `[32767..-32768]` for 16-bit devices (`ADS111x`). pub fn set_high_threshold_raw(&mut self, value: i16) -> Result<(), Error<E>> { let register_value = CONV::convert_threshold(value)?; self.write_register(Register::HIGH_TH, register_value) } - /// Set comparator mode + /// Sets the comparator mode. pub fn set_comparator_mode(&mut self, mode: ComparatorMode) -> Result<(), Error<E>> { let config = match mode { ComparatorMode::Traditional => self.config.with_low(BF::COMP_MODE), @@ -80,7 +80,7 @@ where Ok(()) } - /// Set comparator polarity + /// Sets the comparator polarity. pub fn set_comparator_polarity( &mut self, polarity: ComparatorPolarity, @@ -94,7 +94,7 @@ where Ok(()) } - /// Set comparator latching + /// Sets the comparator latching. pub fn set_comparator_latching( &mut self, latching: ComparatorLatching, @@ -108,9 +108,9 @@ where Ok(()) } - /// Activate comparator and set the alert queue + /// Activates the comparator and sets the alert queue. /// - /// The comparator can be disabled with [`disable_comparator()`](struct.Ads1x1x.html#method.disable_comparator) + /// The comparator can be disabled with [`disable_comparator`](Self::disable_comparator). pub fn set_comparator_queue(&mut self, queue: ComparatorQueue) -> Result<(), Error<E>> { let config = match queue { ComparatorQueue::One => self.config.with_low(BF::COMP_QUE1).with_low(BF::COMP_QUE0), @@ -122,11 +122,12 @@ where Ok(()) } - /// Disable comparator (default) + /// Disables the comparator. (default) + /// + /// This sets the ALERT/RDY pin to high-impedance. /// - /// This will set the ALERT/RDY pin to high-impedance. - /// The comparator can be enabled by setting the comparator queue. - /// See [`set_comparator_queue()`](struct.Ads1x1x.html#method.set_comparator_queue) + /// The comparator can be enabled by setting the comparator queue using + /// the [`set_comparator_queue`](Self::set_comparator_queue) method. pub fn disable_comparator(&mut self) -> Result<(), Error<E>> { let config = self .config @@ -137,13 +138,12 @@ where Ok(()) } - /// Use the ALERT/RDY pin as conversion-ready pin. + /// Enables the ALERT/RDY pin as conversion-ready function. /// - /// This the ALERT/RDY pin outputs the OS bit when in OneShot mode, and - /// provides a continuous-conversion ready pulse when in - /// continuous-conversion mode. + /// When in one-shot mode, this makes the ALERT/RDY pin output the OS bit, + /// in continuous-conversion mode, provides a continuous-conversion ready pulse. /// - /// When calling this the comparator will be reset to default and the thresholds will be cleared. + /// When calling this the comparator will be reset to default and any thresholds will be cleared. pub fn use_alert_rdy_pin_as_ready(&mut self) -> Result<(), Error<E>> { if self.config != self diff --git a/src/devices/mode/continuous.rs b/src/devices/mode/continuous.rs index edc87c2..d514a9a 100644 --- a/src/devices/mode/continuous.rs +++ b/src/devices/mode/continuous.rs @@ -1,4 +1,4 @@ -//! Continuous measurement mode +//! Continuous measurement mode. use crate::{ conversion, devices::OperatingMode, mode, Ads1x1x, ChannelId, Error, ModeChangeError, Register, @@ -10,7 +10,7 @@ where I2C: embedded_hal::i2c::I2c<Error = E>, CONV: conversion::ConvertMeasurement, { - /// Change operating mode to OneShot + /// Changes to one-shot operating mode. pub fn into_one_shot( mut self, ) -> Result<Ads1x1x<I2C, IC, CONV, mode::OneShot>, ModeChangeError<E, Self>> { @@ -29,13 +29,13 @@ where }) } - /// Read the most recent measurement + /// Reads the most recent measurement. pub fn read(&mut self) -> Result<i16, Error<E>> { let value = self.read_register(Register::CONVERSION)?; Ok(CONV::convert_measurement(value)) } - /// Select the channel for measurements. + /// Selects the channel used for measurements. /// /// Note that when changing the channel in continuous conversion mode, the /// ongoing conversion will be completed. diff --git a/src/devices/mode/mod.rs b/src/devices/mode/mod.rs index 670ebe9..356c67a 100644 --- a/src/devices/mode/mod.rs +++ b/src/devices/mode/mod.rs @@ -1,4 +1,2 @@ -//! Functions for all devices specific to each operating mode - mod continuous; mod oneshot; diff --git a/src/devices/mode/oneshot.rs b/src/devices/mode/oneshot.rs index 10cdadb..22b6d51 100644 --- a/src/devices/mode/oneshot.rs +++ b/src/devices/mode/oneshot.rs @@ -1,16 +1,18 @@ -//! Common functions +//! One-shot measurement mode. + +use core::marker::PhantomData; + use crate::{ conversion, devices::OperatingMode, mode, Ads1x1x, BitFlags, ChannelId, Config, Error, ModeChangeError, Register, }; -use core::marker::PhantomData; impl<I2C, IC, CONV, E> Ads1x1x<I2C, IC, CONV, mode::OneShot> where I2C: embedded_hal::i2c::I2c<Error = E>, CONV: conversion::ConvertMeasurement, { - /// Change operating mode to Continuous + /// Changes to continuous operating mode. pub fn into_continuous( mut self, ) -> Result<Ads1x1x<I2C, IC, CONV, mode::Continuous>, ModeChangeError<E, Self>> { @@ -40,13 +42,12 @@ where I2C: embedded_hal::i2c::I2c<Error = E>, CONV: conversion::ConvertMeasurement, { - /// Request that the ADC begin a conversion on the specified channel. + /// Requests that the ADC begins a conversion on the specified channel. /// /// The output value will be within `[2047..-2048]` for 12-bit devices /// (`ADS101x`) and within `[32767..-32768]` for 16-bit devices (`ADS111x`). /// The voltage that these values correspond to must be calculated using - /// the full-scale range selected. - /// See [`FullScaleRange`](enum.FullScaleRange.html). + /// the full-scale range ([`FullScaleRange`](crate::FullScaleRange)) selected. /// /// Returns `nb::Error::WouldBlock` while a measurement is in progress. /// @@ -1,8 +1,10 @@ /// ICs use crate::private; -pub struct Resolution12Bit(pub(crate) ()); -pub struct Resolution16Bit(pub(crate) ()); +#[non_exhaustive] +pub struct Resolution12Bit; +#[non_exhaustive] +pub struct Resolution16Bit; macro_rules! ic_marker { ($name:ident) => { @@ -36,7 +36,7 @@ //! [`disable_comparator()`]: struct.Ads1x1x.html#method.disable_comparator //! [`use_alert_rdy_pin_as_ready()`]: struct.Ads1x1x.html#method.use_alert_rdy_pin_as_ready //! -//! ## The devices +//! # 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 @@ -55,7 +55,7 @@ //! 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 is transferred through I2C. +//! periods. Data is transferred through I²C. //! //! Here is a comparison of the caracteristics of the devices: //! @@ -72,19 +72,17 @@ //! - [ADS101x](http://www.ti.com/lit/ds/symlink/ads1015.pdf) //! - [ADS111x](http://www.ti.com/lit/ds/symlink/ads1115.pdf) //! -//! ## Usage examples (see also examples folder) +//! # Examples //! //! 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(...)`. +//! In the following examples an instance of the device ADS1013 will be created. //! //! Please find additional examples using hardware in this repository: [driver-examples] //! //! [driver-examples]: https://github.com/eldruin/driver-examples //! -//! ### Create a driver instance for an ADS1013 with the default address. +//! ## Creating a Driver Instance for an ADS1013 //! //! ```no_run //! use linux_embedded_hal::I2cdev; @@ -98,7 +96,7 @@ //! let dev = adc.destroy_ads1013(); //! ``` //! -//! ### Create a driver instance for an ADS1013 with the ADDR pin connected to SDA. +//! ## Creating a driver instance for an ADS1013 with the ADDR pin connected to SDA. //! //! ```no_run //! use linux_embedded_hal::I2cdev; @@ -108,7 +106,8 @@ //! let adc = Ads1x1x::new_ads1013(dev, TargetAddr::Sda); //! ``` //! -//! ### Make a one-shot measurement +//! ## Taking a One-Shot Measurement +//! //! ```no_run //! use ads1x1x::{channel, Ads1x1x, TargetAddr}; //! use linux_embedded_hal::I2cdev; @@ -121,7 +120,7 @@ //! let _dev = adc.destroy_ads1013(); // get I2C device back //! ``` //! -//! ### Change into continuous conversion mode and read the last measurement +//! ## Changing to Continuous Conversion Mode and Reading the Last Measurement //! //! Changing the mode may fail in case there was a communication error. //! In this case, you can retrieve the unchanged device from the error type. @@ -133,7 +132,9 @@ //! let dev = I2cdev::new("/dev/i2c-1").unwrap(); //! let adc = Ads1x1x::new_ads1013(dev, TargetAddr::default()); //! match adc.into_continuous() { -//! Err(ModeChangeError::I2C(e, adc)) => /* mode change failed handling */ panic!(), +//! Err(ModeChangeError::I2C(e, adc)) => { +//! panic!("Mode change failed: {e}") +//! }, //! Ok(mut adc) => { //! let measurement = adc.read().unwrap(); //! // ... @@ -142,7 +143,7 @@ //! ``` //! //! -//! ### Set the data rate +//! ## Setting the Data Rate //! For 12-bit devices, the available data rates are given by `DataRate12Bit`. //! For 16-bit devices, the available data rates are given by `DataRate16Bit`. //! @@ -155,7 +156,8 @@ //! adc.set_data_rate(DataRate16Bit::Sps860).unwrap(); //! ``` //! -//! ### Configure the comparator +//! ## Configuring the Comparator +//! //! Configure the comparator to assert when the voltage drops below -1.5V //! or goes above 1.5V in at least two consecutive conversions. Then the //! ALERT/RDY pin will be set high and it will be kept so until the diff --git a/src/types.rs b/src/types.rs index 1e4b075..e240780 100644 --- a/src/types.rs +++ b/src/types.rs @@ -31,7 +31,7 @@ pub mod mode { pub struct Continuous(()); } -/// Data rate for ADS1013, ADS1014, ADS1015 +/// Data rate for ADS101x. #[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Ord, PartialOrd, Hash)] pub enum DataRate12Bit { /// 128 SPS @@ -51,7 +51,7 @@ pub enum DataRate12Bit { Sps3300, } -/// Data rate for ADS1113, ADS1114, ADS1115 +/// Data rate for ADS111x. #[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Ord, PartialOrd, Hash)] pub enum DataRate16Bit { /// 8 SPS @@ -73,7 +73,7 @@ pub enum DataRate16Bit { Sps860, } -/// Comparator mode (only for ADS1x14, ADS1x15) +/// Comparator mode (only for ADS1x14, ADS1x15). #[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Ord, PartialOrd, Hash)] pub enum ComparatorMode { #[default] @@ -92,7 +92,7 @@ pub enum ComparatorMode { Window, } -/// Comparator polarity (only for ADS1x14, ADS1x15) +/// Comparator polarity (only for ADS1x14, ADS1x15). #[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Ord, PartialOrd, Hash)] pub enum ComparatorPolarity { #[default] @@ -102,7 +102,7 @@ pub enum ComparatorPolarity { ActiveHigh, } -/// Comparator latching (only for ADS1x14, ADS1x15) +/// Comparator latching (only for ADS1x14, ADS1x15). /// /// Select whether the ALERT/RDY pin latches after being asserted or clears /// after conversions are within the margin of the upper and lower @@ -123,7 +123,7 @@ pub enum ComparatorLatching { Latching, } -/// Comparator alert queue (only for ADS1x14, ADS1x15) +/// Comparator alert queue (only for ADS1x14, ADS1x15). /// /// The default state of the comparator is deactivated. It can be activated by setting /// the comparator queue. @@ -138,7 +138,7 @@ pub enum ComparatorQueue { Four, } -/// Full-scale range configuration for the programmable gain amplifier (PGA) (only for ADS1x14, ADS1x15) +/// Full-scale range configuration for the programmable gain amplifier (PGA) (only for ADS1x14, ADS1x15). /// /// This sets the input voltage measurable range. /// The FSR is fixed at ±2.048 V in the ADS1x13. |