Skip to content

Commit c3b96f0

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

File tree

2 files changed

+182
-51
lines changed

2 files changed

+182
-51
lines changed

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

Lines changed: 97 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -2,23 +2,19 @@
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
9+
/// In the first naive example, [`Voltmeter`] is implemented
1410
/// using a spin loop and only returns once data is ready.
1511
///
1612
/// ```
17-
/// # use embedded_hal_async::adc::{AdcChannel, ErrorKind, ErrorType, Error};
18-
/// #
19-
/// struct MySpinningAdc;
13+
/// use embedded_hal_async::adc::{ErrorKind, ErrorType, Error, Voltmeter};
14+
///
15+
/// struct MySpinningVoltmeter;
2016
///
21-
/// impl MySpinningAdc {
17+
/// impl MySpinningVoltmeter {
2218
/// pub fn is_ready(&mut self) -> bool {
2319
/// // Just pretend this returns `false` the first few times.
2420
/// true
@@ -29,21 +25,21 @@ pub use embedded_hal::adc::{Error, ErrorKind, ErrorType};
2925
/// }
3026
/// }
3127
///
32-
/// impl ErrorType for MySpinningAdc {
28+
/// impl ErrorType for MySpinningVoltmeter {
3329
/// type Error = ErrorKind;
3430
/// }
3531
///
36-
/// impl AdcChannel for MySpinningAdc {
32+
/// impl Voltmeter for MySpinningVoltmeter {
3733
/// async fn measure_nv(&mut self) -> Result<i64, Self::Error> {
3834
/// Ok(self.measure_mv().await? as i64 * 1_000_000)
3935
/// }
4036
///
41-
/// async fn measure_mv(&mut self) -> Result<i32, Self::Error> {
37+
/// async fn measure_mv(&mut self) -> Result<i16, Self::Error> {
4238
/// while !self.is_ready() {
4339
/// core::hint::spin_loop();
4440
/// }
4541
///
46-
/// Ok(self.data() as i32)
42+
/// Ok(self.data() as i16)
4743
/// }
4844
/// }
4945
/// ```
@@ -52,28 +48,31 @@ pub use embedded_hal::adc::{Error, ErrorKind, ErrorType};
5248
/// When the “ready pin” goes high, data is ready.
5349
///
5450
/// ```
55-
/// # use embedded_hal_async::{adc::{self, ErrorKind, ErrorType, Error, AdcChannel}, digital::{self, Wait, Error as _, ErrorType as _}};
56-
/// #
57-
/// struct MyWaitingAdc<T> {
51+
/// use embedded_hal_async::{
52+
/// adc::{self, ErrorKind, ErrorType, Error, Voltmeter},
53+
/// digital::{self, Wait, Error as _, ErrorType as _},
54+
/// };
55+
///
56+
/// struct MyWaitingVoltmeter<T> {
5857
/// ready_pin: T,
5958
/// };
6059
///
61-
/// impl<T> MyWaitingAdc<T> {
60+
/// impl<T> MyWaitingVoltmeter<T> {
6261
/// pub fn data(&mut self) -> u16 {
6362
/// 3300
6463
/// }
6564
/// }
6665
///
67-
/// impl<T> adc::ErrorType for MyWaitingAdc<T> {
66+
/// impl<T> adc::ErrorType for MyWaitingVoltmeter<T> {
6867
/// type Error = adc::ErrorKind;
6968
/// }
7069
///
71-
/// impl<T: Wait> AdcChannel for MyWaitingAdc<T> {
70+
/// impl<T: Wait> Voltmeter for MyWaitingVoltmeter<T> {
7271
/// async fn measure_nv(&mut self) -> Result<i64, Self::Error> {
7372
/// Ok(self.measure_mv().await? as i64 * 1_000_000)
7473
/// }
7574
///
76-
/// async fn measure_mv(&mut self) -> Result<i32, Self::Error> {
75+
/// async fn measure_mv(&mut self) -> Result<i16, Self::Error> {
7776
/// match self.ready_pin.wait_for_high().await {
7877
/// Ok(()) => (),
7978
/// Err(err) => return Err(match err.kind() {
@@ -82,28 +81,43 @@ pub use embedded_hal::adc::{Error, ErrorKind, ErrorType};
8281
/// })
8382
/// }
8483
///
85-
/// Ok(self.data() as i32)
84+
/// Ok(self.data() as i16)
8685
/// }
8786
/// }
8887
/// ```
89-
pub trait AdcChannel: ErrorType {
90-
/// Take a measurement in nV (nanovolts).
88+
pub trait Voltmeter: ErrorType {
89+
/// Measures voltage in nV (nanovolts).
90+
///
91+
/// This can measure between -9223372036.854775808V and 9223372036.854775807V.
9192
async fn measure_nv(&mut self) -> Result<i64, Self::Error>;
9293

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

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

104-
impl<T> AdcChannel for &mut T
118+
impl<T> Voltmeter for &mut T
105119
where
106-
T: AdcChannel + ?Sized,
120+
T: Voltmeter + ?Sized,
107121
{
108122
#[inline]
109123
async fn measure_nv(&mut self) -> Result<i64, Self::Error> {
@@ -116,7 +130,58 @@ where
116130
}
117131

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

‎embedded-hal/src/adc.rs

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

8-
/// Read data from an ADC.
8+
/// Blocking voltmeter for measuring voltage.
99
///
1010
/// # Note for Implementers
1111
///
1212
/// This should wait until data is ready and then read it.
1313
///
1414
/// # Examples
1515
///
16-
/// In the first naive example, [`AdcChannel`] is implemented
16+
/// In the first naive example, [`Voltmeter`] is implemented
1717
/// using a spin loop and only returns once data is ready.
1818
///
1919
/// ```
20-
/// use embedded_hal::adc::{AdcChannel, ErrorKind, ErrorType, Error};
20+
/// use embedded_hal::adc::{ErrorKind, ErrorType, Error, Voltmeter};
2121
///
22-
/// struct MySpinningAdc;
22+
/// struct MySpinningVoltmeter;
2323
///
24-
/// impl MySpinningAdc {
24+
/// impl MySpinningVoltmeter {
2525
/// pub fn is_ready(&mut self) -> bool {
2626
/// // Just pretend this returns `false` the first few times.
2727
/// true
@@ -32,42 +32,57 @@ use crate::defmt;
3232
/// }
3333
/// }
3434
///
35-
/// impl ErrorType for MySpinningAdc {
35+
/// impl ErrorType for MySpinningVoltmeter {
3636
/// type Error = ErrorKind;
3737
/// }
3838
///
39-
/// impl AdcChannel for MySpinningAdc {
39+
/// impl Voltmeter for MySpinningVoltmeter {
4040
/// fn measure_nv(&mut self) -> Result<i64, Self::Error> {
4141
/// Ok(self.measure_mv()? as i64 * 1_000_000)
4242
/// }
4343
///
44-
/// fn measure_mv(&mut self) -> Result<i32, Self::Error> {
44+
/// fn measure_mv(&mut self) -> Result<i16, Self::Error> {
4545
/// while !self.is_ready() {
4646
/// core::hint::spin_loop();
4747
/// }
4848
///
49-
/// Ok(self.data() as i32)
49+
/// Ok(self.data() as i16)
5050
/// }
5151
/// }
5252
/// ```
53-
pub trait AdcChannel: ErrorType {
54-
/// Take a measurement in nV (nanovolts).
53+
pub trait Voltmeter: ErrorType {
54+
/// Measures voltage in nV (nanovolts).
55+
///
56+
/// This can measure between -9223372036.854775808V and 9223372036.854775807V.
5557
fn measure_nv(&mut self) -> Result<i64, Self::Error>;
5658

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

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

68-
impl<T> AdcChannel for &mut T
83+
impl<T> Voltmeter for &mut T
6984
where
70-
T: AdcChannel + ?Sized,
85+
T: Voltmeter + ?Sized,
7186
{
7287
#[inline]
7388
fn measure_nv(&mut self) -> Result<i64, Self::Error> {
@@ -80,11 +95,62 @@ where
8095
}
8196

8297
#[inline]
83-
fn measure_mv(&mut self) -> Result<i32, Self::Error> {
98+
fn measure_mv(&mut self) -> Result<i16, Self::Error> {
8499
(*self).measure_mv()
85100
}
86101
}
87102

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

0 commit comments

Comments
 (0)