RGBAL: multi‑primary LED control in WLED

Multi-primary LED systems add amber, lime or white emitters to the red, green and blue primaries of a conventional RGB fixture. This article examines what those additional channels contribute, why the RGB-plus-white colour model used by most LED controllers cannot exploit them fully, and how a calibrated conversion stage can be added to WLED, an open-source ESP32 lighting controller, so that ordinary colour requests are rendered through four or five independently characterised emitters.

A linear colour-mixing model is developed for an RGBL fixture based on the Cree XNPAPL package and extended to a discrete five-channel RGBAL arrangement. The model shows that amber and phosphor-converted lime lie inside the RGB chromaticity triangle and therefore do not extend the gamut, but that they increase the luminance available at a given chromaticity by a factor of 1.7 at D65 and by more than five at amber and lime chromaticities, while raising the CRI of a D65 white from 38.6 to 68.7. A sweep of the Planckian locus identifies 3000 K as the design white point, and a luminance-headroom analysis shows that limiting the white recipe to 85% of peak luminance improves CRI by 8.9 points and R₉ by nearly 38 points.

The firmware fork implements the conversion as a 17³ lookup table, solved offline by convex optimisation and interpolated tetrahedrally on the device in linear light with 16-bit channel precision. The closed-loop calibration method, in which each emitter is measured with a spectrometer, the channel model is rebuilt from the measured spectra and the rendered output is verified by ΔE 2000, is described together with the hardware, thermal, optical and temporal-modulation requirements of an architectural luminaire.

WLED is an open-source firmware for ESP8266 and ESP32 microcontrollers that is most commonly used to drive decorative addressable LED strips. It provides Wi-Fi provisioning, a mature web interface, presets, an effects library, JSON and MQTT interfaces, and integrations with home-automation platforms. It also supports analogue, PWM-driven outputs: single-colour, CCT, RGB, RGBW and five-channel RGBCCT buses, together with selected addressable RGBW and RGBCCT chipsets. The electrical control required for a five-output luminaire therefore already exists.

What WLED lacks is a colour model for more than three chromatic primaries. Its internal representation is an RGB triple, one white value and a separate correlated colour temperature (CCT) blend. That model suits fixtures whose additional channels are white emitters of fixed chromaticity, but it has no means of deciding how five emitters with different spectra should be combined to produce a specified white, pastel or saturated colour. A five-channel RGBAL fixture can be wired to the RGBCCT bus and driven, but the result is an approximation governed by white-handling logic rather than a colour calculation.

This article addresses that gap. Sections 2 and 3 describe the terminology and characteristics of RGBW, RGBWW, RGBCCT, RGBA, RGBL and RGBAL systems and the applications in which additional primaries are of value. Section 4 examines the colour model implemented by stock WLED. Section 5 develops the linear mixing theory for a fixture with more than three primaries, and Section 6 presents modelled results for the candidate emitters. Section 7 describes the WLED_RGBAL firmware fork, which adds four- and five-primary PWM bus types, a spectrometer-derived lookup table, 16-bit internal channel data and a calibration interface. Sections 8 to 11 cover the hardware architecture of the luminaire, the temporal-modulation requirements imposed by cameras, the closed-loop calibration method and the considerations that shape the optimisation.

Development approach

Two configurations are used. During commissioning, while the optics, thermal design and driver stage are being developed, the fixture is driven through stock WLED's RGBCCT output with the two nominal white channels mapped to amber and lime. Once the emitters and drivers are stable enough to be measured, the fixture is moved to the RGBAL fork and a colour profile calibrated to the finished hardware. This separation allows electrical and mechanical work to proceed on stock firmware while the colour engine is developed against a simulated fixture.

Each letter in a channel designation normally represents one independently driven emitter colour. The naming is not applied consistently across strips, fixtures and marketplaces, and the same label can describe products with different channel counts. The part number, pinout and channel diagram are therefore more reliable than the acronym in a product listing. Table 1 summarises the common systems.

Combining amber and lime

RGBAL provides the mixer with more than one route to a given target colour. Amber produces warm oranges directly rather than through an inefficient red-and-green mixture. Lime supplies efficient mid-spectrum energy for whites and pastels, while amber adds long-wavelength content that improves the rendering of skin and other warm materials. The additional freedom can be used to improve luminous output, colour rendition, electrical load or thermal headroom, depending on the objective chosen for the mixer.

RGBAL does not in general enlarge the outer colour gamut. Amber and lime usually sit inside the triangle formed by the RGB primaries on a chromaticity diagram, so their value lies in spectral quality and efficiency within that gamut rather than in new boundary colours. Section 6 quantifies this for the candidate emitters.

Additional primaries are most valuable when a fixture must illuminate real materials rather than simply produce coloured light. Four application areas illustrate the requirement.

Two sources can have nearly identical chromaticity and CCT while producing very different spectral power distributions. Materials reflect those spectra differently, so timber, red paint or skin may appear natural under one source and flat under the other. Chromaticity alone is therefore an incomplete specification for illumination.

The colour rendering index (CRI, or R_a) remains the familiar shorthand for rendering quality, but it reduces the subject to a single average over eight moderately saturated test samples. The supplementary index R₉ reports saturated red, which R_a treats poorly. IES TM-30 was developed to address these limitations and adds a fidelity index (R_f), a gamut index (R_g) and hue-specific information. These metrics are used throughout this article to compare candidate recipes.

WLED's documented light capabilities are RGB, white and CCT. Its JSON colour array holds three or four values for RGB or RGBW, and each segment stores CCT as a separate quantity. This representation suits RGBCCT fixtures: the fourth colour value sets the white level, and the CCT value divides it between the warm-white and cool-white emitters.

Analogue single-colour, CCT, RGB, RGBW and RGBCCT outputs have been supported since WLED 0.13.1, and the addressable WS2805 and FW1906 RGBCCT devices since 0.15.0-b2. These are genuine five-channel modes, but they operate on the RGB-plus-white-and-temperature model rather than on a general five-primary colour vector. The PWM bus implementation makes this explicit. The five-channel type is designated PWM RGBCCT; it writes RGB directly, derives the warm-white and cold-white values from the white level and CCT, and sends them to channels four and five.

Mapping the white channels to amber and lime

The mapping is electrically valid. The nominal warm-white output drives amber and the cold-white output drives lime. WLED's white slider then controls their combined level and the CCT slider shifts the balance from amber to lime.

The result is an approximation rather than five-primary colour management. WLED continues to treat the two channels as a white-temperature pair. The auto-white function can add them whenever it extracts a white component from RGB. Effects generate RGB values and so do not exercise the additional pair as a five-primary mixer would. The CCT additive-blending setting determines how strongly both channels can be driven near the centre of the range, and WLED's documentation notes that high additive blending increases heat and reduces LED life.

Integration approaches

Three arrangements are available for driving a four- or five-emitter fixture from WLED. They serve different purposes and are not mutually exclusive.

At fixed junction temperature and drive current, additive light mixing is linear. The CIE XYZ tristimulus contribution of each emitter at full drive can be measured and arranged as the columns of a matrix. A target colour is then expressed as a weighted combination of the channels:

where M is the 3 × 5 matrix of measured emitter tristimulus values and the channel vector holds the linear drive fraction of each emitter. With three tristimulus constraints and five controls the system is under-determined: a two-dimensional family of channel mixtures produces the same chromaticity and luminance. That freedom is the reason the additional channels are useful. A solver can select, from the family, the mixture that uses least power, remains within channel limits, minimises spectral discontinuities, balances junction temperatures or most closely matches a reference illuminant.

A practical solver constrains channel values to be non-negative and within current limits. It also requires measured dimming curves, because PWM duty, optical output and perceived brightness are three distinct quantities.

Chromaticity matching and spectral matching

The tristimulus matrix places the output at a specified chromaticity, but CRI and TM-30 depend on the complete spectral power distribution. Two mixtures with identical chromaticity can render objects differently. A calibrated mixer therefore needs a second objective, evaluated on the spectra, to choose among the metameric mixtures. Without one, the alternative is to rely on individually measured recipes rather than on general colourimetric accuracy.

Direct control and calibrated control

Direct control of individual channels is appropriate for bench measurement and for isolating single emitters, but it offers no fixture-to-fixture consistency. LED wavelength and flux vary with bin and temperature, and nominally identical emitters differ measurably, which is why professional manufacturers calibrate each luminaire individually.

The firmware fork described in Section 7 applies this approach. The colour cube is solved offline against measured data, the result is stored as a compact lookup table, and the ESP32 performs only interpolation at run time. The optimisation is carried out once, during calibration, rather than for every rendered frame.

The emitter model places amber and phosphor-converted lime inside the triangle formed by red, green and blue on the CIE 1931 chromaticity diagram. Neither adds a boundary colour, but both provide brighter and spectrally fuller routes to colours that RGB can already reach.

The initial model is based on the Cree XNPAPL package, with red at approximately 625 nm, green at 528 nm, blue at 458 nm and a modelled phosphor-converted lime peaking near 558 nm. Adding lime leaves the area of the chromaticity hull unchanged to four decimal places, while substantially changing the predicted luminance and colour-rendering performance. Figure 1 shows the geometry.

Luminance and rendering within the gamut

Table 2 compares the modelled luminance available at four target chromaticities with and without the amber and lime channels, together with the CRI of the resulting D65 white. The luminance values are relative model outputs and are comparable only with each other.

Candidate emitters

The first hardware build uses an RGBL package rather than the final five-colour arrangement. The four-die Cree package places every source within one optical footprint, which simplifies colour mixing on the first board. The RGBAL version uses discrete emitters, which permits free choice of each primary but makes mechanical alignment and beam homogenisation more demanding. Table 3 summarises the candidates.

Selection of the design white point

A sweep of the Planckian locus from 2200 K to 6500 K (Table 4) shows that 3000 K gives the best overall balance of CRI R_a, TM-30 R_f and saturated-red rendering R₉. Moving to 2700 K improves R_a by only 0.1 point but reduces R₉ by almost 12 points, which is a poor exchange for skin, timber and other warm materials. Higher colour temperatures raise the modelled efficacy but reduce both fidelity indices.

Further observations from the model

Royal blue extends the gamut. Unlike amber and lime, substituting a shorter-wavelength royal blue for the standard blue die moves an outer vertex of the RGB triangle. The model predicts approximately 4.8% more chromaticity area, together with higher TM-30 R_f and efficacy. Standard blue retains a small R_a advantage, which illustrates that R_a and TM-30 measure different aspects of colour quality.

The optimised warm-white recipe excludes the green die. At and below 3000 K the model's best white sets the narrow green emitter to zero. Broad lime peaks in a similar region and supplies the required luminance more efficiently. Green remains necessary for saturated greens and cyans, but it is not the preferred contributor to the warm-white recipe.

The fork does not modify WLED's effects or interface to understand amber and lime. In the WLED 0.16-dev codebase on which it is based, perceptual processing is applied before the PWM bus receives the colour. The multi-primary bus therefore receives a linear-light RGB request, interpolates the calibrated table and produces four or five physical channel values.

Table 5 lists the components of the implementation and their function. The colour science is concentrated in a host toolchain so that the device performs only table interpolation.

Degrees of freedom in drive space

Section 5 showed that five drives and three colour constraints leave two free dimensions. Figure 2 illustrates one of them: a line through two-channel drive space along which every point produces the same colour to the eye but a different spectrum. The offline optimiser selects a point on that line according to the chosen balance of efficacy and spectral fidelity, and the selected value is what the lookup table stores.

Design decisions

1. A lookup table rather than a run-time optimiser. Five primaries and three colour constraints leave a family of possible mixtures, and selecting among them is computationally expensive. Interpolating a pre-solved 17³ grid is inexpensive and deterministic.
2. Tetrahedral rather than trilinear interpolation. Tetrahedral interpolation produces far less drift along the neutral axis, where even a slight colour cast is visible.
3. The profile resides on LittleFS. The table of approximately 48 kB is fixture-specific data. Storing it on the filesystem keeps it out of compile-time flash and allows replacement without a firmware rebuild.
4. The table is indexed in linear light. The mapping is smoother and easier to approximate in linear space, and a user-adjusted display gamma cannot silently invalidate the calibration.
5. Internal channel values are 16-bit. Low-level five-primary mixtures frequently depend on small differences between channels. Retaining precision avoids discarding timer resolution before the PWM stage.
6. Bus identifiers come from a reserved block. The fork uses types 96 and 97, leaving upstream PWM numbering untouched.

Simulated profile performance

For the modelled Cree RGBL fixture at 3000 K, the 17³ profile produces CRI 89.1, TM-30 R_f 87.8 and a 3005 K white. Of the 4,913 grid points, 327 (6.7%) require gamut mapping. Across 2,898 in-gamut test colours passed through the quantised table, the mean ΔE 2000 is 0.02 and the maximum is 1.40.

These figures characterise the lookup table, not the emitter model. A low interpolation error shows that the table reproduces the model's solution with little additional error; it does not show that the model's spectra match the physical emitters. An inaccurate spectral model produces inaccurate output however precisely the table reproduces it, which is why the calibration method in Section 10 rebuilds the model from measured spectra.

The design treats the fixture as a luminaire first and a WLED project second. The ESP32 provides the control interface, the colour-mapping stage converts requests into channel values, a driver stage converts those values into regulated emitter currents, and the optical engine combines the emitters into a single beam.

Controller

An ESP32 is used because it provides the processing headroom and LittleFS capacity needed for the calibration profile, together with a considerably higher default PWM frequency than the ESP8266 (Section 9).

Output stage

WLED's GPIO pins are control signals, not LED power outputs. A constant-voltage strip requires a suitable switching device per channel, and high-power emitters require regulated constant-current drivers. The output stage includes a defined off-state bias, gate or input resistors, hardware current limits, fusing and a safe power-up state. WLED's own guidance for analogue strips likewise calls for external MOSFET circuitry and protection against overload and over-temperature.

Thermal design

Thermal assessment uses the worst credible channel mixture rather than a single emitter at full output. A centre CCT blend activates amber and lime together, and a calibrated RGBAL recipe may run several channels at high current simultaneously. A temperature sensor near the LED substrate controls thermal derating, and photometric measurements are taken only after the heatsink has reached equilibrium, since stable temperature is a prerequisite for stable colour.

Optics

Several visibly distinct sources require sufficient mixing distance or a reflector or homogenising optic. The four-die Cree package gives the RGBL build a shared optical footprint; the discrete RGBAL version is less forgiving. A diffuser may conceal the individual emitters when viewed directly yet still cast coloured shadows onto nearby objects. Beam uniformity is therefore assessed at the intended installation distance, across the edge of the field and at low dim levels.

Design requirements

A PWM-dimmed luminaire can appear steady to the eye while producing rolling bands or exposure variation on camera. WLED's default analogue PWM frequency is 19,531 Hz on the ESP32, compared with 880 Hz on the ESP8266, and this is one reason for selecting the ESP32. The higher frequency avoids many common camera artefacts but does not guarantee their absence: shutter time, frame rate, rolling-shutter readout, PWM bit depth, driver behaviour and low-duty operation can all interact.

Higher PWM frequency also reduces the available PWM resolution and increases switching loss. WLED derives the PWM bit depth from the frequency and the timer clock, so the highest available frequency is not necessarily the best setting. Frequency is in any case only one component of flicker performance. Modulation depth, duty cycle and waveform shape also matter, particularly on camera, and output should be measured across the dimming range rather than assumed to be flicker-free. The following tests form the assessment.

Calibration replaces the provisional emitter model with measurements of the finished fixture, generates a fixture-specific lookup table and verifies the rendered output against intent. Figure 3 shows the closed-loop workflow, and the numbered procedure follows.

1. Stabilise the mechanics, currents and temperature. The heatsink, optic, drive current and permitted simultaneous-channel load are finalised first. Cold-start drift is recorded, and the profile is built only after thermal equilibrium.
2. Drive one emitter at a known duty. The fork's raw override bypasses the lookup table, auto-white handling and WLED's perceptual brightness curve. The bypass is essential: without it a nominal 50% request can correspond to roughly 12% duty, and the calibration would learn the wrong transfer function.
3. Capture each spectrum at several levels. An Avantes AvaSpec 2048-2 spectrometer measures each die across a sweep of duty levels. Several levels are required because driver droop, LED heating and supply sag distort the flux-versus-duty relationship.
4. Build the channel model. Each spectrum is integrated against the CIE colour-matching functions to obtain its XYZ contribution. The results form the 3 × N matrix and replace the provisional emitter model with data from the finished fixture.
5. Select the white point and headroom. The luminance ceiling is swept to locate the knee at which additional brightness begins to cost a disproportionate amount of colour quality.
6. Solve the colour cube. The toolchain solves 4,913 small convex problems, one per grid point, in about six seconds. In-gamut points balance colour accuracy, rendering and efficiency. Out-of-gamut requests are reduced in chroma while hue and lightness are held as steady as possible.
7. Upload with validation. The device checks the profile signature, version, geometry and CRC before hot-loading it. A rejected file leaves the previous calibration active.
8. Close the loop. Known colours are commanded, the beam is re-measured and ΔE 2000 is calculated against intent. The check is repeated at low output, after thermal soak and across the expected ambient range.
9. Store verified recipes as presets. Proven architectural and camera looks are stored as WLED presets so that every installation recalls identical states.

Luminance headroom

At the absolute luminance ceiling the three colour constraints can fully determine the channel mixture, leaving the optimiser no freedom to improve the spectrum. Reducing the target luminance restores that freedom. Table 6 shows the effect on the modelled 3000 K recipe.

In the model, limiting the recipe to 85% of peak luminance improves CRI by 8.9 points, R₉ by nearly 38 points and efficacy by about 5%. Below 0.85 the solution no longer changes, which identifies that setting as the knee. WLED's master brightness then scales all channels together, so the spectral mix is preserved at lower brightness levels.

Instrumentation

A spectrometer is the reference instrument for this method because the rendering metrics and the fidelity objective both require the full spectral power distribution. A tristimulus colour meter can supply usable chromaticity and luminance for the basic mixing matrix, but it cannot reveal spectral discontinuities or support reliable rendering metrics. A camera or phone is useful for demonstrating a result but is unsuitable as the sole calibration instrument. Where no spectrometer is available, a single comprehensive measurement session with a borrowed or hired instrument yields more than further iterations of unmeasured firmware.

Four aspects of the optimisation and verification formulation have a disproportionate effect on the result. Each produces plausible but incorrect output when handled naively, and the treatment adopted in the toolchain is recorded here.

Sources of error in a physical fixture

• Ambiguous naming: RGBWW does not indicate whether four or five channels are controllable.
• Common-anode and common-cathode hardware: the driver topology and polarity setting must match the LEDs. Software cannot correct a hardware mismatch.
• Auto-white: WLED can derive white from RGB, which in the repurposed RGBAL mapping adds amber or lime unexpectedly. Manual white should be used during characterisation.
• CCT blend heat: additive centre blending can drive both secondary channels hard. That case must be tested against the current limits and the thermal design.
• Power estimation: WLED's brightness limiter is useful, but a high-power analogue engine still needs hardware limits and a supply sized from measured loads.
• Thermal colour drift: flux and wavelength move with temperature. A temperature-stable fixture is easier to calibrate and to match.
• Optical separation: a diffuser that appears uniform at ten centimetres can still cast separated colour shadows at the wall.
• Low-level dimming: the bottom few per cent expose PWM resolution, driver turn-on thresholds, channel mismatch and camera banding.
• Visual calibration: the visual system adapts quickly. Side-by-side references and instruments prevent an approximate match from becoming a permanent coefficient table.
• Network exposure: WLED is a local controller. A luminaire's web interface should not be exposed directly to the public internet.

The value of an RGBAL emitter set lies not in a larger gamut but in the additional routes it provides to colours within the RGB triangle. Red, green and blue define the boundary. Amber supplies warmth without a red-and-green compromise, and lime fills an efficient region of the middle spectrum. Together they allow an architectural luminaire to produce saturated colour and considerably better pale and white light than a three-primary engine.

WLED is a suitable foundation because it already provides Wi-Fi provisioning, a mature interface, presets, APIs and effects, and because its RGBCCT output can drive a five-emitter fixture during commissioning. Its colour model, however, is limited to RGB plus white and CCT. The fork resolves this by placing a measured conversion stage after WLED's perceptual processing. A 17³ lookup table, solved offline by convex optimisation and interpolated tetrahedrally in linear light with 16-bit precision, converts ordinary colour requests into four or five calibrated drive values without changes to the effects or interface.

The modelled results identify 3000 K as the design white point, show that the optimised warm white omits the green die, and show that limiting the recipe to 85% of peak luminance yields a substantial gain in colour quality for a modest loss of output. These are model results, conditional on the assumed emitter spectra and in particular on the lime spectrum. The calibration method of Section 10 is the means by which the model is replaced with measured data and the rendered output verified by ΔE 2000, and the same measurements determine the fixture's dimming behaviour, thermal drift and optical mixing.