docs: Rewrite bq27441 README addressing all review comments.

Author: nedseb

lib/bq27441/README.md

@@ -1,123 +1,211 @@
-# MicroPython BQ27441 Library
-
-This library is a port of the [SparkFun BQ27441-G1A LiPo Fuel Gauge Arduino Library](https://github.com/sparkfun/SparkFun_BQ27441_Arduino_Library). 
-
-# Features
-
-* I²C communication
-* battery voltage measurement
-* state of charge (SoC)
-* remaining and full capacity
-* average, standby and max current
-* average power measurement
-* state of health (SoH)
-* battery and internal temperature
-* configurable design capacity
-* power management (shutdown / wake-up)
-* GPOUT interrupt configuration (SOC_INT / BAT_LOW)
+# BQ27441 MicroPython Driver
+
+MicroPython driver for the **Texas Instruments BQ27441-G1A** LiPo fuel gauge.
+
+This library is a port of the [SparkFun BQ27441 Arduino Library](https://github.com/sparkfun/SparkFun_BQ27441_Arduino_Library).
 
-# I2C Address
+## Supported Device
 
-* **Default address:** `0x55` 
+| Parameter            | Value            |
+| -------------------- | ---------------- |
+| Device               | BQ27441-G1A      |
+| Interface            | I²C              |
+| Default I²C address  | `0x55`           |
+| Operating voltage    | 2.5–4.5 V       |
+| Default capacity     | 650 mAh          |
 
-**Important:**
-The BQ27441 only responds on I²C when a **battery is connected**.
+**Note:** The BQ27441 only responds on I²C when a battery is connected.
 
-# Basic Usage
+## Features
+
+* Battery voltage measurement (mV)
+* State of charge (%)
+* Remaining and full capacity (mAh)
+* Average, standby, and max current
+* Average power
+* State of health (%)
+* Battery and internal temperature
+* Configurable design capacity
+* Power management (shutdown / wake-up)
+* GPOUT interrupt configuration (SOC_INT / BAT_LOW)
+* Seal / unseal device control
+
+## Basic Usage
 
 ```python
 from machine import I2C
 from bq27441 import BQ27441
 
 i2c = I2C(1)
-
 bq = BQ27441(i2c)
 
-voltage = bq.voltage_mv()        # mV
-soc = bq.state_of_charge()       # %
+print("Voltage:", bq.voltage_mv(), "mV")
+print("Charge:", bq.state_of_charge(), "%")
+print("Current:", bq.current_average(), "mA")
+```
+
+## API Reference
 
-print("Voltage:", voltage, "mV")
-print("State of Charge:", soc, "%")
+### Initialization
+
+```python
+bq = BQ27441(i2c, address=0x55)
+```
+
+### Quick Measurements
+
+* `bq.voltage_mv()` — battery voltage in mV
+* `bq.state_of_charge()` — battery level in % (filtered)
+* `bq.capacity_remaining()` — remaining capacity in mAh
+* `bq.capacity_full()` — full charge capacity in mAh
+* `bq.current_average()` — average current in mA
+* `bq.state_of_health()` — battery health in %
+* `bq.power()` — average power in mW
+
+### Advanced Measurements with Type Constants
+
+Several methods accept a type parameter for different measurement modes. The type constants are defined in `bq27441.device`:
+
+```python
+from bq27441.device import CurrentMeasureType, CapacityMeasureType
+from bq27441.device import SocMeasureType, SohMeasureType, TempMeasureType
 ```
 
-# API
+#### Current
 
-## Measurements
+```python
+bq.current(CurrentMeasureType.AVG)    # Average current (default)
+bq.current(CurrentMeasureType.STBY)   # Standby current
+bq.current(CurrentMeasureType.MAX)    # Max current
+```
 
-### Voltage & Power
+#### Capacity
 
-* `voltage_mv()` — battery voltage in mV
-* `power()` — average power
+```python
+bq.capacity(CapacityMeasureType.REMAIN)      # Remaining (default)
+bq.capacity(CapacityMeasureType.FULL)         # Full charge
+bq.capacity(CapacityMeasureType.AVAIL)        # Available
+bq.capacity(CapacityMeasureType.AVAIL_FULL)   # Full available
+bq.capacity(CapacityMeasureType.REMAIN_F)     # Remaining filtered
+bq.capacity(CapacityMeasureType.REMAIN_UF)    # Remaining unfiltered
+bq.capacity(CapacityMeasureType.FULL_F)       # Full filtered
+bq.capacity(CapacityMeasureType.FULL_UF)      # Full unfiltered
+bq.capacity(CapacityMeasureType.DESIGN)       # Design capacity
+```
 
-### Current
+#### State of Charge
 
-* `current_average()` — average current
-* `current(type)` — current (AVG, STBY, MAX)
+```python
+bq.soc(SocMeasureType.FILTERED)     # Filtered SoC (default)
+bq.soc(SocMeasureType.UNFILTERED)   # Unfiltered SoC
+```
 
-### Capacity
+#### State of Health
 
-* `capacity_remaining()` — remaining capacity (mAh)
-* `capacity_full()` — full charge capacity (mAh)
-* `capacity(type)` — advanced capacity readings
+```python
+bq.soh(SohMeasureType.PERCENT)    # Health percentage (default)
+bq.soh(SohMeasureType.SOH_STAT)   # Health status bits
+```
 
-### Charge & Health
+#### Temperature
 
-* `state_of_charge()` — battery level (%)
-* `soc(type)` — filtered / unfiltered SoC
-* `state_of_health()` — battery health (%)
-* `soh(type)` — detailed SoH
+```python
+bq.temperature(TempMeasureType.BATTERY)        # Battery temperature
+bq.temperature(TempMeasureType.INTERNAL_TEMP)  # Internal IC temperature
+```
 
-### Temperature
+**Note:** Temperature is returned as a raw register value (units of 0.1 K). To convert to °C: `temp_c = raw / 10.0 - 273.15`.
 
-* `temperature(type)` — battery or internal temperature
+### Configuration
 
-## Configuration
+```python
+# Set battery design capacity
+bq.set_capacity(650)
 
-* `set_capacity(mAh)` — set battery design capacity
-* `enter_config(user_control)` — enter config mode
-* `exit_config(resim=True)` — exit config mode
+# Configuration mode (required for some settings)
+bq.enter_config(user_control=True)
+# ... modify settings ...
+bq.exit_config(resim=True)
+```
 
 ### GPOUT / Alerts
 
-* `set_gpout_function(type)` — SOC_INT or BAT_LOW
-* `set_gpout_polarity(active_high)`
-* `set_soc1_thresholds(set, clear)`
-* `set_socf_thresholds(set, clear)`
-* `pulse_gpout()`
+```python
+from bq27441.device import GpoutFunctionType
+
+# Configure GPOUT function
+bq.set_gpout_function(GpoutFunctionType.SOC_INT)  # SoC change interrupt
+bq.set_gpout_function(GpoutFunctionType.BAT_LOW)   # Battery low alert
+
+# GPOUT polarity
+bq.gpout_polarity()                  # Read current polarity
+bq.set_gpout_polarity(active_high=True)
+
+# GPOUT pin direction
+bq.configure_gpout_input()
+bq.configure_gpout_output()
+
+# SoC thresholds
+bq.set_soc1_thresholds(set_soc=15, clear_soc=20)
+bq.set_socf_thresholds(set_socf=5, clear_socf=10)
+
+# Read thresholds
+bq.soc1_set_threshold()
+bq.soc1_clear_threshold()
+bq.socf_set_threshold()
+bq.socf_clear_threshold()
+
+# SoC flags and delta
+bq.soc_flag()                        # SoC1 threshold crossed
+bq.socf_flag()                       # SoCF threshold crossed
+bq.soci_delta()                      # SoC interrupt delta
+bq.set_soci_delta(delta=1)
+
+# Pulse GPOUT
+bq.pulse_gpout()
+```
 
-## Power Management
+### Power Management
 
-* `power_on()` — wake device
-* `power_off()` — enter shutdown
-* `enable_shutdown_mode()`
-* `enter_shutdown_mode()`
-* `disable_shutdown_mode()`
+* `bq.power_on()` — wake device from shutdown
+* `bq.power_off()` — enter shutdown mode
+* `bq.enable_shutdown_mode()` — enable shutdown via GPOUT
+* `bq.enter_shutdown_mode()` — enter shutdown
+* `bq.disable_shutdown_mode()` — disable shutdown mode
 
-## Device Info & Control
+### Device Control
 
-* `device_id()` — read device ID
-* `is_valid_device()` — check device identity
-* `flags()` — read status flags
-* `reset()` — full reset
-* `soft_reset()` — soft reset
+* `bq.device_id()` — read device type ID
+* `bq.is_valid_device()` — check if device is BQ27441
+* `bq.flags()` — read status flags register
+* `bq.reset()` — full device reset
+* `bq.soft_reset()` — soft reset
 
-# Examples
+### Seal / Unseal
 
-| Example file    | Description                                      |
-| --------------- | ------------------------------------------------ |
-| `fuel_gauge.py` | Basic battery monitoring (voltage, SoC, current) |
+* `bq.sealed()` — check if device is sealed
+* `bq.seal()` — seal the device (restrict configuration access)
+* `bq.unseal()` — unseal for configuration
 
-Run with:
+### Operation Config
 
-```sh
+* `bq.op_config()` — read OpConfig register
+* `bq.write_op_config(value)` — write OpConfig register
+
+## Examples
+
+| File             | Description                                      |
+| ---------------- | ------------------------------------------------ |
+| `fuel_gauge.py`  | Battery monitoring (voltage, SoC, current, health) |
+
+```bash
 mpremote mount lib/bq27441 run lib/bq27441/examples/fuel_gauge.py
 ```
 
----
-
-# Notes
+## Notes
 
-* The **BQ27441 requires a connected LiPo battery** to respond on I²C
-* Default design capacity is **650 mAh** (configurable) 
-* Some configuration operations require entering **config mode**
-* The device may be **sealed**, requiring unsealing for advanced configuration
+* The BQ27441 requires a connected LiPo battery to respond on I²C.
+* Default design capacity is 650 mAh (configurable via `set_capacity()`).
+* Some configuration operations require entering config mode with `enter_config()`.
+* The device may be sealed; use `unseal()` before advanced configuration.
+* Temperature readings are raw register values in 0.1 K units (see conversion above).