1. This site uses cookies. By continuing to use this site, you are agreeing to our use of cookies. Learn More.

a) Effect development

This page describes the necessary information needed to develop additional effects for the Hyperion server. Each effect script is defined in the configuration file using a unique name and a set of arguments. The Hyperion server exposes a module _hyperion_ to the embedded Python effect script. The API of the module will be described and an example effect is discussed.

Also have a look at the b-Effect-development-kit:

Module hyperion


Dictionary containing the arguments of the script (equivalent of the Json structure in the configration file)

The number of leds which are controlled by Hyperion


Returns True if Hyperion requests the effect to stop execution and return.

setColor(_red_, _green_, _blue_)
Set the color of all leds to the color specified by the arguments. The provided value should be an integer between 0 and 255.

Set the color of the leds to the colors specified by the data array. _colorData_ should be a bytearray with a length of 3 * _ledCount_ bytes: RGBRGBRGB...RGB

setImage(_width_, _height_, _colorData_)
Set the color of the leds according an image. The size of the image is specified by _width_ and _height_ and _colorData_ is a bytearray containing the color data. The array should be 3 * _width_ * _height_ bytes long. Image data is stored row-wise and starts on the top left of the image.

Effect deployment
Effects are deployed by placing them in the effect folder (/usr/share/hyperion/effects/) together with one or more effect configuration files. Each effect configuration file defines a single effect (name, script, and arguments). Below is an example of such effect configuration file:

  "name" : "Rainbow swirl fast",
  "script" : "rainbow-swirl.py",
  "args" :
  "rotation-time" : 3.0,
  "brightness" : 1.0,
  "reverse" : false
Color swirl example

This section discusses a simple effect, the rainbow swirl, as an example. First we need to import any required modules.

import hyperion
import time
import colorsys
The module hyperion contains the exposed Hyperion interface, time is required for the necessary sleep function, and colorsys provides a function to convert HSV colors to RGB. Next step is to get the the script arguments from the args variable and add default values for unset items. To avoid problems when arguments are set to a value which is outside the required range, the arguments are corrected.

# Get the parameters
rotationTime = hyperion.args.get('rotation-time', 3.0)
brightness = hyperion.args.get('brightness', 1.0)
saturation = hyperion.args.get('saturation', 1.0)
reverse = hyperion.args.get('reverse', False)

# Check parameters
rotationTime = max(0.1, rotationTime)
brightness = max(0.0, min(brightness, 1.0))
saturation = max(0.0, min(saturation, 1.0))
For this effect we build an array which is rotated arouns all leds in a specified time. Now it is time to initialize the bytearray with color data.

# Initialize the led data
ledData = bytearray()
for i in range(hyperion.ledCount):
  hue = float(i)/hyperion.ledCount
  rgb = colorsys.hsv_to_rgb(hue, saturation, brightness)
  ledData += bytearray((int(255*rgb[0]), int(255*rgb[1]), int(255*rgb[2])))
We want the calculated led data to make a full rotation in the specifed time. Therefor, the required sleep time is calculated. We make this full rotation in _ledCount_ steps. When the update rate of the leds is too high (we don't want to overload the system when running an effect), we take bigger steps.

# Calculate the sleep time and rotation increment
increment = 3
sleepTime = rotationTime / hyperion.ledCount
while sleepTime < 0.05:
  increment *= 2
  sleepTime *= 2
increment %= hyperion.ledCount

# Switch direction if needed
if reverse:
  increment = -increment
Now we have all information and we can start the run loop. It is important to stop when Hyperion asks the effect to quit and therefor we call the _abort_ function. It is also important to sleep in each iteration, otherwise the CPU will spend all of its processing power on executing the effect. For this effect we set the new colors and prepare new colors by moving some data from the back to the start of the bytearray.

# Start the write data loop
while not hyperion.abort():
  ledData = ledData[-increment:] + ledData[:-increment]
And this is already the entire script. Check out the other effects for more inspiration.

This page has been seen 6,800 times.