96 lines
3.3 KiB
Markdown
96 lines
3.3 KiB
Markdown
# 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.
|