ECE497 Project Christmas Light Controller

Team members: Josh Woods and Ricky Rung

Grading Template
I'm using the following template to grade. Each slot is 10 points. 0 = Missing, 5=OK, 10=Wow!

 10 Executive Summary 10 Installation Instructions 10 User Instructions 10 Highlights 10 Theory of Operation 10 Work Breakdown 10 Future Work 10 Conclusions 10 Demo 10 Not Late Comments: This is a real slick setup. Well done. I look forward to seeing it from my office.

Score: 100/100

Executive Summary


Click for Video Our project is to create a user interface to control 320 LED lights on a 10 meter LED strip. The LED strip will then be put on the ECE Department’s tree during the holiday season.

The interface will be online, and will allow anyone to write code to control the lights on the tree. Users will also be able to select patterns that others have programmed, if they don’t want to write their own.

Submitted programs will each run for a specified length of time. A queue will be used, so if multiple people write programs at once, each program will get a chance to run. When one program’s run time expires, the next program will run, until the queue is empty. If no programs are waiting to run, the last run program will continue indefinitely.

There will also be a speaker near the tree which will play holiday music, selected through the online interface. A separate “music queue” will be used to store songs to play. Users will be able to select from a list of songs to add music to the queue.

This will be a fun and exciting holiday feature for the ECE department.

Needed Hardware
In addition to a BeagleBone, you will need:


 * Adafruit's LPD8806 LED String
 * Sold by the meter. Need to order 5 meters for a roll.  Our project uses two rolls, for a total of 10 meters.  The code can be easily adapted for more or less lights as needed.
 * 5V Power Supply
 * The LEDs use a lot of power. We used a 5V, 5A power supply to power our 10 meters, but we needed more power to have all the LEDs on full brightness.  Adafruit sells a 5V, 10A supply, linked above, that they recommend to power the LEDs.
 * USB Audio Dongle
 * Necessary if you want to use the BeagleBone to play holiday music. Connects to the USB port of the BeagleBone and has a 3.5mm audio output.
 * Speaker
 * Must be connected to the output of the USB Audio Dongle to play music for everyone to hear. Headphones can be used instead for testing.

Software Setup
git clone https://github.com/gfrung4/ECTree.git cd ECTree ./install.sh ./setup.sh
 * Clone the repository to your BeagleBone.
 * Run the install.sh script in the repository. This needs to be run only once, but might take a while.
 * Run the setup.sh script in the repository. This needs to be run every time you start up your BeagleBone.

Hardware Setup

 * Connect the 5V power supply to the VCC and ground pins of the LED strip.
 * Connect the CLK pin of LED strip to P9_22 of your BeagleBone.
 * Connect the DI pin of the LED strip to the P9_18 pin of your BeagleBone.
 * Connect the ground of the power supply to the ground of your BeagleBone.
 * Plug the audio dongle into the USB port on your BeagleBone, and connect a speaker or headphones to the audio output of the dongle.

Running
./web.js
 * Run the server script, web.js.

Troubleshooting
-bash: ./web.js: Permission denied This can be resolved by giving the owner of the file execute permissions, using this command: chmod 744 web.js Then try running it again and it will work! ./web.js events.js:85 throw er; // Unhandled 'error' event ^ Error: listen EADDRINUSE at exports._errnoException (util.js:746:11) at Server._listen2 (net.js:1158:14) at listen (net.js:1184:10) at Server.listen (net.js:1269:5) at Object. (/root/ECTree/web.js:237:6) at Module._compile (module.js:460:26) at Object.Module._extensions..js (module.js:478:10) at Module.load (module.js:355:32) at Function.Module._load (module.js:310:12) at Function.Module.runMain (module.js:501:10) If you get this error, it means bonescript is running automatically on your BeagleBone, and is using port 80. To resolve this conflict, you can either change the port that ECTree runs on or stop bonescript. To stop bonescript, just run these two commands. Don't worry! This won't be permanent. It will only be stopped until the BeagleBone restarts. This does mean, however, that you'll need to run these commands each time you start your BeagleBone. systemctl stop bonescript.socket systemctl disable bonescript.socket If you'd rather not stop bonescript, you can also change the port ECTree runs on. Open web.js in your favorite text editor and find this section: http.listen(80, function {    console.log('The server has started.'); }); Change 80 to some other port number that is not used for something else on your BeagleBone. The disadvantage of this is that you'll have to include that port number when accessing the web interface, so instead of http://ip, you'll have to go to http://ip:port. If you don't want to have to include a port like this, do the disable bonescript steps above instead.
 * You may not have permissions to execute the web.js after cloning the repository. If not, you'll get this error:
 * You may get an error when running web.js if something else is using port 80. This error looks like this:

Once you've disabled bonescript or changed the port, try running again and the error will be gone. ./web.js

User Instructions

 * Once the web.js server is running on the BeagleBone, you can access the web interface by pointing your browser to your BeagleBone's IP address. If your BeagleBone is connected to your computer via USB, that IP address is 192.168.7.2, so open your favorite web browser, type 192.168.7.2 into the address bar, and press enter.
 * Once there, you should see the interface:
 * You can click Write Program to begin writing code.
 * If you need help getting started, click the Learn button in the navigation at the top of the page. This will take you to the tutorial.
 * After completing the tutorial, you will be able to see your lights in action! You can then write more programs from the main page, now that you know how to do it!  Enjoy the light show!

Highlights

 * Thanks to the Bootstrap framework, our user interface will work on any browser including smartphones. This makes it easier for people passing by to change the lights!  It's difficult to write programs on a smartphone, but previously written programs can be easily selected, and music can be added to the queue as well.
 * While our project allows any user to write code to control the lights, the code actually runs in the user's browser and the result is sent to the BeagleBone in the form of a list of "frames". This keeps our BeagleBone safe.  Running arbitrary code submitted by users on the BeagleBone itself would be a major security flaw.  Anyone could just write an infinite loop and crash the program!  Or worse, they could write code that called commands to delete everything on the BeagleBone or take control of it for malicious uses.
 * All light display patterns made by the users are saved for future use. Although the interface only displays the most recent 10 patterns, it would be easy to modify to support searching through all past patterns.  This gives people who don't want to code a variety of fun programs to run.
 * The code is written in a way that allows more audio files to be easily added to expand the list of holiday music the BeagleBone can play.

Theory of Operation

 * 1) A server listens on port 80 for users to connect.
 * 2) When a user connects, they are sent the main page.
 * 3) Scripts on the main page request the light and music queues, which are displayed to the user.
 * 4) The server sends an update whenever the queue changes, which causes the interface to update showing the new queue.
 * 5) The user can send three different packets to control the lights and music:
 * 6) New Program : Contains a JavaScript object (in JSON format) that represents the program the user just wrote.  The server saves the program for future use, and also adds it to the queue.
 * 7) Choose Program : Contains a single number, the program index, of the program that the user wants to play.  This is used when the user wants to play a program that someone else already wrote, rather than write their own.  The program is added to the queue.
 * 8) Add Music : Contains a single number, the music index, of the song the user wants to play.  The song is added to the queue.

Work Breakdown

 * Getting hardware SPI on the BeagleBone working to control the lights.
 * George


 * Writing server-side code.
 * Josh & George


 * Writing user interface.
 * Josh & George


 * Writing server side queue code to play light programs and audio one at a time
 * Josh


 * Writing interface code to display the queue to the user in a table
 * George


 * Getting the BeagleBone to work with the USB Audio Dongle to play audio
 * Josh

Future Work

 * Making the lights "dance" to the beat of the music.
 * More previously submitted programs. The interface currently only shows the past 10 programs, which means any programs prior to this can't be run anymore!  We'd like to expand it to show all the programs, but this would require "pages" of programs or a search feature, as there would eventually be too many to show at one time.
 * Program GIF preview on the interface. We had experimented with having the BeagleBone generate a GIF preview of each submitted program so that future users could see what the programs looked like before playing them on the tree.  Sometimes the names alone weren't descriptive enough to figure out what the programs did.  We were unable to get this working in time.
 * Administration interface. Since anyone can submit a program (and name it), there is the potential for unwanted programs or inappropriate names being submitted.  Right now, there is no way to remove these programs or change their names, and no way to block the users that submit them.  A simple hidden administration page that allows programs to be deleted is required before this is used on a larger scale.  The ability to block specific IP addresses, or limit submissions to a certain IP range (campus only, for example) would be nice as well.  This will be added before the lights are used on the real tree and opened to the entire department (and campus).
 * More user input validation. There were two exploits that were unpatched:
 * Submitting an empty program (typing no code) would cause the server to crash on the BeagleBone, requiring it to be manually restarted.
 * Using very short delays (~1 millisecond) would cause the SPI buffer to fill up, resulting in future programs not getting executed because the buffer is still finishing the previous program.
 * These could be resolved by blocking invalid programs (empty programs or programs with delays that are too short). This change will be made before the lights are used on the real tree and opened to the entire department (and campus) to avoid issues.

Josh
I really enjoyed working on this project because I got to learn and explore some of the aspects of web programming. It will be nice to come back to campus after fall break and see the project in use and see how much action the lights will be getting.

Ricky
This project was a lot of fun to work on. I intend to continue working on it over the next week or so (and maybe even over Thanksgiving break) to make sure it's ready to go on the department's tree. I hope that people participate in making programs for the lights. If we can get people interested in it, I think it'll be a great success!