drivers: Standardize read and measurement method naming.

nedseb · nedseb · commit be4f22e995cd · 2026-03-15T16:22:22.000+01:00
diff --git a/README.md b/README.md
@@ -84,7 +84,7 @@ bq = BQ27441(i2c)
 
 # Reading battery information
 bq.state_of_charge() # State of charge in %
-bq.voltage() # Voltage in mV
+bq.voltage_mv() # Voltage in mV
 bq.current_average() # Average current discharge in mA
 bq.capacity_full() # Full capacity in mAh
 bq.capacity_remaining() # Remaining capacity in mAh
@@ -250,7 +250,7 @@ i2c = machine.I2C(1)
 apds = APDS9960(i2c)
 
 apds.enable_light_sensor()
-light = apds.read_ambient_light()
+light = apds.ambient_light()
 
 ```
 
@@ -327,7 +327,7 @@ i2c = machine.I2C(1)
 pads = WSEN_PADS(i2c)
 
 # Reading values
-pressure = pads.pressure()       # Pressure in hPa
+pressure = pads.pressure_hpa()       # Pressure in hPa
 temperature = pads.temperature() # Temperature in °C
 ```
 
@@ -476,6 +476,7 @@ lib/<component>/
 - **Reset methods**: `reset()` for hardware reset (pin toggle), `soft_reset()` for software reset (register write), `reboot()` for memory reboot (reload trimming).
 - **Power methods**: `power_on()` / `power_off()`. All drivers must implement both.
 - **Status methods**: `_status()` returns the raw status register as an int (private), `data_ready()` returns True when all channels have new data, `<measurement>_ready()` for per-channel readiness (e.g. `temperature_ready()`, `pressure_ready()`).
+- **Measurement methods**: bare noun without unit suffix only for `temperature()` (°C) and `humidity()` (%RH). All others include the unit: `pressure_hpa()`, `distance_mm()`, `voltage_mv()`, `acceleration_g()`, etc. `read()` for combined reading returning a tuple, `<measurement>_raw()` for raw register values.
 
 ### Linting
 
diff --git a/lib/apds9960/apds9960/device.py b/lib/apds9960/apds9960/device.py
@@ -169,7 +169,7 @@ def is_gesture_available(self):
         return val == APDS9960_BIT_GVALID
 
     # processes a gesture event and returns best guessed gesture
-    def read_gesture(self):
+    def gesture(self):
         fifo_level = 0
         fifo_data = []
 
@@ -258,7 +258,7 @@ def _ensure_proximity_enabled(self):
             raise OSError("APDS9960 proximity data ready timeout")
 
     # reads the ambient (clear) light level as a 16-bit value
-    def read_ambient_light(self):
+    def ambient_light(self):
         self._ensure_light_enabled()
         # read value from clear channel, low byte register
         low = self._read_reg(APDS9960_REG_CDATAL)
@@ -269,7 +269,7 @@ def read_ambient_light(self):
         return low + (high << 8)
 
     # reads the red light level as a 16-bit value
-    def read_red_light(self):
+    def red_light(self):
         self._ensure_light_enabled()
         # read value from red channel, low byte register
         low = self._read_reg(APDS9960_REG_RDATAL)
@@ -280,7 +280,7 @@ def read_red_light(self):
         return low + (high << 8)
 
     # reads the green light level as a 16-bit value
-    def read_green_light(self):
+    def green_light(self):
         self._ensure_light_enabled()
         # read value from green channel, low byte register
         low = self._read_reg(APDS9960_REG_GDATAL)
@@ -291,7 +291,7 @@ def read_green_light(self):
         return low + (high << 8)
 
     # reads the blue light level as a 16-bit value
-    def read_blue_light(self):
+    def blue_light(self):
         self._ensure_light_enabled()
         # read value from blue channel, low byte register
         low = self._read_reg(APDS9960_REG_BDATAL)
@@ -306,7 +306,7 @@ def read_blue_light(self):
     # *******************************************************************************
 
     # reads the proximity level as an 8-bit value
-    def read_proximity(self):
+    def proximity(self):
         self._ensure_proximity_enabled()
         return self._read_reg(APDS9960_REG_PDATA)
 
diff --git a/lib/apds9960/examples/ambient_light.py b/lib/apds9960/examples/ambient_light.py
@@ -15,7 +15,7 @@
 oval = -1
 while True:
     sleep(0.25)
-    val = apds.read_ambient_light()
+    val = apds.ambient_light()
     if val != oval:
         print("AmbientLight={}".format(val))
         oval = val
diff --git a/lib/apds9960/examples/gesture.py b/lib/apds9960/examples/gesture.py
@@ -36,5 +36,5 @@
 while True:
     sleep(0.5)
     if apds.is_gesture_available():
-        motion = apds.read_gesture()
+        motion = apds.gesture()
         print("Gesture={}".format(dirs.get(motion, "unknown")))
diff --git a/lib/apds9960/examples/proximity.py b/lib/apds9960/examples/proximity.py
@@ -17,7 +17,7 @@
 oval = -1
 while True:
     sleep(0.25)
-    val = apds.read_proximity()
+    val = apds.proximity()
     if val != oval:
         print("proximity={}".format(val))
         oval = val
diff --git a/lib/bq27441/bq27441/device.py b/lib/bq27441/bq27441/device.py
@@ -174,7 +174,7 @@ def state_of_health(self):
         return self.soh(SohMeasureType.PERCENT)
 
     # Reads and returns the battery voltage
-    def voltage(self):
+    def voltage_mv(self):
         """Return current voltage"""
         return self.read_word(BQ27441_COMMAND_VOLTAGE)
 
diff --git a/lib/bq27441/examples/fuel_gauge.py b/lib/bq27441/examples/fuel_gauge.py
@@ -13,7 +13,7 @@
 
 while True:
     print("State of Charge:", fg.state_of_charge(), "%")
-    print("Battery Voltage:", fg.voltage(), "mV")
+    print("Battery Voltage:", fg.voltage_mv(), "mV")
     print("Average Current:", fg.current_average(), "mA")
     print("Full Capacity:", fg.capacity_full(), "/")
     print("Remaining Capacity:", fg.capacity_remaining(), "mAh")
diff --git a/lib/hts221/hts221/device.py b/lib/hts221/hts221/device.py
@@ -193,7 +193,3 @@ def calibrate_temperature(self, ref_low, measured_low, ref_high, measured_high):
             raise ValueError("measured_low and measured_high must differ")
         self._temp_gain = float(ref_high - ref_low) / delta
         self._temp_offset = float(ref_low) - self._temp_gain * float(measured_low)
-
-    def get(self):
-        h, t = self.read()
-        return [h, t]
diff --git a/lib/lis2mdl/README.md b/lib/lis2mdl/README.md
@@ -63,7 +63,7 @@ mag = LIS2MDL(i2c)
 ### Read magnetic field
 
 ```python
-x, y, z = mag.read_magnet_uT()
+x, y, z = mag.magnetic_field_ut()
 print("Magnetic field (µT):", x, y, z)
 ```
 
@@ -181,7 +181,7 @@ Expected value: `0x40`
 ### Read temperature (approximate)
 
 ```python
-print("Temperature (°C):", mag.read_temperature_c())
+print("Temperature (°C):", mag.temperature())
 ```
 
 ### Check data readiness
@@ -204,12 +204,12 @@ print("Register dump:", regs)
 
 | Method                             | Description                    |
 | ---------------------------------- | ------------------------------ |
-| `read_magnet_raw()`                | Raw sensor values (int16)      |
-| `read_magnet_uT()`                 | Magnetic field in µT           |
-| `read_magnet_calibrated_norm()`    | Calibrated and normalized data |
+| `magnetic_field_raw()`                | Raw sensor values (int16)      |
+| `magnetic_field_ut()`                 | Magnetic field in µT           |
+| `calibrated_field()`    | Calibrated and normalized data |
 | `heading_flat_only()`              | Flat compass heading           |
 | `heading_with_tilt_compensation()` | Tilt-corrected heading         |
-| `read_temperature_c()`             | Read relative temperature      |
+| `temperature()`             | Read relative temperature      |
 | `power_on()` / `power_off()`      | Power management               |
 | `soft_reset()` / `reboot()`        | Sensor reset functions         |
 
diff --git a/lib/lis2mdl/examples/magnet_fieldForce.py b/lib/lis2mdl/examples/magnet_fieldForce.py
@@ -12,6 +12,6 @@
 print("Calibration complete.")
 
 while True:
-    field_strength = mag.magnitude_uT()
+    field_strength = mag.magnitude_ut()
     print("Champ magnétique :", field_strength, "µT")
     sleep_ms(100)
diff --git a/lib/lis2mdl/examples/magnet_test.py b/lib/lis2mdl/examples/magnet_test.py
@@ -245,16 +245,16 @@ def test_reads(dev):
     ok &= isinstance(ready, bool)
 
     # MAG RAW
-    xr, yr, zr = dev.read_magnet_raw()
+    xr, yr, zr = dev.magnetic_field_raw()
     print(
-        f"read_magnet_raw: (X,Y,Z)=({xr},{yr},{zr}) LSB  =>",
+        f"magnetic_field_raw: (X,Y,Z)=({xr},{yr},{zr}) LSB  =>",
         "OK" if all(isinstance(v, int) for v in (xr, yr, zr)) else "FAIL",
     )
     ok &= all(isinstance(v, int) for v in (xr, yr, zr))
 
     # MAG µT vs RAW
-    xu, yu, zu = dev.read_magnet_uT()
-    print(f"read_magnet_uT: (X,Y,Z)=({xu:.2f},{yu:.2f},{zu:.2f}) µT")
+    xu, yu, zu = dev.magnetic_field_ut()
+    print(f"magnetic_field_ut: (X,Y,Z)=({xu:.2f},{yu:.2f},{zu:.2f}) µT")
     # check consistency of conversion µT ≈ raw*0.15
     ok_conv = (
         _approx_equal(xu, xr * 0.15, 0.5)
@@ -265,25 +265,25 @@ def test_reads(dev):
     ok &= ok_conv
 
     # MAGNITUDE
-    B = dev.magnitude_uT()
+    B = dev.magnitude_ut()
     print(
-        f"magnitude_uT: |B|={B:.1f} µT (Earth ~25-65 µT).  =>",
+        f"magnitude_ut: |B|={B:.1f} µT (Earth ~25-65 µT).  =>",
         "OK" if MAGNETIC_FIELD_MIN <= B <= MAGNETIC_FIELD_MAX else "FAIL",
     )
     ok &= MAGNETIC_FIELD_MIN <= B <= MAGNETIC_FIELD_MAX  # wide, since local disturbances are possible
 
     # CALIBRATION NORM
-    xc, yc, zc = dev.read_magnet_calibrated_norm()
-    print(f"read_magnet_calibrated_norm: ({xc:.3f},{yc:.3f},{zc:.3f})")
+    xc, yc, zc = dev.calibrated_field()
+    print(f"calibrated_field: ({xc:.3f},{yc:.3f},{zc:.3f})")
     # expected: magnitudes ~[-2..+2] after simple calibration
     ok_cal_rng = abs(xc) < 5 and abs(yc) < 5 and abs(zc) < 5
     print("Calibration norm (|val|<5) =>", "OK" if ok_cal_rng else "WARN")
     ok &= ok_cal_rng
 
     # TEMP
-    t1 = dev.read_temperature_c()
+    t1 = dev.temperature()
     sleep_ms(50)
-    t2 = dev.read_temperature_c()
+    t2 = dev.temperature()
     print(f"TempC: t1={t1:.2f}°C, t2={t2:.2f}°C (8 LSB/°C, absolute offset unknown)")
     # test: type & broad plausible range
     ok_temp = (
diff --git a/lib/lis2mdl/lis2mdl/device.py b/lib/lis2mdl/lis2mdl/device.py
@@ -178,9 +178,9 @@ def _ensure_data(self):
                 sleep_ms(2)
             raise OSError("LIS2MDL data ready timeout")
 
-    def read_magnet_raw(self):
-        """Reads the raw magnetic field (LSB). Same as read_magnet(), but more explicit."""
-        return self.read_magnet()  # (x,y,z) int16 LSB
+    def magnetic_field_raw(self):
+        """Reads the raw magnetic field (LSB). Same as magnetic_field(), but more explicit."""
+        return self.magnetic_field()  # (x,y,z) int16 LSB
 
     def _status(self) -> int:
         """Reads STATUS_REG (0x67)."""
@@ -203,34 +203,34 @@ def _read_reg(self, reg):
 
     _MAG_LSB_TO_uT = 0.15  # 1.5 mG/LSB ≈ 0.15 µT/LSB
 
-    def read_magnet_uT(self):  # noqa: N802
+    def magnetic_field_ut(self):
         """Reads the magnetic field in µT, uncalibrated (simple conversion from LSB)."""
-        x, y, z = self.read_magnet()
+        x, y, z = self.magnetic_field()
         return (
             x * self._MAG_LSB_TO_uT,
             y * self._MAG_LSB_TO_uT,
             z * self._MAG_LSB_TO_uT,
         )
 
-    def read_magnet_calibrated_norm(self):
+    def calibrated_field(self):
         """Reads the calibrated field (offset/scale per axis), normalized (unitless, ~circle in XY)."""
-        x, y, z = self.read_magnet()
+        x, y, z = self.magnetic_field()
         x = (x - self.x_off) / self.x_scale
         y = (y - self.y_off) / self.y_scale
         z = (z - self.z_off) / self.z_scale
         return (x, y, z)
 
-    def magnitude_uT(self) -> float:  # noqa: N802
+    def magnitude_ut(self) -> float:
         """Total magnetic field strength (µT)."""
-        x, y, z = self.read_magnet_uT()
+        x, y, z = self.magnetic_field_ut()
         return math.sqrt(x * x + y * y + z * z)
 
     @staticmethod
     def _to_int16(v):
         # Convert an unsigned 16-bit value to a signed 16-bit value.
         return v - 0x10000 if v & 0x8000 else v
 
-    def read_magnet(self):
+    def magnetic_field(self):
         # Read the raw magnetic field data (X, Y, Z) from the sensor.
         self._ensure_data()
         buf = self.i2c.readfrom_mem(self.address, LIS2MDL_OUTX_L_REG | 0x80, 6)
@@ -249,7 +249,7 @@ def read_temperature_raw(self) -> int:
         v = (hi << 8) | lo
         return v - 0x10000 if (v & 0x8000) else v
 
-    def read_temperature_c(self) -> float:
+    def temperature(self) -> float:
         """Temperature in °C (8 LSB/°C + empirical offset).
 
         The LIS2MDL temperature sensor has no guaranteed absolute zero
@@ -327,10 +327,10 @@ def read_registers(self, start_addr: int, length: int) -> bytes:
 
     def read_all(self) -> dict:
         """Grouped reading useful for debug & logs."""
-        raw = self.read_magnet_raw()
-        mag_ut = self.read_magnet_uT()
-        cal = self.read_magnet_calibrated_norm()
-        temp = self.read_temperature_c()
+        raw = self.magnetic_field_raw()
+        mag_ut = self.magnetic_field_ut()
+        cal = self.calibrated_field()
+        temp = self.temperature()
         st = self._status()
         return {"raw": raw, "uT": mag_ut, "cal_norm": cal, "tempC": temp, "status": st}
 
@@ -357,7 +357,7 @@ def calibrate_minmax_2d(self, samples=300, delay_ms=20):
         xmax = ymax = -1e9
 
         for _ in range(samples):
-            x, y, _ = self.read_magnet()
+            x, y, _ = self.magnetic_field()
             xmin = min(xmin, x)
             xmax = max(xmax, x)
             ymin = min(ymin, y)
@@ -382,7 +382,7 @@ def calibrate_minmax_3d(self, samples=600, delay_ms=20):
         xmax = ymax = zmax = -1e9
 
         for _ in range(samples):
-            x, y, z = self.read_magnet()
+            x, y, z = self.magnetic_field()
             xmin = min(xmin, x)
             xmax = max(xmax, x)
             ymin = min(ymin, y)
@@ -419,7 +419,7 @@ def calibrate_quality(self, samples_check=200, delay_ms=10):
         ys = []
         zs = []
         for _ in range(samples_check):
-            x, y, z = self.read_magnet()
+            x, y, z = self.magnetic_field()
             xc, yc, zc = self.calibrate_apply(x, y, z)
             xs.append(xc)
             ys.append(yc)
@@ -536,7 +536,7 @@ def heading_flat_only(self):
         Reads the sensor and returns the angle (0..360°) assuming the board is FLAT.
         Uses XY (no tilt compensation).
         """
-        x, y, z = self.read_magnet()
+        x, y, z = self.magnetic_field()
         return self.heading_from_vectors(x, y, z, calibrated=True)
 
     def heading_with_tilt_compensation(self, read_accel):
@@ -545,7 +545,7 @@ def heading_with_tilt_compensation(self, read_accel):
         read_accel() must return (ax, ay, az) ~g.
         """
 
-        x, y, z = self.read_magnet()
+        x, y, z = self.magnetic_field()
         # 3D calibration
         x = (x - self.x_off) / (self.x_scale or 1.0)
         y = (y - self.y_off) / (self.y_scale or 1.0)
diff --git a/lib/vl53l1x/vl53l1x/device.py b/lib/vl53l1x/vl53l1x/device.py
@@ -164,9 +164,12 @@ def _ensure_data(self):
                 machine.lightsleep(10)
             raise OSError("VL53L1X data ready timeout")
 
-    def read(self):
+    def distance_mm(self):
         self._ensure_data()
         data = self.i2c.readfrom_mem(self.address, 0x0089, 17, addrsize=16)
-        final_crosstalk_corrected_range_mm_sd0 = (data[13] << 8) + data[14]
+        distance_mm = (data[13] << 8) + data[14]
         self._clear_interrupt()
-        return final_crosstalk_corrected_range_mm_sd0
+        return distance_mm
+
+    def read(self):
+        return self.distance_mm()
diff --git a/lib/wsen-pads/README.md b/lib/wsen-pads/README.md
@@ -131,7 +131,7 @@ from wsen_pads.const import ODR_10_HZ
 
 sensor.set_continuous(odr=ODR_10_HZ)
 
-pressure = sensor.pressure()
+pressure = sensor.pressure_hpa()
 temperature = sensor.temperature()
 ```
 
diff --git a/lib/wsen-pads/examples/continuous_reader.py b/lib/wsen-pads/examples/continuous_reader.py
@@ -10,7 +10,7 @@
 sensor.set_continuous(odr=ODR_10_HZ)
 
 for _ in range(10):
-    pressure = sensor.pressure()
+    pressure = sensor.pressure_hpa()
     temperature = sensor.temperature()
 
     print("P:", pressure, "hPa  T:", temperature, "°C")
diff --git a/lib/wsen-pads/examples/test.py b/lib/wsen-pads/examples/test.py
diff --git a/lib/wsen-pads/wsen_pads/device.py b/lib/wsen-pads/wsen_pads/device.py
diff --git a/tests/scenarios/apds9960.yaml b/tests/scenarios/apds9960.yaml
diff --git a/tests/scenarios/board_temperature_comparison.yaml b/tests/scenarios/board_temperature_comparison.yaml
diff --git a/tests/scenarios/bq27441.yaml b/tests/scenarios/bq27441.yaml
diff --git a/tests/scenarios/lis2mdl.yaml b/tests/scenarios/lis2mdl.yaml
diff --git a/tests/scenarios/wsen_pads.yaml b/tests/scenarios/wsen_pads.yaml
