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 and example effect is discussed.

Module hyperion

Variables

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

ledCount
The number of leds which are controlled by Hyperion

Functions

**abort**() 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

setColor(colorData)
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 together with one or more effect configuration files. Each effect configuration file defines a single effect (name, script, and arguments). Below is a 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 switl, as an example. First we need to import any required modules. ```python 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. ```python # 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.
```python
# 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():
        hyperion.setColor(ledData)
        ledData = ledData[-increment:] + ledData[:-increment]
        time.sleep(sleepTime)

And this is already the entire script. Check out the other effects for more inspiration.