TL;DR This server allows you to control RGB LED strips through a REST API. (But it really does so much more than that, so you should keep reading.)
After buying an LED Light Strip, I was very disappointed with what it could do. It comes with an IR remote that gives you a few choices of colors and patterns, but nothing too elaborate. There are a few existing ways to get the lights to synchronize with music, but most of them are too complicated and require users to start and stop the program through the terminal. Needless to say, a party is the worst time to have to open up ssh and start a program.
Aurora addresses these issues with a unified REST API. The API allows you to display:
- Static Presets (All the functionality of the IR remote)
- Solid colors
- Fades between two or more colors
- Sequences containing colors, fades or other sequences
- Music Visualization (based on LightshowPi)
This project was designed specifically to run on a Raspberry Pi. It's been confirmed to work on the Raspberry Pi 3 and Zero, but should work on any model.
For a simple hardware setup, follow this tutorial. Other multi-strip configurations are possible too.
Before running the project you need to install python 3.7 (or later). To do this you need to build the latest version from source.
-
Install the following build tools on your system.
$ sudo apt-get update $ sudo apt-get install build-essential tk-dev libncurses5-dev libncursesw5-dev libreadline6-dev libdb5.3-dev libgdbm-dev libsqlite3-dev libssl-dev libbz2-dev libexpat1-dev liblzma-dev zlib1g-dev -
Download and install the latest version of python from source. Replace the url in the wget command with the latest version from the official site.
$ https://www.python.org/ftp/python/3.7.0/Python-3.7.0.tgz $ tar -xzf Python-3.7.0.tgz $ cd Python-3.7.0 $ ./configure $ make -j4 $ sudo make install
This server reads audio for the visualizer from a UNIX named pipe or FIFO. Any program that is capable of outputting audio to a FIFO can be used as the audio source. Some examples are:
- Raspotify ― A client for Spotify Connect
- Mopidy ― A music server that can stream from Spotify, SoundCloud, Google Play Music, and more.
In the end, it doesn't matter what program you use as long as it writes audio to the FIFO specified in the config file. The default location is /tmp/aurora-fifo
To install the server from source, first clone the repository:
#HTTP
$ git clone https://github.com/barrymcandrews/aurora-server.git
#SSH
$ git clone git@github.com:barrymcandrews/aurora-server.git
Next, install the dependencies, build and install the project:
$ cd aurora-server
$ sudo python3 setup.py build
$ sudo python3 setup.py install
Aurora Server's configuration file is located at /etc/aurora.conf. There you can specify your hardware setup. You can also change settings related to the visualizer. For a full description of all configuration options see the comments in the example config file.
To start the server manually just run the aurora command:
$ sudo aurora
You can also use aurora as a systemd service:
$ sudo systemctl enable aurora
$ sudo systemctl start aurora
A very limited Swagger documentation page is also available by running the project and navigating to localhost:5000/swagger
Before you can set the lights to a color you need to know what lights are connected to the server. You can find this out by making a GET request to /api/v2/channels
[
{
"device": "main",
"label": "green",
"pin": 3
},
{
"device": "main",
"label": "red",
"pin": 2
},
{
"device": "main",
"label": "blue",
"pin": 0
},
{
"device": "secondary",
"label": "green",
"pin": 23
},
{
"device": "secondary",
"label": "red",
"pin": 22
},
{
"device": "secondary",
"label": "blue",
"pin": 21
}
]When setting the lights to a color or pattern you create a "preset" on the server. Presets are handled as CRUD resources at the endpoint /api/v2/presets. Each preset contains a list of channels that the preset will be applied to, and a payload specifing how the preset should be displayed.
To get a list of all running presets on the server make a GET request to /api/v2/presets.
[
{
"id": 1,
"name": "main-blue",
"channels": [
{
"device": "main",
"label": "blue",
"pin": 0
},
{
"device": "main",
"label": "red",
"pin": 2
},
{
"device": "main",
"label": "green",
"pin": 3
}
],
"payload": {
"type": "levels",
"levels": {
"blue": 100,
"red": 0,
"green": 0
}
}
}
]This response means that the device named "main" is set to the solid color blue.
To create a new preset make a POST request to /api/v2/presets. For convience, you can provide device names instead of channels when creating presets. Note in the example below the "devices" key used instead of "channels". Listing a device is the same as listing all channels tagged with that device name.
{
"name": "complicated-preset",
"devices": [
"led-strip-1"
],
"payload": {
"type": "sequence",
"children": [
{
"type": "levels",
"levels": {
"red": 100,
"green": 0,
"blue": 50
}
},
{
"type": "fade",
"children": [
{
"type": "levels",
"levels": {
"red": 100,
"green": 100,
"blue": 50
}
},
{
"type": "levels",
"levels": {
"red": 0,
"green": 0,
"blue": 0
}
}
]
}
]
}
}Once you submit a preset post request, the server will begin to display the preset payload. If the preset you submitted conflicts with any existing presets, the existing presets will be stopped first.
The preset payload determines what will be displayed on the lights. You can display simple colors or more complicated patterns.
There are four types of payloads:
- Levels
- Fade
- Sequence
- Visualizer
Using these elements, you can create any possible pattern for your lights.
Levels are solid colors. In a levels payload, you must provide channel labels and their values. Usually a levels payload will contain red, green, and blue keys. However, depending on your hardware setup you could have other channel labels such as white.
{
"type": "levels",
"levels": {
"red": 0,
"green": 0,
"blue": 0
}
}Fades smoothly transition between two or more colors. In a fade payload, you must provide a list of levels to fade between. Once the fade is complete it will restart at the beginning. Note that the server does not fade between the last element and the first element when it loops back.
{
"type": "fade",
"delay": 5,
"children": [
{
"type": "levels",
"levels": {
"red": 100,
"green": 0,
"blue": 0
}
},
{
"type": "levels",
"levels": {
"red": 0,
"green": 0,
"blue": 100
}
}
]
}Sequences are lists of other payloads. They display other payloads for a certain amount of time and then move on to the next one. Sequences can contain levels, fades, or other sequences.
{
"type": "sequence",
"delay": 1,
"children": [
{
"type": "levels",
"levels": {
"red": 100,
"green": 0,
"blue": 0
}
},
{
"type": "levels",
"levels": {
"red": 0,
"green": 100,
"blue": 0
}
},
{
"type": "levels",
"levels": {
"red": 0,
"green": 0,
"blue": 100
}
}
]
}Visualizer payloads tell the server to display colors based on the music playing. The visualizer is very CPU intensive, so there can only be one visualizer preset on the server at a time.
{
"type": "visualizer",
"visualizer": {
"filter": "classic"
}
}