docs: Rewrite hts221 README addressing all review comments.

Author: nedseb

lib/hts221/README.md

@@ -2,47 +2,42 @@
 
 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
 
 ```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()
 
@@ -53,126 +48,92 @@ 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
 
 | File          | Description                            |
 | ------------- | -------------------------------------- |
 | `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.