From 66561e8a489928f3847179b66ee289ba9b7682a7 Mon Sep 17 00:00:00 2001 From: Charly-sketch Date: Mon, 23 Mar 2026 15:12:21 +0100 Subject: [PATCH 1/2] docs: Expand README for hts221 driver. --- lib/hts221/README.md | 179 +++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 174 insertions(+), 5 deletions(-) diff --git a/lib/hts221/README.md b/lib/hts221/README.md index d65aa6ca..f0b2bfc8 100644 --- a/lib/hts221/README.md +++ b/lib/hts221/README.md @@ -1,9 +1,178 @@ -# MicroPython Driver for the HTS221 Humidity Sensor +# HTS221 MicroPython Driver -This library is a port of the [MicroPython Driver for the HTS221 Humidity Sensor](https://github.com/jposada202020/MicroPython_HTS221/tree/master). +MicroPython driver for the **STMicroelectronics HTS221** humidity and temperature sensor. -The examples could be easily tested with [mpremote](https://docs.micropython.org/en/latest/reference/mpremote.html) with the following command : +The HTS221 provides: -```sh - mpremote mount . run examples/humidity.py +* **Relative humidity (%)** +* **Temperature (°C)** + +This driver offers a simple and complete API for configuration, measurement, calibration, and power management using **I²C**. + +## Features + +* I²C communication +* Device identification (`WHO_AM_I`) +* Relative humidity measurement +* Temperature measurement +* One-shot measurement mode +* Continuous measurement mode +* Configurable output data rate (ODR) +* Configurable averaging +* Data-ready status flags +* Power management (power on/off, reboot) +* Built-in factory calibration usage +* User temperature calibration: + * offset correction + * two-point calibration + +## I²C Address + +* Default address: **0x5F** + +## Basic Usage + +```python +from machine import I2C +from hts221 import HTS221 + +# Initialize I2C +i2c = I2C(1) + +# Initialize sensor +sensor = HTS221(i2c) + +# Read values +humidity = sensor.humidity() +temperature = sensor.temperature() + +print("Humidity:", humidity, "%") +print("Temperature:", temperature, "°C") + +# Read both at once +h, t = sensor.read() +``` + +## API + +### Device Information + +```python +device_id() +``` + +Returns the sensor device ID (`WHO_AM_I` register). + +### Data Readiness + +```python +data_ready() +temperature_ready() +humidity_ready() ``` + +* `data_ready()` → both humidity and temperature available +* `temperature_ready()` → temperature available +* `humidity_ready()` → humidity available + +### Measurements + +```python +temperature() +humidity() +read() +read_one_shot() +``` + +* `temperature()` → temperature in °C +* `humidity()` → relative humidity in % +* `read()` → `(humidity, temperature)` +* `read_one_shot()` → performs a one-shot measurement and returns `(humidity, temperature)` + +### One-Shot Mode + +```python +trigger_one_shot() +``` + +Triggers a single measurement (used internally by `read_one_shot()`). + +### Configuration + +```python +get_odr() +set_odr(odr) +set_continuous(odr) +``` + +* `get_odr()` → returns current output data rate +* `set_odr(odr)` → set ODR (0 = one-shot mode) +* `set_continuous(odr)` → enable continuous mode (ODR ≠ 0) + +### Averaging Configuration + +```python +get_av() +set_av(av) +``` + +Controls internal averaging for humidity and temperature. + +### Power Management + +```python +power_on() +power_off() +reboot() +``` + +* `power_on()` → enable sensor +* `power_off()` → disable sensor +* `reboot()` → reload calibration data and reboot memory + +### Temperature Calibration + +```python +set_temp_offset(offset_c) +calibrate_temperature(ref_low, measured_low, ref_high, measured_high) +``` + +* `set_temp_offset(offset_c)` + Apply a simple temperature offset correction. + +* `calibrate_temperature(...)` + Perform a **two-point calibration**: + + * improves accuracy + * adjusts both gain and offset + +## Examples + +| File | Description | +| ------------- | -------------------------------------- | +| `humidity.py` | Basic humidity and temperature reading | + +Run with: + +```bash +mpremote mount lib/htss221 run examples/htss221/examples/humidity.py +``` + +--- + +## Notes + +* The driver uses **factory calibration data** stored in the sensor. +* Temperature can be further corrected using: + + * `set_temp_offset()` (simple correction) + * `calibrate_temperature()` (recommended for precision) +* In one-shot mode, the driver automatically waits for data readiness. +* In power-down or one-shot mode, measurements trigger automatically when needed. + +--- + +## Source + +This library is a port of: +[https://github.com/jposada202020/MicroPython_HTS221/tree/master](https://github.com/jposada202020/MicroPython_HTS221/tree/master) From f6ddfc18965292e633ed4aa30f806ae766122763 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20NEDJAR?= Date: Mon, 23 Mar 2026 16:57:49 +0100 Subject: [PATCH 2/2] docs: Rewrite hts221 README addressing all review comments. --- lib/hts221/README.md | 157 ++++++++++++++++--------------------------- 1 file changed, 59 insertions(+), 98 deletions(-) diff --git a/lib/hts221/README.md b/lib/hts221/README.md index f0b2bfc8..4d13d052 100644 --- a/lib/hts221/README.md +++ b/lib/hts221/README.md @@ -2,33 +2,32 @@ MicroPython driver for the **STMicroelectronics HTS221** humidity and temperature sensor. -The HTS221 provides: +This library is a port of [MicroPython_HTS221](https://github.com/jposada202020/MicroPython_HTS221). -* **Relative humidity (%)** -* **Temperature (°C)** +## Supported Sensor -This driver offers a simple and complete API for configuration, measurement, calibration, and power management using **I²C**. +| Parameter | Value | +| -------------------- | ----------------- | +| Interface | I²C | +| Default I²C address | `0x5F` | +| Device ID | `0xBC` | +| Humidity range | 0–100 %RH | +| Humidity accuracy | ±3.5 %RH | +| Temperature range | −40 to +120 °C | +| Temperature accuracy | ±0.5 °C | ## Features * I²C communication * Device identification (`WHO_AM_I`) -* Relative humidity measurement -* Temperature measurement -* One-shot measurement mode -* Continuous measurement mode +* Humidity and temperature measurement +* One-shot and continuous measurement modes * Configurable output data rate (ODR) * Configurable averaging * Data-ready status flags -* Power management (power on/off, reboot) -* Built-in factory calibration usage -* User temperature calibration: - * offset correction - * two-point calibration - -## I²C Address - -* Default address: **0x5F** +* Power management (on/off, reboot) +* Factory calibration (automatic) +* User temperature calibration (offset and two-point) ## Basic Usage @@ -36,13 +35,9 @@ This driver offers a simple and complete API for configuration, measurement, cal from machine import I2C from hts221 import HTS221 -# Initialize I2C i2c = I2C(1) - -# Initialize sensor sensor = HTS221(i2c) -# Read values humidity = sensor.humidity() temperature = sensor.temperature() @@ -53,98 +48,78 @@ print("Temperature:", temperature, "°C") h, t = sensor.read() ``` -## API +## API Reference -### Device Information +### Initialization ```python -device_id() +sensor = HTS221(i2c, address=0x5F) ``` -Returns the sensor device ID (`WHO_AM_I` register). - -### Data Readiness +### Device Information ```python -data_ready() -temperature_ready() -humidity_ready() +sensor.device_id() ``` -* `data_ready()` → both humidity and temperature available -* `temperature_ready()` → temperature available -* `humidity_ready()` → humidity available +Returns the sensor device ID (`WHO_AM_I` register, expected `0xBC`). ### Measurements -```python -temperature() -humidity() -read() -read_one_shot() -``` +* `sensor.temperature()` — temperature in °C +* `sensor.humidity()` — relative humidity in % +* `sensor.read()` — returns `(humidity, temperature)` +* `sensor.read_one_shot()` — triggers a one-shot conversion and returns `(humidity, temperature)` after a fixed 15 ms delay + +### Data Readiness -* `temperature()` → temperature in °C -* `humidity()` → relative humidity in % -* `read()` → `(humidity, temperature)` -* `read_one_shot()` → performs a one-shot measurement and returns `(humidity, temperature)` +* `sensor.data_ready()` — `True` when both humidity and temperature are available +* `sensor.temperature_ready()` — `True` when temperature is available +* `sensor.humidity_ready()` — `True` when humidity is available ### One-Shot Mode ```python -trigger_one_shot() +sensor.trigger_one_shot() ``` -Triggers a single measurement (used internally by `read_one_shot()`). +Triggers a single conversion with a 15 ms delay. Used internally by `read_one_shot()`. ### Configuration -```python -get_odr() -set_odr(odr) -set_continuous(odr) -``` +* `sensor.get_odr()` — returns current output data rate +* `sensor.set_odr(odr)` — set ODR (0 = one-shot, 1 = 1 Hz, 2 = 7 Hz, 3 = 12.5 Hz) +* `sensor.set_continuous(odr)` — enable continuous mode. Raises `ValueError` if `odr=0`. -* `get_odr()` → returns current output data rate -* `set_odr(odr)` → set ODR (0 = one-shot mode) -* `set_continuous(odr)` → enable continuous mode (ODR ≠ 0) +### Averaging -### Averaging Configuration +* `sensor.get_av()` — returns current averaging configuration register +* `sensor.set_av(av)` — set humidity and temperature averaging (raw register value) -```python -get_av() -set_av(av) -``` - -Controls internal averaging for humidity and temperature. +The AV_CONF register controls internal averaging for both channels. Higher values improve noise but increase conversion time. Refer to the HTS221 datasheet for the register encoding. ### Power Management -```python -power_on() -power_off() -reboot() -``` - -* `power_on()` → enable sensor -* `power_off()` → disable sensor -* `reboot()` → reload calibration data and reboot memory +* `sensor.power_on()` — enable sensor +* `sensor.power_off()` — disable sensor +* `sensor.reboot()` — reload factory calibration data from non-volatile memory ### Temperature Calibration ```python -set_temp_offset(offset_c) -calibrate_temperature(ref_low, measured_low, ref_high, measured_high) +# Simple offset correction +sensor.set_temp_offset(-1.2) + +# Two-point calibration (gain + offset) +sensor.calibrate_temperature( + ref_low=0.0, + measured_low=0.8, + ref_high=50.0, + measured_high=48.7, +) ``` -* `set_temp_offset(offset_c)` - Apply a simple temperature offset correction. - -* `calibrate_temperature(...)` - Perform a **two-point calibration**: - - * improves accuracy - * adjusts both gain and offset +No calibration is required for basic usage — the driver applies factory calibration automatically. ## Examples @@ -152,27 +127,13 @@ calibrate_temperature(ref_low, measured_low, ref_high, measured_high) | ------------- | -------------------------------------- | | `humidity.py` | Basic humidity and temperature reading | -Run with: - ```bash -mpremote mount lib/htss221 run examples/htss221/examples/humidity.py +mpremote mount lib/hts221 run lib/hts221/examples/humidity.py ``` ---- - ## Notes -* The driver uses **factory calibration data** stored in the sensor. -* Temperature can be further corrected using: - - * `set_temp_offset()` (simple correction) - * `calibrate_temperature()` (recommended for precision) -* In one-shot mode, the driver automatically waits for data readiness. -* In power-down or one-shot mode, measurements trigger automatically when needed. - ---- - -## Source - -This library is a port of: -[https://github.com/jposada202020/MicroPython_HTS221/tree/master](https://github.com/jposada202020/MicroPython_HTS221/tree/master) +* The driver uses factory calibration data stored in the sensor, read automatically at initialization. +* `temperature()`, `humidity()`, and `read()` poll the sensor's status bits via `_ensure_data()` to wait for fresh data before returning. +* `read_one_shot()` triggers a conversion and waits a fixed 15 ms delay before reading registers (no status polling). +* In power-down or one-shot mode, calling a measurement method automatically triggers a new conversion.