Errors, results, pins and configuration.
More...
|
| 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...
|
| |
|
|
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 |
| |
Errors, results, pins and configuration.
◆ Bank
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
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
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
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
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
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
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
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
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.
|
◆ 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
-
| a2 | true when A2 is high. |
| a1 | true when A1 is high. |
| a0 | true 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
-
- 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
-
| pin | 0 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
-
- 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 |
◆ kDefaultI2cAddress
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.