Colour¶
The colour order, RGBW, brightness and gamma: what goes on the wire for a colour you set.
Datasheet sections this page relies on
- 24 bit data, GRB, high bit first: Worldsemi WS2812B-V5 V5.0, Composition of 24bit Data, p. 4
- 32 bit data and its order: RGBW (revisions 01 and 03): Opsco SK6812RGBX-XX Rev. 03, 13. The data structure of 32bit, p. 6
- 32 bit data and its order: GRBW: Opsco SK6812RGBX-XX Rev. 07, 13. The data structure of 32bit, p. 9
All of them, with the driver API for each: Datasheet map.
What a pixel receives¶
A pixel takes 24 bits (32 on SK6812RGBW), high bit first, one byte per colour channel, and the order of the channels is fixed by the part. Pixel 0 is the one nearest the controller; a frame is every pixel back to back, then the reset.
| Parts | Order on the wire | Datasheet |
|---|---|---|
| WS2812, WS2812B, WS2812C, WS2812D, SK6812, SK6812MINI | G, R, B (kOrderGrb) |
V5, p. 4 |
| SK6812RGBW Rev 07 | G, R, B, W (kOrderGrbw) |
skw-07, p. 9 |
| SK6812RGBW Rev 01 and Rev 03 | R, G, B, W (kOrderRgbw) |
skw-03, p. 6 |
The three SK6812RGBW documents disagree. Variant::Sk6812Rgbw defaults to GRBW, the later revision. If red and green
are swapped on your strip, it is an older part: set the order to RGBW.
// An SK6812RGBW strip: four channels, white last. Rev 01 and Rev 03 datasheets send red first.
ws2812_rmt::Config RgbwConfig(bool old_revision) {
ws2812_rmt::Config c = ws2812_rmt::Config::Default();
c.variant = ws2812_rmt::Variant::Sk6812Rgbw;
if (old_revision) {
c.use_default_order = false;
c.order = ws2812_rmt::kOrderRgbw; // red and green swapped on the strip means: use this
}
return c;
}
The order is data: a ColourOrder of up to four channels. Any permutation of R, G, B and (for four channels) W is
valid, which covers clone parts that use another order. Validate() refuses an order with a repeated channel, a
white channel in a three-channel order, or a count other than 3 or 4.
// The pure encoder, without a strip: what the wire carries for one pixel.
bool EncodeOne() {
std::array<uint8_t, 3> wire{};
const ws2812_rmt::Colour c{0x12, 0x34, 0x56, 0};
const size_t n =
ws2812_rmt::EncodePixel(c, ws2812_rmt::kOrderGrb, 255, ws2812_rmt::Gamma::None, wire);
return (n == 3U) && (wire[0] == 0x34U) && (wire[1] == 0x12U) && (wire[2] == 0x56U); // green first
}
Brightness and gamma¶
Config::brightness and SetBrightness() scale every channel linearly at Show(): 255 leaves a value unchanged, 0
is off, and the value is rounded, not truncated. The stored colours are never changed, so brightness is reversible.
Gamma, off by default, maps each value through a 2.2 table before brightness:
using Strip = ws2812_rmt::Ws2812Rmt<MyPort, 30>;
void Dim(Strip& strip, bool night) {
strip.SetBrightness(night ? 20 : 255); // linear; the stored colours are untouched
strip.SetGamma(ws2812_rmt::Gamma::Gamma22);
}
The pixels have 256 PWM levels per channel and nothing else: brightness and gamma are convenience of the driver, not chip features. A strip dimmed by brightness 20 has about 5 levels per channel left; if you need smooth fades at low light, dim with the strip's supply or work in a wider colour type of your own.
White¶
An RGBW pixel has a white die. ExtractWhite() moves the common part of red, green and blue into white, for a strip
that should show an RGB colour with the white die. It is never applied implicitly:
// RGB colour on an RGBW strip with the white die: the common part of R, G and B moves to W.
ws2812_rmt::Colour Warm() {
return ws2812_rmt::ExtractWhite(ws2812_rmt::Colour{200, 100, 50, 0}); // {150, 50, 0, 50}
}
Wheel¶
Wheel() returns a fully saturated colour for a position from 0 to 255 (red to green to blue to red). It is a helper
for demos; the driver has no animations or effects:
// An animation is ordinary code: the driver has Wheel() and SetPixel(), not effects.
template <typename Strip>
void Rainbow(Strip& strip, uint8_t phase) {
for (size_t i = 0; i < strip.Length(); ++i) {
const auto position = static_cast<uint8_t>(phase + ((i * 256U) / strip.Length()));
static_cast<void>(strip.SetPixel(i, ws2812_rmt::Wheel(position)));
}
}