|
PCA9685 Driver 0.1.0
API reference
|
The PCA9685 driver: everything it declares lives here; internals in detail.
More...
Namespaces | |
| namespace | reg |
| The PCA9685 register map. | |
Classes | |
| class | CheckedConfig |
| A configuration proven valid at build time. More... | |
| struct | Config |
Everything EnsureInitialized() writes to the chip. More... | |
| class | I2cInterface |
| CRTP base of the platform I2C port. More... | |
| class | PCA9685 |
| Driver for one PCA9685 on a platform port. More... | |
| struct | Pwm |
| The value of one channel: its four registers, decoded (table 7, figure 9). More... | |
| struct | Result |
| The value of a call, or why there is none. More... | |
| struct | Result< void > |
| The result of a call that returns no value. More... | |
Concepts | |
| concept | I2cPort |
Satisfied by a class that derives from I2cInterface<Port> and implements the required bus hooks with exactly the types above, noexcept and returning bool. | |
Enumerations | |
| enum class | CtrlPin : uint8_t { OutputEnable = 0 } |
Control pins the port may drive through the optional GpioSet() hook. More... | |
| enum class | GpioSignal : uint8_t { INACTIVE = 0 , ACTIVE = 1 } |
| Logical level of a control pin; the port maps it to the physical polarity. More... | |
| enum class | I2cFailure : uint8_t { Other = 0 , AddressNack = 1 , DataNack = 2 } |
Why a Write() or WriteRead() hook returned false, as the optional GetLastFailure() hook reports it. More... | |
| enum class | Error : uint8_t { Error::Ok = 0 , Error::NotInitialized = 1 , Error::InvalidArgument = 2 , Error::Bus = 3 , Error::Timeout = 4 , Error::DeviceIdMismatch = 5 , Error::Crc = 6 , Error::Busy = 7 , Error::DeviceFault = 8 , Error::Unsupported = 9 , Error::WriteMismatch = 16 , Error::NoDevice = 17 , Error::DeviceReset , Error::InvalidReply = 19 , Error::Asleep = 20 , Error::StateUnknown = 21 , Error::ExternalClockLatched = 22 } |
Why a call failed. Every call of the driver returns one of these in its Result. More... | |
| enum class | LogLevel : uint8_t { LogLevel::Error = 0 , LogLevel::Warning , LogLevel::Info , LogLevel::Debug } |
Severity passed to the optional Log() hook. More... | |
| enum class | Verify : uint8_t { Verify::None = 0 , Verify::ReadBack = 1 } |
| Whether a call reads back what it wrote (handbook KB-ARCH-041). More... | |
| enum class | OutputDrive : uint8_t { OutputDrive::OpenDrain = 0 , OutputDrive::TotemPole = 1 } |
| The output stage of all 16 outputs (MODE2.OUTDRV, table 6). More... | |
| enum class | ClockSource : uint8_t { ClockSource::Internal = 0 , ClockSource::External = 1 } |
| The clock the PWM counter runs from (MODE1.EXTCLK, table 5). More... | |
| enum class | SleepMode : uint8_t { SleepMode::OutputsOff = 0 , SleepMode::HoldOutputs = 1 } |
What Sleep() does with the outputs (section 7.3.1.1). More... | |
Functions | |
| constexpr Config | KconfigDefaults () noexcept |
| The configuration menuconfig selected, on top of the reset values. | |
| constexpr const char * | ToString (Error error) noexcept |
| The name of an error, for logs. | |
| constexpr Pwm | PwmOff () noexcept |
| constexpr Pwm | PwmFullOn () noexcept |
| constexpr bool | IsOff (const Pwm &pwm) noexcept |
| Whether a channel value switches the channel off: LEDn_OFF_H[4] set, which takes precedence over everything else (section 7.3.3). | |
| 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, different (the registers "should never be programmed with the same values", section 7.3.4). | |
| constexpr Result< Pwm > | PwmForDuty (uint16_t duty, uint16_t phase=0U) noexcept |
| The channel value for a duty cycle and a phase delay. | |
| constexpr Error | Validate (const Config &config) noexcept |
| Check a configuration without touching the chip. | |
| 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. | |
| 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). | |
| 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. Uses the chip's programmed prescaler (handbook KB-CPP-128). | |
| 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 SetPulseWidthUs() programmed. | |
| constexpr Config | DirectLedPreset () noexcept |
LEDs wired from the supply through a resistor to the outputs (figure 15): open drain, inverted, so that a channel that is off leaves the output high impedance and the LED dark. Mind the reset level: a chip that resets is not inverted and drives every output low, which lights such an LED until EnsureInitialized() runs again (docs/hardware.md). | |
| constexpr Config | ServoPreset () noexcept |
| Hobby servos and external N-type drivers (figure 13): totem pole, not inverted, so the reset level, low, is off. 50 Hz, a 20 ms period. | |
| void | ConfigIsInvalid () noexcept |
Reached only when a CheckedConfig is built from an invalid configuration: it is never defined, so the build fails and names it (KB-CPP20-013). | |
| constexpr const char * | GetDriverVersion () noexcept |
| constexpr uint32_t | GetDriverVersionMajor () noexcept |
| constexpr uint32_t | GetDriverVersionMinor () noexcept |
| constexpr uint32_t | GetDriverVersionPatch () noexcept |
Variables | |
| constexpr uint8_t | kChannelCount = reg::kChannels |
| Number of PWM channels, LED0 to LED15. | |
| constexpr uint32_t | kCountsPerPeriod = 4096U |
| Counter steps per PWM period: 4096 (12 bits, section 7.3.3). | |
| constexpr uint16_t | kMaxCount = reg::kMaxCount |
| Highest ON or OFF count, 4095. | |
| constexpr uint16_t | kFullDuty = 4096U |
SetDuty() value for a channel that is on for the whole period (full ON). | |
| constexpr uint32_t | kInternalOscillatorHz = 25'000'000U |
| Typical frequency of the internal oscillator, in hertz (section 2, table 5). | |
| constexpr uint32_t | kMaxOscillatorHz = 50'000'000U |
| Highest EXTCLK frequency, in hertz (table 15, f_EXTCLK). | |
| constexpr uint32_t | kMinOscillatorHz = 1'000'000U |
| constexpr uint32_t | kMaxPwmFrequencyHz = 10'000U |
| constexpr uint32_t | kOscillatorStartUs = 500U |
| Oscillator start-up after SLEEP is cleared, in microseconds (table 5, note 2: 500 us maximum). | |
| constexpr uint8_t | kMinI2cAddress = 0x40 |
| Lowest I2C address of a PCA9685: 1 A5 A4 A3 A2 A1 A0 with every pin low (figure 4). | |
| constexpr uint8_t | kMaxI2cAddress = 0x7F |
| Highest I2C address of a PCA9685, every address pin high. | |
| constexpr uint8_t | kAllCallAddress = 0x70 |
Bus requirements | |
What the PCA9685 needs from the I2C bus. A port and a board configuration check their settings against these with | |
| constexpr uint8_t | kI2cAddress = kMinI2cAddress |
| 7-bit I2C address with A5 to A0 low, 1000000 (section 7.1.1, figure 4); the pins add 0 to 63. | |
| constexpr uint32_t | kMaxClockHz = 1'000'000U |
| Highest SCL frequency: Fast-mode Plus, 1 MHz (table 15, f_SCL). | |
| constexpr bool | kRepeatedStart = true |
The PCA9685 driver: everything it declares lives here; internals in detail.
|
strong |
Control pins the port may drive through the optional GpioSet() hook.
|
strong |
|
strong |
Why a Write() or WriteRead() hook returned false, as the optional GetLastFailure() hook reports it.
Only AddressNack changes what the driver returns: nothing acknowledged the address byte, so nothing reached the chip, and the driver returns Error::NoDevice and keeps its copy. Every other failure, and every failure of a port without the hook, is Error::Bus, and the bytes the chip acknowledged before it may have been stored.
|
constexprnoexcept |
The configuration menuconfig selected, on top of the reset values.
Config{} with the frequency, clock and output options taken from Kconfig.
|
inlineconstexpr |
true: a register read is a combined write-read with a repeated START (figure 22): the control register is written, then the address is sent again with R/W = 1.