WLED/usermods/pca9685

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:

   [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:

{
  "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:

{
  "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.