PCA9685 Driver 0.1.0
API reference
Loading...
Searching...
No Matches
pca9685_i2c_interface.hpp
Go to the documentation of this file.
1// clang-format off: the hook table below must keep one row per line.
30// clang-format on
31#ifndef PCA9685_I2C_INTERFACE_HPP
32#define PCA9685_I2C_INTERFACE_HPP
33
34#include <array>
35#include <concepts>
36#include <cstddef>
37#include <cstdint>
38#include <span>
39
40#include "pca9685_detail.hpp"
41#include "pca9685_types.hpp"
42
43namespace pca9685 {
44
52inline constexpr uint8_t kI2cAddress = kMinI2cAddress;
54inline constexpr uint32_t kMaxClockHz = 1'000'000U;
57inline constexpr bool kRepeatedStart = true;
61enum class CtrlPin : uint8_t {
62 OutputEnable = 0,
65};
66
68enum class GpioSignal : uint8_t {
69 INACTIVE = 0,
70 ACTIVE = 1,
71};
72
82enum class I2cFailure : uint8_t {
83 Other = 0,
84 AddressNack = 1,
85 DataNack = 2,
86};
87
98template <typename Derived>
100public:
102 I2cInterface(const I2cInterface&) = delete;
105
106protected:
108 I2cInterface() noexcept = default;
110 ~I2cInterface() noexcept = default;
111};
112
124template <typename Port>
125concept I2cPort = std::derived_from<Port, I2cInterface<Port>> && requires {
126 detail::ExactHook<Port, bool() noexcept>::Take(&Port::EnsureInitialized);
127 detail::ExactHook<Port, bool(uint8_t, const uint8_t*, std::size_t) noexcept>::Take(&Port::Write);
128 detail::ExactHook<Port, bool(uint8_t, const uint8_t*, std::size_t, uint8_t*,
129 std::size_t) noexcept>::Take(&Port::WriteRead);
130};
131
132namespace detail {
133
134// Optional hooks, all in this one place (KB-CPP-036): a `Declares*` concept only tests the name,
135// the `Has*` concept the exact signature, `noexcept` and the result type. The driver rejects a hook
136// that is declared but does not match (KB-CPP20-007).
137
139template <typename Port>
140concept DeclaresDelayUs =
141 requires { &Port::DelayUs; } || requires(Port& port) { port.DelayUs(1_u32); };
142
144template <typename Port>
145concept HasDelayUs = requires { ExactHook<Port, void(uint32_t) noexcept>::Take(&Port::DelayUs); };
146
148template <typename Port>
149concept DeclaresGpioSet = requires { &Port::GpioSet; } || requires(Port& port) {
150 port.GpioSet(CtrlPin::OutputEnable, GpioSignal::INACTIVE);
151};
152
154template <typename Port>
155concept HasGpioSet =
156 requires { ExactHook<Port, bool(CtrlPin, GpioSignal) noexcept>::Take(&Port::GpioSet); };
157
159template <typename Port>
160concept DeclaresGetLastFailure = requires {
161 &Port::GetLastFailure;
162} || requires(Port& port, I2cFailure& failure) { port.GetLastFailure(failure); };
163
166template <typename Port>
167concept HasGetLastFailure =
168 requires { ExactHook<Port, bool(I2cFailure&) noexcept>::Take(&Port::GetLastFailure); };
169
171template <typename Port>
172concept DeclaresLog =
173 requires { &Port::Log; } || requires(Port& port) { port.Log(LogLevel::Info, ""); };
174
176template <typename Port>
177concept HasLog =
178 requires { ExactHook<Port, void(LogLevel, const char*) noexcept>::Take(&Port::Log); };
179
182template <typename Port>
183void DelayUs(Port& port, uint32_t us) noexcept {
184 if constexpr (HasDelayUs<Port>) {
185 port.DelayUs(us);
186 } else {
187 static_assert(kAlwaysFalse<Port>,
188 "pca9685: the port must implement `void DelayUs(uint32_t us) noexcept`");
189 }
190}
191
193template <typename Port>
194void Log(Port& port, [[maybe_unused]] LogLevel level,
195 [[maybe_unused]] const char* message) noexcept {
196 if constexpr (HasLog<Port>) {
197 port.Log(level, message);
198 } else {
199 (void)port;
200 }
201}
202
205template <typename Port>
206[[nodiscard]] Error TransferError(Port& port) noexcept {
207 if constexpr (HasGetLastFailure<Port>) {
208 I2cFailure failure = I2cFailure::Other;
209 if (port.GetLastFailure(failure) && (failure == I2cFailure::AddressNack)) {
210 return Error::NoDevice;
211 }
212 } else {
213 (void)port;
214 }
215 return Error::Bus;
216}
217
219inline constexpr std::size_t kMaxBurst =
220 static_cast<std::size_t>(reg::kChannels) * reg::kBytesPerChannel;
221
223template <std::size_t N>
224concept BurstSize = (N >= 1U) && (N <= kMaxBurst);
225
230template <I2cPort Port>
231class RegisterBus {
232public:
233 RegisterBus(Port& port, uint8_t address) noexcept : port_(port), address_(address) {}
234
235 Port& GetPort() & noexcept {
236 return port_;
237 }
238
239 [[nodiscard]] uint8_t GetAddress() const noexcept {
240 return address_;
241 }
242
244 template <std::size_t N>
245 requires BurstSize<N>
246 Error Read(uint8_t reg, std::span<uint8_t, N> out) noexcept {
247 return Read(reg, std::span<uint8_t>{out});
248 }
249
252 Error Read(uint8_t reg, std::span<uint8_t> out) noexcept {
253 if (out.empty() || (out.size() > kMaxBurst)) {
254 return Error::InvalidArgument;
255 }
256 const std::array<uint8_t, 1> pointer{reg};
257 return port_.WriteRead(address_, pointer.data(), pointer.size(), out.data(), out.size())
258 ? Error::Ok
259 : TransferError(port_);
260 }
261
263 template <std::size_t N>
264 requires BurstSize<N>
265 Error Write(uint8_t reg, std::span<const uint8_t, N> data) noexcept {
266 return Write(reg, std::span<const uint8_t>{data});
267 }
268
271 Error Write(uint8_t reg, std::span<const uint8_t> data) noexcept {
272 if (data.empty() || (data.size() > kMaxBurst)) {
273 return Error::InvalidArgument;
274 }
275 std::array<uint8_t, 1U + kMaxBurst> frame{};
276 frame[0] = reg;
277 const std::size_t count = data.size();
278 for (std::size_t i = 0U; i < count; ++i) {
279 frame[1U + i] = data[i];
280 }
281 return port_.Write(address_, frame.data(), count + 1U) ? Error::Ok : TransferError(port_);
282 }
283
284private:
285 Port& port_;
286 uint8_t address_;
287};
288
289} // namespace detail
290
291} // namespace pca9685
292
293#endif // PCA9685_I2C_INTERFACE_HPP
CRTP base of the platform I2C port.
Definition pca9685_i2c_interface.hpp:99
I2cInterface(const I2cInterface &)=delete
Ports are not copied: the driver holds a reference.
I2cInterface() noexcept=default
Only the derived port is constructed.
I2cInterface & operator=(const I2cInterface &)=delete
Ports are not copied: the driver holds a reference.
Satisfied by a class that derives from I2cInterface<Port> and implements the required bus hooks with ...
Definition pca9685_i2c_interface.hpp:125
constexpr uint8_t kMinI2cAddress
Lowest I2C address of a PCA9685: 1 A5 A4 A3 A2 A1 A0 with every pin low (figure 4).
Definition pca9685_types.hpp:273
Error
Why a call failed. Every call of the driver returns one of these in its Result.
Definition pca9685_types.hpp:39
The PCA9685 driver: everything it declares lives here; internals in detail.
Definition pca9685.hpp:30
I2cFailure
Why a Write() or WriteRead() hook returned false, as the optional GetLastFailure() hook reports it.
Definition pca9685_i2c_interface.hpp:82
@ DataNack
The device acknowledged its address, then not a data byte.
@ AddressNack
No device acknowledged the address byte.
@ Other
Arbitration lost, a stuck line, a timeout, or a NACK the port cannot place.
constexpr bool kRepeatedStart
Definition pca9685_i2c_interface.hpp:57
constexpr uint8_t kI2cAddress
7-bit I2C address with A5 to A0 low, 1000000 (section 7.1.1, figure 4); the pins add 0 to 63.
Definition pca9685_i2c_interface.hpp:52
GpioSignal
Logical level of a control pin; the port maps it to the physical polarity.
Definition pca9685_i2c_interface.hpp:68
@ ACTIVE
The pin function is asserted: for OE, outputs enabled (pin low).
@ INACTIVE
The pin function is deasserted: for OE, outputs disabled (pin high).
CtrlPin
Control pins the port may drive through the optional GpioSet() hook.
Definition pca9685_i2c_interface.hpp:61
constexpr uint32_t kMaxClockHz
Highest SCL frequency: Fast-mode Plus, 1 MHz (table 15, f_SCL).
Definition pca9685_i2c_interface.hpp:54
Compile-time helpers of the PCA9685 driver: typed integer literals, exact hook matching,...
Public types of the PCA9685 driver: errors, Result<T>, channel values, configuration,...