Step 21: Using PureData or other Software to Control the Saiko5
OSC Packet Format
Basic functionality can be easily accessed through the use of the liblo library, available for python, C, PureData, and other languages. Example code of basic python scripts for controlling lights can be found in the saiko5 archive available in the Downloads section, in the subfolder /saiko5/software/scripts/
Basic Example Code
address = liblo.Address("192.168.1.222", "2222")
liblo.send(address, '/light/color/set', ('f', 0.8), ('f', 0.0), ('f', 0.2))
In this code example, which is all that is required to control a Saiko5 fixture, there are three lines.
1. import liblo
This imports the liblo library. You will need to have python-liblo installed for this functionality to be activated.
2. address = liblo.Address("192.168.1.222", "2222")
This creates a liblo address object, which can be used to send packets over OSC to the light at the given IP address. The lights are programmed by default to listen on port 2222, and to the computer at 192.168.1.2. However, these settings can be changed easily by uploading a modified version of the firmware. Note that if you have multiple lights, you will need to send the commands to all lights to do updates.
3. liblo.send(address, '/light/color/set', ('f', 0.8), ('f', 0.0), ('f', 0.2))
This creates and sends an OSC packet. The specification that the lights are expecting is the path '/light/color/set', followed by three floats, which correspond to the RGB brightness between 0 and 1.
Note that this is configured to send commands out as RGB data. This is not the preferred colorspace for dealing with LED lighting, and we highly recommend the use of HSI (Hue, Saturation, Intensity) for the local representation of light color. Code is available for converting from HSI to RGB in python in the saiko5 software repository at /saiko5/software/puredata/server/HSI2RGB.py
Hue is an intuitive way to think about "color", with values ranging between 0 and 360 degrees, where 0 degrees and 360 degrees are red, and as the hue increases, it passes first through yellow, then green, then cyan, then blue, then magenta before returning to red. This representation allows for the straightforward coding of steady color changes.
Saturation is an intuitive way to think about the "whiteness" of a color, with a saturation of 1.0 meaning as pure as possible of a color, and a saturation of 0.0 meaning white regardless of the hue. The use of saturation values less than 1.0 allows for the easy display of pastel colors.
Intensity is the natural representation for the brightness of a LED light fixture. Intensity is defined here as the sum of the red, green, and blue channels, between 0.0 and 1.0. This is different than the "value" used in HSV, where the value is defined as the maximum value between the red, green, and blue channels. Although the use of intensity instead of value limits the maximum brightness of the light to the brightness of a single channel alone, we feel that this is a more natural way to use a color changing light fixture. For example, in HSI colorspace, a HSI value, if intensity is constant, and the hue is changed, the total power being put out by the light fixture remains constant. However, in HSV colorspace, if the value is constant, and the hue is changed, the power being put out by the light fixture changes.
This is especially evident in the example of going from red to yellow (or any primary to secondary color). In the case of red, a HSV value of (0, 1, 1) is equivalent to a RGB value of (1, 0, 0). This is the same result that would come from using the HSI value (0, 1, 1). However, for yellow, the HSV value of (60, 1, 1) would result in an RGB value of (1, 1, 0) while a HSI value of (60, 1, 1) would result in an RGB value of (0.5, 0.5, 0). In the case of constant value, the amount of light being put out is higher for yellow than red by a factor of two, while in teh case of constant intensity, the amount of light being put out is unchanged.
The Saiko5 Software
The Saiko5 Software was primarily developed on Ubuntu 10.04. We highly recommend that to be certain that your setup will function you download and use our LiveCD image which will provide a basic Ubuntu environment with our software preinstalled and set up. However, we understand that this isn't an ideal situation for all users, and so software is also provided on our Downloads page. The saiko5 repository is split into two main folders, /saiko5/firmware/ and /saiko5/software/. This documentation will discuss the software contained in the /saiko5/software/ folder.
The gui folder contains a graphical user interface written in python using wxpython for widgets. This software allows for basic control over the light fixtures using a point and click interface, including choosing a HSI color, picking IP addresses to send the commands to, and doing basic color cycling modes. To use this software, open the saikoControlGui.py in python.
The scripts folder contains basic example code for controlling the light fixtures using liblo in python. Note that using these will require manual configuration of the IP addresses of the lights you are attempting to control.
* colorcycle.py -- This is a basic color cycling program using 100% saturation and a constant rate of change.
* setpurple.py -- This is the very basic script shown above in three lines which will set the color of the chosen light to our favorite shade of purple.
* udpstresstest.py -- This script will stress test your network and the lights by sending udp packets to the lights. You can use this to determine how stable your wireless network is.
The puredata folder contains source code for doing audio analysis using puredata with an accompanying python server for actual communication with the Saiko5 light fixtures. This is the software that is used to make the videos of music response on the page. The screenshot shows the PureData + Python Server being used actively to control the Saiko5 Fixture.
* analyzer.pd -- This is the puredata analyzer. It requires pd-extended, as well as pd-aubio (the aubio music analysis library) to function.
* server/HSI2RGB.py -- This python script converts HSI values to RGB.
* server/lightconfiguration.py -- This python script contains the configuration information for the Saiko5 fixtures being controlled.
* server/lightevents.py -- This python script has the basic code for the python server. This is the code that will generally be modified to add new functionality to the server.
* server/lightserver.py -- This is the overall python script that must be running for the analyzer.pd software to function. It is designed to listen for OSC packets on port 2223, and those packets are provided by the puredata software.