Skip to content

Commit 53d7e85

Browse files
docs: Harmonize wsen-hids README — add I2C address and power sections. (#209)
* docs: Harmonize wsen-hids README — add I2C address and power sections. * docs: Remove useless I2C section in wsen-hids readme. * docs: Specify timeout for read_one_shot in wsen-hids readme. * docs: Add ODR_ONE_SHOT option in wsen-hids readme. * docs: Add device_id and enable_bdu to wsen-hids readme. * docs: Rel=move emoji in wsen-hids readme. * docs: Remove trailing whitespace in wsen-hids readme. * docs: Clarify AVG configuration on wsen-hids readme. * docs: Remove unused PIN import from wsen-hids readme.
1 parent 9f0762a commit 53d7e85

1 file changed

Lines changed: 82 additions & 26 deletions

File tree

lib/wsen-hids/README.md

Lines changed: 82 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -39,26 +39,19 @@ Main characteristics:
3939
| Humidity accuracy | ±1.8 %RH |
4040
| Temperature accuracy | ±0.2 °C |
4141

42-
---
43-
4442
# Quick Example
4543

4644
```python
47-
from machine import I2C, Pin
45+
from machine import I2C
4846
from time import sleep
4947
from wsen_hids import WSEN_HIDS
5048

51-
i2c = I2C(
52-
0,
53-
scl=Pin(9),
54-
sda=Pin(8),
55-
freq=100000,
56-
)
49+
i2c = I2C(1)
5750

5851
sensor = WSEN_HIDS(i2c)
5952

6053
while True:
61-
humidity, temperature = sensor.read_one_shot()
54+
humidity, temperature = sensor.read()
6255

6356
print("Humidity: {:.2f} %RH".format(humidity))
6457
print("Temperature: {:.2f} °C".format(temperature))
@@ -87,6 +80,27 @@ sensor = WSEN_HIDS(
8780
)
8881
```
8982

83+
### `device_id()`
84+
85+
Read the device identification register.
86+
87+
```python
88+
sensor.device_id()
89+
```
90+
91+
**Returns:** `int` — Device ID (`WHO_AM_I` register value)
92+
93+
94+
### `enable_bdu(enable=True)`
95+
96+
Enable or disable Block Data Update (BDU).
97+
98+
```python
99+
sensor.enable_bdu(enable=True)
100+
```
101+
102+
When enabled, output registers are not updated until both high and low bytes are read. Recommended to avoid reading inconsistent data.
103+
90104
---
91105

92106
# Reading Measurements
@@ -113,21 +127,27 @@ temperature = sensor.temperature()
113127

114128
### Measurement behavior
115129

116-
After initialization, the sensor operates in **one-shot mode** (ODR = 00).
130+
After initialization, the sensor operates in **one-shot mode** (ODR = 00).
117131
If `read()`, `humidity()`, or `temperature()` are called while the sensor is not in continuous mode, the driver **automatically triggers a one-shot conversion** to ensure fresh data is returned.
118132

119-
This allows simple usage:
120-
121133
```python
122134
humidity, temperature = sensor.read()
135+
```
123136

124-
Continuous measurements can be enabled with sensor.set_continuous().
137+
Continuous measurements can be enabled with:
138+
139+
```python
140+
sensor.set_continuous(WSEN_HIDS.ODR_1_HZ)
141+
```
142+
143+
---
125144

126145
# One-Shot Measurement
127146

128147
Trigger a single conversion:
129148

130149
```python
150+
# Default timeout (100 ms)
131151
humidity, temperature = sensor.read_one_shot()
132152
```
133153

@@ -150,6 +170,7 @@ sensor.set_continuous(WSEN_HIDS.ODR_1_HZ)
150170
Available output data rates:
151171

152172
```python
173+
WSEN_HIDS.ODR_ONE_SHOT
153174
WSEN_HIDS.ODR_1_HZ
154175
WSEN_HIDS.ODR_7_HZ
155176
WSEN_HIDS.ODR_12_5_HZ
@@ -165,7 +186,7 @@ sensor.set_one_shot_mode()
165186

166187
# Averaging Configuration
167188

168-
Configure internal measurement averaging:
189+
Configure internal measurement averaging for **temperature and humidity**:
169190

170191
```python
171192
sensor.set_average(avg_t=WSEN_HIDS.AVG_16, avg_h=WSEN_HIDS.AVG_16)
@@ -184,7 +205,42 @@ AVG_128
184205
AVG_256
185206
```
186207

187-
Higher averaging improves noise performance but increases conversion time.
208+
**Defaults:**
209+
210+
```python
211+
AVG_T_DEFAULT = AVG_16
212+
AVG_H_DEFAULT = AVG_16
213+
```
214+
215+
**Notes:**
216+
217+
* The same averaging constants (`AVG_*`) are used for both temperature and humidity
218+
* Internally, temperature and humidity are configured in separate registers, but they share identical averaging values
219+
* Higher averaging improves noise performance but increases conversion time
220+
221+
---
222+
223+
# Power Management
224+
225+
The driver provides basic power control methods:
226+
227+
```python
228+
sensor.power_off()
229+
```
230+
231+
Disables the sensor by clearing the PD bit.
232+
233+
```python
234+
sensor.power_on()
235+
```
236+
237+
Re-enables the sensor (restores active mode).
238+
239+
```python
240+
sensor.reboot()
241+
```
242+
243+
Reloads internal memory and calibration data from non-volatile memory.
188244

189245
---
190246

@@ -204,7 +260,7 @@ Disable heater:
204260
sensor.enable_heater(False)
205261
```
206262

207-
⚠️ Measurements should **not be taken while the heater is active**.
263+
Measurements should **not be taken while the heater is active**.
208264

209265
---
210266

@@ -213,10 +269,9 @@ sensor.enable_heater(False)
213269
Check measurement readiness:
214270

215271
```python
216-
sensor.status()
272+
sensor.data_ready()
217273
sensor.humidity_ready()
218274
sensor.temperature_ready()
219-
sensor.data_ready()
220275
```
221276

222277
These helpers read the **STATUS register** and indicate when fresh data is available.
@@ -227,7 +282,14 @@ These helpers read the **STATUS register** and indicate when fresh data is avail
227282

228283
The driver automatically reads the sensor’s **factory calibration coefficients** during initialization and applies the conversion formulas internally.
229284

230-
No user calibration is required.
285+
Additional calibration methods are available:
286+
287+
```python
288+
sensor.set_temp_offset(offset_c)
289+
sensor.calibrate_temperature(ref_low, measured_low, ref_high, measured_high)
290+
```
291+
292+
No calibration is required for basic usage.
231293

232294
---
233295

@@ -244,9 +306,3 @@ Examples include:
244306
* basic one-shot measurements
245307
* continuous measurement mode
246308
* driver validation tests
247-
248-
Run an example using:
249-
250-
```bash
251-
mpremote mount lib/wsen-hids run lib/wsen-hids/examples/continuous_mode.py
252-
```

0 commit comments

Comments
 (0)