PCA9685 Driver 0.1.0
API reference
Loading...
Searching...
No Matches
Classes | Namespaces | Enumerations | Functions | Variables
pca9685_types.hpp File Reference

Public types of the PCA9685 driver: errors, Result<T>, channel values, configuration, presets and the frequency and pulse-width arithmetic. More...

#include <cstdint>
#include "pca9685_detail.hpp"
#include "pca9685_registers.hpp"
#include "pca9685_version.h"

Go to the source code of this file.

Classes

struct  pca9685::Result< T >
 The value of a call, or why there is none. More...
 
struct  pca9685::Result< void >
 The result of a call that returns no value. More...
 
struct  pca9685::Pwm
 The value of one channel: its four registers, decoded (table 7, figure 9). More...
 
struct  pca9685::Config
 Everything EnsureInitialized() writes to the chip. More...
 
class  pca9685::CheckedConfig
 A configuration proven valid at build time. More...
 

Namespaces

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

Enumerations

enum class  pca9685::Error : uint8_t {
  pca9685::Error::Ok = 0 , pca9685::Error::NotInitialized = 1 , pca9685::Error::InvalidArgument = 2 , pca9685::Error::Bus = 3 ,
  pca9685::Error::Timeout = 4 , pca9685::Error::DeviceIdMismatch = 5 , pca9685::Error::Crc = 6 , pca9685::Error::Busy = 7 ,
  pca9685::Error::DeviceFault = 8 , pca9685::Error::Unsupported = 9 , pca9685::Error::WriteMismatch = 16 , pca9685::Error::NoDevice = 17 ,
  pca9685::Error::DeviceReset , pca9685::Error::InvalidReply = 19 , pca9685::Error::Asleep = 20 , pca9685::Error::StateUnknown = 21 ,
  pca9685::Error::ExternalClockLatched = 22
}
 Why a call failed. Every call of the driver returns one of these in its Result. More...
 
enum class  pca9685::LogLevel : uint8_t { pca9685::LogLevel::Error = 0 , pca9685::LogLevel::Warning , pca9685::LogLevel::Info , pca9685::LogLevel::Debug }
 Severity passed to the optional Log() hook. More...
 
enum class  pca9685::Verify : uint8_t { pca9685::Verify::None = 0 , pca9685::Verify::ReadBack = 1 }
 Whether a call reads back what it wrote (handbook KB-ARCH-041). More...
 
enum class  pca9685::OutputDrive : uint8_t { pca9685::OutputDrive::OpenDrain = 0 , pca9685::OutputDrive::TotemPole = 1 }
 The output stage of all 16 outputs (MODE2.OUTDRV, table 6). More...
 
enum class  pca9685::ClockSource : uint8_t { pca9685::ClockSource::Internal = 0 , pca9685::ClockSource::External = 1 }
 The clock the PWM counter runs from (MODE1.EXTCLK, table 5). More...
 
enum class  pca9685::SleepMode : uint8_t { pca9685::SleepMode::OutputsOff = 0 , pca9685::SleepMode::HoldOutputs = 1 }
 What Sleep() does with the outputs (section 7.3.1.1). More...
 

Functions

constexpr const char * pca9685::ToString (Error error) noexcept
 The name of an error, for logs.
 
constexpr Pwm pca9685::PwmOff () noexcept
 
constexpr Pwm pca9685::PwmFullOn () noexcept
 
constexpr bool pca9685::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 pca9685::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 > pca9685::PwmForDuty (uint16_t duty, uint16_t phase=0U) noexcept
 The channel value for a duty cycle and a phase delay.
 
constexpr Error pca9685::Validate (const Config &config) noexcept
 Check a configuration without touching the chip.
 
constexpr Result< uint8_t > pca9685::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 pca9685::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 > pca9685::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 pca9685::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 pca9685::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 pca9685::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 pca9685::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 * pca9685::GetDriverVersion () noexcept
 
constexpr uint32_t pca9685::GetDriverVersionMajor () noexcept
 
constexpr uint32_t pca9685::GetDriverVersionMinor () noexcept
 
constexpr uint32_t pca9685::GetDriverVersionPatch () noexcept
 

Variables

constexpr uint8_t pca9685::kChannelCount = reg::kChannels
 Number of PWM channels, LED0 to LED15.
 
constexpr uint32_t pca9685::kCountsPerPeriod = 4096U
 Counter steps per PWM period: 4096 (12 bits, section 7.3.3).
 
constexpr uint16_t pca9685::kMaxCount = reg::kMaxCount
 Highest ON or OFF count, 4095.
 
constexpr uint16_t pca9685::kFullDuty = 4096U
 SetDuty() value for a channel that is on for the whole period (full ON).
 
constexpr uint32_t pca9685::kInternalOscillatorHz = 25'000'000U
 Typical frequency of the internal oscillator, in hertz (section 2, table 5).
 
constexpr uint32_t pca9685::kMaxOscillatorHz = 50'000'000U
 Highest EXTCLK frequency, in hertz (table 15, f_EXTCLK).
 
constexpr uint32_t pca9685::kMinOscillatorHz = 1'000'000U
 
constexpr uint32_t pca9685::kMaxPwmFrequencyHz = 10'000U
 
constexpr uint32_t pca9685::kOscillatorStartUs = 500U
 Oscillator start-up after SLEEP is cleared, in microseconds (table 5, note 2: 500 us maximum).
 
constexpr uint8_t pca9685::kMinI2cAddress = 0x40
 Lowest I2C address of a PCA9685: 1 A5 A4 A3 A2 A1 A0 with every pin low (figure 4).
 
constexpr uint8_t pca9685::kMaxI2cAddress = 0x7F
 Highest I2C address of a PCA9685, every address pin high.
 
constexpr uint8_t pca9685::kAllCallAddress = 0x70
 

Detailed Description

Public types of the PCA9685 driver: errors, Result<T>, channel values, configuration, presets and the frequency and pulse-width arithmetic.

Everything here is plain data and constexpr arithmetic with no platform dependency, so handlers, tests and tools can include it without the driver template. The configuration defaults are the chip's reset values (section 7.3), so Config{} describes a chip that was just reset.

Section, table and figure numbers refer to the NXP PCA9685 product data sheet, Rev. 4 (16 April 2015).