dbrgn / shtcx-rs

Platform agnostic Rust driver for the Sensirion SHTCx temperature/humidity sensors.

Rust SHTCx / SHTWx Driver

This is a platform agnostic Rust driver for the Sensirion SHTCx and SHTWx temperature / humidity sensor series, based on the embedded-hal traits.

Tested with the following sensors:

• SHTC1
• SHTC3
• SHTW2

Docs: https://docs.rs/shtcx

The Device

The Sensirion SHTCx series offers low-power high-precision digital temperature and humidity sensors that communicate over the I²C bus.

The SHTWx series uses the same protocol, but in a wafer-level chip-scale package (WLCSP).

Status

• Measure temperature and humidity
• Get device identifier
• Sleep / Wakeup commands
• Soft reset command
• Support for low power mode
• CRC checks
• Docs

Examples

There are a few examples in the examples directory: The linux-<target> example queries the sensor a few times using linux-embedded-hal, while the monitor-<target> example implements a terminal based real-time graphical temperature/humidity monitoring tool.

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT) at your option.

Contributing

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

shtcx-rs's Issues

Using shtcx-rs with esp rust board: Error linking with 'rust-lld' failed

Hello!

Does your crate support no_std?

I am testing your driver with the board esp-rust-board in a public repository

The board that I am using has a esp32-c3 and the project was made using the no-std esp-template

Apart from that in the entry function I have created a delay instance, an embedded_hal I2C device and a ShtCx (shtcx::shtc3) following your example on shtc3.

When I compile I am receiving the next output where it looks like Looks like _defmt_timestamp, _defmt_write, _defmt_release, and _defmt_acquire are not defined:

$ i2c-playground$ cargo build -r

   Compiling i2c-playground v0.1.0 (/home/jubeor/repos/esp32/i2c-playground)
error: linking with `rust-lld` failed: exit status: 1
  |
  = note: LC_ALL="C" PATH="/home/jubeor/.rustup/toolchains/nightly-x86_64-unknown-linux-gnu/lib/rustlib/x86_64-unknown-linux-gnu/bin:/home/jubeor/.rustup/toolchains/nightly-x86_64-unknown-linux-gnu/lib/rustlib/x86_64-unknown-linux-gnu/bin:/home/jubeor/.rustup/toolchains/nightly-x86_64-unknown-linux-gnu/lib/rustlib/x86_64-unknown-linux-gnu/bin:/home/jubeor/.vscode-server/bin/dc96b837cf6bb4af9cd736aa3af08cf8279f7685/bin/remote-cli:/home/jubeor/.local/bin:/home/jubeor/.cargo/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/usr/lib/wsl/lib:/mnt/c/Python312/Scripts/:/mnt/c/Python312/:/mnt/c/WINDOWS/system32:/mnt/c/WINDOWS:/mnt/c/WINDOWS/System32/Wbem:/mnt/c/WINDOWS/System32/WindowsPowerShell/v1.0/:/mnt/c/WINDOWS/System32/OpenSSH/:/mnt/c/Program Files/usbipd-win/:/mnt/c/ProgramData/chocolatey/bin:/mnt/c/Program Files/CMake/bin:/mnt/c/Program Files/Git/cmd:/mnt/c/Program Files/Nordic Semiconductor/nrf-command-line-tools/bin/:/mnt/c/Program Files/Docker/Docker/resources/bin:/mnt/c/Users/julio/.cargo/bin:/mnt/c/Users/julio/AppData/Local/Microsoft/WindowsApps:/mnt/c/Users/julio/AppData/Local/Programs/Microsoft VS Code/bin:/mnt/c/Users/julio/AppData/Local/GitHubDesktop/bin:/mnt/c/Program Files/7-Zip:/snap/bin" VSLANG="1033" "rust-lld" "-flavor" "gnu" "/tmp/rustcAS1JuY/symbols.o" "/home/jubeor/repos/esp32/i2c-playground/target/riscv32imc-unknown-none-elf/release/deps/i2c_playground-0095ce173ac13dc5.i2c_playground.5a238fac89fffd17-cgu.0.rcgu.o" "--as-needed" "-L" "/home/jubeor/repos/esp32/i2c-playground/target/riscv32imc-unknown-none-elf/release/deps" "-L" "/home/jubeor/repos/esp32/i2c-playground/target/release/deps" "-L" "/home/jubeor/repos/esp32/i2c-playground/target/riscv32imc-unknown-none-elf/release/build/defmt-cdbaabff50e00dda/out" "-L" "/home/jubeor/repos/esp32/i2c-playground/target/riscv32imc-unknown-none-elf/release/build/esp-hal-a32f964e66e5afab/out" "-L" "/home/jubeor/repos/esp32/i2c-playground/target/riscv32imc-unknown-none-elf/release/build/esp32c3-fc84e1c9f68b6962/out" "-L" "/home/jubeor/.rustup/toolchains/nightly-x86_64-unknown-linux-gnu/lib/rustlib/riscv32imc-unknown-none-elf/lib" "-Bstatic" "/home/jubeor/repos/esp32/i2c-playground/target/riscv32imc-unknown-none-elf/release/deps/libcompiler_builtins-6283647fa719c848.rlib" "-Bdynamic" "-z" "noexecstack" "-L" "/home/jubeor/.rustup/toolchains/nightly-x86_64-unknown-linux-gnu/lib/rustlib/riscv32imc-unknown-none-elf/lib" "-o" "/home/jubeor/repos/esp32/i2c-playground/target/riscv32imc-unknown-none-elf/release/deps/i2c_playground-0095ce173ac13dc5" "--gc-sections" "-Tlinkall.x"
  = note: rust-lld: error: undefined symbol: _defmt_acquire
          >>> referenced by bit.rs:790 (/home/jubeor/.rustup/toolchains/nightly-x86_64-unknown-linux-gnu/lib/rustlib/src/rust/library/core/src/ops/bit.rs:790)
          >>>               /home/jubeor/repos/esp32/i2c-playground/target/riscv32imc-unknown-none-elf/release/deps/i2c_playground-0095ce173ac13dc5.i2c_playground.5a238fac89fffd17-cgu.0.rcgu.o:(main)
          >>> referenced by bit.rs:790 (/home/jubeor/.rustup/toolchains/nightly-x86_64-unknown-linux-gnu/lib/rustlib/src/rust/library/core/src/ops/bit.rs:790)
          >>>               /home/jubeor/repos/esp32/i2c-playground/target/riscv32imc-unknown-none-elf/release/deps/i2c_playground-0095ce173ac13dc5.i2c_playground.5a238fac89fffd17-cgu.0.rcgu.o:(main)
          >>> referenced by bit.rs:790 (/home/jubeor/.rustup/toolchains/nightly-x86_64-unknown-linux-gnu/lib/rustlib/src/rust/library/core/src/ops/bit.rs:790)
          >>>               /home/jubeor/repos/esp32/i2c-playground/target/riscv32imc-unknown-none-elf/release/deps/i2c_playground-0095ce173ac13dc5.i2c_playground.5a238fac89fffd17-cgu.0.rcgu.o:(main)
          >>> referenced 4 more times
          
          rust-lld: error: undefined symbol: _defmt_release
          >>> referenced by bit.rs:790 (/home/jubeor/.rustup/toolchains/nightly-x86_64-unknown-linux-gnu/lib/rustlib/src/rust/library/core/src/ops/bit.rs:790)
          >>>               /home/jubeor/repos/esp32/i2c-playground/target/riscv32imc-unknown-none-elf/release/deps/i2c_playground-0095ce173ac13dc5.i2c_playground.5a238fac89fffd17-cgu.0.rcgu.o:(main)
          >>> referenced by bit.rs:790 (/home/jubeor/.rustup/toolchains/nightly-x86_64-unknown-linux-gnu/lib/rustlib/src/rust/library/core/src/ops/bit.rs:790)
          >>>               /home/jubeor/repos/esp32/i2c-playground/target/riscv32imc-unknown-none-elf/release/deps/i2c_playground-0095ce173ac13dc5.i2c_playground.5a238fac89fffd17-cgu.0.rcgu.o:(main)
          >>> referenced by mod.rs:1785 (/home/jubeor/.rustup/toolchains/nightly-x86_64-unknown-linux-gnu/lib/rustlib/src/rust/library/core/src/ptr/mod.rs:1785)
          >>>               /home/jubeor/repos/esp32/i2c-playground/target/riscv32imc-unknown-none-elf/release/deps/i2c_playground-0095ce173ac13dc5.i2c_playground.5a238fac89fffd17-cgu.0.rcgu.o:(main)
          >>> referenced 4 more times
          
          rust-lld: error: undefined symbol: _defmt_write
          >>> referenced by mod.rs:54 (/home/jubeor/.cargo/registry/src/index.crates.io-6f17d22bba15001f/esp-hal-0.17.0/src/rom/mod.rs:54)
          >>>               /home/jubeor/repos/esp32/i2c-playground/target/riscv32imc-unknown-none-elf/release/deps/i2c_playground-0095ce173ac13dc5.i2c_playground.5a238fac89fffd17-cgu.0.rcgu.o:(main)
          >>> referenced by mod.rs:54 (/home/jubeor/.cargo/registry/src/index.crates.io-6f17d22bba15001f/esp-hal-0.17.0/src/rom/mod.rs:54)
          >>>               /home/jubeor/repos/esp32/i2c-playground/target/riscv32imc-unknown-none-elf/release/deps/i2c_playground-0095ce173ac13dc5.i2c_playground.5a238fac89fffd17-cgu.0.rcgu.o:(main)
          >>> referenced by mod.rs:54 (/home/jubeor/.cargo/registry/src/index.crates.io-6f17d22bba15001f/esp-hal-0.17.0/src/rom/mod.rs:54)
          >>>               /home/jubeor/repos/esp32/i2c-playground/target/riscv32imc-unknown-none-elf/release/deps/i2c_playground-0095ce173ac13dc5.i2c_playground.5a238fac89fffd17-cgu.0.rcgu.o:(main)
          >>> referenced 2 more times
          
          rust-lld: error: undefined symbol: _defmt_timestamp
          >>> referenced by mod.rs:85 (src/export/mod.rs:85)
          >>>               /home/jubeor/repos/esp32/i2c-playground/target/riscv32imc-unknown-none-elf/release/deps/i2c_playground-0095ce173ac13dc5.i2c_playground.5a238fac89fffd17-cgu.0.rcgu.o:(defmt::export::header::he9e354b212ebc8cf)
          

error: could not compile `i2c-playground` (bin "i2c-playground") due to 1 previous error

Any ideas?

Test on SHTC1 and maybe SHTW2

@rnestler maybe you could do this?

To build the examples:

./build-rpi.sh

Then copy target/arm-unknown-linux-musleabihf/release/examples/linux-shtc1 to the Raspberry Pi and run it.

If this works, you could update the "Tested with the following sensors" section in README.md and in the docs in src/lib.rs.

Allow reading raw measurement data

...without conversion.

Use polling (NACK) instead of fixed sleep durations

Right now we use fixed sleep durations, because prior to embedded-hal 1 there was no way to detect a NACK in a hardware-independent way.

Now that there's ErrorKind::NoAcknowledge, we could poll instead.

Support for embedded-hal 1.0

Breaking changes in embedded-hal 1.0.0-rc.1 are incompatible with this driver.
I have a working version at: https://github.com/Radiator-Labs/shtcx-rs, and will submit a PR when the complete build is operational. The driver operates correctly, which I am testomg on an STM32WL55 application.

I am not able to submit the PR at this time, as one of the dev-dependencies, embedded-hal-mock, is not compatible with embedded-hal 1.0.0-rc.1. There is a PR awaiting incorporation, which is tracked by: dbrgn/embedded-hal-mock#86 (Which I now realize is also by you. Thank you for all the goodness!)
linux-embedded-hal is up to the new standard, as of: rust-embedded/linux-embedded-hal#96

Hardware CRC

Many STM32 MCUs (including the STM32L071) feature a hardware CRC implementation.

As an optimization, it would be nice if the default CRC software-implementation could be swapped with a custom implementation that may be faster.

This could be done using a trait:

public trait Crc {
    fn crc8(data: &[u8]) -> u8;
}

The driver struct would then be parametrized:

pub struct ShtCx<S: ShtSensor, I2C, C: Crc, D> {
    crc: C,
    ...
}

The simplest way to pass in the concrete implementation would be if the default factory functions (like shtc3) use the default implementation, but the ShtCx struct would allow swapping the implementation:

impl ShtCx<S: ShtSensor, I2C, C: Crc, D> {
    pub fn use_crc<CRC: Crc>(crc: CRC) -> Self<S, I2C, CRC, D> {
        self.crc = crc;
        self
    }
}

However, I'm not sure if the software implementation can be optimized out by the compiler or not. Probably not. Maybe a builder would be better.

What do you think, @rnestler?

Expose measurement duration

...it could be useful with the async API.

Async implementation

I would like to ask if there is interest in making an async version of the crate?

I'm using the sensor in an embassy project and while some other sensors use async version of the I2C bus and I can use embassy_embedded_hal::shared_bus::asynch::i2c::I2cDevice to share the bus across multiple tasks, it's not possible to use a driver crate with a blocking I2C impl.

Add multi-device support

Add feature flags:

• shtc3
• shtc1
• shtw2
• generic

Put features that are only available on some sensors behind those feature flags (e.g. low-power mode, which isn't available on SHTC1).

If no feature flag is specified, fall back to generic, which uses conservative defaults (slowest timings). I'm not yet sure whether or not advanced features (like low power mode) should be disabled in that case or not. (Use case: A device that is compatible with multiple of these sensors and that can decide which features to use by querying the device ID.)

@rnestler do you have some SHTC1 and SHTW2 devboards around for testing? I only have the SHTC3 at hand.