Skip to content
APA102 LED control client and flask webserver
Python HTML
Branch: master
Clone or download
Pull request Compare This branch is 135 commits ahead, 43 commits behind tinue:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Hi! If you're at my HOPE workshop, Here are your setup instructions

Screenshot of LED control Server

This library should let you create a web-controlled APA102 LED strip, with logic in python, run on a Raspberry Pi.

It's written entirely in python and designed to be easily modifiable. Please feel free to clone, fork, or contribute

This was demo'd at PyCon at the talk "Visualizing Algorithms with Python and Programmable LEDs"

Here are the slides from that talk:

Here is the video (youtube) Unfortunately the cropping means you can't seem the schemes in action. I will try to correct this soon.


All of the light patterns are called Schemes. I've described a few below


This is a gentle, calming rainbow pattern that visualizes the output of a Perlin random number generator. This is like a random number generator that is moody, where each value is random overall, but correlated to the values around it. A great pattern.


This pattern is bright during the day, but slowly dims and reddens as the night goes on. The intention is to create lighting that won't cause you to stay up late by cutting out blue light at night. It's inspired by the desktop program 'f.lux' that does the same thing. In the morning, this scheme has an artifical sunrise, and then turns green shortly after as a signal to start the day.


This is the Perlin scheme, but it is filtered through Flux, so it reddens as the night goes on, has a sunrise, etc. This is a good scheme for permanent room lighting.


This is a visualization of real time San Francisco Bus Position. However, it wasn't as cool as it sounds because buses turn out to be quite slow.


This Scheme is designed for meditation. It slowly pulses at the rate of a very slow breath, so you can match your breath to it and calm down. It also slowly dims from one side, like a candle burning down, to mark the passage of time

Distribution / Beta / Sort

These are visualizations of various algorithms. Distribution shows a demo of sampling from various kinds of distributions. Beta shows training of a beta distribution, and the Sort scheme shows several different Computer Science sorting algorithms. Sort is really cool


It's a big party

AgentScheme / RTS

Some attempts I made to make a game-like scheme with independent entities that interacted with eachother. Incomplete

Fullscan / OneOneOne / HueTest / Gamma Correction Demo

These exist for debugging/dev purposes.


This exists to teach people how to edit their own scheme. Start editing here


This is designed to be run on a raspberry pi, but it may be possible to run it on other similar boards. Any kind of raspberry pi should do, though the pinout changes based on board.

I'm teaching a workshop on how to build one of these at Hackers on Planet Earth on July 20. Here's the setup instructions for that event - they're probably generally applicable HOPE Workshop Setup


To install, I believe you can use pip. I clone and then do pip install -d . This library is not distributed on pip yet, so you must clone it first.

You may encounter an issue with the spidev library if you are installing on a Mac/not a pi. That's the hardware interface library and it is not available for platforms without SPI headers. You can comment it out of the if you want to install there. There's a debug mode that makes programming light patterns away from hardware possible. EDIT: I believe I have fixed the spidev issue in by making it only install on the correct architecture. Let me know if you run into issues


The meat of this is in the client executable. That is the program that actually controls the LEDs, and is designed to be run on the Pi. It can be used in conjunction with a server, or as a standalone CLI script.

python liteup/ sorts

There are many useful and cool themes that I've written, and I've tried to make it easy to add more.


There's a server component, which gives you a webpage that can control the LED pattern. That can be hosted on any website, and even the pi itself. You can configure the client to look for commands from any web address, but it will default to localhost.

python liteup/server/

This library expects python 3.6 or above. I used berryconda to install 3.6 on the raspberry pi.

Please open an issue if you encounter any problems while installing. This is a process that I want to make smoother.


This uses APA102 strips, which can be purchased from a variety of places. I recommend Amazon, Aliexpress and Adafruit, in that order.

Once you have your strip, and your pi, I recommend setting it up like in this diagram. Here's a diagram of how I recommend setting it up: Circuit Diagram

Tinue's APA102_Pi readme has some good tips on how to configure a raspberry pi to be headless, and more information on wiring in case you get stuck. I have followed that pretty much exactly, with the exception that I did not use a level shifter chip, I feed the data and clock directly from the Pi into the strip. This has not given me a problem to date.

Run on Boot

I have included two systemd service files that I use to run my lights on boot in the raspberry pi. Right now, you need to place those manually (and you may need to edit them to include your local python locations and clone locations). If you do that, you should get the server and the client to run on boot


Each light pattern is called a Scheme, and is a python class that inherits from schemes/ There's an init function that is called once to set it up, and then a paint function that is called over and over again to generate the led strips patterns. If paint returns True, the strip will be redrawn. Modify/call functions on self.strip within a Scheme class to generate the pattern.

I recommend reading first, and then copying those to make your first schemes. Schemes can get quite complicated and include any arbitrary python including API calls, but that's a good starting place to see the interface. There are lots of helper methods in /lib/ and that can help you do things like convert between colorspaces, gamma correct, paint a uniform color, etc.

If you are trying to write a new scheme, I recommend to do it on the raspberry pi itself to iterate faster. I have had a lot of luck with mounting the raspberry pi locally with 'sshfs' and editing with my IDE on the local files, which is then mirrored to the pi.

Future Development

This project is at a nice place now, and I use it for daily room lighting, but I would like to improve it. Ideally, each scheme would be able to define any options that it wants, and have the server present those options to the user to control the details of the scheme. The bones of this are in place, but it should be fleshed out. I would also like to make some longer running schemes with emergent behavior.


At PyCon 2018, I was introduced to CircuitPython, which is an awesome project that allows you to run python directly on microcontrollers. I ported two of the schemes (perlin and sorts) to circuitpython. I have it running on a Gemma with a ring of 16 NeoPixels (ws2812), but it should be easy to extend that to other circuitpython chips.

You can find that in the circuitpy folder

Thanks Tinue

Liteup contains a a fork of the great APA102_Pi library by tinue.

It contains a lot of code from APA102_Pi, but also a significant number of more themes, as well as a server and client for web-control, and extensions from APA102_Pi.

You can’t perform that action at this time.