Today, I'll go through the steps to use a raspberry pi to get your Christmas lights flashing with music. With just a few bucks of extra material, I walk you through converting your regular Christmas lights into a whole-house light show. The goal here is to go from scratch. Although this guide is intended for people who don't know how to use linux at all and those who do alike, the focus is for people for whom linux and the raspberry pi are a complete mystery. There is much more that can be done with the lightshowpi software and more sophisticated hardware, but this is about just getting started.

Step 1: Material

First the must have:

You will need your christmas lights. I highly recommend sticking to DC powered lights. If you don't have any, instead of playing with mains voltage, get some LED strips, or DC powered christmas light strings.
A raspberry pi; different configurations need different hardware
- If you get a pi zero or pi zero w, you will need **A decent kit will have all of these already**
  - an HDMI audio extractor
  - a mini HDMI cable
  - header pins, or just solder directly into the board
  - a USB OTG adapter
  - A soldering iron
- If you get a pi A, A+, B or B2, or zero (non w), you will need a wifi dongle
- If you get a pi 3 kit, nothing else

A speaker with aux in and auxiliary cable. Bluetooth audio is wonky on the pi zero w and pi 3 unfortunately.
a memory card (minimum 4gb), usually included in kits
An 8 channel relay board (5v)
Female to female header pins

Temporary needs: this is temporary so I would recommend just using whatever you already have for the few hours it will be needed

A USB mouse and keyboard
Access to an HDMI monitor or TV
A USB hub if switching between mouse and keyboard are too annoying and your other USB ports are occupied

Optional

A large power supply that you will use for all your lights
- If you go this route, you also need to make an power cord, or to cut an extension cord and use it as your power cord
as well as your pi with a buck converter
and maybe even higher voltage lights if needed with a step-up converter

Step 2: Setting Up the Pi 1: Installing Raspbian

The first step is to get raspbian on your device. I will cover all of these in a single block, and cover the hardware separately.

I recommend downloading noobs from the pi foundation https://www.raspberrypi.org/downloads/noobs/

Just unzip, and copy over to your freshly formatted micro SD card. That's it. Once you turn on your pi, it will guide you through the installation.

Step 3: Setting Up the Pi 2: Setup SSH and VNC

Having SSH and VNC setup means you won't need to keep the pi plugged in to a huge mess of wires. Everything will be doable from 2 windows on your laptop or even from your phone. We will often precede our commands with "sudo", this essentially gives our command the administrator privileges.

First change your password. Open a terminal window and type the following and you will be prompted to enter the default password (raspberry) and then put in your own password.
- sudo passwd
now copy your IP address with the following command
- ifconfig

Now go to the settings menu, and turn on the SSH and VNC. You can now reboot the pi and unplug it from the monitor, keyboard, and mouse.

Step 4: Setting Up the Pi 3: Use Bitvise SSH to Access Your Pi

I recommend bitvise because it has an integrated SFTP tool, as well as a good interface. Enter your IP address you copied over earlier, use the username pi, and your new password. Keep the default port (22). The terminal should open when you select login.

Step 5: Setting Up the Pi 4: Update Your Pi

Before you do anything else, run the updates

First, you update the library of what packages are available with
- sudo apt-get update
Once its done running, you actually install the updates with
- sudo apt-get upgrade
For good measure, make sure your pi firmware is up to date (this should already be done through upgrade)
- sudo rpi-update

Step 6: Setting Up the Pi 5: Installing Lightshowpi

This part of the steps is available directly on the lightshowpi website. I will include them for convenience. I will add a few explanations in there.

sudo apt-get install git-core
- apt-get is what gets the packages, and here we will install git-core, dependencies (programs git-core needs to run) will automatically be added
cd ~
- cd is to change directories, while ~ means /home/*username*/, in this case it would be /home/pi/; using that or ~ should work just the same
git clone https://togiles@bitbucket.org/togiles/lightshowpi.git
- That just copied over the folder structure we need
cd lightshowpi
- now we move over to the folder we just downloaded
git fetch && git checkout stable
- now we get the needed files
cd /home/pi/lightshowpi
- we move over to the correct folder; in linux, unless we create system links, we always have to move over to the correct folder before launching scripts
sudo ./install.sh
- this does the actual installation; this took about 3 hours on my pi zero w
sudo reboot
- now we reboot!

Step 7: Wiring Your Stuff

However you end up powering your devices depends on what you are using. There are many options here, but at the end of the day, you will need 5v for your pi, either through a USB, or using the header pins and a custom power solution like I did. All the power you are interrupting should be DC. AC line voltage will work just fine, but it brings along extra risk. Low voltage is far safer.

Step 8: Wiring Your Stuff 2: Soldering the Pins

If you are using a pi zero, you will either have to solder header pins, or solder the wires directly at the pin holes themselves.

Step 9: Wiring Your Stuff 3: Connecting the Pi to the Relay Board

We are using the wiringpi pin numbering. There is an alternative naming convention out there, just use the chart I provided, or go to wiringpi.com

From the relay board, with the pins towards your, from left to right, you will connect to the following on the pi

pin 20: ground
pin 11: GPIO 0
pin 12: GPIO 1
pin 13: GPIO 2
pin 15: GPIO 3
pin 16: GPIO 4
pin 18: GPIO 5
pin 22: GPIO 6
pin 7: GPIO 7
pin 4: 5v power

If you are powering your pi from the header pins, then the +5v will go to pin 2, and the - (ground) will go to pin 6.

Step 10: Wiring Your Stuff 4: Wiring Your Relays

The relays work like a switch. However you would wire your lights directly to your power, do that, but then cut the live wire and put each end of that cut wire on one of the relays. Each relays have 3 terminals. 2 of them are together, and powering the relay separates them, the other one becomes connected to the center terminal when the relay is powered. The little diagram of a corner shape shows you which one is separate (in red). The opposing ends (first and last) of each relay will never be connected. If you want, you can do always-on and use the 2 in the green, it just means the lightshowpi commands will be in reverse. It might be useful if you want the lights to default to on after the music ends.

Step 11: Test It

I used these little LEDs to test my board, but really you can just look at the red light that is on the relay board. Each relay already has its own LED.

Don't forget to navigate to the lightshowpi folder first
- cd /home/pi/lightshowpi/
Then use one of these test commands
- sudo python py/hardware_controller.py --state=flash
- sudo python py/hardware_controller.py --state=fade

To end the test, use CTRL+C

Step 12: Enjoy!

Now it's time to setup your actual christmas lights, and enjoy the show. Don't forget to check out my full video!

To run your first song, use the demo file provided by the lightshowpi devs

sudo python py/synchronized_lights.py --file=/home/pi/lightshowpi/music/sample/ovenrake_deck-the-halls.mp3

To play any other son, just change the name of the mp3 at the end of that command. This is where the sftp feature of bitvise comes in; you can simply click and drag your files.