This page aims to list common problems people have with the plugin. Please read it before opening issues.
This is going to be an ever-evolving page, as I learn of common issues people identify when setting up the plugin.
Got something to contribute? You can send a PR to edit this page, just click the 'Edit on GitHub' button. All contributions are welcome, and you will help someone else out!
These questions aim for self-diagnosis - there is no guarantee that your problem will be listed!
First things first, make sure that your OS configuration test passes - the LEDs do not usually work without these tests passing.
It is likely that the OS level config is incorrect. To fix this, please head to the OS Configuration Test section (under 'Utilities') to run a test and fix the configuration. See the OS Configuration Test docs.
The dependency the plugin relies on needs to be updated for every new Raspberry Pi board. This often happens quickly, but your install may be outdated. You can manually upgrade the dependency to the latest version:
pip install -U rpi-ws281x
This needs to be done from within your OctoPrint install's virtual environment. On OctoPi, this would be
Some strips do not like 3.3V signals, and if you do use 3.3v (without a level shifter) then please keep the wires to the LEDs fairly short to avoid voltage drop. Alternatively, use a level shifter if it seems that you are suffering from this issue.
Some GPIO touchscreens (and possibly some others?) use SPI to process data. This conflicts with this plugin's use of SPI to drive the LEDs and as a result you may not be able to use both.
Errors in the log file are similar to this:
ws2811_init failed with code -13 (Unable to initialize SPI)
Unfortunately, there is nothing you can do about this. If you know what you are doing, you may be able to run the LEDs using PWM but please note that this requires root access to the Raspberry Pi and for security reasons this is not recommended for OctoPrint.
Adding a 470Ω resistor in the signal line can help. Some guides recommend this, in my experience it is not always required. Worth a try if you have unstable signal to the LEDs. Link to the relevant issue report.
Mixed reports that using a sacrificial LED on a short wire (to avoid voltage drop) can be beneficial for the LED strip. See this Hackaday article for more details. This solution is untested, only linked because it might be useful. Support for skipping the first LED on the animations is in the next release of the plugin.
Make sure you have the correct order of RGB strip selected in the strip settings. You can use the LED Strip test to help debug this issue quickly. The colour order and strip type you were sold is not necessarily what works, do not hesitate to change the strip type settings until it works!
My current theory behind this issue is bad power supply to the Raspberry Pi, which will create a throttled and unstable system. This can impact the precise timing the LEDs require and means they only display white.
Make sure you restart the OctoPrint server, and reload the web interface. You should see the wizard pop up, or the light/torch icon in the navbar. I have had some reports of caching meaning the configuration wizard does not show.
This plugin requires a Raspberry Pi to run. It should run on any Linux-based OS on any Raspberry Pi, and it has detection mechanisms in place and will not load if the device it is installed on is not a Pi. This is logged, so you will see an explanation in the octoprint.log file if this is the case.