Flexible LED controller designed to run on a Raspberry Pi, and drive WS2801 LED strings. Has a Django web-based interface for access anywhere.

Although it is more work to set up (and completely optional), PiLight is designed to be run in a server/client configuration - with a powerful server driving the configuration interface, and computing color data to send to the LEDs; and a lightweight client script running on the Raspberry Pi. See the Client/Server section below for more details.

For more information, check out the following sources:

  • Blog post detailing hardware and installation of PiLight
  • Demo video showing the PiLight interface and lights running


The instructions below describe the configuration of a "standalone" installation of PiLight, such as onto a Raspberry Pi. While the Raspberry Pi is perfectly capable of running the PiLight configuration interface, and producing color data for the LEDs, its processor can sometimes struggle with the workload, reducing "framerate" to <10 updates per second.

For high-performance installations running complex animations, it's recommended to run PiLight on a more powerful server computer, and use the lightweight PiLight Client as the only software running on the Raspberry Pi. If you intend to use this configuration, then pay attention to the following differences in installation:

  • Install PiLight (as per the instructions below) onto your intended server computer
  • Install PiLight Client onto the Raspberry Pi, according to the instructions on that page
  • Do NOT install the full PiLight software onto your Raspberry Pi
  • In the PiLight file, set LIGHTS_DRIVER_MODE to 'server'
  • Make sure to open your RabbitMQ port (usually 5672) on your server computer, so that the Raspberry Pi can access it
  • You still need to run the lightdriver command on your server computer - this will now output to the RabbitMQ queue for the client to pick up, instead of directly to the LEDs


Install all prerequisites first:

Note: These instructions assume you're using a Raspberry Pi with Occidentalis for the most part - omit sudo if your flavor doesn't use it, for example. This is all tested working with a 512MB Raspberry Pi device, and Occidentalis v0.2.

Download the source to a desired location:

hg clone

Install the Python dependencies:

cd pilight
sudo pip install -r requirements.txt

Note: If you get an error message about available space on the device, it's likely your /tmp folder is too small. Run sudo nano /etc/default/tmpfs, change TMP_SIZE to 200M, then try pip install -r requirements.txt again. You may run into this when installing on a Raspberry Pi device.

Note: If setting up a server installation on Windows, with PostgreSQL, you may find it easier to install the psycopg2 package from a binary installer instead of with pip. Download the binary corresponding to your Python/PostgreSQL version.

Create a new database in your DBMS (e.g. PostgreSQL) to use for PiLight.

Copy the settings file and make required changes (particularly set up your light parameters, and database instance):

cd pilight
cp pilight/ pilight/

Note: Be sure to edit your new file!

Setup the database:

python syncdb
python migrate
python loaddata fixtures/initial_data.json
python createcachetable pilight_cache

Launch PiLight

Once you've gone through all the installation steps, you're ready to run PiLight!

First, ensure that RabbitMQ and your DBMS are running. Then, run the following commands in separate console windows (or use screen):

sudo python lightdriver


python runserver --noreload

Note: lightdriver and runserver are both blocking commands that run until stopped, which is why they must be in separate console windows. We bind runserver to so that it can be accessed from other devices on the network, not just localhost. This is useful for controlling PiLight from your phone or computer. --noreload reduces CPU usage by the web service significantly when idle. This is especially important when running in standalone mode.

That's it! You should now be able to access the interface to control the lights by accessing http://localhost:8000/.

Starting Automatically

If running PiLight from a Raspberry Pi, it may be beneficial to have the server and light driver start automatically when the device boots. This saves having to connect a keyboard or SSH to your Pi whenever the power cycles. It's suggested that you do this by using screen. First, open your screen config:

nano ~/.screenrc

Suggested config to use (important piece commented):

startup_message off
vbell off
escape /
defscrollback 5000
hardstatus alwayslastline
hardstatus string '%{= kG}%-Lw%{= kW}%50> %n*%f %t%{= kG}%+Lw%< %{= kG}%-=%D %m/%d/%y | %C:%s %A'

chdir $HOME
screen -t shell 0 bash
screen -t shell 1 bash

# Crucial tabs:
chdir $HOME/pilight/pilight
screen -t pl 2 sh -c 'python runserver --noreload; exec bash'
screen -t pl-driver 3 sh -c 'python lightdriver; exec bash'

chdir $HOME
select 0

This will open two extra tabs (2+3) for PiLight on startup - one for the web interface, and one for the light driver. The final step is to have screen run at startup. There are a few ways to do this, but crontab is likely the simplest. Run crontab -e, then enter a line like the following:

@reboot sleep 30 && screen -d -m -A

This will wait a minute (you can try lowering this timeout) after system reboot, then open screen in a detached mode. The delay is necessary due to other services starting up. If you SSH into the Pi later, you can view the opened processes by running screen -R. Navigate screens by Ctrl+A then the screen id (0 through 3 in the above example).



PiLight is designed around a simple "Colors" + "Transformations" system. You specify both parts in the configuration interface.

  • Colors define the "initial" or "base" states for each individual LED. Using the PiLight interface, you can "paint" colors onto the LEDs. Specify a tool (solid/smooth), tool radius and opacity, and a color. Then, click individual lights to start painting. The lights will refresh after each click.
  • Transformations get applied in real time when the light driver is running. They modify the base colors based on a variety of input parameters, and usually a "time" component. Typically they will produce an animation effect, such as flashing or scrolling. Transformations can be added to the "active" stack. Each transformation is applied in sequence, for each "frame" that gets sent to the LEDs. Multiple transformations of the same type can be stacked; for example, to have a slow flash, with faster small fluctuations.

Note: Currently parameters for transforms are not editable via nice controls. However, when adding a transform, sensible defaults will be applied, and you can edit the parameter string by hand. This should be fairly self-explanatory.

You can view a 10-second preview of what the lights will look like after animations are applied (animated in-browser) by hitting the Preview button.

Running the light driver

Changes in the configuration interface are instantly sent to the light driver if it's currently running. You can also use the buttons at the top right to control the driver:

  • Refresh will force the light driver to reload its configuration (if it's started), as well as refresh the configuration page for any changes
  • Start will start the light driver so that it powers the lights and runs transforms
  • Stop will stop the light driver and power off the lights - then await a new Start command

Note: These buttons all have no effect if the driver is not running. Remember to start it with python lightdriver.

Loading and saving

You can save the current configuration by typing a name in the text box at top right, and hitting Save. You can also load past configurations with the Load button.

Note: If you load a configuration, changes you make are NOT automatically saved back to that configuration. Make sure you hit Save again when you're done. This will overwrite previous settings, if a configuration already exists with the same name.


Periodically you may want to update PiLight to get the latest features and bug fixes. Just run the following commands from the pilight/pilight directory:

hg pull
hg update
python syncdb
python migrate
python loaddata fixtures/initial_data.json