# PCA9685 Usermod

This usermod allows you to control a PCA9685 16-channel 12-bit PWM Servo Driver via I2C.

## Features
- **Specific Control**: 4x RGB LEDs + 2x White LEDs via JSON API.
- **Animation Support**: Mirrors WLED internal pixels to PCA9685 channels, allowing WLED effects and segments to work on I2C LEDs.

## Installation

1. Copy the `usermods/pca9685` folder to your WLED `usermods` directory (if not already there).
2. Add the `Adafruit PWM Servo Driver Library` to your `lib_deps`.
   In `platformio_override.ini`:
   ```ini
   [env:usermods]
   lib_deps = 
       adafruit/Adafruit PWM Servo Driver Library @ ^2.4.1
   ```
3. Register the usermod by adding `#include "usermods/pca9685/usermod_pca9685.h"` in `wled00/usermods_list.cpp` or ensuring it is picked up by the build system if configured that way (auto-discovery depends on WLED version, manual include is safer). 
   *However, WLED's `REGISTER_USERMOD` macro usually handles the hook if the file is included in the build.* 

   **Recommended:** Add `-D USERMOD_PCA9685` to your build flags and use `wled00/usermods_list.cpp` to conditionally include it if you want to keep it optional, OR just include the header if compiling a custom build.

## Configuration

Navigate to the "Usermods" settings page in WLED.
- **enabled**: Enable/Disable the usermod.
- **i2c_addr**: I2C address of the PCA9685 (default 64 / 0x40).
- **pwm_freq**: PWM frequency in Hz (default 50).

## Usage (JSON API)

### Smart Control (RGB & White)
Control 4 RGB LEDs and 2 White LEDs using standard 0-255 values.
* **RGB 1-4**: Mapped to channels 0-11 in groups of 3 (RGB).
* **White 1-2**: Mapped to channels 12 and 13.

**Example Payload:**
```json
{
  "pca9685": {
    "rgb": [
      [255, 0, 0],   // RGB 1 (Red)
      [0, 255, 0],   // RGB 2 (Green)
      [0, 0, 255],   // RGB 3 (Blue)
      [255, 255, 0]  // RGB 4 (Yellow)
    ],
    "white": [
      255, // White 1 (Full Brightness)
      128  // White 2 (50% Brightness)
    ]
  }
}
```

### Raw Channel Control
Directly control any channel (0-15) with raw PWM values (0-4096).
* `4096` = Fully On
* `0` = Fully Off
* `0-4095` = PWM Duty Cycle

**Example:**
```json
{
  "pca9685": {
    "14": 4096, // Turn Channel 14 ON
    "15": 1024  // Set Channel 15 to 25% brightness
  }
}
```
**Note:** Raw control overrides Smart Control if both are sent for the same channel.

## Configuration Guide for Animations

### 1. Simple Setup (PCA9685 ONLY)
If you only have the PCA9685 connected:
*   Set **LED Preferences > Length** to `6`.
*   Effect segments will map 1:1.

### 2. Hybrid Setup (NeoPixel Strip + PCA9685)
Example: 300 LED Strip + PCA9685.
1.  **LED Preferences**:
    *   Set **Length** to `306` (300 for Strip + 6 for PCA).
    *   Set **LED Output 1** to control the first 300 LEDs (your physical strip).
2.  **Usermod Config**:
    *   Set **pixelOffset** to `300`.
    *   *Result:* Pixels 0-299 are your strip. Pixels 300-305 are mirrored to PCA9685.
3.  **Manual Control (White LEDs)**:
    *   If you want to control White LEDs manually via JSON API but keep RGB animations:
    *   Set **mirrorWhite** to `false`.
    *   Set **mirrorRgb** to `true`.
4.  **Segments**:
    *   **Segment 0**: 0-300 (Main Strip)
    *   **Segment 1**: 300-304 (PCA RGB) -> Apply Rainbow effect here.
    *   **Segment 2**: 304-306 (PCA White) -> Manual control or Breathe effect.