PCA9685 Driver 0.1.0
API reference
Loading...
Searching...
No Matches
Namespaces | Classes | Concepts | Enumerations | Functions | Variables
pca9685 Namespace 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 static_assert (handbook KB-CPP-123).

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
 

Detailed Description

The PCA9685 driver: everything it declares lives here; internals in detail.

Enumeration Type Documentation

◆ CtrlPin

enum class pca9685::CtrlPin : uint8_t
strong

Control pins the port may drive through the optional GpioSet() hook.

Enumerator
OutputEnable 

OE, active low on the package pin (section 7.4). INACTIVE (pin high) sets every output to the MODE2.OUTNE level, which the driver makes the level of a channel that is off; ACTIVE (pin low) lets the channels drive.

◆ GpioSignal

enum class pca9685::GpioSignal : uint8_t
strong

Logical level of a control pin; the port maps it to the physical polarity.

Enumerator
INACTIVE 

The pin function is deasserted: for OE, outputs disabled (pin high).

ACTIVE 

The pin function is asserted: for OE, outputs enabled (pin low).

◆ I2cFailure

enum class pca9685::I2cFailure : uint8_t
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.

Enumerator
Other 

Arbitration lost, a stuck line, a timeout, or a NACK the port cannot place.

AddressNack 

No device acknowledged the address byte.

DataNack 

The device acknowledged its address, then not a data byte.

Function Documentation

◆ KconfigDefaults()

constexpr Config pca9685::KconfigDefaults ( )
constexprnoexcept

The configuration menuconfig selected, on top of the reset values.

Returns
Config{} with the frequency, clock and output options taken from Kconfig.

Variable Documentation

◆ kRepeatedStart

constexpr bool pca9685::kRepeatedStart = true
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.