15#ifndef PCA9685_TYPES_HPP
16#define PCA9685_TYPES_HPP
22#include "pca9685_version.h"
39enum class [[nodiscard]]
Error : uint8_t {
90 return "NotInitialized";
92 return "InvalidArgument";
98 return "DeviceIdMismatch";
104 return "DeviceFault";
106 return "Unsupported";
108 return "WriteMismatch";
112 return "DeviceReset";
114 return "InvalidReply";
118 return "StateUnknown";
120 return "ExternalClockLatched";
140 [[nodiscard]]
constexpr bool ok() const noexcept {
141 return error == Error::Ok;
144 constexpr explicit operator bool() const noexcept {
154 return {v, Error::Ok};
172 [[nodiscard]]
constexpr bool ok() const noexcept {
173 return error == Error::Ok;
176 constexpr explicit operator bool() const noexcept {
305 return Pwm{.
on_count = 0U, .off_count = 0U, .full_on =
true, .full_off =
false};
329 return pwm.full_on || pwm.full_off || (pwm.on_count != pwm.off_count);
353 const uint32_t off = (
static_cast<uint32_t
>(phase) +
static_cast<uint32_t
>(duty)) & 0x0FFFU;
355 .off_count =
static_cast<uint16_t
>(off),
414 const uint32_t rounded = (oscillator_hz + (divisor / 2U)) / divisor;
427constexpr uint32_t
FrequencyFor(uint8_t prescale, uint32_t oscillator_hz)
noexcept {
428 const uint32_t divisor =
kCountsPerPeriod * (
static_cast<uint32_t
>(prescale) + 1U);
429 return (oscillator_hz + (divisor / 2U)) / divisor;
442 uint32_t oscillator_hz)
noexcept {
443 using detail::operator
""_u16;
444 if (width_us == 0U) {
447 const uint64_t per_count = 1'000'000ULL * (
static_cast<uint64_t
>(prescale) + 1ULL);
448 const uint64_t counts =
449 ((
static_cast<uint64_t
>(width_us) * oscillator_hz) + (per_count / 2ULL)) / per_count;
450 if ((counts == 0ULL) || (counts >
kMaxCount)) {
465 uint32_t oscillator_hz)
noexcept {
466 const uint64_t ticks =
static_cast<uint64_t
>(counts) * (
static_cast<uint64_t
>(prescale) + 1ULL);
467 const uint64_t osc = (oscillator_hz == 0U) ? 1ULL :
static_cast<uint64_t
>(oscillator_hz);
468 return static_cast<uint32_t
>(((ticks * 1'000'000'000ULL) + (osc / 2ULL)) / osc);
472 if (!detail::IsEnumerator(config.clock) || !detail::IsEnumerator(config.output_drive)) {
475 return PrescaleFor(config.pwm_frequency_hz, config.oscillator_hz).error;
488 c.invert_outputs =
true;
489 c.pwm_frequency_hz = 1000U;
525static_assert(
PwmForDuty(819U, 409U).value.off_count == 1228U);
527static_assert(
PwmForDuty(3686U, 3685U).value.off_count == 3275U);
531 !
IsValid(Pwm{.on_count = 4096U}));
558 [[nodiscard]]
constexpr const Config&
Get() const& noexcept {
562 void Get() const&& = delete;
570 return PCA9685_VERSION_STRING;
574 return PCA9685_VERSION_MAJOR;
578 return PCA9685_VERSION_MINOR;
582 return PCA9685_VERSION_PATCH;
A configuration proven valid at build time.
Definition pca9685_types.hpp:546
constexpr const Config & Get() const &noexcept
Definition pca9685_types.hpp:558
consteval CheckedConfig(const Config &config) noexcept
Check config at build time.
Definition pca9685_types.hpp:552
void Get() const &&=delete
Not on a temporary: the reference would dangle (KB-CPP20-044).
constexpr uint8_t kPreScaleReset
30: about 200 Hz from the 25 MHz oscillator.
Definition pca9685_registers.hpp:101
constexpr uint8_t kChannels
Number of LED channels.
Definition pca9685_registers.hpp:47
constexpr uint16_t kMaxCount
Highest LEDn_ON and LEDn_OFF count: the 12-bit counter runs 0 to 4095 (section 7.3....
Definition pca9685_registers.hpp:96
constexpr uint8_t kPreScaleMin
The hardware forces at least 3 (1526 Hz).
Definition pca9685_registers.hpp:102
constexpr uint32_t FrequencyFor(uint8_t prescale, uint32_t oscillator_hz) noexcept
The PWM frequency a prescaler gives, rounded to the nearest hertz (equation 1 inverted).
Definition pca9685_types.hpp:427
constexpr Config DirectLedPreset() noexcept
LEDs wired from the supply through a resistor to the outputs (figure 15): open drain,...
Definition pca9685_types.hpp:485
constexpr uint32_t GetDriverVersionMinor() noexcept
Definition pca9685_types.hpp:577
constexpr Error Validate(const Config &config) noexcept
Check a configuration without touching the chip.
Definition pca9685_types.hpp:471
constexpr uint32_t GetDriverVersionPatch() noexcept
Definition pca9685_types.hpp:581
constexpr Result< uint8_t > PrescaleFor(uint32_t frequency_hz, uint32_t oscillator_hz) noexcept
The PRE_SCALE value for a frequency, by equation 1 of section 7.3.5, rounded to nearest.
Definition pca9685_types.hpp:407
constexpr uint32_t PulseNsForCounts(uint16_t counts, uint8_t prescale, uint32_t oscillator_hz) noexcept
The pulse width of a number of counts, in nanoseconds, rounded to nearest: what a quantised SetPulseW...
Definition pca9685_types.hpp:464
constexpr bool IsOff(const Pwm &pwm) noexcept
Whether a channel value switches the channel off: LEDn_OFF_H[4] set, which takes precedence over ever...
Definition pca9685_types.hpp:314
constexpr Config ServoPreset() noexcept
Hobby servos and external N-type drivers (figure 13): totem pole, not inverted, so the reset level,...
Definition pca9685_types.hpp:498
constexpr uint8_t kChannelCount
Number of PWM channels, LED0 to LED15.
Definition pca9685_types.hpp:253
LogLevel
Severity passed to the optional Log() hook.
Definition pca9685_types.hpp:195
constexpr const char * ToString(Error error) noexcept
The name of an error, for logs.
Definition pca9685_types.hpp:85
constexpr uint8_t kMinI2cAddress
Lowest I2C address of a PCA9685: 1 A5 A4 A3 A2 A1 A0 with every pin low (figure 4).
Definition pca9685_types.hpp:273
constexpr Result< Pwm > PwmForDuty(uint16_t duty, uint16_t phase=0U) noexcept
The channel value for a duty cycle and a phase delay.
Definition pca9685_types.hpp:343
constexpr uint8_t kMaxI2cAddress
Highest I2C address of a PCA9685, every address pin high.
Definition pca9685_types.hpp:275
constexpr uint32_t kMaxOscillatorHz
Highest EXTCLK frequency, in hertz (table 15, f_EXTCLK).
Definition pca9685_types.hpp:263
constexpr Result< uint16_t > CountsForPulseUs(uint32_t width_us, uint8_t prescale, uint32_t oscillator_hz) noexcept
The counts of a pulse width at a prescaler: one count is (prescale + 1) / oscillator seconds....
Definition pca9685_types.hpp:441
ClockSource
The clock the PWM counter runs from (MODE1.EXTCLK, table 5).
Definition pca9685_types.hpp:216
constexpr uint16_t kFullDuty
SetDuty() value for a channel that is on for the whole period (full ON).
Definition pca9685_types.hpp:259
constexpr uint32_t kOscillatorStartUs
Oscillator start-up after SLEEP is cleared, in microseconds (table 5, note 2: 500 us maximum).
Definition pca9685_types.hpp:271
SleepMode
What Sleep() does with the outputs (section 7.3.1.1).
Definition pca9685_types.hpp:222
OutputDrive
The output stage of all 16 outputs (MODE2.OUTDRV, table 6).
Definition pca9685_types.hpp:210
void ConfigIsInvalid() noexcept
Reached only when a CheckedConfig is built from an invalid configuration: it is never defined,...
constexpr const char * GetDriverVersion() noexcept
Definition pca9685_types.hpp:569
constexpr uint32_t GetDriverVersionMajor() noexcept
Definition pca9685_types.hpp:573
constexpr Pwm PwmOff() noexcept
Definition pca9685_types.hpp:299
Error
Why a call failed. Every call of the driver returns one of these in its Result.
Definition pca9685_types.hpp:39
constexpr uint32_t kMaxPwmFrequencyHz
Definition pca9685_types.hpp:269
constexpr uint32_t kInternalOscillatorHz
Typical frequency of the internal oscillator, in hertz (section 2, table 5).
Definition pca9685_types.hpp:261
constexpr uint32_t kMinOscillatorHz
Definition pca9685_types.hpp:266
constexpr Pwm PwmFullOn() noexcept
Definition pca9685_types.hpp:304
constexpr uint16_t kMaxCount
Highest ON or OFF count, 4095.
Definition pca9685_types.hpp:257
constexpr bool IsValid(const Pwm &pwm) noexcept
Whether a channel value can be written: both counts at most 4095 and, unless a full bit is set,...
Definition pca9685_types.hpp:325
Verify
Whether a call reads back what it wrote (handbook KB-ARCH-041).
Definition pca9685_types.hpp:203
constexpr uint8_t kAllCallAddress
Definition pca9685_types.hpp:278
constexpr uint32_t kCountsPerPeriod
Counter steps per PWM period: 4096 (12 bits, section 7.3.3).
Definition pca9685_types.hpp:255
@ Warning
Something unexpected that the driver recovered from.
@ Info
Lifecycle events: initialised, reset found.
@ Debug
Detail for bring-up.
@ Internal
The internal oscillator, 25 MHz typical. Reset value.
@ External
The EXTCLK pin, DC to 50 MHz; sticky until a power cycle or software reset.
@ OpenDrain
Sink only. Needed for LEDs with integrated Zener diodes (section 10, Q5).
@ TotemPole
Sink 25 mA, source 10 mA. Reset value.
@ Crc
Not returned by this driver (I2C transfers carry no CRC).
@ DeviceFault
Not returned by this driver (the chip reports no faults).
@ Unsupported
The port has no output-enable GpioSet() hook, which this call needs.
@ Timeout
Not returned by this driver (no wait polls the chip).
@ Busy
Not returned by this driver (the chip has no busy state).
@ None
Write only. Default.
The PCA9685 driver: everything it declares lives here; internals in detail.
Definition pca9685.hpp:30
Compile-time helpers of the PCA9685 driver: typed integer literals, exact hook matching,...
PCA9685 register map: addresses, bit fields and reset values (datasheet section 7....
Everything EnsureInitialized() writes to the chip.
Definition pca9685_types.hpp:377
bool invert_outputs
MODE2.INVRT. Reset value: not inverted.
Definition pca9685_types.hpp:385
uint32_t pwm_frequency_hz
Definition pca9685_types.hpp:378
uint32_t oscillator_hz
Definition pca9685_types.hpp:380
OutputDrive output_drive
MODE2.OUTDRV. Reset value: totem pole.
Definition pca9685_types.hpp:384
ClockSource clock
MODE1.EXTCLK. Reset value: internal.
Definition pca9685_types.hpp:383
The value of one channel: its four registers, decoded (table 7, figure 9).
Definition pca9685_types.hpp:287
bool full_on
LEDn_ON_H[4].
Definition pca9685_types.hpp:291
uint16_t off_count
Definition pca9685_types.hpp:289
friend constexpr bool operator==(const Pwm &lhs, const Pwm &rhs) noexcept=default
Exact comparison of every field (integral members only, KB-CPP20-033).
bool full_off
LEDn_OFF_H[4]. Reset value: set.
Definition pca9685_types.hpp:292
uint16_t on_count
LEDn_ON[11:0], 0 to 4095.
Definition pca9685_types.hpp:288
static constexpr Result Success() noexcept
Definition pca9685_types.hpp:181
static constexpr Result Failure(Error e) noexcept
A failed result.
Definition pca9685_types.hpp:189
constexpr bool ok() const noexcept
Definition pca9685_types.hpp:172
The value of a call, or why there is none.
Definition pca9685_types.hpp:135
constexpr bool ok() const noexcept
Definition pca9685_types.hpp:140
static constexpr Result Success(T v) noexcept
A successful result.
Definition pca9685_types.hpp:153
static constexpr Result Failure(Error e) noexcept
A failed result.
Definition pca9685_types.hpp:161