How to make new effects

This guide is intended for those who want to contribute their own effects to the plugin, for the benefit of other users. It intends to be a comprehensive guide for the pieces related specifically to the plugin, and assumes prior coding knowledge & a basic understanding of git systems.

Forking & installing the plugin in editable mode

Plugin can be forked via Github which allows you to make the changes then propose them back to this repo.

You'll then need to clone the repo to where you are going to create the effects. Then, from the command line you'll want to change into the new plugin directory( cd OctoPrint-WS281x_LED_Status).

Using pip from your virtual environment to install the plugin. On OctoPi installs this would be ~/oprint/bin/pip install -e .

Restart the OctoPrint server (`sudo service octoprint restart) to activate the plugin.

Creating your effects.

Here's an example of the Color Wipe effect:

def color_wipe(strip, queue, color, delay, max_brightness=255):
    strip.setBrightness(max_brightness)
    for i in range(strip.numPixels()):
        strip.setPixelColorRGB(i, *color)
        strip.show()
        if not queue.empty():
            return
        milli_sleep(delay)
    for i in range(strip.numPixels()):
        strip.setPixelColorRGB(i, 0, 0, 0)
        strip.show()
        if not queue.empty():
            return
        milli_sleep(delay)

All effects get passed the same 5 parameters:

• strip: the rpi_ws281x.PixelStrip object
• queue: an instance of multiprocessing.queue
• color: a 3-tuple of r, g, b values.
• delay: the time in milliseconds to wait between frames
• max_brightness: The brightness that the strip should be set to.

The three constraints to creating effects:

• must call `strip.setBrightness(max_brightness) first, as other effects may have left the brightness low.
• Remember to call strip.show() once the LED frame is configured, to actually update the pixels.
• must check the queue is not empty before sleeping, so that if there is a new effect needed then the current one can abort. See snippet below.

  if not queue.empty():
      return
  milli_sleep(delay)

Contributing to the plugin

Test and commit your changes, then you can create a PR 🙂 Please make them against maintenance or devel branch, since master forms the latest release which is downloaded by users.