PCAL9555 Driver 0.1.0
API reference
Loading...
Searching...
No Matches
pcal9555_types.hpp
Go to the documentation of this file.
1
12#ifndef PCAL9555_TYPES_HPP
13#define PCAL9555_TYPES_HPP
14
15#include <cstdint>
16
17#include "pcal9555_version.h"
18
20namespace pcal9555 {
21
36enum class [[nodiscard]] Error : uint8_t {
37 // Base set: the same names and values in every driver of the org (standards/driver.md).
38 Ok = 0,
39 NotInitialized = 1,
41 InvalidArgument = 2,
43 Bus = 3,
46 Timeout = 4,
51 Crc = 6,
52 Busy = 7,
53 DeviceFault = 8,
54 Unsupported = 9,
56 // Chip-specific values start at 16; each one is returned by some call (tests/test_errors.cpp).
57 WriteMismatch = 16,
61 NoDevice = 17,
65 DeviceReset = 18,
70};
71
77constexpr const char* ToString(Error error) noexcept {
78 switch (error) {
79 case Error::Ok:
80 return "Ok";
82 return "NotInitialized";
84 return "InvalidArgument";
85 case Error::Bus:
86 return "Bus";
87 case Error::Timeout:
88 return "Timeout";
90 return "DeviceIdMismatch";
91 case Error::Crc:
92 return "Crc";
93 case Error::Busy:
94 return "Busy";
96 return "DeviceFault";
98 return "Unsupported";
100 return "WriteMismatch";
101 case Error::NoDevice:
102 return "NoDevice";
104 return "DeviceReset";
105 default:
106 break; // a value made by static_cast from an integer that is not an enumerator
107 }
108 return "Unknown";
109}
110
118template <typename T>
119struct [[nodiscard]] Result {
120 T value{};
121 Error error{Error::Ok};
122
124 [[nodiscard]] constexpr bool ok() const noexcept {
125 return error == Error::Ok;
126 }
128 constexpr explicit operator bool() const noexcept {
129 return ok();
130 }
131
137 static constexpr Result Success(T v) noexcept {
138 return {v, Error::Ok};
139 }
145 static constexpr Result Failure(Error e) noexcept {
146 return {T{}, e};
147 }
148};
149
151template <>
152struct [[nodiscard]] Result<void> {
153 Error error{Error::Ok};
154
156 [[nodiscard]] constexpr bool ok() const noexcept {
157 return error == Error::Ok;
158 }
160 constexpr explicit operator bool() const noexcept {
161 return ok();
162 }
163
165 static constexpr Result Success() noexcept {
166 return {Error::Ok};
167 }
173 static constexpr Result Failure(Error e) noexcept {
174 return {e};
175 }
176};
177
179enum class LogLevel : uint8_t {
180 Error = 0,
181 Warning,
182 Info,
183 Debug,
184};
185
190enum class Variant : uint8_t {
191 Pca9555 = 0,
192 Pcal9555a = 1,
193};
194
196enum class Direction : uint8_t {
197 Output = 0,
198 Input = 1,
199};
200
202enum class DriveStrength : uint8_t {
203 Quarter = 0,
204 Half = 1,
205 ThreeQuarters = 2,
206 Full = 3,
207};
208
220enum class Verify : uint8_t {
221 None = 0,
222 ReadBack = 1,
223};
224
226enum class Pull : uint8_t {
227 None = 0,
228 Up = 1,
229 Down = 2,
230};
231
233enum class OutputMode : uint8_t {
234 PushPull = 0,
235 OpenDrain = 1,
236};
237
239enum class Bank : uint8_t {
240 Port0 = 0,
241 Port1 = 1,
242};
243
245inline constexpr uint8_t kPinCount = 16;
247inline constexpr uint16_t kAllPins = 0xFFFF;
249inline constexpr uint8_t kMinI2cAddress = 0x20;
251inline constexpr uint8_t kMaxI2cAddress = 0x27;
254inline constexpr uint8_t kDefaultI2cAddress = kMinI2cAddress;
255
261constexpr uint16_t PinMask(uint8_t pin) noexcept {
262 return (pin < kPinCount) ? static_cast<uint16_t>(uint32_t{1} << static_cast<uint32_t>(pin))
263 : uint16_t{0};
264}
265
273constexpr uint8_t AddressFromPins(bool a2, bool a1, bool a0) noexcept {
274 return static_cast<uint8_t>(static_cast<uint32_t>(kMinI2cAddress) | (a2 ? 4U : 0U) |
275 (a1 ? 2U : 0U) | (a0 ? 1U : 0U));
276}
277
283constexpr uint32_t DriveStrengthAll(DriveStrength level) noexcept {
284 // Two bits per code: a value that is not an enumerator is masked, never shifted into the next
285 // pin.
286 const uint32_t code = static_cast<uint32_t>(level) & 0x3U;
287 uint32_t codes = 0U;
288 for (uint32_t pin = 0U; pin < kPinCount; ++pin) {
289 codes |= code << (2U * pin);
290 }
291 return codes;
292}
293
302struct Config {
305
306 uint16_t output_high_mask{0xFFFF};
308 uint16_t input_mask{0xFFFF};
309
311 uint32_t drive_strength_codes{0xFFFF'FFFFU};
312 uint16_t input_latch_mask{0};
313 uint16_t pull_enable_mask{0xFFFF};
314 uint16_t pull_up_mask{0xFFFF};
315 uint16_t interrupt_mask{0xFFFF};
318
325 [[nodiscard]] friend constexpr bool operator==(const Config& lhs,
326 const Config& rhs) noexcept = default;
327};
328
337constexpr Error Validate(const Config& config) noexcept {
338 if ((static_cast<uint32_t>(config.variant) > static_cast<uint32_t>(Variant::Pcal9555a)) ||
339 (static_cast<uint32_t>(config.port0_mode) > static_cast<uint32_t>(OutputMode::OpenDrain)) ||
340 (static_cast<uint32_t>(config.port1_mode) > static_cast<uint32_t>(OutputMode::OpenDrain))) {
342 }
343 if (config.variant == Variant::Pca9555) {
344 // Every field but the four both parts have must be at its power-up value. The comparison is
345 // of the whole struct, so a field added later is covered without a change here.
346 Config agile = config;
347 const Config reset{};
348 agile.output_high_mask = reset.output_high_mask;
349 agile.polarity_invert_mask = reset.polarity_invert_mask;
350 agile.input_mask = reset.input_mask;
351 if (!(agile == reset)) {
352 return Error::Unsupported;
353 }
354 }
355 return Error::Ok;
356}
357
359constexpr const char* GetDriverVersion() noexcept {
360 return PCAL9555_VERSION_STRING;
361}
363constexpr uint32_t GetDriverVersionMajor() noexcept {
364 return PCAL9555_VERSION_MAJOR;
365}
367constexpr uint32_t GetDriverVersionMinor() noexcept {
368 return PCAL9555_VERSION_MINOR;
369}
371constexpr uint32_t GetDriverVersionPatch() noexcept {
372 return PCAL9555_VERSION_PATCH;
373}
374
377} // namespace pcal9555
378
379#endif // PCAL9555_TYPES_HPP
Error
Why a call failed. Every call of the driver returns one of these in its Result.
Definition pcal9555_types.hpp:36
constexpr uint32_t GetDriverVersionMinor() noexcept
Definition pcal9555_types.hpp:367
constexpr const char * GetDriverVersion() noexcept
Definition pcal9555_types.hpp:359
constexpr uint8_t kMaxI2cAddress
Highest 7-bit I2C address (A2, A1, A0 all high).
Definition pcal9555_types.hpp:251
constexpr uint8_t kPinCount
Number of pins.
Definition pcal9555_types.hpp:245
constexpr uint8_t kMinI2cAddress
Lowest 7-bit I2C address (A2, A1, A0 all low): 0100 A2 A1 A0 (data sheet section 6....
Definition pcal9555_types.hpp:249
Direction
Direction of a pin (configuration register: 1 = input).
Definition pcal9555_types.hpp:196
constexpr const char * ToString(Error error) noexcept
The name of an error, for logs.
Definition pcal9555_types.hpp:77
Pull
Pull resistor of a pin, PCAL9555A only (pull enable and selection registers).
Definition pcal9555_types.hpp:226
constexpr uint32_t DriveStrengthAll(DriveStrength level) noexcept
Drive strength codes with every pin at one level, in the layout of Config.
Definition pcal9555_types.hpp:283
DriveStrength
Output drive strength of a pin, PCAL9555A only (data sheet section 6.2.6).
Definition pcal9555_types.hpp:202
constexpr uint8_t kDefaultI2cAddress
Definition pcal9555_types.hpp:254
constexpr Error Validate(const Config &config) noexcept
Check a configuration without touching the chip.
Definition pcal9555_types.hpp:337
OutputMode
Output stage of a whole port, PCAL9555A only (output port configuration register).
Definition pcal9555_types.hpp:233
constexpr uint8_t AddressFromPins(bool a2, bool a1, bool a0) noexcept
The 7-bit address for the levels of the address pins.
Definition pcal9555_types.hpp:273
LogLevel
Severity passed to the optional Log() hook.
Definition pcal9555_types.hpp:179
Variant
Which part is on the bus. The driver does not detect it: the data sheets do not say how a PCA9555 ans...
Definition pcal9555_types.hpp:190
Verify
Whether a pin call reads back what it wrote, chosen per call (the last parameter of every pin and Agi...
Definition pcal9555_types.hpp:220
constexpr uint32_t GetDriverVersionPatch() noexcept
Definition pcal9555_types.hpp:371
constexpr uint32_t GetDriverVersionMajor() noexcept
Definition pcal9555_types.hpp:363
constexpr uint16_t kAllPins
Mask of every pin.
Definition pcal9555_types.hpp:247
Bank
One of the two 8-pin ports.
Definition pcal9555_types.hpp:239
constexpr uint16_t PinMask(uint8_t pin) noexcept
The mask of one pin.
Definition pcal9555_types.hpp:261
@ Crc
Not returned by this driver (I2C transfers carry no CRC).
@ DeviceFault
Not returned by this driver (the chip reports no faults).
@ Ok
The call succeeded.
@ Timeout
Not returned by this driver (the chip has no timed operation).
@ Busy
Not returned by this driver (the chip has no busy state).
@ Output
The pin drives the output port value.
@ Input
High-impedance input. Power-up value.
@ Down
100 kOhm pull-down (enable 1, selection 0).
@ Up
100 kOhm pull-up (enable 1, selection 1). Power-up value.
@ ThreeQuarters
0.75 of the maximum drive.
@ Quarter
0.25 of the maximum drive.
@ Full
The maximum drive. Power-up value.
@ Half
0.5 of the maximum drive.
@ OpenDrain
Low-side transistor only; the pull resistors of the port are disconnected.
@ PushPull
Both transistors active. Power-up value.
@ Warning
Something unexpected that the driver recovered from.
@ Info
Lifecycle events: initialised.
@ Debug
Detail for bring-up.
@ Pcal9555a
PCAL9555A: also the Agile I/O bank at 0x40 to 0x4F.
@ Pca9555
PCA9555 (or a PCAL9555A used as one): registers 0x00 to 0x07 only. Default.
@ None
Write only. Default.
@ ReadBack
Write, then read the register back; a difference is Error::WriteMismatch.
@ Port1
P1_0 to P1_7, pins 8 to 15.
@ Port0
P0_0 to P0_7, pins 0 to 7.
The PCAL9555 driver: everything it declares lives here; internals in detail.
Definition pcal9555.hpp:26
Everything EnsureInitialized() and ApplyConfig() write to the chip.
Definition pcal9555_types.hpp:302
Variant variant
Driver side: which part is fitted. The Agile I/O calls need Variant::Pcal9555a.
Definition pcal9555_types.hpp:304
uint16_t interrupt_mask
PCAL9555A: 1 = the pin raises no interrupt.
Definition pcal9555_types.hpp:315
uint16_t polarity_invert_mask
Polarity inversion: 1 = input reads inverted.
Definition pcal9555_types.hpp:307
OutputMode port1_mode
PCAL9555A: output stage of port 1 (ODEN1).
Definition pcal9555_types.hpp:317
OutputMode port0_mode
PCAL9555A: output stage of port 0 (ODEN0).
Definition pcal9555_types.hpp:316
uint16_t pull_enable_mask
PCAL9555A: 1 = pull resistor connected.
Definition pcal9555_types.hpp:313
friend constexpr bool operator==(const Config &lhs, const Config &rhs) noexcept=default
Field by field; every field is an integer or an enumeration, so equality is exact.
uint16_t input_mask
Configuration: 1 = input, 0 = output. Power-up: inputs.
Definition pcal9555_types.hpp:308
uint16_t input_latch_mask
PCAL9555A: 1 = input change latched until read.
Definition pcal9555_types.hpp:312
uint16_t output_high_mask
Output ports: 1 = drive high. Power-up: all high.
Definition pcal9555_types.hpp:306
uint32_t drive_strength_codes
PCAL9555A: drive strength codes (DriveStrength), two bits per pin, pin n at bits 2n+1....
Definition pcal9555_types.hpp:311
uint16_t pull_up_mask
PCAL9555A: 1 = pull-up, 0 = pull-down.
Definition pcal9555_types.hpp:314
static constexpr Result Success() noexcept
Definition pcal9555_types.hpp:165
static constexpr Result Failure(Error e) noexcept
A failed result.
Definition pcal9555_types.hpp:173
constexpr bool ok() const noexcept
Definition pcal9555_types.hpp:156
The value of a call, or why there is none.
Definition pcal9555_types.hpp:119
constexpr bool ok() const noexcept
Definition pcal9555_types.hpp:124
static constexpr Result Failure(Error e) noexcept
A failed result.
Definition pcal9555_types.hpp:145
static constexpr Result Success(T v) noexcept
A successful result.
Definition pcal9555_types.hpp:137