PiLight

Posted on

Recently, my friend shared a link on Facebook about some dudes who’d made their own infinity table. While I don’t necessarily have the time or dedication to build an actual table, I was intrigued by the idea of running an LED string using a Raspberry Pi. And so, one impulse purchase and a few days of development later — I had built PiLight!

In short, PiLight is the software that I came up with to configure and run my lights. PiLight is a Django (Python web-framework) application, so naturally there’s a web-based interface for tweaking the settings. This is a nice solution, because it means that you can configure the lights from literally any device that has a web browser — your phone, tablet, computer, etc. You can read more about how to download and install PiLight on the project page, so this blog post will focus instead on my own end-to-end experience with setting up the Raspberry Pi and getting PiLight working. You can follow it as an informal (but very detailed) guide to doing something like this yourself.

Introduction

I had originally intended to run PiLight as a “standalone” application on the Raspberry Pi, so that the Pi would handle everything, from powering the configuration interface, to driving the LEDs. However, once I got it working, it became evident that the little ARM processor in the Pi just wasn’t quite cut out to perform the amount of processing I wanted it to. While it worked fine, if I added complex animations, the update rate would drop to a point where it was very noticeable (<10fps).

Thus, I decided to build a client/server model for PiLight… PiLight itself would run on a more powerful “server” computer, and the Pi essentially becomes a super thin client that just pipes color data from the server, directly to the LEDs without any processing. This turned out to work really well, and greatly simplifies the installation process on the Pi. As such, I’ll describe this process below.

The hardware

Here’s a list of hardware that I purchased, and my thoughts after getting everything set up:

  • Raspberry Pi Starter Pack — On the whole, I think it was worth the extra money for me to get the starter pack due to the “development” nature of what I was doing. If you intend to put the Pi straight into a final “product”, you probably don’t need the extra stuff that it comes with. Just get a parallel cable to break out of the Pi’s IO pins (and an SD card and maybe a case), and you’ll be golden.
  • Miniature WiFi Module — This seemed like a great idea initially… And it does indeed work awesome if PiLight is in standalone mode. However, I found that the extra latency/variability introduced by the WiFi connection made for a “stuttery” experience when running in client/server mode. If you’re running client/server, and you can find a way to get the Pi hard-wired to your network via LAN cable, you should do that instead. In my case, I’m keeping the Pi close to power/network sources, and running the LEDs out on a longer cable. More on that below.
  • Female DC Power Adapter Screw Block — Definitely recommend this. Handy for hooking in power without soldering.
  • 12mm Diffused Flat Digital RGB LED Pixels (2x strand of 25) — I chose to go for the “flat” pixels (as opposed to the “thin” style) — whichever you choose depends mostly on what you want to use them for. In retrospect the thin ones probably would have been better for inserting into drillholes in wood, for example. You can link up as many strings as you like — just make sure you have a big enough power supply. I elected to get two.
  • 4-pin JST SM Plug + Receptacle Cable Set — Good wire breakout for hooking up to the LED strings.
  • 5V 2A Switching Power Supply — Enough to power my 2 LED strings and the Pi simultaneously.

All together it ran me about $200. You could save around $100 by dropping the WiFi module, purchasing only what you need from the starter kit items, and soldering everything together.

Setting up the server

Because I was developing PiLight on my desktop PC, when it came time to hook up to the Raspberry Pi, I already had PiLight up and running. Thus, I won’t describe in full how to configure the server. However, there are detailed instructions available on the project page. In short, you will need to do the following:

  • Install Python, RabbitMQ, PostgreSQL, Mercurial and pip (if you don’t already have them)
  • Create a database for use by PiLight
  • Clone the PiLight project repository and install Python dependencies
  • Setup PiLight settings, and the database
  • Run PiLight (both the configuration interface, and the light driver)

Make sure that you open the RabbitMQ port (usually 5672) in your firewall so the client can access it.

Setting up the Raspberry Pi — software

The Raspberry Pi is essentially a miniature computer — one that needs an operating system and other software to be installed before it’s useful.

Unfortunately the default Raspbian (debian-based) OS does not include the hardware-based SPI support that we need to send color data to the LEDs. Therefore, we instead use Occidentalis — which is based on Raspbian but does include what we need. Follow the instructions here to go through the steps of formatting the SD card and extracting the OS image to the card. Then, insert the card into the Raspberry Pi, hook up a monitor and USB keyboard, and boot ‘er up!

You should be presented with a simple configuration interface. Here are the steps I went through:

  • Expand storage
  • Upgrade tools (if you have the Pi hooked up to the network)
  • Restart the device
  • Set the password for “pi” user
  • Enable SSH
  • Set the device name to whatever you like
  • (optional) Set up WiFi — as per these instructions
  • Restart the device
  • (optional) Run “ifconfig” to see what IP address the Pi has
  • (optional) Configure your router’s DHCP server so the Pi has a fixed IP address — ensures you’ll always be able to find it via SSH!

Now you should have a working Occidentalis installation! I choose to run my Pi in a “headless” configuration, meaning that it has no peripherals connected, and I instead work on it via SSH. So, go back to your server computer, and open an SSH connection to your Pi using  (use “ssh” on Linux/OSX, or PuTTY on Windows). Then, we’ll get some software installed and set up. Run the following commands:

Clone pilight-client and set up dependencies:

Copy the settings and configure:

  • cp settings.py.default settings.py
  • nano settings.py

The only thing you should need to change, is to enter your server host name.

That’s it!

Setting up the Raspberry Pi — hardware

The Raspberry Pi should now be ready to go in terms of software — but you still need to connect the lights! So, shut it down and disconnect the power:

  • Via SSH, run “sudo shutdown -h now”
  • Wait for all the lights inside the Pi to stop blinking… The red power light might remain on, but once the activity light stops you should be OK to unplug it

Grab your light strings and link them up end-to-end. Look at one of the lights, and try to find an arrow. This arrow points to the output end of the string. We want to connect to the input end. Grab the JST SM connector that fits onto the input end — this is what you’ll wire into the Pi. It doesn’t really matter how you get everything connected (whether you are soldering, or using a breadboard, or some other means), it just matters where everything links up. You should hook things up based on the wire colors that go into your JST SM plug:

  • Red = 5V — this should go into the power socket positive terminal
  • Blue or Black = Ground — this should go into the power socket negative terminal
  • Green = Clock — Goes into the “SCLK” pin on the Raspberry Pi
  • Yellow = Data — Goes into the “MOSI” pin on the Raspberry Pi

It appears that the order of these wires differs between the thin and flat versions of the LEDs — so just go by color. Once you’ve identified the wires, follow these instructions to figure out which pins to hook the Clock/Data lines to. If you run wires from the power plug to the pins on the Pi as per the instructions, then you’ll only need a single power source, rather than needing to power the Pi separately. I definitely recommend doing this.

A little tip if you’re using the breadboard and parallel cable included in the starter kit… Insert the parallel cable into the pin breakout piece included in the kit _first_ (not the Pi) — it will only go into the breakout piece one way. Then it should be obvious which way the cable plugs into the Raspberry Pi.

Putting it all together

Once you’re all wired up, plug the power supply into the socket that you’ve wired in. The Pi should boot up — although the LEDs won’t do anything quite yet. Once the Pi has fully booted, SSH in, and run the following command:

  • sudo python pilight-client/pilight-client.py

You should see an acknowledgement message that the client is now waiting for data. If you see a connection error, make sure you’ve configured the host name correctly, that RabbitMQ is running on the server, and the RabbitMQ port is opened on your firewall.

Next, make sure PiLight is running on the server — if you haven’t already, run the following commands in separate console windows:

  • python manage.py lightdriver
  • python manage.py runserver 0.0.0.0:8000

Then, connect to http://:8000/ and you should be good to go! Just hit Start and the lights should all turn on! Now you can play around, set colors, and add transforms! The lights should update in near real-time.

Final touches

There are a few things you can do to make your installation a little nicer. Here are some ideas for extra things you can do:

  • On your router, forward port 8000 to your server computer. That way PiLight will be accessible outside your local network. Use a dynamic DNS provider to give your internet IP address a nice hostname. Note: If you do this, then it’s recommended you add authentication to PiLight using the configuration option — otherwise strangers can control your lights!
  • Solder together your own “extension cable”. In my case, I wanted the Raspberry Pi to sit on the floor near power and network, and then run a long cable to where the lights were placed. There are many ways to do this, but an easy and cheap solution is to use some old Cat5/Cat6 network cable. This cable contains 4 twisted pairs of wires. Cut the ends off the length of cable that you want, remove some of the outside layer, then strip the insulation from all of the wires. You can twist together each of the pairs, and be left with effectively 4 wires — one for each of the connections to the LEDs. Twisting the pairs should ensure more than enough current capacity. Just make sure that you wire up the colors consistently at each end. For a really clean install, you could wire ethernet sockets (RJ45) to the Pi and the lights, and use an intact ethernet cable to connect the two. I think this is the route I will go when I fabricate something to put my lights into.