diff --git a/public/images/apds9930.jpg b/public/images/apds9930.jpg new file mode 100644 index 0000000000..603292d9e4 Binary files /dev/null and b/public/images/apds9930.jpg differ diff --git a/src/content/docs/components/sensor/apds9930.md b/src/content/docs/components/sensor/apds9930.md new file mode 100644 index 0000000000..f1699c32fa --- /dev/null +++ b/src/content/docs/components/sensor/apds9930.md @@ -0,0 +1,217 @@ +--- +description: "Instructions for setting up APDS9930 sensors." +title: "APDS9930 Sensor" +params: + seo: + description: Instructions for setting up APDS9930 sensors. + image: apds9930.jpg +--- + +{{< anchor "apds9930-component" >}} + +## Component/Hub + +The `apds9930` sensor platform allows you to use your APDS9930 ambient light and proximity sensors +([datasheet](https://docs.broadcom.com/doc/AV02-3190EN), +[Broadcom](https://www.broadcom.com/products/optical-sensors/ambient-light-photo-sensors/apds-9930)) with ESPHome. +The [I²C](/components/i2c) is +required to be set up in your configuration for this sensor to work. + +{{< img src="apds9930.jpg" alt="APDS9930 Module" caption="APDS9930 Ambient Light and Proximity Sensor Module" width="80.0%" class="align-center" >}} + +```yaml +# Example configuration entry +apds9930: + address: 0x39 + update_interval: 60s + led_drive: 100ma + proximity_gain: 8x + ambient_light_gain: 1x + +sensor: + - platform: apds9930 + type: illuminance + illuminance: + name: "Room Illuminance" + + - platform: apds9930 + type: proximity + proximity: + name: "Object Proximity" +``` + +## Configuration variables + +The configuration is made up of two parts: The central component and individual sensors. + +### Base Configuration + +- **address** (*Optional*, int): The I²C address of the sensor. Defaults to `0x39`. +- **update_interval** (*Optional*, [Time](/guides/configuration-types#time)): The interval + to check the sensor. Defaults to `60s`. + +- **led_drive** (*Optional*): The LED drive strength for proximity detection. One of `100ma`, `50ma`, `25ma`, `12.5ma`. Defaults to `100ma`. +- **proximity_gain** (*Optional*): The proximity sensor gain level. One of `1x`, `2x`, `4x`, `8x`. Defaults to `8x`. +- **ambient_light_gain** (*Optional*): The ambient light sensor gain level. One of `1x`, `8x`, `16x`, `120x`. Defaults to `1x`. +- **proximity_diode** (*Optional*, int): Which diode to use for proximity detection. Valid range: 0-3. Defaults to `2`. + +## Sensor + +The `apds9930` sensor allows you to use your {{< docref "apds9930/" >}} to perform different +measurements. + +Configuration variables: + +- **type** (**Required**, string): The type of sensor measurement. One of + + - `illuminance` - Measures illuminance in lux using a two-channel photodiode with IR compensation + - `proximity` - Measures object proximity as a raw 16-bit value (0-1023, higher values indicate closer objects) + +- **apds9930_id** (*Optional*, [ID](/guides/configuration-types#config-id)): Manually specify the ID of the APDS9930 hub. +- All other options from [Sensor](/components/sensor). + +## Sensor Types Details + +### Ambient Light Sensor + +The ambient light sensor uses two photodiodes (Ch0: visible + IR, Ch1: IR only) to calculate accurate lux values with IR compensation. The sensor automatically adjusts for different lighting conditions and provides illuminance measurements suitable for: + +- Automatic display brightness adjustment +- Daylight harvesting systems +- Light level monitoring +- Circadian rhythm lighting control + +**Output**: Illuminance in lux (unit: `lx`, device class: `illuminance`) + +### Proximity Sensor + +The proximity sensor uses an infrared LED and photodiode to detect nearby objects. Unlike the APDS9960 which outputs percentages, the APDS9930 provides raw 16-bit proximity counts (0-1023) for higher resolution and more flexible threshold configuration. + +**Output**: Raw proximity count (0-1023, unitless, higher values = closer objects) + +**Typical values**: + +- Far away (>10cm): 0-50 +- Medium distance (5-10cm): 50-200 +- Near (<5cm): 200-1023 + +## Advanced Configuration + +### Gain Settings + +The gain settings affect sensor sensitivity. Higher gain increases sensitivity but may cause saturation in bright conditions. + +**Ambient Light Gain**: + +- `1x`: Best for bright environments (>1000 lux) +- `8x`: Good for office lighting (100-1000 lux) +- `16x`: Good for dim lighting (10-100 lux) +- `120x`: Best for very dim conditions (<10 lux) + +**Proximity Gain**: + +- `1x`: Short range, less sensitive +- `2x`: Moderate range +- `4x`: Good range +- `8x`: Maximum range and sensitivity (default) + +### LED Drive Strength + +Controls the infrared LED current for proximity detection. Higher current increases detection range but consumes more power: + +- `100ma`: Maximum range (default) +- `50ma`: Good range, lower power +- `25ma`: Reduced range, low power +- `12.5ma`: Minimal range, minimum power + +## Complete Example + +```yaml +i2c: + sda: GPIO21 + scl: GPIO22 + scan: true + +apds9930: + address: 0x39 + update_interval: 60s + led_drive: 100ma + proximity_gain: 8x + ambient_light_gain: 1x + proximity_diode: 2 + +sensor: + - platform: apds9930 + type: illuminance + illuminance: + name: "Living Room Illuminance" + id: living_room_lux + filters: + - sliding_window_moving_average: + window_size: 5 + send_every: 5 + on_value_range: + - below: 50 + then: + - light.turn_on: main_light + - above: 200 + then: + - light.turn_off: main_light + + - platform: apds9930 + type: proximity + proximity: + name: "Object Proximity" + id: object_proximity + filters: + - throttle: 1s + on_value_range: + - above: 500 + then: + - logger.log: "Object detected nearby" + - switch.turn_on: proximity_alert + - below: 100 + then: + - switch.turn_off: proximity_alert +``` + +## Troubleshooting + +### Proximity Sensor Not Responding + +- Increase `led_drive` to `100ma` for maximum range +- Increase `proximity_gain` to `8x` +- Verify the IR LED is powered (some modules require VL pin connection) +- Check for obstructions or coverings on the sensor +- Ensure the proximity diode setting is correct (default: `2`) + +### Noisy or Unstable Readings + +- Add filters to smooth readings: + + ```yaml + filters: + - sliding_window_moving_average: + window_size: 10 + send_every: 5 + ``` + +- Reduce `update_interval` for faster updates +- Shield sensor from electrical noise sources +- Use proper power supply decoupling capacitors + +## Device IDs + +The APDS9930 may report one of two device IDs: + +- `0x12` - Most common +- `0x39` - Alternative ID + +Both IDs are valid and the component automatically recognizes either. + +## See Also + +- [Sensor Filters](/components/sensor#sensor-filters) +- [I²C Bus](/components/i2c) +- {{< apiref "apds9930/apds9930.h" "apds9930/apds9930.h" >}} +- [APDS9930 Datasheet](https://docs.broadcom.com/doc/AV02-3190EN) diff --git a/src/content/docs/components/sensor/images/apds9930.jpg b/src/content/docs/components/sensor/images/apds9930.jpg new file mode 100644 index 0000000000..603292d9e4 Binary files /dev/null and b/src/content/docs/components/sensor/images/apds9930.jpg differ