summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMarkus Reiter <me@reitermark.us>2024-11-23 22:49:30 +0100
committerGitHub <noreply@github.com>2024-11-23 22:49:30 +0100
commit0edd5527161809dfbc0c76e39c462e3a4f00beb7 (patch)
treebb55dd2015752ce100d21682a5f452b9f5c4d208
parentd3af2b6074e8698b8b83f79758e23070a8b80002 (diff)
downloadads1x1x-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.md2
-rw-r--r--README.md5
-rw-r--r--src/channel.rs3
-rw-r--r--src/devices/common.rs4
-rw-r--r--src/devices/features/mod.rs3
-rw-r--r--src/devices/features/tier1.rs6
-rw-r--r--src/devices/features/tier2.rs54
-rw-r--r--src/devices/mode/continuous.rs8
-rw-r--r--src/devices/mode/mod.rs2
-rw-r--r--src/devices/mode/oneshot.rs13
-rw-r--r--src/ic.rs6
-rw-r--r--src/lib.rs28
-rw-r--r--src/types.rs14
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
diff --git a/README.md b/README.md
index 9ef686d..0ba4f49 100644
--- a/README.md
+++ b/README.md
@@ -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.
///
diff --git a/src/ic.rs b/src/ic.rs
index 56dfc6a..8e4db42 100644
--- a/src/ic.rs
+++ b/src/ic.rs
@@ -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) => {
diff --git a/src/lib.rs b/src/lib.rs
index 2a7597d..2e111a4 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -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.