Apa102-pi is a pure Python library to drive APA102 and SK9822 type LED strands. It is supposed to work on a Raspberry Pi, and is not tested on any other platform.
APA102 LEDs are typically 5050 type LEDs with an additional driver chip per LED. The driver chip takes care of receiving the desired colour via its input lines, and then holding this colour until a new command arrives.
Depending on the LEDs vendor, they might be called "APA102", "SK9822", "Superled", or "DotStar". They must not be confused with the three-wire WS2812 LEDs, also known as "NeoPixel".
The really nice part about the driver chip is this: Once it has received its own colour command, it forwards any further colour commands from its input to its output lines. This allows to easily chain multiple LEDs together. Colour command #1 lights the first LED, command #2 the next LED, and so forth. Sending for example 300 colour commands does light an entire 5 Meter, 60 LEDs per Meter strip.
Some APA102 pictures are available here.
The library takes care of the details on sending colour commands. It is supposed to be educational, and is therefore written in Python. The library is fast enough to produce nice colour effects on a 300 LED strand, even though it is running via the Python interpreter. However, if you need something really fast, e.g. to drive a small "display" based on APA102 LEDs with 15 frames per second, then you have to look elsewhere.
-
A Raspberry Pi, running an up-to-date version of Raspbian / Raspberry Pi OS. To date, Raspberry Pi OS 2020-12-02 is out, and the library works fine with this release. It should run on all Raspberry Pi models, from Zero to 4.
-
If hardware SPI is used: SPI enabled and active (
raspi-config, Interface Options, SPI, <Yes>); The SPI must be free and unused. -
For software SPI (bit bang mode): Two free GPIO pins
-
Three libraries from Adafruit: Adafruit-Blinka, adafruit-circuitpython-bitbangio, and adafruit-circuitpython-busdevice. These libraries will be installed automatically if you follow the steps in [Use the APA102 project as a library].
For a permanent installation, a 10$ Raspberry Pi Zero W can be dedicated to the task of driving the LEDs. The connector to the LED stripe would be soldered directly to the correct ports on the board. For development purposes, a Raspberry Pi 4 Model B is a better choice due to its greater speed. Even the 1GB model is more than enough for this purpose.
The Raspberry Pi is a 3.3 volt device, and the APA102 LEDs are 5 volt devices. Therefore, it is possible that the first LED driver chip does not properly detect the 3.3 volt SPI signal from the Raspberry Pi. The first chip will amplify the signal to 5 volts before passing it on, so it is really only the first chip that must detect the 3.3 volt signal. To avoid this risk, use a 74AHCT125 or 74AHC125 level shifter for both the clock and the MOSI signal. In my limited testing with four different stripes from various Chinese sources I had no issues without a level shifter, but your experience might be different.
Without a level shifter, the wiring is very simple:
-
LED ground to one of the Raspberry ground pins
-
LED Data to Raspberry SPI MOSI
-
LED Clock to Raspberry SPI SCLK
A note about "chip select": The Raspberry Pi’s SPI0 bus has two hardware Chip Select pins: CE0 and CE1.
They correspond to the devices /dev/spidev0.0 and /dev/spidev0.1.
A typical SPI device has one Chip Select input line.
So, on a stock Raspberry Pi one can connect two SPI devices: Both share SCLK, MOSI and MISO, and each one uses its own Chip Select.
You might be wondering where the Chip Select input line is on an LED strip.
Answer: There is none.
You therefore can’t disable the Strip from reading data on SCLK/MOSI, at least not without additional hardware.
For example, you can wire the chip select GPIO of the Raspberry Pi to the level shifter "output-enable" pin.
The Adafruit library does not use or support the hardware chip select pins of the Raspberry Pi. Instead, any free GPIO pin can be used. Because this is multiplexed in software, it is very slow. The feature supports e.g. sensors, where you have a lot of them (more than two), and each sensor only sends or receives a limited amount of data. The apa102-pi library attempts to use this software multiplexing if a CE value is passed on driver initialization. The strip will update a lot slower if this is used. It is still a bit faster than bitbang, though. Please note that I have not tested this feature, because I never assembled the hardware required for this.
The LED strip uses a lot of power (roughly 20mA per LED, i.e. 60mA for one bright white dot). If you try to power the LEDs from the Raspberry Pi 5V output, you will most likely immediately kill the Raspberry! Therefore, I recommend not to connect the power line of the LED with the Raspberry. To be on the safe side, use a separate USB power supply for the Raspberry, and a strong 5V supply for the LEDs. If you use a level shifter, power it from the 5V power supply as well.
Having said this, you can power the Raspberry from the same power supply as the LED stripes (instead of using an extra USB power supply). If you decide to do this, make sure to never plug a USB power supply to the Raspberry Pi, or you risk that the LEDs try to take power through the Raspberry.
All combined, this is my extremely low-tech wiring diagram:
And here it is, the finished contraption running a "rainbow" program:
This is a Raspberry Pi Zero W with a Phat Beat amplifier on top. The amplifier’s "VU meter" is simply a bunch of APA 102 LEDs; They show the "Rainbow" color scheme:
Plugged into the USB port is a WLAN stick (nowadays I use a Raspberry Pi Zero W, of course). This way I can reprogram the light show from my desk, even if the strips sit outside as a Christmas light. Compare this to an Arduino/WS2812 based installation: To reprogram one has to take the Arduino inside, or a laptop outside.