|
PCA9685 Driver 0.1.0
API reference
|
Driver for one PCA9685 on a platform port. More...
#include <pca9685.hpp>
Public Member Functions | |
| PCA9685 (Port &port, uint8_t address=kI2cAddress, const Config &config={}) noexcept | |
Bind the driver to a port, a 7-bit I2C address and a configuration. No I/O, no checks: EnsureInitialized() validates both. | |
| PCA9685 (const PCA9685 &)=delete | |
| One driver object per chip. | |
| PCA9685 & | operator= (const PCA9685 &)=delete |
| One driver object per chip. | |
Lifecycle | |
| Result< void > | EnsureInitialized () noexcept |
Start the chip on the first call. Once it has succeeded, a later call runs the reset check (one 3-byte read) and returns Ok, or starts again from step 1 when the chip reset. | |
| bool | IsInitialized () const noexcept |
| Result< void > | Deinitialize () noexcept |
| Switch every channel off and put the chip to sleep, its low-power safe state, and mark the driver uninitialised. | |
| Result< void > | ApplyConfig (const Config &config) noexcept |
Replace the configuration. When initialised, run the whole start-up of EnsureInitialized() again with it, which switches every channel off first; otherwise only store it (no I/O). | |
| const Config & | GetConfig () const &noexcept |
| void | GetConfig () const &&=delete |
| Not on a temporary driver: the reference would dangle (handbook KB-CPP20-044). | |
| uint8_t | GetAddress () const noexcept |
| Result< void > | CheckForReset () noexcept |
| Find out whether the chip reset since the start: one 3-byte read of MODE1, MODE2 and SUBADR1 (about 90 us at 400 kHz), a second one only to confirm reset evidence; also the pending wake check, when there is one (one more read). | |
Channels | |
| Result< void > | SetPwm (uint8_t channel, const Pwm &value, Verify verify=Verify::None) noexcept |
| Set one channel to a value: one 4-byte write (LEDn_ON_L to LEDn_OFF_H), or for an off value the one byte LEDn_OFF_H = 0x10. | |
| Result< void > | SetDuty (uint8_t channel, uint16_t duty, uint16_t phase=0U, Verify verify=Verify::None) noexcept |
Set one channel to a duty cycle with a phase delay (PwmForDuty()), as SetPwm(). | |
| Result< uint32_t > | SetPulseWidthUs (uint8_t channel, uint32_t width_us, Verify verify=Verify::None) noexcept |
Set one channel to a pulse of width_us at the start of each period, as SetPwm(). | |
| Result< void > | SetFullOn (uint8_t channel, Verify verify=Verify::None) noexcept |
Switch one channel fully on (LEDn_ON_H bit 4), as SetPwm(channel, PwmFullOn()). | |
| Result< void > | SetChannelOff (uint8_t channel, Verify verify=Verify::None) noexcept |
Switch one channel off (LEDn_OFF_H bit 4), as SetPwm(channel, PwmOff()). Never refused. | |
| Result< void > | SetChannels (uint8_t first, std::span< const Pwm > values) noexcept |
Set values.size() consecutive channels from first in one transfer, so that with OCH = 0 they change together at the STOP (section 7.3.2, note 2). | |
| Result< void > | SetChannelsOff (uint16_t mask) noexcept |
Switch off every channel in mask (bit n = channel n), one data byte per channel (LEDn_OFF_H = 0x10). Never refused: a failed write does not stop the others. A mask of 0 sends nothing. | |
| Result< void > | SetAllOff () noexcept |
| Switch every channel off with one data byte, ALL_LED_OFF_H = 0x10 (figure 24, the orderly shutdown of section 7.3.1.1). Never refused. | |
| Result< Pwm > | GetChannel (uint8_t channel) const noexcept |
| The value the driver last wrote to or read from a channel. No I/O. | |
| uint16_t | GetUncertainChannels () const noexcept |
| Result< Pwm > | ReadChannel (uint8_t channel) noexcept |
Read one channel from the chip into the driver's copy: one 3-byte read of MODE1, MODE2 and SUBADR1 (the reset check: a 4-byte read needs AI) and one 4-byte read. A read of all zeros, which SDA stuck low also gives, is confirmed by one more MODE1/MODE2/SUBADR1 read and is InvalidReply when that read does not match the running chip. | |
| Result< std::array< Pwm, kChannelCount > > | ReadChannels () noexcept |
| Read all 16 channels into the driver's copy: the reset check, then one 64-byte read. Makes every channel known again. | |
Output enable (OE pin) | |
| Result< void > | DisableOutputs () noexcept |
Drive OE high: every output goes to the MODE2.OUTNE level, which the driver makes the level of a channel that is off, within 60 ns (table 15, t_PHZ). The fast switch-off: no I2C, and it works in every state, uninitialised, asleep or with a broken bus. Before the first EnsureInitialized() and after a chip reset, OUTNE is the reset value: low. | |
| Result< void > | EnableOutputs () noexcept |
| Drive OE low: the outputs follow their channels again. A switch-on of every channel at once, so it is refused while any channel is unknown or the wake check fails. | |
Frequency, sleep and restart | |
| Result< void > | SetPwmFrequency (uint32_t frequency_hz) noexcept |
| Change the PWM frequency of all channels (PRE_SCALE, section 7.3.5). | |
| Result< uint8_t > | GetPrescale () const noexcept |
| The prescaler the driver last wrote and read back. No I/O. | |
| Result< uint32_t > | GetPwmFrequencyHz () const noexcept |
| The PWM frequency of the programmed prescaler, rounded to the nearest hertz. No I/O. | |
| Result< uint8_t > | ReadPrescale () noexcept |
| Read PRE_SCALE into the driver's copy: the reset check, then a 1-byte read. | |
| Result< void > | Sleep (SleepMode mode=SleepMode::OutputsOff) noexcept |
| Stop the oscillator (MODE1.SLEEP = 1): the low-power mode (section 7.3.1). | |
| Result< void > | Wake () noexcept |
| Start the oscillator and the channels again (section 7.3.1.1). | |
| bool | MayBeAsleep () const noexcept |
Diagnostics: raw access and the last values read | |
| Result< uint8_t > | ReadRegister (uint8_t address) noexcept |
| Read one register once: one transfer, no retry, no check (handbook KB-CPP-129). | |
| uint8_t | GetLastMode1 () const noexcept |
| uint8_t | GetLastMode2 () const noexcept |
Driver for one PCA9685 on a platform port.
Lifecycle: construct with the configuration (no I/O), EnsureInitialized() (every channel off, the configuration written and read back, the oscillator started), use, optionally Deinitialize() (every channel off, asleep). Every call that touches the chip returns Error::NotInitialized until EnsureInitialized() has succeeded once; no call starts the chip implicitly. DisableOutputs() (a pin write) and Deinitialize() work in every state, and once started the switch-offs keep working while uninitialised (after a reset was found).
Channels are numbered 0 to 15 (LED0 to LED15). The driver keeps a copy of every channel it wrote (GetChannel()). A switch-on writes all four registers of the channel in one transfer, and the driver keeps MODE2.OCH = 0, so the four reach the output together at the STOP (section 7.3.2, note 2). Nothing is read back unless the call's last argument is Verify::ReadBack.
Switch-offs are one data byte and never refused. A switch-off is 0x10 to LEDn_OFF_H, or to ALL_LED_OFF_H for every channel (figure 24): one byte is stored or not, and full OFF takes precedence (table 7), so even a failed switch-off never makes a channel more active (a 4-byte burst NACKed part-way could: new ON bytes with the old OFF bytes, applied at the STOP). A channel call whose value is off (full_off), a mask or bank call's off entries (sent first, before any burst), SetAllOff() and DisableOutputs() always send their write, whatever the driver doubts; a call that refuses its switch-ons still sends its switch-offs. Ok from a switch-off means the output is off: while the chip may be asleep holding its outputs (after Sleep(SleepMode::HoldOutputs)), the write is sent and the call returns Asleep; DisableOutputs() then switches off at once.
Resets. A power-on reset (supply below V_POR) or a software reset (general call, 06h) loads every register with its reset value: MODE1 = 0x11 (asleep, AI clear), every channel full OFF (sections 7.5, 7.6). The driver always sets MODE1.AI and never clears it, and writes MODE2, EXTCLK and SUBADR1 (detail::kSubAdr1Sentinel, inert while SUB1 = 0) only at start-up; every reset check reads MODE1, MODE2 and SUBADR1 in one 3-byte burst, and AI = 0 or any of the others different from the copy is reset evidence. SUBADR1 is the sentinel no MODE1 write of the driver can mask. The evidence is confirmed by a second read before the driver acts (rule 12d); acting drives OE high, writes ALL_LED_OFF_H, marks the driver uninitialised and returns DeviceReset. The driver reads them before it writes MODE1 from its copy (Sleep(), Wake(), SetPwmFrequency()), in CheckForReset(), EnsureInitialized() once started and EnableOutputs(), and with every Verify::ReadBack. A reset the driver has not seen yet leaves the chip asleep, and asleep no output can switch on (table 5, note 4); the driver wakes the chip only with a MODE1 write that it follows with a read of MODE1, MODE2, SUBADR1 and PRE_SCALE, so a reset can never leave the chip running on a configuration other than the driver's.
Failed writes. A switch-on or burst whose transfer failed with Bus may have reached the chip, in whole or in part (the bytes before a NACK are stored). The channels it covered become unknown (GetUncertainChannels(), GetChannel() returns StateUnknown) until a successful write or a read; EnableOutputs() refuses while any is unknown. A failed PRE_SCALE write makes the prescaler unknown, and SetPulseWidthUs() refuses until ReadPrescale() or a successful SetPwmFrequency(). A failed MODE1 write that may have woken the chip leaves the wake check pending: the next call runs it first, and a switch-on is refused until it passes. NoDevice, an address NACK, proves nothing arrived: nothing becomes unknown.
Optional port hooks, found at compile time:
| Hook | Used for | Without it |
|---|---|---|
bool GpioSet(CtrlPin, GpioSignal) noexcept | OE: disabled first and enabled last by EnsureInitialized(); DisableOutputs(), EnableOutputs() | OE is wired low; the two calls return Unsupported |
bool GetLastFailure(I2cFailure& failure) noexcept | Telling an address NACK (NoDevice) from other bus failures | Every failed transfer is Bus |
void Log(LogLevel, const char* message) noexcept | One line per lifecycle event or failure | Nothing is logged |
void DelayUs(uint32_t us) noexcept is required: the oscillator start-up wait. A hook declared with the wrong signature (for example void GpioSet(...)) is a compile error.
| Port | Your class derived from I2cInterface<Port>. |
|
inlineexplicitnoexcept |
Bind the driver to a port, a 7-bit I2C address and a configuration. No I/O, no checks: EnsureInitialized() validates both.
| port | The port; it must outlive the driver. |
| address | 7-bit I2C address, kMinI2cAddress to kMaxI2cAddress (0x40 plus A5..A0) except kAllCallAddress. |
| config | What EnsureInitialized() writes. |
|
noexcept |
Replace the configuration. When initialised, run the whole start-up of EnsureInitialized() again with it, which switches every channel off first; otherwise only store it (no I/O).
| config | Checked with Validate() before any I/O. |
Ok, InvalidArgument (nothing stored or sent), or the errors of EnsureInitialized() (the driver is then uninitialised).
|
noexcept |
Find out whether the chip reset since the start: one 3-byte read of MODE1, MODE2 and SUBADR1 (about 90 us at 400 kHz), a second one only to confirm reset evidence; also the pending wake check, when there is one (one more read).
Call it where a supply dip is possible, for example once per control period: a reset the driver has not seen leaves the chip asleep with every channel off, and channel calls keep returning Ok because a write cannot tell (the chip acknowledges it).
Ok, NotInitialized, NoDevice, Bus, InvalidReply (a read-only bit reads 1, or an inconsistent frame) or DeviceReset (confirmed by two reads; OE high, every channel off, the driver uninitialised: call EnsureInitialized()).
|
noexcept |
Switch every channel off and put the chip to sleep, its low-power safe state, and mark the driver uninitialised.
Always does its work, whatever the driver believes (never started, started, or a reset found). An address that EnsureInitialized() refuses is InvalidArgument with no I/O (0x70 is LED All Call at power-up). Otherwise it drives OE high first (with GpioSet(); it needs no bus), brings the bus up and sends ALL_LED_OFF_H = 0x10, then, only when the switch-off was sent (asleep, an output still on would be held on), a wake first when an output may be held and MODE1.SLEEP. Ok only when all of it was sent. The driver is uninitialised afterwards either way.
Ok, InvalidArgument, NoDevice or Bus.
|
noexcept |
Drive OE high: every output goes to the MODE2.OUTNE level, which the driver makes the level of a channel that is off, within 60 ns (table 15, t_PHZ). The fast switch-off: no I2C, and it works in every state, uninitialised, asleep or with a broken bus. Before the first EnsureInitialized() and after a chip reset, OUTNE is the reset value: low.
Ok, Unsupported (the port has no GpioSet()) or Bus (the pin write failed).
|
noexcept |
Drive OE low: the outputs follow their channels again. A switch-on of every channel at once, so it is refused while any channel is unknown or the wake check fails.
Ok, NotInitialized, Unsupported, StateUnknown (a channel is unknown: nothing sent), Bus or DeviceReset.
|
noexcept |
Start the chip on the first call. Once it has succeeded, a later call runs the reset check (one 3-byte read) and returns Ok, or starts again from step 1 when the chip reset.
Checks the configuration and the address (no I/O when either is bad), brings the bus up, then:
GpioSet()), ALL_LED_OFF_H = 0x10 (one byte: it works whatever MODE1.AI holds, section 7.3.1.1), MODE2 with OCH = 0 and the configured drive, inversion and OUTNE, and ALL_LED_OFF_H again, now sure to reach the outputs at the STOP (an earlier run may have left OCH = 1). Each of the four is sent even when one before it failed.DeviceIdMismatch when they cannot come from a PCA9685; ExternalClockLatched when EXTCLK is set and the internal clock is asked for), writes SLEEP and AI (the oscillator stops, so PRE_SCALE can be written), sets EXTCLK by the two-write sequence of table 5 when asked, writes PRE_SCALE and the SUBADR1 sentinel.kOscillatorStartUs (internal clock only, table 5 note 2), reads MODE1, MODE2, SUBADR1 and PRE_SCALE once more, and enables OE.0.5 ms of waiting and thirteen transfers. After a failure the driver stays uninitialised and the next call starts again at step 1.
Ok, InvalidArgument (the configuration or the address; no I/O), NoDevice, Bus, ExternalClockLatched, DeviceIdMismatch, DeviceReset (the chip reset during the start-up) or WriteMismatch (the chip did not wake).
|
inlinenoexcept |
|
noexcept |
The value the driver last wrote to or read from a channel. No I/O.
| channel | 0 to 15. |
NotInitialized, InvalidArgument, or StateUnknown (its last write failed: call ReadChannel()).
|
inlinenoexcept |
pwm_frequency_hz follows SetPwmFrequency(). No I/O.
|
inlinenoexcept |
|
inlinenoexcept |
|
noexcept |
The prescaler the driver last wrote and read back. No I/O.
NotInitialized or StateUnknown (its last write failed).
|
noexcept |
The PWM frequency of the programmed prescaler, rounded to the nearest hertz. No I/O.
GetPrescale().
|
inlinenoexcept |
|
inlinenoexcept |
EnsureInitialized(), until Deinitialize() or a found reset. No I/O.
|
inlinenoexcept |
|
noexcept |
Read one channel from the chip into the driver's copy: one 3-byte read of MODE1, MODE2 and SUBADR1 (the reset check: a 4-byte read needs AI) and one 4-byte read. A read of all zeros, which SDA stuck low also gives, is confirmed by one more MODE1/MODE2/SUBADR1 read and is InvalidReply when that read does not match the running chip.
| channel | 0 to 15. |
NotInitialized, InvalidArgument, NoDevice, Bus, DeviceReset or InvalidReply.
|
noexcept |
Read all 16 channels into the driver's copy: the reset check, then one 64-byte read. Makes every channel known again.
ReadChannel().
|
noexcept |
Read PRE_SCALE into the driver's copy: the reset check, then a 1-byte read.
NotInitialized, NoDevice, Bus, InvalidReply or DeviceReset.
|
noexcept |
Read one register once: one transfer, no retry, no check (handbook KB-CPP-129).
For bring-up and diagnostics. No register of the PCA9685 changes when read.
| address | 0x00 to 0x45 (MODE1 to LED15_OFF_H) or 0xFE (PRE_SCALE); the write-only ALL_LED registers and the reserved TestMode register are refused. |
NotInitialized, InvalidArgument (nothing sent), NoDevice or Bus.
|
noexcept |
Switch every channel off with one data byte, ALL_LED_OFF_H = 0x10 (figure 24, the orderly shutdown of section 7.3.1.1). Never refused.
Ok, NotInitialized, NoDevice, Bus, Asleep or DeviceReset.
|
noexcept |
Switch one channel off (LEDn_OFF_H bit 4), as SetPwm(channel, PwmOff()). Never refused.
| channel | 0 to 15. |
| verify | As SetPwm(); a value that is not an enumerator reads nothing back. |
Ok, NotInitialized, InvalidArgument (the channel; nothing sent), NoDevice, Bus, Asleep (written, but an output may hold its level until Wake()), DeviceReset, InvalidReply or WriteMismatch.
|
noexcept |
Set values.size() consecutive channels from first in one transfer, so that with OCH = 0 they change together at the STOP (section 7.3.2, note 2).
When any value fails IsValid(), or the pending wake check fails, the call refuses the switch-ons but still writes every off value, one channel per transfer, and returns the refusal.
| first | The first channel, 0 to 15. |
| values | 1 to 16 - first values. |
Ok, NotInitialized, InvalidArgument (the range: nothing sent; a value: the switch-offs sent), NoDevice, Bus, Asleep or DeviceReset.
|
noexcept |
Switch off every channel in mask (bit n = channel n), one data byte per channel (LEDn_OFF_H = 0x10). Never refused: a failed write does not stop the others. A mask of 0 sends nothing.
| mask | The channels. |
Ok, NotInitialized, the first failure of the writes (NoDevice, Bus), Asleep or DeviceReset.
|
noexcept |
Set one channel to a duty cycle with a phase delay (PwmForDuty()), as SetPwm().
| channel | 0 to 15. |
| duty | 0 (off, a switch-off) to kFullDuty (full ON). |
| phase | 0 to 4095: the count at which the output is asserted. |
| verify | As SetPwm(). |
SetPwm().
|
noexcept |
|
noexcept |
Set one channel to a pulse of width_us at the start of each period, as SetPwm().
The counts come from the chip's prescaler as the driver last wrote and read it back (handbook KB-CPP-128) and Config::oscillator_hz; the internal oscillator is 25 MHz typical, so calibrate oscillator_hz for servo work (docs/hardware.md).
| channel | 0 to 15. |
| width_us | The pulse width; 0 is off (a switch-off). |
| verify | As SetPwm(). |
SetPwm(); InvalidArgument also when the width rounds to 0 or more than 4095 counts, StateUnknown when the prescaler is unknown after a failed write.
|
noexcept |
Set one channel to a value: one 4-byte write (LEDn_ON_L to LEDn_OFF_H), or for an off value the one byte LEDn_OFF_H = 0x10.
An off value (full_off) is a switch-off, whatever else the value holds, and is never refused; once the driver has started it is sent also while uninitialised. Any other value must pass IsValid(), and is refused (nothing sent) while the wake check is pending and fails.
| channel | 0 to 15. |
| value | The channel value. |
| verify | Verify::ReadBack to read MODE1, MODE2, SUBADR1 and the channel back (two more reads); an off value matches any value with full OFF. |
Ok, NotInitialized, InvalidArgument (channel, value or verify; nothing sent), NoDevice, Bus, Asleep, DeviceReset, InvalidReply or WriteMismatch.
|
noexcept |
Change the PWM frequency of all channels (PRE_SCALE, section 7.3.5).
PRE_SCALE ignores writes while MODE1.SLEEP is 0 (table 4, note 1), so: the reset check (MODE1 read), MODE1.SLEEP if the chip is awake (the outputs hold for the moment), PRE_SCALE, a read back of PRE_SCALE (unconditional: the chip acknowledges a write it ignores), then, if it was awake, the wake of Wake() with its restart. Channel counts stay as they are, so pulse widths scale with the period: write them again after it.
| frequency_hz | 1 to kMaxPwmFrequencyHz; the prescaler must be 3 to 255. |
Ok, NotInitialized, InvalidArgument (nothing sent), NoDevice, Bus, InvalidReply, DeviceReset or WriteMismatch (PRE_SCALE did not take the value).
|
noexcept |
Stop the oscillator (MODE1.SLEEP = 1): the low-power mode (section 7.3.1).
SleepMode::OutputsOff first switches every channel off (ALL_LED, never refused) and sleeps only if that write succeeded. SleepMode::HoldOutputs keeps the channels for Wake() to restart; while asleep an output may hold the level it had (the data sheet does not say), so a switch-off then returns Asleep. Both read MODE1 first (the reset check) and write MODE1 from the copy.
| mode | What happens to the outputs. |
Ok, NotInitialized, InvalidArgument (mode; nothing sent), NoDevice, Bus, InvalidReply or DeviceReset.
|
noexcept |
Start the oscillator and the channels again (section 7.3.1.1).
Reads MODE1 (the reset check), writes MODE1 with SLEEP = 0, waits kOscillatorStartUs (internal clock), reads MODE1, MODE2 and PRE_SCALE (the wake check), and when RESTART reads 1 writes it back as 1, which restarts the channels that ran before Sleep(): the data sheet's order, SLEEP clear for 500 us before RESTART.
Ok, NotInitialized, NoDevice, Bus, InvalidReply, DeviceReset or WriteMismatch (SLEEP still reads 1).