From cce1f4a966157fddf3d4eec8abb8783bf24197e6 Mon Sep 17 00:00:00 2001 From: Charly-sketch Date: Mon, 23 Mar 2026 15:51:28 +0100 Subject: [PATCH 1/2] docs: Expand README for apds9960 driver. --- lib/apds9960/README.md | 284 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 282 insertions(+), 2 deletions(-) diff --git a/lib/apds9960/README.md b/lib/apds9960/README.md index 1d784eba..278ccc10 100644 --- a/lib/apds9960/README.md +++ b/lib/apds9960/README.md @@ -2,8 +2,288 @@ This library is a port of the [Python (and MicroPython) APDS-9960 Library](https://github.com/liske/python-apds9960/). -The examples could be easily tested with [mpremote](https://docs.micropython.org/en/latest/reference/mpremote.html) with the following command : +## Features + +The APDS-9960 is a multifunction sensor providing: + +* **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) + +## I2C Address + +Default I2C address: + +```python +0x39 +``` + +## Basic Usage + +```python +from machine import I2C, Pin +from apds9960 import uAPDS9960 + +i2c = I2C(0, scl=Pin(22), sda=Pin(21)) +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() +``` + +* `ambient_light()` + Read ambient (clear) light value + +* `red_light()` + Read red channel value + +* `green_light()` + Read green channel value + +* `blue_light()` + Read blue channel value + +* `light_ready()` + Check if light data is ready + +#### Sensor control + +* `enable_light_sensor(interrupts=True)` + Enable ambient light sensing + +* `disable_light_sensor()` + Disable ambient light sensing + +#### 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 + +### Proximity + +#### Reading measurements + +```python +proximity = sensor.proximity() +``` + +* `proximity()` + Read proximity value + +* `proximity_ready()` + Check if proximity data is ready + +#### Sensor control + +* `enable_proximity_sensor(interrupts=True)` + Enable proximity sensing + +* `disable_proximity_sensor()` + Disable proximity sensing + +#### 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 + +### Gesture + +#### Reading measurements + +```python +sensor.enable_gesture_sensor() + +if sensor.is_gesture_available(): + gesture = sensor.gesture() +``` + +* `gesture()` + Read detected gesture + +* `is_gesture_available()` + Check if a gesture is available + +#### Sensor control + +* `enable_gesture_sensor(interrupts=True)` + Enable gesture detection + +* `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 + +#### 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 +``` + +### Exceptions + +* `APDS9960InvalidDevId` — invalid device ID detected +* `APDS9960InvalidMode` — 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 | + +Run example: ```sh - mpremote mount . run examples/ambient_light.py +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) From f225ec4b89b31ef9c0f0a9f39a1c804fece86161 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20NEDJAR?= Date: Mon, 23 Mar 2026 17:09:35 +0100 Subject: [PATCH 2/2] docs: Rewrite apds9960 README addressing all review comments. --- lib/apds9960/README.md | 312 +++++++++++++---------------------------- 1 file changed, 94 insertions(+), 218 deletions(-) diff --git a/lib/apds9960/README.md b/lib/apds9960/README.md index 278ccc10..6720946a 100644 --- a/lib/apds9960/README.md +++ b/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.