Add APDS-9930 sensor documentation

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)