docs: Rewrite apds9960 README addressing all review comments.

Author: nedseb

lib/apds9960/README.md

@@ -1,171 +1,112 @@
-# MicroPython APDS-9960 Library
+# APDS-9960 MicroPython Driver
 
-This library is a port of the [Python (and MicroPython) APDS-9960 Library](https://github.com/liske/python-apds9960/).
+MicroPython driver for the **Broadcom APDS-9960** proximity, gesture, color, and ambient light sensor.
 
-## Features
-
-The APDS-9960 is a multifunction sensor providing:
+This library is a port of [python-apds9960](https://github.com/liske/python-apds9960/).
 
-* **Ambient light sensing (ALS)** — clear + RGB channels
-* **RGB color sensing** — red, green, blue intensity
-* **Proximity detection** — object distance estimation
-* **Gesture detection** — directional gestures (up, down, left, right, near, far)
+## Supported Sensor
 
-## I2C Address
+| Parameter           | Value                             |
+| ------------------- | --------------------------------- |
+| Device              | APDS-9960                         |
+| Interface           | I²C                               |
+| Default I²C address | `0x39`                            |
+| Device ID           | `0xAB`                            |
+| Functions           | ALS, RGB, proximity, gesture      |
+| Proximity range     | 0–255 (relative)                  |
+| ALS resolution      | 16-bit per channel                |
 
-Default I2C address:
+## Features
 
-```python
-0x39
-```
+* Ambient light sensing (ALS) — clear channel
+* RGB color sensing — red, green, blue channels
+* Proximity detection — object distance estimation
+* Gesture detection — directional gestures (up, down, left, right, near, far)
+* Power management (on/off)
+* Configurable gains, LED drive, and thresholds
+* Interrupt support for light, proximity, and gesture
 
 ## Basic Usage
 
 ```python
-from machine import I2C, Pin
+from machine import I2C
 from apds9960 import uAPDS9960
 
-i2c = I2C(0, scl=Pin(22), sda=Pin(21))
+i2c = I2C(1)
 sensor = uAPDS9960(i2c)
 
 # Read ambient light
 ambient = sensor.ambient_light()
 print("Ambient light:", ambient)
-```
-
-Parfait — voici une version **alignée sur le style ism330dl / wsen-hids**, avec wording homogène, phrases courtes et impératives, et structure cohérente.
-
----
-
-## API
-
-### General
-
-* `device_id()`
-  Get the device ID
-
-* `power_on()`
-  Enable the sensor
-
-* `power_off()`
-  Disable the sensor
-
-* `get_mode()`
-  Get the current mode register value
-
-* `set_mode(mode, enable=True)`
-  Enable or disable a sensor mode
-
-* `data_ready()`
-  Check if light and proximity data are ready
-
-## API
-
-### Ambient Light & Color
 
-#### Reading measurements
-
-```python
-ambient = sensor.ambient_light()
-red = sensor.red_light()
-green = sensor.green_light()
-blue = sensor.blue_light()
+# Read proximity
+prox = sensor.proximity()
+print("Proximity:", prox)
 ```
 
-* `ambient_light()`
-  Read ambient (clear) light value
+## API Reference
 
-* `red_light()`
-  Read red channel value
+### General
 
-* `green_light()`
-  Read green channel value
+* `sensor.device_id()` — read device ID (expected `0xAB`)
+* `sensor.power_on()` — enable the sensor
+* `sensor.power_off()` — disable the sensor
+* `sensor.data_ready()` — `True` when light and proximity data are ready
+* `sensor.get_mode()` — read current mode register
+* `sensor.set_mode(mode, enable=True)` — enable or disable a sensor mode
 
-* `blue_light()`
-  Read blue channel value
+### Ambient Light and Color
 
-* `light_ready()`
-  Check if light data is ready
+#### Measurements
 
-#### Sensor control
+* `sensor.ambient_light()` — read ambient (clear) light value
+* `sensor.red_light()` — read red channel
+* `sensor.green_light()` — read green channel
+* `sensor.blue_light()` — read blue channel
+* `sensor.light_ready()` — `True` when light data is available
 
-* `enable_light_sensor(interrupts=True)`
-  Enable ambient light sensing
+#### Control
 
-* `disable_light_sensor()`
-  Disable ambient light sensing
+* `sensor.enable_light_sensor(interrupts=True)` — enable ALS
+* `sensor.disable_light_sensor()` — disable ALS
 
 #### Configuration
 
-* `get_ambient_light_gain()` / `set_ambient_light_gain(value)`
-  Get or set ambient light gain
-
-* `get_light_int_low_threshold()` / `set_light_int_low_threshold(value)`
-  Get or set low interrupt threshold
-
-* `get_light_int_high_threshold()` / `set_light_int_high_threshold(value)`
-  Get or set high interrupt threshold
-
-* `get_ambient_light_int_enable()` / `set_ambient_light_int_enable(enable)`
-  Enable or disable light interrupts
-
-* `clear_ambient_light_int()`
-  Clear ambient light interrupt
+* `sensor.get_ambient_light_gain()` / `sensor.set_ambient_light_gain(value)` — ALS gain (0=1x, 1=4x, 2=16x, 3=64x)
+* `sensor.get_light_int_low_threshold()` / `sensor.set_light_int_low_threshold(value)` — low interrupt threshold
+* `sensor.get_light_int_high_threshold()` / `sensor.set_light_int_high_threshold(value)` — high interrupt threshold
+* `sensor.get_ambient_light_int_enable()` / `sensor.set_ambient_light_int_enable(enable)` — interrupt enable
+* `sensor.clear_ambient_light_int()` — clear light interrupt
 
 ### Proximity
 
-#### Reading measurements
-
-```python
-proximity = sensor.proximity()
-```
-
-* `proximity()`
-  Read proximity value
+#### Measurements
 
-* `proximity_ready()`
-  Check if proximity data is ready
+* `sensor.proximity()` — read proximity value (0–255)
+* `sensor.proximity_ready()` — `True` when proximity data is available
 
-#### Sensor control
+#### Control
 
-* `enable_proximity_sensor(interrupts=True)`
-  Enable proximity sensing
-
-* `disable_proximity_sensor()`
-  Disable proximity sensing
+* `sensor.enable_proximity_sensor(interrupts=True)` — enable proximity
+* `sensor.disable_proximity_sensor()` — disable proximity
 
 #### Configuration
 
-* `get_proximity_gain()` / `set_proximity_gain(value)`
-  Get or set proximity gain
-
-* `get_led_drive()` / `set_led_drive(value)`
-  Get or set LED drive strength
-
-* `get_led_boost()` / `set_led_boost(value)`
-  Get or set LED boost
-
-* `get_prox_int_low_thresh()` / `set_prox_int_low_thresh(value)`
-  Get or set low proximity threshold
-
-* `get_prox_int_high_thresh()` / `set_prox_int_high_thresh(value)`
-  Get or set high proximity threshold
-
-* `get_proximity_int_enable()` / `set_proximity_int_enable(enable)`
-  Enable or disable proximity interrupts
-
-* `clear_proximity_int()`
-  Clear proximity interrupt
-
-* `get_prox_photo_mask()` / `set_prox_photo_mask(mask)`
-  Get or set proximity photodiode mask
-
-* `get_prox_gain_comp_enable()` / `set_prox_gain_comp_enable(enable)`
-  Enable or disable gain compensation
+* `sensor.get_proximity_gain()` / `sensor.set_proximity_gain(gain)` — proximity gain (0=1x, 1=2x, 2=4x, 3=8x)
+* `sensor.get_led_drive()` / `sensor.set_led_drive(drive)` — LED drive strength (0=100mA, 1=50mA, 2=25mA, 3=12.5mA)
+* `sensor.get_led_boost()` / `sensor.set_led_boost(boost)` — LED boost
+* `sensor.get_prox_int_low_thresh()` / `sensor.set_prox_int_low_thresh(value)` — low proximity threshold
+* `sensor.get_prox_int_high_thresh()` / `sensor.set_prox_int_high_thresh(value)` — high proximity threshold
+* `sensor.get_proximity_int_low_threshold()` / `sensor.set_proximity_int_low_threshold(value)` — low threshold (alternative)
+* `sensor.get_proximity_int_high_threshold()` / `sensor.set_proximity_int_high_threshold(value)` — high threshold (alternative)
+* `sensor.get_proximity_int_enable()` / `sensor.set_proximity_int_enable(enable)` — interrupt enable
+* `sensor.clear_proximity_int()` — clear proximity interrupt
+* `sensor.get_prox_photo_mask()` / `sensor.set_prox_photo_mask(mask)` — photodiode mask
+* `sensor.get_prox_gain_comp_enable()` / `sensor.set_prox_gain_comp_enable(enable)` — gain compensation
 
 ### Gesture
 
-#### Reading measurements
+#### Measurements
 
 ```python
 sensor.enable_gesture_sensor()
@@ -174,116 +115,51 @@ if sensor.is_gesture_available():
     gesture = sensor.gesture()
 ```
 
-* `gesture()`
-  Read detected gesture
+* `sensor.gesture()` — read detected gesture
+* `sensor.is_gesture_available()` — `True` when a gesture is pending
 
-* `is_gesture_available()`
-  Check if a gesture is available
+**Note:** Gesture detection is not auto-enabled. Call `enable_gesture_sensor()` before polling `gesture()`.
 
-#### Sensor control
+#### Control
 
-* `enable_gesture_sensor(interrupts=True)`
-  Enable gesture detection
-
-* `disable_gesture_sensor()`
-  Disable gesture detection
+* `sensor.enable_gesture_sensor(interrupts=True)` — enable gesture detection
+* `sensor.disable_gesture_sensor()` — disable gesture detection
 
 #### Configuration
 
-* `get_gesture_enter_thresh()` / `set_gesture_enter_thresh(value)`
-  Get or set gesture entry threshold
-
-* `get_gesture_exit_thresh()` / `set_gesture_exit_thresh(value)`
-  Get or set gesture exit threshold
-
-* `get_gesture_gain()` / `set_gesture_gain(value)`
-  Get or set gesture gain
-
-* `get_gesture_led_drive()` / `set_gesture_led_drive(value)`
-  Get or set gesture LED drive
-
-* `get_gesture_wait_time()` / `set_gesture_wait_time(value)`
-  Get or set gesture wait time
-
-* `get_gesture_int_enable()` / `set_gesture_int_enable(enable)`
-  Enable or disable gesture interrupts
-
-* `get_gesture_mode()` / `set_gesture_mode(enable)`
-  Enable or disable gesture mode
+* `sensor.get_gesture_enter_thresh()` / `sensor.set_gesture_enter_thresh(value)` — entry threshold
+* `sensor.get_gesture_exit_thresh()` / `sensor.set_gesture_exit_thresh(value)` — exit threshold
+* `sensor.get_gesture_gain()` / `sensor.set_gesture_gain(value)` — gesture gain
+* `sensor.get_gesture_led_drive()` / `sensor.set_gesture_led_drive(value)` — gesture LED drive
+* `sensor.get_gesture_wait_time()` / `sensor.set_gesture_wait_time(value)` — wait time between gesture cycles
+* `sensor.get_gesture_int_enable()` / `sensor.set_gesture_int_enable(enable)` — gesture interrupt enable
+* `sensor.get_gesture_mode()` / `sensor.set_gesture_mode(enable)` — gesture mode
 
 #### Advanced
 
-* `reset_gesture_parameters()`
-  Reset internal gesture state
-
-* `process_gesture_data()`
-  Process raw gesture data
-
-* `decode_gesture()`
-  Decode gesture direction from data
-
-## Sensor Control
-
-### Enable sensors
-
-```python
-sensor.enable_light_sensor()
-sensor.enable_proximity_sensor()
-sensor.enable_gesture_sensor()
-```
-
-### Disable sensors
-
-```python
-sensor.disable_light_sensor()
-sensor.disable_proximity_sensor()
-sensor.disable_gesture_sensor()
-```
-
-## Configuration Examples
-
-### Set ambient light gain
-
-```python
-sensor.set_ambient_light_gain(1)  # 1x, 4x, 16x, 64x
-```
-
-### Set proximity gain
-
-```python
-sensor.set_proximity_gain(2)  # 1x, 2x, 4x, 8x
-```
-
-### Set LED drive strength
-
-```python
-sensor.set_led_drive(0)  # 100mA, 50mA, 25mA, 12.5mA
-```
+* `sensor.reset_gesture_parameters()` — reset internal gesture state
+* `sensor.process_gesture_data()` — process raw gesture FIFO data
+* `sensor.decode_gesture()` — decode gesture direction from processed data
 
 ### Exceptions
 
-* `APDS9960InvalidDevId` — invalid device ID detected
-* `APDS9960InvalidMode` — invalid mode selection 
+* `APDS9960InvalidDevId` — raised when device ID does not match `0xAB`
+* `APDS9960InvalidMode` — raised for invalid mode selection
 
 ## Examples
 
-| Example                     | Description               |
-| --------------------------- | ------------------------- |
-| `examples/ambient_light.py` | Read ambient light values |
-| `examples/proximity.py`     | Detect object proximity   |
-| `examples/gesture.py`       | Detect gestures           |
+| File               | Description                      |
+| ------------------ | -------------------------------- |
+| `ambient_light.py` | Read ambient light and RGB values |
+| `proximity.py`     | Detect nearby objects             |
+| `gesture.py`       | Detect directional gestures       |
 
-Run example:
-
-```sh
+```bash
 mpremote mount lib/apds9960 run lib/apds9960/examples/ambient_light.py
 ```
 
 ## Notes
 
-* The driver automatically enables sensors when needed (lazy activation).
-* Gesture detection requires continuous polling via `gesture()`.
-* Works with both:
-
-  * `APDS9960` (generic Python)
-  * `uAPDS9960` (MicroPython optimized) 
+* Ambient light and proximity reads automatically enable their respective sensors when needed (lazy activation).
+* Gesture detection must be explicitly enabled before polling.
+* Both `APDS9960` and `uAPDS9960` (MicroPython-optimized) classes are exported.