Skip to content

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.

api_tasks.cpp
// 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.

colour.cpp
// 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:

api_tasks.cpp
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:

colour.cpp
// 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:

colour.cpp
// 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)));
  }
}