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.

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 ``` 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))

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(255rgb[0]), int(255rgb[1]), int(255*rgb[2])))

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

Start the write data loop

while not hyperion.abort(): hyperion.setColor(ledData) ledData = ledData[-increment:] + ledData[:-increment] time.sleep(sleepTime)