I've tried to make this setup process as simple as possible, while it was already easy it is even easier with this guide.

Installation

Install the plugin via OctoPrint's bundled plugin manager or manually using this URL:

https://github.com/cp2004/OctoPrint-WS281x_LED_Status/releases/latest/download/release.zip

Once you have installed and enabled the plugin, OctoPrint will prompt you to restart the server.

Check you have the right hardware:

Next up: Wiring your LEDs

This documentation should tell you all you need to know about how to use the plugin. There's a lot of information here, please be sure to read some of it before opening issues in case the solution is here.

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

WS281x LEDs are very simple to wire with their 3 LEDs. There are three options of how to wire, each detailed below.

Raspberry Pi Wiring

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.

No Level Shifting

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 GPIO 10 to LED Data in

• Power supply GND to LED GND

• Power supply 5V to LED 5V

Level Shifting Chip

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.

Wiring of this is as follows:

• Common ground between:

  • Pi GND

  • LED GND

  • Power Supply GND

  • 74AHCT125 GND

  • 74AHCT125 pin 1OE

• Pi GPIO 10 to 74AHCT125 pin 1A

• 74AHCT125 pin 1Y to LED Data in

• Power supply 5V to:

  • 74AHCT125 VCC

  • LED 5V

Wiring with a Diode

The diode method is a quick way to reduce the power supply voltage slightly, so that the LED strip can read the 3.3v.

Wiring is as follows:

• Pi GPIO 10 to LED Data in

• 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

On to the next stage: SPI setup

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.

Initial Setup Wizard & OS Configuration Test

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 most OS 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, so the buffer size must be increased to control more 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

Final stage: Initial Configuration

LED Strips

The 4 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.

Power Supplies

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.

Level Shifting

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.

Raspberry Pi

All models of Raspberry Pi are supported currently, however for new models I will have to wait for upstream support from the rpi-ws281x library first. This page will be updated if this happens!

This also means that no other devices than a Raspberry Pi are supported. There are no alternative libraries for WS281x LED control (for Python) that could enable this, so there is nothing that can be done. Sorry!

The plugin will not load if it is not running on a Raspberry Pi, even if it does install.

Got the necessary hardware? Wire it up!

Using WS281x LEDs to create a flash for a timelapse

By using the power of @ commands it is very easy to make your LEDs react to other plugins that use GCODE scripts. For example, to make the LEDs flash for the timelapse, to light it up, you can use the following settings:

• Enable 'Torch mode is a toggle' in the WS281x LED Status settings, and set the torch effect to solid colour & bright white (and colour will do, but white is the most common!)

• OctoLapse Custom Camera Gcode Scripts

  • Before snapshot:

    Copy

    @WS LIGHTS_ON
    @WS TORCH_ON

  • After Snapshot

    Copy

    @WS TORCH_OFF
    @WS LIGHTS_OFF; (Optional) Turn the lights off afterwards

That's it! You can run OctoLapse in test mode to test it out.

Please select the area that most describes what you need help with:

• Configuration of the plugin

• Connecting LEDs and getting them to work

• Reporting a bug in the plugin

Configuration of the plugin

There's a lot of documentation here, that describes in detail the configuration options and the features of the plugin. Be sure to read the pages under the configuration section, such as LED Strip Configuration

Connecting LEDs and making them work

Probably the step that has the most problems, you're not alone here.

Please double check that you have wired the LEDs exactly as shown in the Wiring Guide and double check all connections.

Next up is the troubleshooting guide, where there's a list of common problems identified with solutions. Please check there and make sure your problem isn't listed, or try some of the recommended solutions.

Reporting a bug with the plugin

Really? You found a bug? Ok then, best make sure it is fixed.

Please open a bug report issue providing as much information as possible, including:

• (Always) octoprint.log file

• (Always)plugin_ws281x_led_status_debug.log file, preferably with debug logging enabled.

• Clear, easy steps to reproduce.

• The hardware you are using (if relevant)

• Screenshots/video showing the problems (if necessary - these can help quite a lot)

Please use the bug report template!

The plugin needs access to the underlying hardware to drive the LEDs. To do this it will need to run privileged with docker.

Add the following mappings to docker-compose.yml under the volumes: section of the OctoPrint service

volumes:
 - octoprint:/octoprint

To enable access to the hardware to drive the LEDs, the container must be run privileged:

privileged: true

The final file should look something like this Gist:

This documentation aims to explain all of the settings in the LED Strip Configuration dialog, so you can make the most use of them.

GPIO Pin Options

What other pins work?

To run this without root access, you must use an SPI pin. WS281x LEDs require specific timing pulses, and not every pin can produce these.

On all Pi's, the default, GPIO 10 can be used.

On all Pi's except the original Pi 1 model A and Pi 1 model B, GPIO 20 can be used. This requires adding dtoverlay=spi1-3cs to the /boot/config.txt file to enable SPI1

Other SPI interfaces are available, specific to certain Raspberry Pi models. More details on them can be found on the Raspberry Pi Documentation which contains detailed information. It is unknown if they all work with WS281x LEDs.

Can I use a PWM pin?

Using a PWM pin to drive WS281x LEDs on a Raspberry Pi requires root access. This is out of my control. It is not recommended to run OctoPrint (or any web server) with root privileges due to security reasons. So while yes, you can use PWM you are on your own to configure OctoPrint to run as root.

What about some other GPIO pin?

If it's not an SPI capable pin, or a PWM capable pin then no. This is a hardware limitation of the Raspberry Pi.

Here's all the details of the additional features of the plugin, so you can effectively configure them.

Torch

The torch button can be turned on or off to clear up navbar space if you don't want it. It has the same settings as standard effects but with some added extras for a manual trigger.

Using @ commands to trigger the torch can enable cool integrations with other software, such as OctoLapse.

Toggle Mode

The torch button or @ command turns the torch on permanently, until it is turned off. This blocks any other effects.

Timed Mode

The torch button starts a timer to turn off after configurable length of time.

Auto activate when viewing webcam

The torch will turn on when the control tab is focused in OctoPrint's UI, and turn off when you click off to another tab.

Override active times

Allow the torch mode to be enabled regardless of the active times configuration.

Active Times

The LED strip will turn on at the start time, off at the end time. Potentially useful if you don't want them on overnight.

M150 Intercept

Enable intercepting and using M150 commands. If not checked, these commands will be sent to the printer.

For documentation of the command, please see the M150 Intercept documentation page.

@ Command Reaction

Enable reacting to Host @ Commands.

For documentation of the available commands, please see the Host @ Commands documentation page

Debug Logging

Debug logging logs a lot more information about the effect runner process. This will help massively when reporting issues on GitHub, so please enable it when reporting issues!

Each progress effect has some standard options, to customise them. Individual effects have additional options, listed alongside them.

Standard Options

• Enabled

• Progress Colour The colour to indicate the progress of whatever event is happening.

• Base Colour

  The base/background colour of the progress indication.

In addition, there are two global options:

• Reverse the direction of the progress bar

• Base temperature Heating/cooling progress bar will make '0' the temperature specified. Suggested value is just below room temperature, so that the progress bar starts closer to the end of the strip.

Events

Printing Progress

Matches the progress bar in OctoPrint's UI, on your LED strip.

Heating Progress

Triggered when a blocking heating command (M109 or M190) sent to the printer.

Additional options:

• Index of tool to track Leave this at 0 for single extruder printers, for multiple extruder printers you can choose a single tool to track.

• Enable tracking tool heating

• Enable tracking bed heating

Cooling Progress

Triggered only on print success, this will display the progress of the printer while it is still cooling, until the threshold is reached, and then the 'Print Success' effect would run.

Additional options:

• Track cooling on bed or tool - select one, since they usually cool down at the same time.

• Cooling temperature threshold - the temperature when cooling tracking should stop.

LED Strip Test

Solid colour buttons

These are helpful to test the individual colours of the LED strip, to make sure the hardware and software are configured correctly. Helpful to identify if you might have selected the wrong colour order in the LED strip configuration. Each button sets that colour to maximum intensity, to isolate the individual colours.

You can also set a custom colour to be sent to the LEDs.

Effect test

This section allows for testing a configuration for an effect instantly, without needing to wait for the relevant event to occur. Configure the effect, colour and delay and then press 'Test'!

OS Configuration Test

The popup box will run a configuration test on your OS. It tests for the same things that the initial setup wizard does, to allow you to verify everything is OK down the line.

At any time, you can run a test of the above settings, using the configuration test dialog. When you run the test, it will tell you if all of the steps are filled in correctly, and if they are not, prompt you to fix it with a click of a button.

This data is also logged to octoprint.log on startup, to help me with diagnosing issues reported to rule out this configuration being the problem.

Power Calculation

Calculates the approximate power consumption of the LED strip. Useful to work out if your power supply is up-to-the task.

The nominal value included by default is 40mA, since this is what I have found to be most common. Brighter LEDs take more power, so adjust to what you think is right for your strips.

The plugin reacts to several events to display printing effects. For each of these effects, they have similar settings:

• Enable Whether the effect will run or not

• Effect One of the available effects

• Colour The primary colour to run the effect. Note this is ignored in some effects.

• Delay The length of time to wait between each frame of the effect.

Some events also have some specific settings, these are detailed alongside them.

Events

• Startup

• Printer Connected/Idle

• Printer Disconnected

• Print Success

  • This effect has configurable 'Return to idle' time in seconds. Set to 0 to disable returning to idle.

• Print Failed

• Print Paused

• Printing

  • This effect will override the print progress effect.

Effects

All the standard effects available, with fancy visualisations!

Solid Colour

Sets all LEDs to one colour, forever.

Colour Wipe

Wipes colour across the strip pixel by pixel, then clears it pixel by pixel.

Colour Wipe V2

Wipes colour pixel by pixel, as above, but to clear it turns around and heads backwards.

Pulse

Fades brightness up and down. Looks better in real life than the visualisation below!

Bounce

Sends a pulse of light bouncing from one side of your strip to the other.

Solo Bounce

Sends just a single pixel from one side to the other, bouncing about.

Rainbow

Cycles all the LEDs through the rainbow together.

Rainbow Cycle

Rainbow that cycles across the strip, so a full rainbow is across the whole strip at once.

Crossover

Two pixels bouncing in opposite directions, crossing over in the middle.

Random

Sets all LEDs to a random colour, then changes a random pixel, to a new random colour

Bouncy Balls

A physics based effect, simulating 2 balls bouncing up and down. Looks great on longer strips (and shorter ones too...!).

Unfortunately creating the simulation for this effect didn't work, so is unavailable for now. Sorry!

Custom @ commands

The simplest custom trigger, a custom @ command. All commands are prefixed as such:@WS custom <command> to make sure they do not conflict with others.

You can define your own custom effect to run when this @ command is received.

Custom Events

You can setup the plugin to react to any event you choose for it. For a list of OctoPrint's events, please see it's documentation. 3rd party plugins will add their own events, which should appear in the list to select them.

Like above, you can then add a custom effect that will be triggered whenever this event is received.

Custom Gcode Effects

There's 3 types of triggers here, that you can use.

Gcode Match

Match just the G or M code. For example, if you enter G28, the plugin will match G28 X Y, or G28 Z as well. Or if you enter G29 it will match G29 T as well.

Exact Match

This will match the entire line sent to the printer. If you just want an effect when homing Z, you could enter G28 Z here. The whole line needs to be exactly the same for this effect to trigger.

Regex Match

Here you can enter a valid regex to run against the lines received from the printer. For example, G[0-9]+ would match any G command sent to the printer. You could use M50[0-3] to match any of the EEPROM management commands, M500, M501, M502 or M503.

Native Integration

These apps have built in support for WS281x LED Status, allowing you to control your LEDs directly within them. Thank you to their respective developers for implementing support!

OctoApp

OctoApp has built in support for buttons that can turn your LEDs on and off or activate the 'torch' mode. It also has support for the 'automatic torch on when viewing the webcam' feature, so you can see your prints easily. See a quick demo of this in action, check out the video below:

Non-native integration

Not all apps can integrate with every plugin, so many of them choose to support Host @ Commands instead. This allows you, as the user to define custom controls that use these commands as you wish and use them in a variety of 3rd party apps.

Here are some examples of apps that support Host @ Commands:

• OctoDash

• OctoLapse

• PSU Control

The plugin implements a , which enables external access to the plugin's functionality.

It has a single endpoint, supporting a get request and posting a command.

SimpleAPI Get

GET http://octopi.local/api/plugin/ws281x_led_status

Get current state of the plugin, which includes the light status and the torch status.

Headers

SimpleAPI Command

POST http://octopi.local/api/plugin/ws281x_led_status

Send commands to the plugin, to make it do something.

Headers

Request Body

Commands

From :

@ commands (also known as host commands elsewhere) are special commands you may include in GCODE files streamed through OctoPrint to your printer or send as part of GCODE scripts, through the Terminal Tab, the API or plugins. Contrary to other commands they will never be sent to the printer but instead trigger functions inside OctoPrint.

The plugin reacts to some different @ commands, listed below:

These commands can be used in g-code scripts, or in custom controls in apps - see here for , or the guide on how to create a which also uses @ commands.

Commands should be formatted as such:

M150 [P{intensity}] [R{intensity}] [G{intensity}] [B{intensity}] [W{intensity}]

All of the parameters are optional, and can be included in any order. If an option is not included, its value is 0 - as a result sending an empty M150 command will turn the LEDs off.

Examples:

What does the W parameter do?

On a standard RGB WS281x strip, the W parameter sets an equal value of R, G and B on the LEDs.

If you have an RGBW strip and enable the 'Use dedicated white' setting, the W parameter will control the white LEDs only.

Sending any of R, G or B with the command takes priority over the W.

This is going to be an ever-evolving page, as I learn of common issues people identify when setting up the plugin.

What type of issue are you facing?

These questions aim for self-diagnosis - there is no guarantee that your problem will be listed!

• No LED output at all

• Unstable LED output, flickering, random colours

• Stable LEDs but colours are wrong

• OctoPrint plugin issues - plugin not loading or similar

No LED Output at all

First things first, make sure that your OS configuration test passes - the LEDs do not usually work without these tests passing.

I restored an OctoPrint backup to a new install, but the LEDs no longer work?

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.

No LED output on a new Raspberry Pi log has 'Unsupported board' errors

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

Little/no LED output when not using a level shifter

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.

No LED output when using a GPIO touchscreen

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.

Unstable LED output, flickering and changing colours.

LEDs flicker and change colour loads

You need a common ground between the LEDs, power supply and the Pi - this is the number one cause of flickering. Please check the wiring guide to see how it should be done. You can also see the example video in this issue.

Random flickering of LEDs, unstable signal

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.

More unstable signal fixes

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.

Stable LED output but the colours are wrong

The colours of my LEDs are wrong

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!

After booting the Pi & OctoPrint, LEDs turn solid white and do not recover

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.

To fix the issue, please use an adequate power supply with your Raspberry Pi. See the Raspberry Pi documentation for details on the specification for power supplies for different models.

Generic plugin issues

Can't find the plugin after installation

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.

Plugin does not load on my device

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.

If you are using docker, then make sure you have followed the Setup In Docker page to get the plugin to run.