Skip to content

Quickstart

Run the driver on your PC first, with no hardware; then dim an LED from your MCU: wire the chip, write a small port class, call three driver functions.

Datasheet sections this page relies on

From NXP PCA9685 Rev. 4:

  • Pins and packages (TSSOP28, HVQFN28): 6 Pinning information; Table 3 Pin description, p. 6

All of them, with the driver API for each: Datasheet map.

Try it on your PC

examples/host/ runs the real driver against a simulated PCA9685, through a host port. From the repository root, with CMake and a C++20 compiler:

cmake -S examples/host -B build-example
cmake --build build-example
./build-example/pca9685_host_example
PCA9685 driver 0.1.0 on the host
pca9685: initialised
PWM 50 Hz (PRE_SCALE 121)
LED0 duty 0/4096
LED0 duty 1024/4096
LED0 duty 2048/4096
LED0 duty 3072/4096
LED0 duty 4096/4096
servo on LED1: 1498160 ns pulse

The calls in main.cpp are the ones below; only the port differs on an MCU. CI builds and runs this example on every pull request.

1. Wire it

MCU PCA9685 (TSSOP28 pin) Notes
I2C SCL SCL (26) Pull-up to VDD; 4.7 kΩ suits 100 kHz and 400 kHz
I2C SDA SDA (27) Pull-up to VDD
GND A0 to A5 (1 to 5, 24) Address 0x40 (kI2cAddress); the pins have no pull-ups, never leave one open
GND EXTCLK (25) Must be grounded when the internal oscillator is used
GND OE (23) Outputs always enabled for this example
3.3 V or 5 V VDD (28) 2.3 V to 5.5 V; 100 nF to VSS close to the pin
GND VSS (14)
LED0 (6) LED anode, cathode through 330 Ω to GND Driven high by the totem-pole output

The Hardware page has every pin of both packages, OE wired to a GPIO, servos, open-drain LEDs and the power.

2. Add the driver

Add the repository as a submodule and link the pca9685::pca9685 CMake target. Installation covers CMake on any MCU, the installed package and ESP-IDF.

git submodule add https://github.com/kokeb-labs-drivers/driver-pca9685.git external/driver-pca9685

3. Write the port

The port is the only platform code: it brings the bus up, moves bytes and waits. Replace the platform_* calls with your SDK's.

my_port.hpp
class MyPort : public pca9685::I2cInterface<MyPort> {
public:
  // Bring the bus up once; later calls return true at once.
  bool EnsureInitialized() noexcept {
    if (!ready_) {
      ready_ = platform_i2c_init();
    }
    return ready_;
  }

  // One write transaction: START, address + W, the bytes (register first), STOP.
  bool Write(uint8_t addr, const uint8_t* data, std::size_t len) noexcept {
    return platform_i2c_write(addr, data, len);
  }

  // Write then read with a repeated START in between.
  bool WriteRead(uint8_t addr, const uint8_t* tx, std::size_t tx_len, uint8_t* rx,
                 std::size_t rx_len) noexcept {
    return platform_i2c_write_read(addr, tx, tx_len, rx, rx_len);
  }

  // Wait at least `us` microseconds: the 500 us oscillator start-up depends on it.
  void DelayUs(uint32_t us) noexcept {
    platform_delay_us(us);
  }

private:
  bool ready_ = false;
};

Porting explains each method, the optional hooks and the transfer rules.

4. Dim the LED

main.cpp
#include "pca9685.hpp"

int dim_led_to_quarter(MyPort& port) {
  pca9685::PCA9685<MyPort> pwm(port); // address 0x40 (A5..A0 low), Config{}: no I/O yet

  if (auto r = pwm.EnsureInitialized(); !r) { // 1. every channel off, configured, oscillator on
    return static_cast<int>(r.error); //    Bus or DeviceIdMismatch: check wiring and address
  }
  if (auto r = pwm.SetDuty(0, 1024); !r) { // 2. LED0 on for 1024 of 4096 counts, 200 Hz
    return static_cast<int>(r.error);
  }
  return static_cast<int>(pwm.SetChannelOff(0).error); // 3. off again: never refused
}

What each step does:

  1. EnsureInitialized() calls your port's EnsureInitialized(), switches every output off whatever state the chip was left in, writes Config{} (the reset values: 200 Hz, totem pole, not inverted), reads it back to prove a PCA9685 answers, and wakes the oscillator with its 500 µs start-up wait.
  2. SetDuty(0, 1024) writes LED0's four registers in one transfer: on at count 0, off at count 1024 of 4096.
  3. SetChannelOff(0) sets LED0's full OFF bit. A switch-off is never refused.

This example is built by the host CI, so it compiles against the current headers.

If it does not work

Symptom First thing to check
EnsureInitialized() returns Bus Nothing acknowledged 0x40: SDA, SCL, the pull-ups, VDD, A0 to A5 (Troubleshooting)
EnsureInitialized() returns DeviceIdMismatch Something answered that is not a PCA9685, or SDA is stuck
EnsureInitialized() returns ExternalClockLatched EXTCLK is set on the chip from an earlier run: power-cycle it
The calls return Ok but the LED stays dark OE is high, or the LED's polarity needs invert_outputs (Troubleshooting)

Next

  • API guide: servos, banks of channels, the frequency, sleep and resets.
  • Configuration: presets, every Config field, Kconfig.
  • Examples: the host example and the MCU examples.
  • Platforms: which MCUs have a port and an example.