Troubleshooting¶
Find the cause of an error or of a strip that does not look right. Errors first, then symptoms.
Datasheet sections this page relies on
- Input levels VIH and VIL: Worldsemi WS2812B-V5 V5.0, Electrical Characteristics, p. 2
- RES: the reset low time: Worldsemi WS2812B-V5 V5.0, Data Transfer Time (RES), p. 3
- Input level 0.63 x VDD (later V5 family sheets): Worldsemi WS2812B-V5 V6.1, Electrical Characteristics, p. 3
- 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.
Errors¶
| Symptom | Likely cause | What to do |
|---|---|---|
EnsureInitialized() returns InvalidArgument |
Validate() refused the configuration: a repeated channel in the order, a pixel count above the capacity, a custom timing on a named variant, a reset not above the minimum |
Validate(config, capacity) returns the same error at build time; check each field against Configuration |
EnsureInitialized() returns Bus |
The port could not open the channel (pin in use, no free channel) or report its rate | Read the port's log line; check the pin and the channel count of your MCU |
EnsureInitialized() returns TimingUnreachable |
The port's tick rate is too slow to place a tick count inside a window | Run the channel at 20 MHz or more for a named variant (Timing); or your Custom windows are narrower than a tick |
Show() returns NotInitialized |
EnsureInitialized() did not succeed |
Check its result first |
Show() returns Bus |
Transmit() failed: a timeout, an underrun, a peripheral error |
The pixels are intact: call Show() again; raise transmit_slack_ms for a slow port; see "first pixels right, rest wrong" below |
Show() returns NotPowered |
The supply is off: PowerOn() was not called, failed, or PowerOff() came last |
Call PowerOn() and check its result; a port with a GpioSet() hook starts unpowered |
PowerOn() returns Unsupported |
The port has no GpioSet() hook |
Add the hook, or do not call it: the strip's supply is then yours |
SetPixel() returns InvalidArgument |
The index is past Length() |
Nothing changed; Length() is pixel_count, or the capacity |
Symptoms¶
| Symptom | Likely cause | What to do |
|---|---|---|
| Nothing lights | No ground in common, supply off, DIN not driven, a 3.3 V output on a part that needs 3.5 V, DIN wired to DOUT | Check ground and supply first, then the level (Hardware), then the pin order of the package |
| The first pixel is a wrong colour, the rest follow | The input level is marginal, or the first pixel sees ringing | Fit a level shifter and a 300 to 500 ohm series resistor close to the first pixel |
| Red and green are swapped | The part is an older SK6812RGBW, or a clone with another order | Set Config::order to kOrderRgbw or the order your part uses (Colour) |
| Colours are all wrong but stable | The wire order does not match | Send red, green and blue one at a time and read off the order; set it in Config::order |
| All pixels show one colour | The reset is too short, so each frame latches early, or the frames run together | Check reset_us and the generation of your WS2812B: the Mar-2017 sheet needs a reset above 300 µs, the 2013 sheets say 50 µs |
| Random flicker, or the strip shows stale colours | A gap inside the frame longer than the reset: an underrun | Use DMA where the peripheral has it, enlarge the channel memory, or keep interrupts short during Show() |
| First pixels right, the rest wrong or stale | The frame was cut by a low above the reset | Same as above; log from the port when it detects an underrun and return false |
| Lights on the first pixels only | The frame is longer than the strip's usable chain, or a pixel is dead | A dead pixel stops the chain: swap or bypass it |
| Wrong colours with the default variant on an older strip | The default is the V5 generation | Try Ws2812bPreV5; look at the date of your datasheet (Timing) |
| Two generations in one chain misbehave | There is no waveform inside both windows | Timing, mixed chains |
| Far end dim or tinted | Voltage drop along the strip | Feed the strip from several points, lower the brightness |
| Dim on a 3.3 V logic line only | The input threshold of your part is above 3.3 V at 5 V supply | A level shifter: MinLogicHighMv() is 3.15 V at 5 V and 3.34 V at 5.3 V for the V5 family (only the V5.0 sheet accepts 2.7 V) |
Show() takes longer than expected |
A frame of N pixels takes N x 24 bits x 1.3 µs (the V5 default; 1.25 µs for the shortest legal cycle), plus the reset | FrameTimeUs() gives the worst case; split the strip across channels if you need more frames per second |