PCA9685 Driver 0.1.0
API reference
Loading...
Searching...
No Matches
Public Member Functions | List of all members
pca9685::PCA9685< Port > Class Template 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
 

Detailed Description

template<I2cPort Port>
class pca9685::PCA9685< Port >

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.

Template Parameters
PortYour class derived from I2cInterface<Port>.

Constructor & Destructor Documentation

◆ PCA9685()

template<I2cPort Port>
pca9685::PCA9685< Port >::PCA9685 ( Port &  port,
uint8_t  address = kI2cAddress,
const Config &  config = {} 
)
inlineexplicitnoexcept

Bind the driver to a port, a 7-bit I2C address and a configuration. No I/O, no checks: EnsureInitialized() validates both.

Parameters
portThe port; it must outlive the driver.
address7-bit I2C address, kMinI2cAddress to kMaxI2cAddress (0x40 plus A5..A0) except kAllCallAddress.
configWhat EnsureInitialized() writes.

Member Function Documentation

◆ ApplyConfig()

template<I2cPort Port>
Result< void > pca9685::PCA9685< Port >::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).

Parameters
configChecked with Validate() before any I/O.
Returns
Ok, InvalidArgument (nothing stored or sent), or the errors of EnsureInitialized() (the driver is then uninitialised).

◆ CheckForReset()

template<I2cPort Port>
Result< void > pca9685::PCA9685< Port >::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).

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).

Returns
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()).

◆ Deinitialize()

template<I2cPort Port>
Result< void > pca9685::PCA9685< Port >::Deinitialize ( )
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.

Returns
Ok, InvalidArgument, NoDevice or Bus.

◆ DisableOutputs()

template<I2cPort Port>
Result< void > pca9685::PCA9685< Port >::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.

Returns
Ok, Unsupported (the port has no GpioSet()) or Bus (the pin write failed).

◆ EnableOutputs()

template<I2cPort Port>
Result< void > pca9685::PCA9685< Port >::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.

Returns
Ok, NotInitialized, Unsupported, StateUnknown (a channel is unknown: nothing sent), Bus or DeviceReset.

◆ EnsureInitialized()

template<I2cPort Port>
Result< void > pca9685::PCA9685< Port >::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.

Checks the configuration and the address (no I/O when either is bad), brings the bus up, then:

  1. Switches everything off, whatever state an earlier run left: OE high (with 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.
  2. Reads MODE1 and the byte after it (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.
  3. Identity, a check no floating or stuck line can pass (the chip has no ID register): MODE1, MODE2, SUBADR1 and PRE_SCALE must read back exactly what was written, and every channel full OFF.
  4. Wakes the oscillator (MODE1.SLEEP = 0), waits 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.

Returns
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).

◆ GetAddress()

template<I2cPort Port>
uint8_t pca9685::PCA9685< Port >::GetAddress ( ) const
inlinenoexcept
Returns
The 7-bit I2C address passed to the constructor. No I/O.

◆ GetChannel()

template<I2cPort Port>
Result< Pwm > pca9685::PCA9685< Port >::GetChannel ( uint8_t  channel) const
noexcept

The value the driver last wrote to or read from a channel. No I/O.

Parameters
channel0 to 15.
Returns
The value, or NotInitialized, InvalidArgument, or StateUnknown (its last write failed: call ReadChannel()).

◆ GetConfig()

template<I2cPort Port>
const Config & pca9685::PCA9685< Port >::GetConfig ( ) const &
inlinenoexcept
Returns
The configuration stored or last applied; pwm_frequency_hz follows SetPwmFrequency(). No I/O.

◆ GetLastMode1()

template<I2cPort Port>
uint8_t pca9685::PCA9685< Port >::GetLastMode1 ( ) const
inlinenoexcept
Returns
MODE1 as the driver last read it, by any call; 0 before the first. No I/O (handbook KB-CPP-129).

◆ GetLastMode2()

template<I2cPort Port>
uint8_t pca9685::PCA9685< Port >::GetLastMode2 ( ) const
inlinenoexcept
Returns
MODE2 as the driver last read it, by any call; 0 before the first. No I/O.

◆ GetPrescale()

template<I2cPort Port>
Result< uint8_t > pca9685::PCA9685< Port >::GetPrescale ( ) const
noexcept

The prescaler the driver last wrote and read back. No I/O.

Returns
PRE_SCALE, or NotInitialized or StateUnknown (its last write failed).

◆ GetPwmFrequencyHz()

template<I2cPort Port>
Result< uint32_t > pca9685::PCA9685< Port >::GetPwmFrequencyHz ( ) const
noexcept

The PWM frequency of the programmed prescaler, rounded to the nearest hertz. No I/O.

Returns
oscillator / (4096 x (PRE_SCALE + 1)), or the errors of GetPrescale().

◆ GetUncertainChannels()

template<I2cPort Port>
uint16_t pca9685::PCA9685< Port >::GetUncertainChannels ( ) const
inlinenoexcept
Returns
The channels whose last write failed, bit n = channel n; 0 when all are known. No I/O.

◆ IsInitialized()

template<I2cPort Port>
bool pca9685::PCA9685< Port >::IsInitialized ( ) const
inlinenoexcept
Returns
true after a successful EnsureInitialized(), until Deinitialize() or a found reset. No I/O.

◆ MayBeAsleep()

template<I2cPort Port>
bool pca9685::PCA9685< Port >::MayBeAsleep ( ) const
inlinenoexcept
Returns
true when the chip is, or may be, asleep: after Sleep(), or a failed Wake(). No I/O.

◆ ReadChannel()

template<I2cPort Port>
Result< Pwm > pca9685::PCA9685< Port >::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.

Parameters
channel0 to 15.
Returns
The value, or NotInitialized, InvalidArgument, NoDevice, Bus, DeviceReset or InvalidReply.

◆ ReadChannels()

template<I2cPort Port>
Result< std::array< Pwm, kChannelCount > > pca9685::PCA9685< Port >::ReadChannels ( )
noexcept

Read all 16 channels into the driver's copy: the reset check, then one 64-byte read. Makes every channel known again.

Returns
The values, or the errors of ReadChannel().

◆ ReadPrescale()

template<I2cPort Port>
Result< uint8_t > pca9685::PCA9685< Port >::ReadPrescale ( )
noexcept

Read PRE_SCALE into the driver's copy: the reset check, then a 1-byte read.

Returns
PRE_SCALE, or NotInitialized, NoDevice, Bus, InvalidReply or DeviceReset.

◆ ReadRegister()

template<I2cPort Port>
Result< uint8_t > pca9685::PCA9685< Port >::ReadRegister ( uint8_t  address)
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.

Parameters
address0x00 to 0x45 (MODE1 to LED15_OFF_H) or 0xFE (PRE_SCALE); the write-only ALL_LED registers and the reserved TestMode register are refused.
Returns
The register value, or NotInitialized, InvalidArgument (nothing sent), NoDevice or Bus.

◆ SetAllOff()

template<I2cPort Port>
Result< void > pca9685::PCA9685< Port >::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.

Returns
Ok, NotInitialized, NoDevice, Bus, Asleep or DeviceReset.

◆ SetChannelOff()

template<I2cPort Port>
Result< void > pca9685::PCA9685< Port >::SetChannelOff ( uint8_t  channel,
Verify  verify = Verify::None 
)
noexcept

Switch one channel off (LEDn_OFF_H bit 4), as SetPwm(channel, PwmOff()). Never refused.

Parameters
channel0 to 15.
verifyAs SetPwm(); a value that is not an enumerator reads nothing back.
Returns
Ok, NotInitialized, InvalidArgument (the channel; nothing sent), NoDevice, Bus, Asleep (written, but an output may hold its level until Wake()), DeviceReset, InvalidReply or WriteMismatch.

◆ SetChannels()

template<I2cPort Port>
Result< void > pca9685::PCA9685< Port >::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).

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.

Parameters
firstThe first channel, 0 to 15.
values1 to 16 - first values.
Returns
Ok, NotInitialized, InvalidArgument (the range: nothing sent; a value: the switch-offs sent), NoDevice, Bus, Asleep or DeviceReset.

◆ SetChannelsOff()

template<I2cPort Port>
Result< void > pca9685::PCA9685< Port >::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.

Parameters
maskThe channels.
Returns
Ok, NotInitialized, the first failure of the writes (NoDevice, Bus), Asleep or DeviceReset.

◆ SetDuty()

template<I2cPort Port>
Result< void > pca9685::PCA9685< Port >::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().

Parameters
channel0 to 15.
duty0 (off, a switch-off) to kFullDuty (full ON).
phase0 to 4095: the count at which the output is asserted.
verifyAs SetPwm().
Returns
As SetPwm().

◆ SetFullOn()

template<I2cPort Port>
Result< void > pca9685::PCA9685< Port >::SetFullOn ( uint8_t  channel,
Verify  verify = Verify::None 
)
noexcept

Switch one channel fully on (LEDn_ON_H bit 4), as SetPwm(channel, PwmFullOn()).

Parameters
channel0 to 15.
verifyAs SetPwm().
Returns
As SetPwm().

◆ SetPulseWidthUs()

template<I2cPort Port>
Result< uint32_t > pca9685::PCA9685< Port >::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().

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).

Parameters
channel0 to 15.
width_usThe pulse width; 0 is off (a switch-off).
verifyAs SetPwm().
Returns
The programmed width in nanoseconds (quantised to one count), or the errors of SetPwm(); InvalidArgument also when the width rounds to 0 or more than 4095 counts, StateUnknown when the prescaler is unknown after a failed write.

◆ SetPwm()

template<I2cPort Port>
Result< void > pca9685::PCA9685< Port >::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.

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.

Parameters
channel0 to 15.
valueThe channel value.
verifyVerify::ReadBack to read MODE1, MODE2, SUBADR1 and the channel back (two more reads); an off value matches any value with full OFF.
Returns
Ok, NotInitialized, InvalidArgument (channel, value or verify; nothing sent), NoDevice, Bus, Asleep, DeviceReset, InvalidReply or WriteMismatch.

◆ SetPwmFrequency()

template<I2cPort Port>
Result< void > pca9685::PCA9685< Port >::SetPwmFrequency ( uint32_t  frequency_hz)
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.

Parameters
frequency_hz1 to kMaxPwmFrequencyHz; the prescaler must be 3 to 255.
Returns
Ok, NotInitialized, InvalidArgument (nothing sent), NoDevice, Bus, InvalidReply, DeviceReset or WriteMismatch (PRE_SCALE did not take the value).

◆ Sleep()

template<I2cPort Port>
Result< void > pca9685::PCA9685< Port >::Sleep ( SleepMode  mode = SleepMode::OutputsOff)
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.

Parameters
modeWhat happens to the outputs.
Returns
Ok, NotInitialized, InvalidArgument (mode; nothing sent), NoDevice, Bus, InvalidReply or DeviceReset.

◆ Wake()

template<I2cPort Port>
Result< void > pca9685::PCA9685< Port >::Wake ( )
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.

Returns
Ok, NotInitialized, NoDevice, Bus, InvalidReply, DeviceReset or WriteMismatch (SLEEP still reads 1).

The documentation for this class was generated from the following file: