Add embedded-hal-async support

Cargo.toml

@@ -20,12 +20,17 @@ exclude = [
     ".gitignore",
 ]
 
-
 [dependencies]
-defmt = { version = "0.3.2", optional = true }
+defmt = { version = "0.3.8", optional = true }
 embedded-hal = "1.0.0"
-fixed = "1.20.0"
-sensirion-i2c = "0.3.0"
+embedded-hal-async = { version = "1.0.0", optional = true }
+fixed = "1.28.0"
+sensirion-i2c = "0.4"
 
 [features]
 defmt = ["dep:defmt"]
+embedded-hal-async = ["dep:embedded-hal-async", "sensirion-i2c/embedded-hal-async"]
+
+[package.metadata.docs.rs]
+all-features = true
+rustdoc-args = ["--cfg", "docsrs"]

README.md

@@ -58,6 +58,30 @@ if let Ok(measurement) = measurement {
 }
 ```
 
+## `embedded-hal-async` support
+
+This crate has optional support for the [`embedded-hal-async`] crate, which
+provides `async` versions of the `I2c` and `DelayNs` traits. Async support
+is an off-by-default optional feature, so that projects which aren't using
+[`embedded-hal-async`] can avoid the additional dependency.
+
+To use this crate with `embedded-hal-async`, enable the `embedded-hal-async`
+feature flag in your `Cargo.toml`:
+
+```toml
+sht4x = { version = "0.2", features = ["embedded-hal-async"] }
+```
+
+Once the `embedded-hal-async` feature is enabled, construct an instance of
+the `Sht4xAsync` struct, providing types implementing the
+[`embedded_hal_async::i2c::I2c`] and [`embedded_hal_async::delay::DelayNs`]
+traits. The `Sht4xAsync` struct is identical to the `Sht4x` struct,
+except that its methods are `async fn`s.
+
+[`embedded-hal-async`]: https://crates.io/crates/embedded-hal-async
+[`embedded_hal_async::i2c::I2c`]: https://docs.rs/embedded-hal-async/latest/embedded_hal_async/i2c/trait.I2c.html
+[`embedded_hal_async::delay::DelayNs`]: https://docs.rs/embedded-hal-async/latest/embedded_hal_async/delay/trait.DelayNs.html
+
 
 ## Related Work
 

src/error.rs

@@ -1,4 +1,3 @@
-use embedded_hal::i2c::I2c;
 use sensirion_i2c::i2c;
 
 /// Error conditions from accessing SHT4x sensors.
@@ -12,11 +11,11 @@ pub enum Error<E> {
     Crc,
 }
 
-impl<I> From<i2c::Error<I>> for Error<I::Error>
+impl<E> From<i2c::Error<E>> for Error<E::Error>
 where
-    I: I2c,
+    E: embedded_hal::i2c::ErrorType,
 {
-    fn from(err: i2c::Error<I>) -> Self {
+    fn from(err: i2c::Error<E>) -> Self {
         match err {
             i2c::Error::Crc => Error::Crc,
             i2c::Error::I2cRead(e) => Error::I2c(e),

src/lib.rs

@@ -1,12 +1,19 @@
 #![deny(unsafe_code)]
 #![no_std]
 #![doc = include_str!("../README.md")]
+#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
 
 mod commands;
 mod error;
+mod responses;
 mod sht4x;
 mod types;
 
+#[cfg(feature = "embedded-hal-async")]
+mod sht4x_async;
+#[cfg(feature = "embedded-hal-async")]
+pub use self::sht4x_async::Sht4xAsync;
+
 pub use crate::error::*;
 pub use crate::sht4x::*;
 pub use crate::types::*;

src/responses.rs

@@ -0,0 +1,23 @@
+use crate::types::SensorData;
+
+const PAYLOAD_LEN: usize = 4;
+pub(crate) const RESPONSE_LEN: usize = 6;
+
+fn response_payload(response: [u8; RESPONSE_LEN]) -> [u8; PAYLOAD_LEN] {
+    // Response data comes in chunks of three bytes: [MSB, LSB, CRC]. The CRCs got already checked
+    // by sensirion_i2c::read_words_with_crc. So we just have to extract the payload data here.
+    [response[0], response[1], response[3], response[4]]
+}
+
+pub(crate) fn sensor_data_from_response(response: [u8; RESPONSE_LEN]) -> SensorData {
+    let payload = response_payload(response);
+    SensorData {
+        temperature: u16::from_be_bytes([payload[0], payload[1]]),
+        humidity: u16::from_be_bytes([payload[2], payload[3]]),
+    }
+}
+
+pub(crate) fn serial_number_from_response(response: [u8; RESPONSE_LEN]) -> u32 {
+    let payload = response_payload(response);
+    u32::from_be_bytes(payload)
+}

src/sht4x.rs

@@ -1,14 +1,13 @@
 use crate::{
     commands::Command,
     error::Error,
+    responses::{sensor_data_from_response, serial_number_from_response, RESPONSE_LEN},
     types::{Address, HeatingDuration, HeatingPower, Measurement, Precision, SensorData},
 };
 use core::marker::PhantomData;
 use embedded_hal::{delay::DelayNs, i2c::I2c};
 use sensirion_i2c::i2c;
 
-const RESPONSE_LEN: usize = 6;
-
 /// Driver for STH4x sensors.
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[derive(Debug, Eq, Hash, PartialEq)]
@@ -108,7 +107,7 @@ where
 
         self.write_command_and_delay_for_execution(command, delay)?;
         let response = self.read_response()?;
-        let raw = self.sensor_data_from_response(&response);
+        let raw = sensor_data_from_response(response);
 
         Ok(raw)
     }
@@ -133,7 +132,7 @@ where
 
         self.write_command_and_delay_for_execution(command, delay)?;
         let response = self.read_response()?;
-        let raw = self.sensor_data_from_response(&response);
+        let raw = sensor_data_from_response(response);
 
         Ok(raw)
     }
@@ -142,13 +141,7 @@ where
     pub fn serial_number(&mut self, delay: &mut D) -> Result<u32, Error<I::Error>> {
         self.write_command_and_delay_for_execution(Command::SerialNumber, delay)?;
         let response = self.read_response()?;
-
-        Ok(u32::from_be_bytes([
-            response[0],
-            response[1],
-            response[3],
-            response[4],
-        ]))
+        Ok(serial_number_from_response(response))
     }
 
     /// Performs a soft reset of the sensor.
@@ -164,13 +157,6 @@ where
         Ok(response)
     }
 
-    fn sensor_data_from_response(&self, response: &[u8; RESPONSE_LEN]) -> SensorData {
-        SensorData {
-            temperature: u16::from_be_bytes([response[0], response[1]]),
-            humidity: u16::from_be_bytes([response[3], response[4]]),
-        }
-    }
-
     fn write_command_and_delay_for_execution(
         &mut self,
         command: Command,

src/sht4x_async.rs

@@ -0,0 +1,159 @@
+use crate::{
+    commands::Command,
+    error::Error,
+    responses::{sensor_data_from_response, serial_number_from_response, RESPONSE_LEN},
+    types::{Address, HeatingDuration, HeatingPower, Measurement, Precision, SensorData},
+};
+use core::marker::PhantomData;
+use embedded_hal_async::{delay::DelayNs, i2c::I2c};
+use sensirion_i2c::i2c_async;
+
+/// Async driver for STH4x sensors.
+///
+/// This type behaves identically to the [`Sht4x`](crate::Sht4x) type, except
+/// that it uses the `embedded-hal-async` [`I2c`] and [`DelayNs`] traits instead
+/// of the `embedded-hal` traits, and all of its methods are `async fn`s.
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+#[derive(Debug)]
+pub struct Sht4xAsync<I, D> {
+    i2c: I,
+    address: Address,
+    // If we want to globally define the delay type for this struct, we have to consume the type
+    // parameter.
+    _delay: PhantomData<D>,
+}
+
+impl<I, D> Sht4xAsync<I, D>
+where
+    I: I2c,
+    D: DelayNs,
+{
+    /// Creates a new driver instance using the given I2C bus. It configures the default I2C
+    /// address 0x44 used by most family members.
+    ///
+    /// For operating multiple devices on the same bus,
+    /// [`shared-bus`](https://github.com/Rahix/shared-bus) might come in handy.
+    pub fn new(i2c: I) -> Self {
+        Self::new_with_address(i2c, Address::Address0x44)
+    }
+
+    /// Crates a new driver instance using the given I2C bus and address. This constructor allows
+    /// to instantiate the driver for the SHT40-BD1B which uses the non-default I2C address 0x45.
+    ///
+    /// For operating multiple devices on the same bus,
+    /// [`shared-bus`](https://github.com/Rahix/shared-bus) might come in handy.
+    pub fn new_with_address(i2c: I, address: Address) -> Self {
+        Self {
+            i2c,
+            address,
+            _delay: PhantomData,
+        }
+    }
+
+    /// Destroys the driver and returns the used I2C bus.
+    pub fn destroy(self) -> I {
+        self.i2c
+    }
+
+    /// Activates the heater and performs a measurement returning measurands in SI units.
+    ///
+    /// **Note:** The heater is designed to be used up to 10 % of the sensor's lifetime. Please
+    /// check the
+    /// [datasheet](https://sensirion.com/media/documents/33FD6951/624C4357/Datasheet_SHT4x.pdf),
+    /// section 4.9 _Heater Operation_ for details.
+    pub async fn heat_and_measure(
+        &mut self,
+        power: HeatingPower,
+        duration: HeatingDuration,
+        delay: &mut D,
+    ) -> Result<Measurement, Error<I::Error>> {
+        let raw = self.heat_and_measure_raw(power, duration, delay).await?;
+
+        Ok(Measurement::from(raw))
+    }
+
+    /// Activates the heater and performs a measurement returning raw sensor data.
+    ///
+    /// **Note:** The heater is designed to be used up to 10 % of the sensor's lifetime. Please
+    /// check the
+    /// [datasheet](https://sensirion.com/media/documents/33FD6951/624C4357/Datasheet_SHT4x.pdf),
+    /// section 4.9 _Heater Operation_ for details.
+    pub async fn heat_and_measure_raw(
+        &mut self,
+        power: HeatingPower,
+        duration: HeatingDuration,
+        delay: &mut D,
+    ) -> Result<SensorData, Error<I::Error>> {
+        let command = Command::from((power, duration));
+
+        self.write_command_and_delay_for_execution(command, delay)
+            .await?;
+        let response = self.read_response().await?;
+        let raw = sensor_data_from_response(response);
+
+        Ok(raw)
+    }
+
+    /// Performs a measurement returning measurands in SI units.
+    pub async fn measure(
+        &mut self,
+        precision: Precision,
+        delay: &mut D,
+    ) -> Result<Measurement, Error<I::Error>> {
+        let raw = self.measure_raw(precision, delay).await?;
+        Ok(Measurement::from(raw))
+    }
+
+    /// Performs a measurement returning raw sensor data.
+    pub async fn measure_raw(
+        &mut self,
+        precision: Precision,
+        delay: &mut D,
+    ) -> Result<SensorData, Error<I::Error>> {
+        let command = Command::from(precision);
+
+        self.write_command_and_delay_for_execution(command, delay)
+            .await?;
+        let response = self.read_response().await?;
+        let raw = sensor_data_from_response(response);
+
+        Ok(raw)
+    }
+
+    /// Reads the sensor's serial number.
+    pub async fn serial_number(&mut self, delay: &mut D) -> Result<u32, Error<I::Error>> {
+        self.write_command_and_delay_for_execution(Command::SerialNumber, delay)
+            .await?;
+        let response = self.read_response().await?;
+        Ok(serial_number_from_response(response))
+    }
+
+    /// Performs a soft reset of the sensor.
+    pub async fn soft_reset(&mut self, delay: &mut D) -> Result<(), Error<I::Error>> {
+        self.write_command_and_delay_for_execution(Command::SoftReset, delay)
+            .await
+    }
+
+    async fn read_response(&mut self) -> Result<[u8; RESPONSE_LEN], Error<I::Error>> {
+        let mut response = [0; RESPONSE_LEN];
+
+        i2c_async::read_words_with_crc(&mut self.i2c, self.address.into(), &mut response).await?;
+
+        Ok(response)
+    }
+
+    async fn write_command_and_delay_for_execution(
+        &mut self,
+        command: Command,
+        delay: &mut D,
+    ) -> Result<(), Error<I::Error>> {
+        let code = command.code();
+
+        i2c_async::write_command_u8(&mut self.i2c, self.address.into(), code)
+            .await
+            .map_err(Error::I2c)?;
+        delay.delay_ms(command.duration_ms()).await;
+
+        Ok(())
+    }
+}