How to setup and configure the Raspberry Pi's SPI interface for use with WS281x LEDs.
The plugin uses the Raspberry Pi's SPI interface to push data to the LED strip, rather than PWM since it doesn't need to be run as root to use SPI.
As a result of this, there are a couple of OS level configuration items that need to be handled. Luckily for you, the plugin makes this very easy for you to do by providing a UI to run the commands.
Note: You may need to reload the web UI after installing the plugin, to get the wizard to show up. It will not display if all settings are correct or you have dismissed the wizard once already.
The setup wizard requires root access, and therefore the password for the Pi user if you have not configured passwordless sudo, as is default on OctoPi. This password is not stored, and is only used for the steps below.
Add the pi user to the gpio group.
Already configured on newer images. Means the pi users can access the GPIO pins.
Runs sudo adduser pi gpio
Enable SPI. The plugin uses SPI to drive the LEDs, which is disabled by default and needs to be turned on.
Adds dtparam=spi=on to /boot/config.txt
Increase SPI buffer size. Whilst the plugin will work without this, it will only work well with a handful of LEDs.
Adds spidev.bufsize=32768 to the end of /boot/cmdline.txt
Set compatible clock frequency Raspberry Pi 3 or earlier only, not required for a Pi 4 The Pi 3's default internal clock frequency is not compatible with SPI, so it needs to be set to 250 to be compatible.
Adds core_freq=250 to /boot/config.txt
Set a minimum clock frequency Raspberry Pi 4 only On a Raspberry Pi 4, the clock frequency is dynamic and can change when the pi is 'idle' vs. 'working', which causes LEDs to flicker, change colour, or stop working completely. By setting a minimum the same as the max, we stop this dynamic clocking.
Adds core_freq_min=500 to /boot/config.txt
WS281x LED Status OS configuration complete! You will need to reboot your Pi for these changes to take effect.
There are common defaults set in the plugin, here is an explanation of those you should change to match your setup.
Open the plugin's entry in OctoPrint's settings interface, and you should be presented with this view:
Click on the 'LED Strip Settings' button in the top right. The key settings you should edit are listed below:
Strip Type Select the type of strip you have connected to your Pi. Note: This may not be exactly what you were sold, sometimes they send variations. If you have issues, please try similar strip types here.
Number of LEDs This should be easy, count the number of LEDs you have connected and enter the right number!
Max Brightness This setting controls the maximum brightness that your LEDs should reach.
For more details on the rest of these settings, please see the full documentation
Wiring LEDs to your Raspberry Pi is the most important step!
WS281x LEDs are very simple to wire with their 3 LEDs. There are three options of how to wire, each detailed below.
Make sure you have a sufficient power supply!
You cannot power more than a handful of pixels direct from the Raspberry Pi - it can output a maximum of 500mA, which with a printer and camera connected leaves little left for LEDs. Please use an external power supply rated for the number of LEDs you have.
Using SPI to control the LEDs means you can only use one LED strip at a time with the Raspberry Pi. If you have more than one, you can 'chain' them together to make a longer strip.
The hardest part about wiring with a Raspberry Pi is connecting up the 3.3v logic from the Pi to the strip that wants 5v. There are several ways you can do this, which are described in more detail below.
All of the references to GPIO pins here are referring to the BCM Pin numbering. For more details on GPIO pins and the different ways of numbering them please see
It is possible to connect the LEDs up without any kind of level shifting, however mileage varies from strip to strip. I have one setup like this, and one with the full logic shifter. This can work because the spec of the LED strips means they need 0.7 * VDD(5v) which is ~3.5v. Close to the Pi's 3.3, so depending on how tight of a tolerance your strip has, this is possible.
Wiring is as follows:
Pi GND to LED GND
Pi to LED Data in
Power supply GND to LED GND
Power supply 5V to LED 5V
Make sure you have a common ground between the power supply and Pi.
You can use a level shifting chip to convert the signals from 3.3v to 5v. Recommended one to use is a 74AHCT125, I have this and it works well.
Please note that whilst the wiring below is on a breadboard, this is for illustrative purposes and is not suitable for high current installations. Test with a breadboard and few LEDs, then connect them directly.
Wiring of this is as follows:
Common ground between:
Pi GND
LED GND
Power Supply GND
74AHCT125 GND
74AHCT125 pin 1OE
74AHCT125 pin 1Y to LED Data in
Power supply 5V to:
74AHCT125 VCC
LED 5V
The diode method is a quick way to reduce the power supply voltage slightly, so that the LED strip can read the 3.3v.
Make sure you have a diode that can cope with the amount of power drawn! As a result of them running at lower voltage the LEDs may not be as bright.
Please note that whilst the wiring below is on a breadboard, this is for illustrative purposes and is not suitable for high current installations. Test with a breadboard and few LEDs, then connect directly.
Wiring is as follows:
Power supply 5V to 1N4001 diode anode (side without the stripe)
1N4001 diode cathode (side with the stripe) to LED 5V
Power supply GND to Pi GND
Power supply GND to LED GND
Pi to 74AHCT125 pin 1A
Pi to LED Data in
How to setup WS281x LED Status on your Raspberry Pi running OctoPrint.
I've tried to make this setup process as simple as possible, while it was already easy it is even easier with this guide.
Install the plugin via OctoPrint's bundled plugin manager or manually using this URL:
Once you have installed and enabled the plugin, OctoPrint will prompt you to restart the server.
Once the server is back up, you may have to refresh the page for in order for the wizard dialog to show up.
Using the OctoPrint Docker container? There's some additional steps you have to follow for this to work.
This page lists the hardware that is officially supported to use this plugin
The 3 types of LED strips that the plugin supports are:
WS2811 (including B variants)
WS2812 (including B variants)
SK6812 RGB
SK6812 RGBW
Please note as well that 'NeoPixels' are an Adafruit brand name, I find that they are much cheaper direct from China with just as good results, they are the same thing.
At this time, only the RGB LEDs are used. Thanks to a PR from @samwiseg0 this is coming soon!
There are no officially-supported models for power supplies, since they are all the same. However, please make sure you are using an external power supply and not using the RPi GPIO pins to power the LEDs. They cannot provide the power drawn by a strip of WS281x LEDs.
Don't use tiny wires to connect the LEDs - these can heat up and melt if they are too thin.
I have had good results with a 74ACHT125 level shifter, which is recommended by Adafruit for their Neopixels. Please note that while WS281x LEDs work without level shifting, you may need to keep the wires as short as possible - especially when using 12V LEDs.
