Skip to content

LedPeripheral

Source: LedPeripheral.h

LedPeripheral

class LedPeripheral
src/light/drivers/LedPeripheral.h:23

A parallel-WS2812 output peripheral, behind a runtime strategy interface.

ParallelLedDriver owns the controls, lifecycle, tick and encode machinery, driving one peripheral chosen at runtime. The peripheral supplies the variant operations: bring the bus up, hand back its DMA buffer, transmit, tear down.

Not a hot-path boundary: every method here is called per frame or per reinit, never per light. The per-light encode writes into the raw buffer and never calls back into the peripheral.

Prior art: the Strategy pattern, in the same shape this project's other pluggable seams take.

Public Methods

virtual ~LedPeripheral() = default : Virtual, since the orchestrator owns every backend through this interface.

inline void attach(ParallelLedDriver * owner) : Bind the peripheral to its orchestrator, which it reads its shared state through.

virtual uint8_t lanesAvailable() const : Parallel lanes this peripheral's silicon provides on the current chip (0 = not this chip).

virtual bool supportsPinExpander() const : Can this peripheral host the 74HCT595 pin expander? (Needs a DMA that reaches PSRAM.)

virtual inline bool supportsDoubleBuffer() const : Whether this peripheral can run the async double-buffer, overlapping encode and wire.

virtual bool powerOfTwoBus() const : Does the bus width round up to a power of two (8/16), or is it the exact pin count?

virtual const char * initFailMsg() const : The status message when bus init fails on this peripheral.

virtual inline bool busContentionCleared() const : Whether a peripheral a previous init lost to a sibling is free again, so the driver retries.

virtual bool loopbackFullWidth() const : Whether the loopback self-test must build a full-width bus rather than a single lane.

virtual LedHwBlock hwBlock() const : The physical block this backend drives, which the claim guard refuses to double up.

virtual bool busInit(size_t frameBytes, bool wantSecondBuffer) : Create the bus and its DMA buffers, optionally with the double-buffer's second frame.

virtual void busDeinit() : Tear down the bus and its DMA buffer(s).

virtual uint8_t * busBuffer(uint8_t i) : DMA buffer i (0/1) the encoder writes into; buffer 1 is null in single-buffer mode.

virtual size_t busCapacity() const : Per-buffer byte capacity (fixed at bus creation; both buffers equal).

virtual bool busTransmit(uint8_t i, size_t bytes) : Start the transfer of the first bytes of DMA buffer i, reporting whether it began.

virtual bool busWait(uint8_t i, uint32_t ms) : Block up to ms for buffer i's in-flight transfer to complete.

virtual uint32_t busLastTransmitUs() const : The most recent DMA transfer's wire time (µs): the WS2812 output floor.

virtual platform::RmtLoopbackResult busLoopback(const uint8_t * frame, size_t frameBytes, size_t dataBytes, uint8_t rowBits) : Run the loopback self-test on this peripheral (each builds its own bus, per loopbackFullWidth).

virtual inline bool busInitRing(size_t, uint32_t) : Bring the bus up as a streaming ring, returning false when it will not fit.

virtual inline bool busTransmitRing() : Send one frame on the ring (prime + arm + ISR refill). False if the ring isn't up.

virtual inline bool busIsRing() const : Is the live bus a streaming ring?

virtual inline bool wantsRing() const : Should reinit build a ring for the current config instead of the whole-frame path?

virtual inline const char * busRingMode() const : The ring's active-mode label for the status line, or nullptr for the whole-frame path.

virtual inline void addRingControls(ControlList &) : Append this peripheral's ring controls into the shared list. Default: none.

virtual inline void refreshBusKpi() : Refresh any peripheral-specific read-only KPIs (the ring diagnostic). Default: none.

virtual inline bool snapHelperReady() const : Is the core-0 fork-join snapshot helper up (dual-core prime)? Default: no helper.

virtual inline void addBusControls(ControlList &) : Append this peripheral's own bus-pin controls into the shared list.

virtual inline bool busControlTriggersBuild(const char *) const : Does a change to control name require a bus rebuild (a bus pin changed)? Default: no.

virtual inline void recordBusPins() : Snapshot the current bus pins so extraBusPinsCurrent can detect a later change. Default: none.

virtual inline bool extraBusPinsCurrent() const : Are the recorded bus pins still current (no un-applied change)? Default: always current.

virtual inline const char * validateBusFatal() const : A per-peripheral fatal validation (returns a status message) run before bus init. Default: ok.

virtual inline const char * validateBusPins(const uint16_t *, uint8_t) const : A per-peripheral lane-pin validation (returns a warning): e.g. a data pin colliding with WR.

virtual inline uint16_t clockPinForBus() const : The GPIO the bus parks spare lanes on, reached only where the bus rounds wider.

virtual inline bool spareLanesNeedPad() const : Whether a spare bus lane must be parked on a real GPIO.

virtual inline size_t dmaBudgetBytes() const : The whole-frame DMA byte budget; 0 means no bound, as on a PSRAM-capable peripheral.