PCAL9555 Driver 0.1.0
API reference
Loading...
Searching...
No Matches
Namespaces | Classes | Concepts | Enumerations | Functions | Variables
pcal9555 Namespace Reference

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

Namespaces

namespace  reg
 The PCA9555 / PCAL9555A register map.
 

Classes

struct  Config
 Everything EnsureInitialized() and ApplyConfig() write to the chip. More...
 
class  I2cInterface
 CRTP base of the platform I2C port. More...
 
class  PCAL9555
 Driver for one PCA9555 or PCAL9555A on a platform port. 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 hooks with exactly the types above, noexcept and returning bool.
 

Enumerations

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 = 18
}
 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  Variant : uint8_t { Variant::Pca9555 = 0 , 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  Direction : uint8_t { Direction::Output = 0 , Direction::Input = 1 }
 Direction of a pin (configuration register: 1 = input). More...
 
enum class  DriveStrength : uint8_t { DriveStrength::Quarter = 0 , DriveStrength::Half = 1 , DriveStrength::ThreeQuarters = 2 , DriveStrength::Full = 3 }
 Output drive strength of a pin, PCAL9555A only (data sheet section 6.2.6). More...
 
enum class  Verify : uint8_t { Verify::None = 0 , 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  Pull : uint8_t { Pull::None = 0 , Pull::Up = 1 , Pull::Down = 2 }
 Pull resistor of a pin, PCAL9555A only (pull enable and selection registers). More...
 
enum class  OutputMode : uint8_t { OutputMode::PushPull = 0 , OutputMode::OpenDrain = 1 }
 Output stage of a whole port, PCAL9555A only (output port configuration register). More...
 
enum class  Bank : uint8_t { Bank::Port0 = 0 , Bank::Port1 = 1 }
 One of the two 8-pin ports. More...
 

Functions

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

Variables

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

What the PCA9555 and PCAL9555A need 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
 
constexpr uint32_t kMaxClockHz = 400'000U
 Highest SCL frequency: fast mode, 400 kHz (section 13, table 33, f_SCL).
 
constexpr bool kRepeatedStart = true
 

Detailed Description

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

Enumeration Type Documentation

◆ I2cFailure

enum class pcal9555::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 is at the address, and the driver returns Error::NoDevice. Every other failure, and every failure of a port without the hook, is Error::Bus.

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 did not acknowledge a data byte.

Function Documentation

◆ KconfigDefaults()

constexpr Config pcal9555::KconfigDefaults ( )
constexprnoexcept

The configuration menuconfig selected, on top of the power-up values.

Returns
Config{} with the variant, the output levels and the directions taken from Kconfig.

Variable Documentation

◆ kI2cAddress

constexpr uint8_t pcal9555::kI2cAddress = kMinI2cAddress
inlineconstexpr

Base 7-bit I2C address, 0100 A2 A1 A0 with every address pin low (section 6.1, figure 4); the pins add 0 to 7 (AddressFromPins()).

◆ kRepeatedStart

constexpr bool pcal9555::kRepeatedStart = true
inlineconstexpr

true: a register read is a combined write-read with a repeated START (section 7.2): the command byte is written, then the address is sent again with R/W = 1 after a restart.