Skip to content

Commit 608b39e

Browse files
reitermarkusreitermarkus
committed
Rename AdcChannel to Voltmeter and add Ammeter.
1 parent 9ed5035 commit 608b39e

File tree

2 files changed

+182
-57
lines changed

2 files changed

+182
-57
lines changed

‎embedded-hal-async/src/adc.rs‎

Lines changed: 97 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -2,23 +2,18 @@
22
33
pub use embedded_hal::adc::{Error, ErrorKind, ErrorType};
44

5-
/// Read data from an ADC.
6-
///
7-
/// # Note for Implementers
8-
///
9-
/// This should wait until data is ready and then read it.
5+
/// Asynchronous voltmeter for measuring voltage.
106
///
117
/// # Examples
128
///
13-
/// In the first naive example, [`AdcChannel`] is implemented
14-
/// using a spin loop and only returns once data is ready.
9+
/// In the first naive example, [`Voltmeter`] is implemented using a spin loop.
1510
///
1611
/// ```
17-
/// # use embedded_hal_async::adc::{AdcChannel, ErrorKind, ErrorType, Error};
18-
/// #
19-
/// struct MySpinningAdc;
12+
/// use embedded_hal_async::adc::{ErrorKind, ErrorType, Error, Voltmeter};
13+
///
14+
/// struct MySpinningVoltmeter;
2015
///
21-
/// impl MySpinningAdc {
16+
/// impl MySpinningVoltmeter {
2217
/// pub fn is_ready(&mut self) -> bool {
2318
/// // Just pretend this returns `false` the first few times.
2419
/// true
@@ -29,21 +24,21 @@ pub use embedded_hal::adc::{Error, ErrorKind, ErrorType};
2924
/// }
3025
/// }
3126
///
32-
/// impl ErrorType for MySpinningAdc {
27+
/// impl ErrorType for MySpinningVoltmeter {
3328
/// type Error = ErrorKind;
3429
/// }
3530
///
36-
/// impl AdcChannel for MySpinningAdc {
31+
/// impl Voltmeter for MySpinningVoltmeter {
3732
/// async fn measure_nv(&mut self) -> Result<i64, Self::Error> {
3833
/// Ok(self.measure_mv().await? as i64 * 1_000_000)
3934
/// }
4035
///
41-
/// async fn measure_mv(&mut self) -> Result<i32, Self::Error> {
36+
/// async fn measure_mv(&mut self) -> Result<i16, Self::Error> {
4237
/// while !self.is_ready() {
4338
/// core::hint::spin_loop();
4439
/// }
4540
///
46-
/// Ok(self.data() as i32)
41+
/// Ok(self.data() as i16)
4742
/// }
4843
/// }
4944
/// ```
@@ -52,28 +47,31 @@ pub use embedded_hal::adc::{Error, ErrorKind, ErrorType};
5247
/// When the “ready pin” goes high, data is ready.
5348
///
5449
/// ```
55-
/// # use embedded_hal_async::{adc::{self, ErrorKind, ErrorType, Error, AdcChannel}, digital::{self, Wait, Error as _, ErrorType as _}};
56-
/// #
57-
/// struct MyWaitingAdc<T> {
50+
/// use embedded_hal_async::{
51+
/// adc::{self, ErrorKind, ErrorType, Error, Voltmeter},
52+
/// digital::{self, Wait, Error as _, ErrorType as _},
53+
/// };
54+
///
55+
/// struct MyWaitingVoltmeter<T> {
5856
/// ready_pin: T,
5957
/// };
6058
///
61-
/// impl<T> MyWaitingAdc<T> {
59+
/// impl<T> MyWaitingVoltmeter<T> {
6260
/// pub fn data(&mut self) -> u16 {
6361
/// 3300
6462
/// }
6563
/// }
6664
///
67-
/// impl<T> adc::ErrorType for MyWaitingAdc<T> {
65+
/// impl<T> adc::ErrorType for MyWaitingVoltmeter<T> {
6866
/// type Error = adc::ErrorKind;
6967
/// }
7068
///
71-
/// impl<T: Wait> AdcChannel for MyWaitingAdc<T> {
69+
/// impl<T: Wait> Voltmeter for MyWaitingVoltmeter<T> {
7270
/// async fn measure_nv(&mut self) -> Result<i64, Self::Error> {
7371
/// Ok(self.measure_mv().await? as i64 * 1_000_000)
7472
/// }
7573
///
76-
/// async fn measure_mv(&mut self) -> Result<i32, Self::Error> {
74+
/// async fn measure_mv(&mut self) -> Result<i16, Self::Error> {
7775
/// match self.ready_pin.wait_for_high().await {
7876
/// Ok(()) => (),
7977
/// Err(err) => return Err(match err.kind() {
@@ -82,28 +80,43 @@ pub use embedded_hal::adc::{Error, ErrorKind, ErrorType};
8280
/// })
8381
/// }
8482
///
85-
/// Ok(self.data() as i32)
83+
/// Ok(self.data() as i16)
8684
/// }
8785
/// }
8886
/// ```
89-
pub trait AdcChannel: ErrorType {
90-
/// Take a measurement in nV (nanovolts).
87+
pub trait Voltmeter: ErrorType {
88+
/// Measures voltage in nV (nanovolts).
89+
///
90+
/// This can measure between -9223372036.854775808V and 9223372036.854775807V.
9191
async fn measure_nv(&mut self) -> Result<i64, Self::Error>;
9292

93-
/// Take a measurement in mV (microvolts).
93+
/// Measures voltage in mV (microvolts).
94+
///
95+
/// This can measure between -2147.483648V and 2147.483647V.
96+
/// If you need to measure a larger range, use [`measure_nv`](Voltmeter::measure_nv) instead.
97+
///
98+
/// When overriding the default implementation, ensure that the measured voltage is clamped
99+
/// between [`i32::MIN`] and [`i32::MAX`].
94100
async fn measure_uv(&mut self) -> Result<i32, Self::Error> {
95-
Ok((self.measure_nv().await? / 1_000) as i32)
101+
Ok((self.measure_nv().await? / 1_000).clamp(i32::MIN.into(), i32::MAX.into()) as i32)
96102
}
97103

98-
/// Take a measurement in mV (millivolts).
99-
async fn measure_mv(&mut self) -> Result<i32, Self::Error> {
100-
Ok(self.measure_uv().await? / 1_000)
104+
/// Measures voltage in mV (millivolts).
105+
///
106+
/// This can measure between between -32.768V and 32.767V.
107+
/// If you need to measure a larger range,
108+
/// use [`measure_uv`](Voltmeter::measure_uv) or [`measure_nv`](Voltmeter::measure_nv) instead.
109+
///
110+
/// When overriding the default implementation, ensure that the measured voltage is clamped
111+
/// between [`i16::MIN`] and [`i16::MAX`].
112+
async fn measure_mv(&mut self) -> Result<i16, Self::Error> {
113+
Ok((self.measure_uv().await? / 1_000).clamp(i16::MIN.into(), i16::MAX.into()) as i16)
101114
}
102115
}
103116

104-
impl<T> AdcChannel for &mut T
117+
impl<T> Voltmeter for &mut T
105118
where
106-
T: AdcChannel + ?Sized,
119+
T: Voltmeter + ?Sized,
107120
{
108121
#[inline]
109122
async fn measure_nv(&mut self) -> Result<i64, Self::Error> {
@@ -116,7 +129,58 @@ where
116129
}
117130

118131
#[inline]
119-
async fn measure_mv(&mut self) -> Result<i32, Self::Error> {
132+
async fn measure_mv(&mut self) -> Result<i16, Self::Error> {
120133
(*self).measure_mv().await
121134
}
122135
}
136+
137+
/// Asynchronous ammeter (ampere meter) for measuring current.
138+
pub trait Ammeter: ErrorType {
139+
/// Measures current in nA (nanoampere).
140+
///
141+
/// This can measure between -9223372036.854775808A and 9223372036.854775807A.
142+
async fn measure_na(&mut self) -> Result<i64, Self::Error>;
143+
144+
/// Measures current in uA (microampere).
145+
///
146+
/// This can measure between -2147.483648A and 2147.483647A.
147+
/// If you need to measure a larger range, use [`measure_na`](Ammeter::measure_na) instead.
148+
///
149+
/// When overriding the default implementation, ensure that the measured current is clamped
150+
/// between [`i32::MIN`] and [`i32::MAX`].
151+
async fn measure_ua(&mut self) -> Result<i32, Self::Error> {
152+
Ok((self.measure_na().await? / 1_000).clamp(i32::MIN.into(), i32::MAX.into()) as i32)
153+
}
154+
155+
/// Measures current in mA (milliampere).
156+
///
157+
/// This can measure between between -32.768A and 32.767A.
158+
/// If you need to measure a larger range,
159+
/// use [`measure_ua`](Ammeter::measure_ua) or [`measure_na`](Ammeter::measure_na) instead.
160+
///
161+
/// When overriding the default implementation, ensure that the measured voltage is clamped
162+
/// between [`i16::MIN`] and [`i16::MAX`].
163+
async fn measure_ma(&mut self) -> Result<i16, Self::Error> {
164+
Ok((self.measure_ua().await? / 1_000).clamp(i16::MIN.into(), i16::MAX.into()) as i16)
165+
}
166+
}
167+
168+
impl<T> Ammeter for &mut T
169+
where
170+
T: Ammeter + ?Sized,
171+
{
172+
#[inline]
173+
async fn measure_na(&mut self) -> Result<i64, Self::Error> {
174+
(*self).measure_na().await
175+
}
176+
177+
#[inline]
178+
async fn measure_ua(&mut self) -> Result<i32, Self::Error> {
179+
(*self).measure_ua().await
180+
}
181+
182+
#[inline]
183+
async fn measure_ma(&mut self) -> Result<i16, Self::Error> {
184+
(*self).measure_ma().await
185+
}
186+
}

‎embedded-hal/src/adc.rs‎

Lines changed: 85 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -5,23 +5,18 @@ use core::fmt::{Debug, Display};
55
#[cfg(feature = "defmt-03")]
66
use crate::defmt;
77

8-
/// Read data from an ADC.
9-
///
10-
/// # Note for Implementers
11-
///
12-
/// This should wait until data is ready and then read it.
8+
/// Blocking voltmeter for measuring voltage.
139
///
1410
/// # Examples
1511
///
16-
/// In the first naive example, [`AdcChannel`] is implemented
17-
/// using a spin loop and only returns once data is ready.
12+
/// In the first naive example, [`Voltmeter`] is implemented using a spin loop.
1813
///
1914
/// ```
20-
/// use embedded_hal::adc::{AdcChannel, ErrorKind, ErrorType, Error};
15+
/// use embedded_hal::adc::{ErrorKind, ErrorType, Error, Voltmeter};
2116
///
22-
/// struct MySpinningAdc;
17+
/// struct MySpinningVoltmeter;
2318
///
24-
/// impl MySpinningAdc {
19+
/// impl MySpinningVoltmeter {
2520
/// pub fn is_ready(&mut self) -> bool {
2621
/// // Just pretend this returns `false` the first few times.
2722
/// true
@@ -32,42 +27,57 @@ use crate::defmt;
3227
/// }
3328
/// }
3429
///
35-
/// impl ErrorType for MySpinningAdc {
30+
/// impl ErrorType for MySpinningVoltmeter {
3631
/// type Error = ErrorKind;
3732
/// }
3833
///
39-
/// impl AdcChannel for MySpinningAdc {
34+
/// impl Voltmeter for MySpinningVoltmeter {
4035
/// fn measure_nv(&mut self) -> Result<i64, Self::Error> {
4136
/// Ok(self.measure_mv()? as i64 * 1_000_000)
4237
/// }
4338
///
44-
/// fn measure_mv(&mut self) -> Result<i32, Self::Error> {
39+
/// fn measure_mv(&mut self) -> Result<i16, Self::Error> {
4540
/// while !self.is_ready() {
4641
/// core::hint::spin_loop();
4742
/// }
4843
///
49-
/// Ok(self.data() as i32)
44+
/// Ok(self.data() as i16)
5045
/// }
5146
/// }
5247
/// ```
53-
pub trait AdcChannel: ErrorType {
54-
/// Take a measurement in nV (nanovolts).
48+
pub trait Voltmeter: ErrorType {
49+
/// Measures voltage in nV (nanovolts).
50+
///
51+
/// This can measure between -9223372036.854775808V and 9223372036.854775807V.
5552
fn measure_nv(&mut self) -> Result<i64, Self::Error>;
5653

57-
/// Take a measurement in mV (microvolts).
54+
/// Measures voltage in mV (microvolts).
55+
///
56+
/// This can measure between -2147.483648V and 2147.483647V.
57+
/// If you need to measure a larger range, use [`measure_nv`](Voltmeter::measure_nv) instead.
58+
///
59+
/// When overriding the default implementation, ensure that the measured voltage is clamped
60+
/// between [`i32::MIN`] and [`i32::MAX`].
5861
fn measure_uv(&mut self) -> Result<i32, Self::Error> {
59-
Ok((self.measure_nv()? / 1_000) as i32)
62+
Ok((self.measure_nv()? / 1_000).clamp(i32::MIN.into(), i32::MAX.into()) as i32)
6063
}
6164

62-
/// Take a measurement in mV (millivolts).
63-
fn measure_mv(&mut self) -> Result<i32, Self::Error> {
64-
Ok(self.measure_uv()? / 1_000)
65+
/// Measures voltage in mV (millivolts).
66+
///
67+
/// This can measure between between -32.768V and 32.767V.
68+
/// If you need to measure a larger range,
69+
/// use [`measure_uv`](Voltmeter::measure_uv) or [`measure_mv`](Voltmeter::measure_mv) instead.
70+
///
71+
/// When overriding the default implementation, ensure that the measured voltage is clamped
72+
/// between [`i16::MIN`] and [`i16::MAX`].
73+
fn measure_mv(&mut self) -> Result<i16, Self::Error> {
74+
Ok((self.measure_uv()? / 1_000).clamp(i16::MIN.into(), i16::MAX.into()) as i16)
6575
}
6676
}
6777

68-
impl<T> AdcChannel for &mut T
78+
impl<T> Voltmeter for &mut T
6979
where
70-
T: AdcChannel + ?Sized,
80+
T: Voltmeter + ?Sized,
7181
{
7282
#[inline]
7383
fn measure_nv(&mut self) -> Result<i64, Self::Error> {
@@ -80,11 +90,62 @@ where
8090
}
8191

8292
#[inline]
83-
fn measure_mv(&mut self) -> Result<i32, Self::Error> {
93+
fn measure_mv(&mut self) -> Result<i16, Self::Error> {
8494
(*self).measure_mv()
8595
}
8696
}
8797

98+
/// Blocking ammeter (ampere meter) for measuring current.
99+
pub trait Ammeter: ErrorType {
100+
/// Measures current in nA (nanoampere).
101+
///
102+
/// This can measure between -9223372036.854775808A and 9223372036.854775807A.
103+
fn measure_na(&mut self) -> Result<i64, Self::Error>;
104+
105+
/// Measures current in uA (microampere).
106+
///
107+
/// This can measure between -2147.483648A and 2147.483647A.
108+
/// If you need to measure a larger range, use [`measure_na`](Ammeter::measure_na) instead.
109+
///
110+
/// When overriding the default implementation, ensure that the measured current is clamped
111+
/// between [`i32::MIN`] and [`i32::MAX`].
112+
fn measure_ua(&mut self) -> Result<i32, Self::Error> {
113+
Ok((self.measure_na()? / 1_000).clamp(i32::MIN.into(), i32::MAX.into()) as i32)
114+
}
115+
116+
/// Measures current in mA (milliampere).
117+
///
118+
/// This can measure between between -32.768A and 32.767A.
119+
/// If you need to measure a larger range,
120+
/// use [`measure_ua`](Ammeter::measure_ua) or [`measure_na`](Ammeter::measure_na) instead.
121+
///
122+
/// When overriding the default implementation, ensure that the measured voltage is clamped
123+
/// between [`i16::MIN`] and [`i16::MAX`].
124+
fn measure_ma(&mut self) -> Result<i16, Self::Error> {
125+
Ok((self.measure_ua()? / 1_000).clamp(i16::MIN.into(), i16::MAX.into()) as i16)
126+
}
127+
}
128+
129+
impl<T> Ammeter for &mut T
130+
where
131+
T: Ammeter + ?Sized,
132+
{
133+
#[inline]
134+
fn measure_na(&mut self) -> Result<i64, Self::Error> {
135+
(*self).measure_na()
136+
}
137+
138+
#[inline]
139+
fn measure_ua(&mut self) -> Result<i32, Self::Error> {
140+
(*self).measure_ua()
141+
}
142+
143+
#[inline]
144+
fn measure_ma(&mut self) -> Result<i16, Self::Error> {
145+
(*self).measure_ma()
146+
}
147+
}
148+
88149
/// ADC error.
89150
pub trait Error: Debug {
90151
/// Convert error to a generic ADC error kind.

0 commit comments

Comments
 (0)