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.
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.
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¶
#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:
EnsureInitialized()calls your port'sEnsureInitialized(), switches every output off whatever state the chip was left in, writesConfig{}(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.SetDuty(0, 1024)writes LED0's four registers in one transfer: on at count 0, off at count 1024 of 4096.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
Configfield, Kconfig. - Examples: the host example and the MCU examples.
- Platforms: which MCUs have a port and an example.