Display.RGBW

uint8_t tile_display_rgbw_find(tiles_pal_t *hal, uint8_t instance)

Probes the instance's independent-mode base address only (0x50 for instance 0). independent: 1 0 1 Bit4 Bit3 RA9 RA8 -> 0x50-0x53 broadcast: 1 1 0 1 1 RA9 RA8 -> 0x6C-0x6F So 0x50-0x53 are the four register pages in independent mode and 0x6C-0x6F are the same pages under the broadcast address. A bus scan showing all eight is one part behaving correctly — not a second device, and not a board fault. Do not go hunting for it; it has cost bring-up time before.

hal

Platform abstraction handle

instance

Device instance (0 = default address 0x50)

Returns 1 if the device ACKs, 0 otherwise

• A healthy Display.RGBW ACKs on EIGHT addresses, and all eight are the same chip. Per datasheet Table 7-4 the 7-bit address carries the chip address AND the top two bits of the 10-bit register address:

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 full scale to 51 mA, enables all 4 LED channels, and sets the per-channel current limit to LP5811_DC_DEFAULT — ~1 mA at full PWM, NOT half scale. See that constant for why it is deliberately low and how to raise it. 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)

Peak sink current = full_scale * code / 255 (datasheet Eq. 4), where full_scale is 51 mA after init (see set_max_current()). The same code is written to Manual_DC (manual mode) and Auto_DC (autonomous animation mode, registers 0x50-0x53, reset 0), so animations run at the same current as set() / set_color(). continuous per die, 20 mA pulsed at 1/10 duty (LED datasheet, Absolute Maximum Ratings). At the 51 mA full scale that is code 25; at 25.5 mA it is code 50. Codes above that, with PWM near 255, exceed the LED's rating.

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()`. LP5811_PWM_FAULT_DETECT_MIN (25) — datasheet §7.3.5.3 and §7.3.5.4. A channel that is dark, or driven at a very low duty, reports NO fault whether or not one exists. Light the channel you care about, give it a moment to settle, and read faults while it is still lit. Reading them on an idle part returns a clean bill of health that means nothing.

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.

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.

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.

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; for a breathe that runs without the MCU, use tile_display_rgbw_breathe_auto(), which programs the on-chip animation engine (AEU).

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.

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.

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 (R, W, G, B).

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.

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.

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.

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.

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, W, G, B).

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.