WS2812_RMT Driver 0.1.0
API reference
Loading...
Searching...
No Matches
ws2812_rmt.hpp
Go to the documentation of this file.
1
13#ifndef WS2812_RMT_HPP
14#define WS2812_RMT_HPP
15
16#include <algorithm>
17#include <array>
18#include <cstddef>
19#include <cstdint>
20#include <span>
21
22#include "ws2812_rmt_detail.hpp"
24#include "ws2812_rmt_gamma.hpp"
26#include "ws2812_rmt_types.hpp"
27#include "ws2812_rmt_version.h"
28
29namespace ws2812_rmt {
30
31namespace detail {
32
33// Optional hooks: a `Declares*` concept only tests the name, the `Has*` concept the exact
34// signature, `noexcept` and the result type; the driver rejects a hook that is declared but does
35// not match (handbook KB-CPP20-007).
36
38template <typename Port>
39concept DeclaresGpioSet =
40 requires(Port& port) { port.GpioSet(CtrlPin::Power, GpioSignal::ACTIVE); };
41
43template <typename Port>
44concept HasGpioSet =
45 requires { ExactHook<Port, bool(CtrlPin, GpioSignal) noexcept>::Take(&Port::GpioSet); };
46
48template <typename Port>
49concept DeclaresLog = requires(Port& port) { port.Log(LogLevel::Info, ""); };
50
52template <typename Port>
53concept HasLog =
54 requires { ExactHook<Port, void(LogLevel, const char*) noexcept>::Take(&Port::Log); };
55
57template <size_t N>
58concept NonZeroSize = (N > 0U);
59
61template <typename Port>
62void Log(Port& port, LogLevel level, const char* message) noexcept {
63 if constexpr (HasLog<Port>) {
64 port.Log(level, message);
65 } else {
66 static_cast<void>(port);
67 static_cast<void>(level);
68 static_cast<void>(message);
69 }
70}
71
72} // namespace detail
73
99template <Ws2812RmtPort Port, size_t PixelCapacity>
100 requires detail::NonZeroSize<PixelCapacity>
102 static_assert(PixelCapacity <= kMaxPixels, "ws2812_rmt: the capacity is above kMaxPixels");
103 static_assert(!detail::DeclaresGpioSet<Port> || detail::HasGpioSet<Port>,
104 "ws2812_rmt: the optional GpioSet hook must be `bool GpioSet(CtrlPin, GpioSignal) "
105 "noexcept`, so "
106 "that a failed pin write is reported");
107 static_assert(!detail::DeclaresLog<Port> || detail::HasLog<Port>,
108 "ws2812_rmt: the optional Log hook must be `void Log(LogLevel, const char* "
109 "message) noexcept`");
110
111public:
118 explicit Ws2812Rmt(Port& port, const Config& config = Config::Default()) noexcept
119 : port_(port), config_(config), order_(OrderOf(config)), brightness_(config.brightness),
120 gamma_(config.gamma) {}
121
123 Ws2812Rmt(const Ws2812Rmt&) = delete;
125 Ws2812Rmt& operator=(const Ws2812Rmt&) = delete;
126
139
141 [[nodiscard]] bool IsInitialized() const noexcept {
142 return initialized_;
143 }
144
152 Result<void> SetPixel(size_t index, const Colour& colour) noexcept;
153
159 [[nodiscard]] Result<Colour> GetPixel(size_t index) const noexcept;
160
165 void Fill(const Colour& colour) noexcept;
166
168 void Clear() noexcept;
169
174 void SetBrightness(uint8_t brightness) noexcept {
175 brightness_ = brightness;
176 }
177
179 [[nodiscard]] uint8_t Brightness() const noexcept {
180 return brightness_;
181 }
182
188 void SetGamma(Gamma gamma) noexcept {
189 gamma_ = detail::IsEnumerator(gamma) ? gamma : Gamma::None;
190 }
191
207 Result<void> Show() noexcept;
208
218 Result<void> TraceWire(std::span<const uint8_t> bytes) noexcept;
219
225 [[nodiscard]] std::span<const uint8_t> GetLastWire() const& noexcept {
226 return std::span<const uint8_t>(wire_).first(last_wire_size_);
227 }
229 void GetLastWire() const&& = delete;
230
235 Result<void> PowerOn() noexcept;
236
243 Result<void> PowerOff() noexcept;
244
246 [[nodiscard]] size_t Length() const noexcept {
247 const auto wanted = static_cast<size_t>(config_.pixel_count);
248 return ((wanted == 0U) || (wanted > PixelCapacity)) ? PixelCapacity : wanted;
249 }
250
252 [[nodiscard]] uint8_t ChannelsPerPixel() const noexcept {
253 return order_.count;
254 }
255
257 [[nodiscard]] Result<Waveform> CurrentWaveform() const noexcept;
258
263 [[nodiscard]] Result<uint32_t> FrameTimeUs() const noexcept;
264
266 [[nodiscard]] const Config& GetConfig() const& noexcept {
267 return config_;
268 }
270 void GetConfig() const&& = delete;
271
272private:
273 Result<void> initialize() noexcept;
274 [[nodiscard]] uint32_t timeoutMs(size_t bytes) const noexcept;
275 Result<void> send(std::span<const uint8_t> bytes, const char* failure) noexcept;
276 [[nodiscard]] uint32_t resetUs() const noexcept;
277
278 Port& port_;
279 Config config_;
280 ColourOrder order_;
281 uint8_t brightness_;
282 Gamma gamma_;
283 Waveform waveform_{};
284 bool initialized_{false};
288 bool powered_{!detail::HasGpioSet<Port>};
289 bool needs_reset_{false};
290 size_t last_wire_size_{0};
291 std::array<Colour, PixelCapacity> pixels_{};
292 std::array<uint8_t, PixelCapacity * 4U> wire_{};
293};
294
297} // namespace ws2812_rmt
298
299// codeql::misra_deviation_next_line(MD-CPP-009)
300#include "../src/ws2812_rmt.ipp" // IWYU pragma: export
301
302#endif // WS2812_RMT_HPP
Driver for one strip of up to PixelCapacity single-wire addressable LEDs.
Definition ws2812_rmt.hpp:101
Result< Colour > GetPixel(size_t index) const noexcept
Read back a stored colour (the logical colour, before brightness and gamma). No I/O.
void Fill(const Colour &colour) noexcept
Set every pixel of the strip to colour. No I/O.
uint8_t ChannelsPerPixel() const noexcept
Definition ws2812_rmt.hpp:252
void Clear() noexcept
Set every pixel to black. No I/O.
Ws2812Rmt & operator=(const Ws2812Rmt &)=delete
One driver object per strip.
std::span< const uint8_t > GetLastWire() const &noexcept
The bytes Show() encoded last, whether or not they were sent; empty before the first Show()....
Definition ws2812_rmt.hpp:225
Result< void > Show() noexcept
Encode the pixels (gamma, then brightness, in the wire order) and send them, blocking until the frame...
size_t Length() const noexcept
Definition ws2812_rmt.hpp:246
Result< void > SetPixel(size_t index, const Colour &colour) noexcept
Store a colour; nothing is sent until Show(). The logical colour is kept, so brightness stays reversi...
Result< void > PowerOff() noexcept
Switch the strip supply off. The waveform is kept; no re-initialisation is needed....
void GetLastWire() const &&=delete
Not on a temporary driver: the view would dangle (handbook KB-CPP20-044).
Ws2812Rmt(const Ws2812Rmt &)=delete
One driver object per strip.
bool IsInitialized() const noexcept
Definition ws2812_rmt.hpp:141
uint8_t Brightness() const noexcept
Definition ws2812_rmt.hpp:179
void SetBrightness(uint8_t brightness) noexcept
Set the linear brightness applied at Show(); 0 is off, 255 is unchanged. No I/O.
Definition ws2812_rmt.hpp:174
Result< uint32_t > FrameTimeUs() const noexcept
Worst-case time of one Show(): every bit the longer of the two codes, plus the reset.
void GetConfig() const &&=delete
Not on a temporary driver: the reference would dangle (handbook KB-CPP20-044).
Result< void > EnsureInitialized() noexcept
Start the driver, once: the only way to initialise it.
Result< void > TraceWire(std::span< const uint8_t > bytes) noexcept
Single-shot raw access: send bytes exactly as given, as one frame with the resolved waveform....
const Config & GetConfig() const &noexcept
Definition ws2812_rmt.hpp:266
Ws2812Rmt(Port &port, const Config &config=Config::Default()) noexcept
Bind the driver to a port and store the configuration. No I/O, cannot fail; the pixels start black.
Definition ws2812_rmt.hpp:118
Result< void > PowerOn() noexcept
Switch the strip supply on and wait Config::power_on_settle_us.
void SetGamma(Gamma gamma) noexcept
Set the transfer curve applied at Show(); an unknown value acts as Gamma::None. No I/O.
Definition ws2812_rmt.hpp:188
Result< Waveform > CurrentWaveform() const noexcept
constexpr ColourOrder OrderOf(const Config &config) noexcept
The wire order a configuration selects.
Definition ws2812_rmt_functions.hpp:644
LogLevel
Severity passed to the optional Log() hook.
Definition ws2812_rmt_types.hpp:160
Gamma
The transfer curve applied before brightness (convenience, not a chip feature).
Definition ws2812_rmt_types.hpp:215
constexpr size_t kMaxPixels
Largest strip the driver accepts, in pixels.
Definition ws2812_rmt_types.hpp:333
@ Info
Lifecycle events.
The WS2812_RMT driver: everything it declares lives here; internals in detail.
Definition ws2812_rmt.hpp:29
CtrlPin
Control pins the port may drive through the optional GpioSet() hook.
Definition ws2812_rmt_gpio_interface.hpp:37
@ Power
The strip supply or the level shifter's enable; ACTIVE means powered. Idle: INACTIVE.
GpioSignal
Logical level of a pin; the port maps it to the physical polarity.
Definition ws2812_rmt_gpio_interface.hpp:43
@ ACTIVE
The pin function is asserted.
The order of the channels on the wire, first sent first.
Definition ws2812_rmt_types.hpp:268
uint8_t count
3 or 4 channels used.
Definition ws2812_rmt_types.hpp:271
A pixel colour, 8 bit per channel; w is used only by four-channel orders.
Definition ws2812_rmt_types.hpp:229
Everything EnsureInitialized() uses. The defaults suit a current WS2812B (V5, V6).
Definition ws2812_rmt_types.hpp:509
uint32_t pixel_count
Pixels in the strip; 0 means the whole capacity.
Definition ws2812_rmt_types.hpp:515
static constexpr Config Default() noexcept
Definition ws2812_rmt_types.hpp:522
The value of a call, or why there is none.
Definition ws2812_rmt_types.hpp:102
What the port needs to send the frame, in ticks of resolution_hz.
Definition ws2812_rmt_types.hpp:354
Compile-time helpers of the WS2812_RMT driver: exact hook matching and enumeration checks.
The pure functions of the WS2812_RMT driver: colour scaling, gamma, pixel encoding,...
The gamma 2.2 table of the WS2812_RMT driver, written by tools/gen_gamma.py.
The port of the WS2812_RMT driver: the CRTP base, its pin enums and the Ws2812RmtPort concept....
Public types of the WS2812_RMT driver: errors, Result<T>, colours, the timing profile of every suppor...