Display.RGBW

uint8_t tile_display_rgbw_find(tiles_pal_t *hal, uint8_t instance)

Check if a Disp.RGBW is present on the bus.

void tile_display_rgbw_init(tiles_pal_t *hal, uint8_t instance, tile_t *tile, const disp_rgbw_cfg_t *cfg)

Enables the chip, ramps the boost to 4.5 V in 0.1 V committed steps (~1.6 s — avoids the single-step inrush that can brown-out a marginal supply; see version history v2.3.0), sets max current to 51mA, enables all 4 LED channels, and sets current limits to 50%. LSD action is left at "no shutdown" (driver-level choice) so a transient short doesn't latch the device into OFAF state without firmware seeing it. Pass cfg=NULL for defaults.

hal

Platform abstraction handle

instance

Device instance (0 = default address 0x50)

tile

Tile handle to populate

cfg

Optional config, or NULL for defaults

void tile_display_rgbw_sleep(tile_t *tile)

Enter sleep (disable chip).

void tile_display_rgbw_wake(tile_t *tile)

Wake (re-enable chip, LEDs retain previous state).

void tile_display_rgbw_reset(tile_t *tile)

Software reset. Must call init() again after.

void tile_display_rgbw_set(tile_t *tile, uint8_t r, uint8_t g, uint8_t b, uint8_t w)

Set RGBW output levels.

r

[0..255] Red PWM.

g

[0..255] Green PWM.

b

[0..255] Blue PWM.

w

[0..255] White PWM.

void tile_display_rgbw_off(tile_t *tile)

Turn all LEDs off (PWM = 0).

void tile_display_rgbw_set_current(tile_t *tile, uint8_t r, uint8_t g, uint8_t b, uint8_t w)

Set per-channel current limit.

r

[0..255] Red current (fraction of full-scale max).

g

[0..255] Green current.

b

[0..255] Blue current.

w

[0..255] White current.

void tile_display_rgbw_read_faults(tile_t *tile, disp_rgbw_faults_t *out)

Pulls TSD_Config_Status, LOD_Status_0, and LSD_Status_0 from the chip's page-3 register space (the LP5811 multiplexes register pages onto two extra address bits — the driver handles this transparently). Faults latch in the chip until cleared via `clear_faults()`. Open-circuit threshold (VLOD_TH) is fixed by the chip at ~70 mV (25.5 mA mode) or ~180 mV (51 mA mode). Short-circuit threshold (VLSD_TH) is configurable via `set_short_threshold()`.

tile

Initialised tile handle

out

Caller-allocated fault snapshot (zeroed on entry)

void tile_display_rgbw_clear_faults(tile_t *tile)

Writes 0x07 to Fault_Clear (W1C — write 1 to clear). After this call, `read_faults()` reflects only currently-active faults.

tile

Initialised tile handle

void tile_display_rgbw_set_color(tile_t *tile, uint8_t r, uint8_t g, uint8_t b)

Convenience wrapper around @ref tile_display_rgbw_set for the common case where only the RGB channels matter. White is held at zero — drop to `set()` directly if you want to mix white in.

tile

Initialised tile handle

r

Red PWM [0..255]

g

Green PWM [0..255]

b

Blue PWM [0..255]

void tile_display_rgbw_pulse(tile_t *tile, uint8_t r, uint8_t g, uint8_t b, uint16_t ms)

Simple alert / acknowledgement idiom. Blocking — the call returns after `ms` has elapsed and the LEDs have been turned back off. White is forced off (RGB-only); use @ref tile_display_rgbw_set + manual delay if you need full RGBW pulse control.

tile

Initialised tile handle

r

Red PWM [0..255]

g

Green PWM [0..255]

b

Blue PWM [0..255]

ms

Duration in milliseconds

void tile_display_rgbw_breathe(tile_t *tile, uint8_t r, uint8_t g, uint8_t b, uint16_t period_ms)

The "thinking" indicator. Plays a single up-and-down PWM ramp over `period_ms` (i.e., dark → peak → dark = one full breath). Loop in the caller for sustained breathing. Implementation is a software loop — the LP5811 has on-chip animation engines (AEU) that could run this autonomously, but the AEU bytecode/timing semantics aren't fully documented in the public datasheet (see @ref tile_display_rgbw.h "unsupported AEU" annotation). The software loop is fine for indicator-grade breathing at v2.1; revisit when AEU lands.

tile

Initialised tile handle

r

Peak red PWM [0..255]

g

Peak green PWM [0..255]

b

Peak blue PWM [0..255]

period_ms

One full breath duration in milliseconds (>= 64 recommended)

• Blocking. Spends `period_ms` in `delay_ms()`. Call from a dedicated task or accept the stall — the function does not yield to other peripherals.
• White is forced off (RGB-only). Step granularity is fixed at 32 PWM levels per half-cycle; with `period_ms < 64` the delay-per-step rounds to 1 ms and the breath becomes choppy.

void tile_display_rgbw_flash(tile_t *tile, uint8_t r, uint8_t g, uint8_t b, uint8_t count)

Notification idiom — alarm, error indication, "got it" ack. Each blink is 100 ms on, 100 ms off (200 ms per cycle). White is forced off (RGB-only). Leaves the LEDs off after the final blink.

tile

Initialised tile handle

r

Red PWM [0..255]

g

Green PWM [0..255]

b

Blue PWM [0..255]

count

Number of on/off cycles (1..255)

• Blocking. Total runtime is approximately `count * 200` ms. Call from a dedicated task or accept the stall.

uint8_t tile_display_rgbw_is_faulted(tile_t *tile)

Wraps @ref tile_display_rgbw_read_faults and returns 1 if any fault bit is set — open-circuit (LOD), short-circuit (LSD), thermal shutdown (TSD), or configuration error. For per-channel detail (which LED is open / shorted), use `read_faults()` directly. Faults stay latched until cleared via @ref tile_display_rgbw_clear_faults.

tile

Initialised tile handle

Returns 1 if any fault bit is set, 0 if healthy

void tile_display_rgbw_update(tile_t *tile)

The LP5811 only acts on Dev_Config / animation writes once this is issued. Call after set_aeu / set_animation / set_autonomous and before animate_start.

void tile_display_rgbw_animate_start(tile_t *tile)

Start (or restart) autonomous animation on all enabled channels.

void tile_display_rgbw_animate_stop(tile_t *tile)

Stop autonomous animation and return to the INITIAL state.

void tile_display_rgbw_animate_pause(tile_t *tile)

Pause autonomous animation, holding the current output.

void tile_display_rgbw_animate_continue(tile_t *tile)

Resume autonomous animation after a pause.

void tile_display_rgbw_breathe_auto(tile_t *tile, uint8_t channel, uint8_t peak, uint16_t period_ms, uint8_t repeats)

Builds a single-AEU symmetric ramp (0 → peak → 0) on the channel, enables autonomous mode, latches, and starts. Convenience wrapper over the AEU API for the common case.

channel

0-3.

peak

Peak brightness 0-255.

period_ms

Full breathe period (up+down) in ms.

repeats

Whole-pattern repeat: 0-14, 15 = infinite.

void tile_display_rgbw_set_max_current(tile_t *tile, disp_rgbw_max_current_t mode)

Selects 25.5 mA or 51 mA full-scale per channel. After changing, the 8-bit per-channel DC codes (set via `set_current()`) re-scale automatically — DC=255 always means full-scale current. Useful when wiring lower-rated LEDs (drop to 25.5 mA to keep DC resolution fine) or when running cooler / saving power. The driver writes `Dev_Config_0` and re-issues the `CMD_Update` latch (0x55) the chip requires for config-register writes to actually take effect.

tile

Initialised tile handle

mode

25.5 mA (0) or 51 mA (1)

void tile_display_rgbw_set_short_threshold(tile_t *tile, disp_rgbw_lsd_threshold_t threshold)

Lower thresholds catch milder partial-shorts; higher thresholds tolerate more LED forward-voltage variation without false alarms. Driver default (init) is 0.65 × VOUT — most permissive, least likely to mis-fire on cold LEDs whose Vf hasn't settled.

tile

Initialised tile handle

threshold

One of DISP_RGBW_LSD_TH_*

void tile_display_rgbw_set_short_shutdown(tile_t *tile, uint8_t enabled)

When enabled, an LSD fault sends the chip into OFAF (one-fail-all- fail) state — every channel turns off until LSD_Clear is written. When disabled (driver default), the chip flags the fault but keeps driving — firmware decides what to do.

tile

Initialised tile handle

enabled

1 = chip auto-shuts-down on LSD, 0 = report only

void tile_display_rgbw_set_open_shutdown(tile_t *tile, uint8_t enabled)

When enabled (chip default), a per-channel LOD fault turns off that single current sink. When disabled, the chip flags the fault via `read_faults()` but keeps driving the channel — useful when the open is intermittent (e.g., a flexing wire) and firmware wants to retry rather than relying on the chip to recover.

tile

Initialised tile handle

enabled

1 = chip auto-shuts-down a single sink, 0 = report only

uint8_t tile_display_rgbw_ms_to_slope(uint16_t ms)

Convert a duration in milliseconds to the nearest AEU slope/pause code.

ms

Duration in milliseconds (0-8050).

Returns 4-bit time code (0-15) for an AEU T-field or Auto_Pause field.

void tile_display_rgbw_set_autonomous(tile_t *tile, uint8_t channel, uint8_t enabled)

In autonomous mode the on-chip engine runs the channel's AEU program with no MCU intervention; in manual mode the channel follows the PWM registers (set / set_color). Call update() after configuring.

channel

0-3 (R, B, G, W).

enabled

1 = autonomous, 0 = manual.

void tile_display_rgbw_set_aeu(tile_t *tile, uint8_t channel, uint8_t aeu, const display_rgbw_aeu_t *prog)

Program one AEU sub-engine of a channel.

channel

0-3.

aeu

Sub-engine index 1-3.

prog

5-keyframe ramp + slope times + repeat.

void tile_display_rgbw_set_animation(tile_t *tile, uint8_t channel, uint8_t num_aeu, uint8_t pause_start, uint8_t pause_end, uint8_t repeats)

Set a channel's overall autonomous playback.

channel

0-3.

num_aeu

How many AEUs to chain, 1-3.

pause_start

Start-of-pattern pause code (0-15, see ms_to_slope).

pause_end

End-of-pattern pause code (0-15).

repeats

Whole-pattern repeat: 0-14, 15 = infinite.

void tile_display_rgbw_set_exp_dimming(tile_t *tile, uint8_t channel, uint8_t enabled)

Enable/disable exponential PWM dimming for a channel (Dev_Config_5).

channel

0-3.

enabled

1 = exponential curve, 0 = linear.

void tile_display_rgbw_set_phase_align(tile_t *tile, uint8_t channel, uint8_t mode)

Set a channel's PWM phase-align method (Dev_Config_7).

channel

0-3.

mode

0/1 = forward, 2 = middle, 3 = backward align.