PCAL9555 Driver 0.1.0
API reference
Loading...
Searching...
No Matches
Classes | Enumerations | Functions | Variables
Driver types

Errors, results, pins and configuration. More...

Classes

struct  pcal9555::Result< T >
 The value of a call, or why there is none. More...
 
struct  pcal9555::Result< void >
 The result of a call that returns no value. More...
 
struct  pcal9555::Config
 Everything EnsureInitialized() and ApplyConfig() write to the chip. More...
 

Enumerations

enum class  pcal9555::Error : uint8_t {
  pcal9555::Error::Ok = 0 , pcal9555::Error::NotInitialized = 1 , pcal9555::Error::InvalidArgument = 2 , pcal9555::Error::Bus = 3 ,
  pcal9555::Error::Timeout = 4 , pcal9555::Error::DeviceIdMismatch = 5 , pcal9555::Error::Crc = 6 , pcal9555::Error::Busy = 7 ,
  pcal9555::Error::DeviceFault = 8 , pcal9555::Error::Unsupported = 9 , pcal9555::Error::WriteMismatch = 16 , pcal9555::Error::NoDevice = 17 ,
  pcal9555::Error::DeviceReset = 18
}
 Why a call failed. Every call of the driver returns one of these in its Result. More...
 
enum class  pcal9555::LogLevel : uint8_t { pcal9555::LogLevel::Error = 0 , pcal9555::LogLevel::Warning , pcal9555::LogLevel::Info , pcal9555::LogLevel::Debug }
 Severity passed to the optional Log() hook. More...
 
enum class  pcal9555::Variant : uint8_t { pcal9555::Variant::Pca9555 = 0 , pcal9555::Variant::Pcal9555a = 1 }
 Which part is on the bus. The driver does not detect it: the data sheets do not say how a PCA9555 answers a command byte it does not implement, so probing the Agile I/O bank is not safe. More...
 
enum class  pcal9555::Direction : uint8_t { pcal9555::Direction::Output = 0 , pcal9555::Direction::Input = 1 }
 Direction of a pin (configuration register: 1 = input). More...
 
enum class  pcal9555::DriveStrength : uint8_t { pcal9555::DriveStrength::Quarter = 0 , pcal9555::DriveStrength::Half = 1 , pcal9555::DriveStrength::ThreeQuarters = 2 , pcal9555::DriveStrength::Full = 3 }
 Output drive strength of a pin, PCAL9555A only (data sheet section 6.2.6). More...
 
enum class  pcal9555::Verify : uint8_t { pcal9555::Verify::None = 0 , pcal9555::Verify::ReadBack = 1 }
 Whether a pin call reads back what it wrote, chosen per call (the last parameter of every pin and Agile I/O setter). More...
 
enum class  pcal9555::Pull : uint8_t { pcal9555::Pull::None = 0 , pcal9555::Pull::Up = 1 , pcal9555::Pull::Down = 2 }
 Pull resistor of a pin, PCAL9555A only (pull enable and selection registers). More...
 
enum class  pcal9555::OutputMode : uint8_t { pcal9555::OutputMode::PushPull = 0 , pcal9555::OutputMode::OpenDrain = 1 }
 Output stage of a whole port, PCAL9555A only (output port configuration register). More...
 
enum class  pcal9555::Bank : uint8_t { pcal9555::Bank::Port0 = 0 , pcal9555::Bank::Port1 = 1 }
 One of the two 8-pin ports. More...
 

Functions

constexpr const char * pcal9555::ToString (Error error) noexcept
 The name of an error, for logs.
 
constexpr uint16_t pcal9555::PinMask (uint8_t pin) noexcept
 The mask of one pin.
 
constexpr uint8_t pcal9555::AddressFromPins (bool a2, bool a1, bool a0) noexcept
 The 7-bit address for the levels of the address pins.
 
constexpr uint32_t pcal9555::DriveStrengthAll (DriveStrength level) noexcept
 Drive strength codes with every pin at one level, in the layout of Config.
 
constexpr Error pcal9555::Validate (const Config &config) noexcept
 Check a configuration without touching the chip.
 
constexpr const char * pcal9555::GetDriverVersion () noexcept
 
constexpr uint32_t pcal9555::GetDriverVersionMajor () noexcept
 
constexpr uint32_t pcal9555::GetDriverVersionMinor () noexcept
 
constexpr uint32_t pcal9555::GetDriverVersionPatch () noexcept
 

Variables

constexpr uint8_t pcal9555::kPinCount = 16
 Number of pins.
 
constexpr uint16_t pcal9555::kAllPins = 0xFFFF
 Mask of every pin.
 
constexpr uint8_t pcal9555::kMinI2cAddress = 0x20
 Lowest 7-bit I2C address (A2, A1, A0 all low): 0100 A2 A1 A0 (data sheet section 6.1).
 
constexpr uint8_t pcal9555::kMaxI2cAddress = 0x27
 Highest 7-bit I2C address (A2, A1, A0 all high).
 
constexpr uint8_t pcal9555::kDefaultI2cAddress = kMinI2cAddress
 

Detailed Description

Errors, results, pins and configuration.

Enumeration Type Documentation

◆ Bank

enum class pcal9555::Bank : uint8_t
strong

One of the two 8-pin ports.

Enumerator
Port0 

P0_0 to P0_7, pins 0 to 7.

Port1 

P1_0 to P1_7, pins 8 to 15.

◆ Direction

enum class pcal9555::Direction : uint8_t
strong

Direction of a pin (configuration register: 1 = input).

Enumerator
Output 

The pin drives the output port value.

Input 

High-impedance input. Power-up value.

◆ DriveStrength

enum class pcal9555::DriveStrength : uint8_t
strong

Output drive strength of a pin, PCAL9555A only (data sheet section 6.2.6).

Enumerator
Quarter 

0.25 of the maximum drive.

Half 

0.5 of the maximum drive.

ThreeQuarters 

0.75 of the maximum drive.

Full 

The maximum drive. Power-up value.

◆ Error

enum class pcal9555::Error : uint8_t
strong

Why a call failed. Every call of the driver returns one of these in its Result.

Values 0 to 9 are the shared base set; chip-specific values start at 16. The chip has no timed operation, no CRC, no busy state and no fault flag, so Timeout, Crc, Busy and DeviceFault are never returned. The type is [[nodiscard]]: a call whose Error is dropped does not compile without a warning (handbook KB-CPP20-037).

Enumerator
Ok 

The call succeeded.

NotInitialized 

EnsureInitialized() has not succeeded yet, or Deinitialize() ran since, or a call found the chip reset (DeviceReset).

InvalidArgument 

An argument, the address or a Config field is out of range; nothing was sent.

Bus 

A port hook returned false: a bus error, a NACK of a data byte, or a NACK the port cannot place. A port without the optional GetLastFailure() hook reports an absent chip as Bus too.

Timeout 

Not returned by this driver (the chip has no timed operation).

DeviceIdMismatch 

At start-up, something answers at the address but is not the configured part: a register read back differently after EnsureInitialized() wrote it, or a reserved bit of the PCAL9555A output port configuration register read 1.

Crc 

Not returned by this driver (I2C transfers carry no CRC).

Busy 

Not returned by this driver (the chip has no busy state).

DeviceFault 

Not returned by this driver (the chip reports no faults).

Unsupported 

An Agile I/O call or Config field on a driver configured for the PCA9555 (Variant::Pca9555).

WriteMismatch 

After start-up, a register read back differently from what was just written: the chip acknowledged the write but did not keep it (a write dropped on a noisy bus). Pin calls only with Verify::ReadBack; ApplyConfig() always.

NoDevice 

Nothing acknowledged the address byte: no chip at the address, or it is unpowered. Needs a port with the optional GetLastFailure() hook, which tells an address NACK from other failures; without it this is Bus.

DeviceReset 

A running driver found the chip back at its power-up values: a supply dip below the power-on reset voltage reset every register (section 6.4, table 4). Nothing was written; the driver is uninitialised, so call EnsureInitialized(), which writes the copy again in order. A write to the checked register that the chip dropped reads the same way.

◆ LogLevel

enum class pcal9555::LogLevel : uint8_t
strong

Severity passed to the optional Log() hook.

Enumerator
Error 

A call failed.

Warning 

Something unexpected that the driver recovered from.

Info 

Lifecycle events: initialised.

Debug 

Detail for bring-up.

◆ OutputMode

enum class pcal9555::OutputMode : uint8_t
strong

Output stage of a whole port, PCAL9555A only (output port configuration register).

Enumerator
PushPull 

Both transistors active. Power-up value.

OpenDrain 

Low-side transistor only; the pull resistors of the port are disconnected.

◆ Pull

enum class pcal9555::Pull : uint8_t
strong

Pull resistor of a pin, PCAL9555A only (pull enable and selection registers).

Enumerator
None 

No resistor (enable bit 0).

Up 

100 kOhm pull-up (enable 1, selection 1). Power-up value.

Down 

100 kOhm pull-down (enable 1, selection 0).

◆ Variant

enum class pcal9555::Variant : uint8_t
strong

Which part is on the bus. The driver does not detect it: the data sheets do not say how a PCA9555 answers a command byte it does not implement, so probing the Agile I/O bank is not safe.

Enumerator
Pca9555 

PCA9555 (or a PCAL9555A used as one): registers 0x00 to 0x07 only. Default.

Pcal9555a 

PCAL9555A: also the Agile I/O bank at 0x40 to 0x4F.

◆ Verify

enum class pcal9555::Verify : uint8_t
strong

Whether a pin call reads back what it wrote, chosen per call (the last parameter of every pin and Agile I/O setter).

The data sheet needs only the write, so that is the default. ReadBack costs one more I2C read per register written (a 2-byte read after each pair, 1 byte after 0x4F), which more than doubles the call's bus time. It catches a write the chip acknowledged but did not keep (a write dropped on a noisy bus), which ReadInputs() cannot show for an output pin, and returns Error::WriteMismatch for it. EnsureInitialized() and ApplyConfig() always read the whole configuration back.

Enumerator
None 

Write only. Default.

ReadBack 

Write, then read the register back; a difference is Error::WriteMismatch.

Function Documentation

◆ AddressFromPins()

constexpr uint8_t pcal9555::AddressFromPins ( bool  a2,
bool  a1,
bool  a0 
)
constexprnoexcept

The 7-bit address for the levels of the address pins.

Parameters
a2true when A2 is high.
a1true when A1 is high.
a0true when A0 is high.
Returns
0x20 to 0x27.

◆ DriveStrengthAll()

constexpr uint32_t pcal9555::DriveStrengthAll ( DriveStrength  level)
constexprnoexcept

Drive strength codes with every pin at one level, in the layout of Config.

Parameters
levelThe level.
Returns
Two bits per pin, pin n at bits 2n+1..2n.

◆ GetDriverVersion()

constexpr const char * pcal9555::GetDriverVersion ( )
constexprnoexcept
Returns
The driver version, e.g. "0.1.0", from the generated pcal9555_version.h. No I/O.

◆ GetDriverVersionMajor()

constexpr uint32_t pcal9555::GetDriverVersionMajor ( )
constexprnoexcept
Returns
The major version. No I/O.

◆ GetDriverVersionMinor()

constexpr uint32_t pcal9555::GetDriverVersionMinor ( )
constexprnoexcept
Returns
The minor version. No I/O.

◆ GetDriverVersionPatch()

constexpr uint32_t pcal9555::GetDriverVersionPatch ( )
constexprnoexcept
Returns
The patch version. No I/O.

◆ PinMask()

constexpr uint16_t pcal9555::PinMask ( uint8_t  pin)
constexprnoexcept

The mask of one pin.

Parameters
pin0 to 15; 0 to 7 are P0_0 to P0_7, 8 to 15 are P1_0 to P1_7.
Returns
1 << pin, or 0 for a pin out of range (which every mask call rejects).

◆ ToString()

constexpr const char * pcal9555::ToString ( Error  error)
constexprnoexcept

The name of an error, for logs.

Parameters
errorThe error.
Returns
A static string such as "Bus"; "Unknown" for a value that is not an enumerator.

◆ Validate()

constexpr Error pcal9555::Validate ( const Config &  config)
constexprnoexcept

Check a configuration without touching the chip.

Parameters
configThe configuration.
Returns
Error::Ok; Error::InvalidArgument when an enum holds a value that is not an enumerator; Error::Unsupported when variant is Variant::Pca9555 and an Agile I/O field differs from its power-up value.

Variable Documentation

◆ kDefaultI2cAddress

constexpr uint8_t pcal9555::kDefaultI2cAddress = kMinI2cAddress
inlineconstexpr

Default 7-bit I2C address, with A2, A1 and A0 low: the same value as kI2cAddress, the bus requirement in pcal9555_i2c_interface.hpp. Kept so that existing code still compiles.