Configuration¶
pca9685::Config holds everything EnsureInitialized() writes to the chip. Its defaults are the chip's reset
values, so Config{} describes a chip that was just reset.
Datasheet sections this page relies on
From NXP PCA9685 Rev. 4:
- MODE1, sleep, EXTCLK and the oscillator start-up: 7.3.1 Mode register 1, MODE1; Table 5, p. 14
- MODE2, output drive, inversion, change on STOP, OUTNE: 7.3.2 Mode register 2, MODE2; Table 6, p. 16
- PWM frequency, PRE_SCALE: 7.3.5 PWM frequency PRE_SCALE; Equation 1, p. 25
- External drivers, INVRT and OUTDRV: 7.7 Using the PCA9685 with and without external drivers; Table 12; Figures 13 to 15, p. 29
All of them, with the driver API for each: Datasheet map.
Fields¶
| Field | Default (reset value) | Register | Range |
|---|---|---|---|
pwm_frequency_hz |
200 | PRE_SCALE = round(oscillator / (4096 x f)) - 1, 0x1E | PRE_SCALE 3 to 255: about 24 Hz to 1526 Hz at 25 MHz (section 7.3.5) |
oscillator_hz |
25 000 000 | (none: the arithmetic) | 1 MHz to 50 MHz; the internal oscillator is 25 MHz typical |
clock |
ClockSource::Internal |
MODE1.EXTCLK | External is sticky until a power cycle or software reset (table 5) |
output_drive |
OutputDrive::TotemPole |
MODE2.OUTDRV | OpenDrain for LEDs with Zener diodes (section 10, question 5) |
invert_outputs |
false |
MODE2.INVRT | true for loads wired active low (table 12) |
What the driver sets itself:
| Register bits | Value | Why |
|---|---|---|
| MODE1.AI | 1 | Bursts of up to 64 bytes; the reset sentinel (Contract) |
| MODE1.ALLCALL, SUB1 to SUB3 | 0 | No group address can change the chip behind the driver |
| MODE2.OCH | 0 | Every byte of one transfer reaches the outputs together at the STOP (Contract) |
| MODE2.OUTNE | the off level | OE high always switches the outputs off (Hardware) |
The frequency follows equation 1 with rounding: the frequency the chip runs at is
oscillator / (4096 x (PRE_SCALE + 1)), which GetPwmFrequencyHz() returns and FrequencyFor() computes
offline. 200 Hz programs 197 Hz, 50 Hz programs 50 Hz, 1000 Hz programs 1017 Hz.
Presets¶
| Preset | For | Differs from Config{} |
|---|---|---|
ServoPreset() |
Hobby servos, external N-type drivers | 50 Hz |
DirectLedPreset() |
LEDs wired from the supply into the outputs (figure 15) | 1000 Hz, open drain, inverted |
DirectLedPreset() wires a load active low: after a chip reset it is lit until EnsureInitialized() runs again
(Hardware).
pca9685::Config ZenerLedConfig() {
pca9685::Config c{}; // the reset values: 200 Hz, totem pole
c.output_drive = pca9685::OutputDrive::OpenDrain; // LEDs with Zener diodes (section 10, Q5)
c.pwm_frequency_hz = 1000; // PRE_SCALE 5
c.oscillator_hz = 25'000'000; // or the measured value of this board
return c; // pca9685::Validate(c) checks it offline
}
pca9685::Error StartLeds(MyPort& port) {
static pca9685::PCA9685<MyPort> pwm(port, 0x41, ZenerLedConfig()); // A0 high; no I/O
return pwm.EnsureInitialized().error; // InvalidArgument if the config is out of range
}
Validation¶
Validate(config) checks a configuration without the chip: every enumeration holds an enumerator, the oscillator
is in range, the frequency is 1 Hz to kMaxPwmFrequencyHz and its prescaler 3 to 255. EnsureInitialized() and
ApplyConfig() run it before any I/O and return InvalidArgument. A value is never clamped.
A configuration known at build time can be proven there:
// Rejected at build time, naming ConfigIsInvalid, if Validate() fails.
constexpr pca9685::CheckedConfig kBoard{pca9685::Config{.pwm_frequency_hz = 50}};
Changing it later¶
SetPwmFrequency() changes the frequency while running (API guide).
ApplyConfig() on a started driver runs the whole start-up again with the new configuration, which switches every
channel off first; before the start it only stores it.
Kconfig¶
Under ESP-IDF, idf.py menuconfig has a PCA9685 PWM controller menu (_config/Kconfig):
the frequency, the oscillator, the external clock, open drain and inversion. pca9685::KconfigDefaults() in
pca9685_kconfig.hpp returns Config{} with those values; without Kconfig it equals Config{}.