Last post, I discussed using the APA102 LED strip with the raspberry pi. You can create very cool effects with it, but doing so requires quite a bit of code, so I created a library with some basic utility functions and animations for the APA102 LED driver, and I’ll be expanding it in the future as I need more animations for my arcade cabinet. In this post I’ll cover the basics of this library.

API Docs

First off, the most important thing, the API docs. The library is fully documented, and the documentation can be found on libapa102.dirkwillem.nl

Hello, libapa102

To get started, download libapa102 from GitHub and build it. Building projects using this library require wiringPi and the POSIX Threads library (this library is already on your Pi). Also, your program requires root permissions in order to access the GPIO. In the first example, we’ll initialize the LED strip and fill it with a red color using the APA102_Fill function.

#include <apa102.h>

int main() {
  struct APA102* strip = APA102_Init(60);
  APA102_Fill(strip, APA102_CreateFrame(31, 0xFF, 0x00, 0x00));
  return 0;
}

Note that libapa102 uses a struct for LEDs, named APA102_Frame. These contain the brightness and color information on the LED. Also, the library provides a handy function to obtain a APA102_Frame*; APA102_CreateFrame.

If we wanted to, we could also address each LED one by one, using the APA102_WriteLED:

#include <apa102.h>

int main() {
  struct APA102* strip = APA102_Init(60);
  APA102_Begin();
  int i;
  for(i = 0; i < 60; i++) {
    APA102_WriteLED(strip, APA102_CreateFrame(31, 0xFF, 0xFF, 0x00));
  }
  APA102_End();
  return 0;
}

Stripes

Also, we can create so called ‘stripes’ (neighbouring LEDS that are lit, separated by unlit LEDs), whith the APA102_Stripes function. It requires a color, a stripe size (the number of neighouring LEDs that should be lit), and a gap size (the number of neighbouring LEDs that should be unlit). For example:

#include <apa102.h>

int main() {
  struct APA102* strip = APA102_Init(60);
  APA102_Stripes(strip, APA102_CreateFrame(31, 0x00, 0xFF, 0x00), 6, 2, 0);
  return 0;
}

Also, these stripes can have multiple colors in a pattern if we specify an null-terminated array of APA102_Frames using the APA102_MultiStripes function:

#include <apa102.h>

int main() {
  //Initialize strip
  struct APA102* strip = APA102_Init(60);

  //Create the colors array (must be NULL-terminated)
  struct APA102_Frame* colors[5];

  colors[0] = APA102_CreateFrame(31, 0xFF, 0x0, 0x0);
  colors[1] = APA102_CreateFrame(31, 0xFF, 0xFF, 0x0);
  colors[2] = APA102_CreateFrame(31, 0x00, 0xFF, 0x0);
  colors[3] = APA102_CreateFrame(31, 0x00, 0xFF, 0xFF);
  colors[4] = 0;

  //Fill strip
  APA102_MultiStripes(strip, colors, 4, 2, 0, 0);
}

Animations

libapa102 includes functionality for ‘animating’ your LED strip. These animations run in a separate thread, so they won’t halt your main program thread. As of now, there are four animations: blink, pulse, stripes and multistripes. Animations return an APA102_Animation object, which can then be used to kill the animation with the APA102_KillAnimation function. For example, one could use the multistripes animation as follows:

#include <apa102.h>
#include <wiringPi.h>

int main() {
  //Initialize strip
  struct APA102* strip = APA102_Init(60);

  //Create the colors array (must be NULL-terminated)
  struct APA102_Frame* colors[5];

  colors[0] = APA102_CreateFrame(31, 0xFF, 0x0, 0x0);
  colors[1] = APA102_CreateFrame(31, 0xFF, 0xFF, 0x0);
  colors[2] = APA102_CreateFrame(31, 0x00, 0xFF, 0x0);
  colors[3] = APA102_CreateFrame(31, 0x00, 0xFF, 0xFF);
  colors[4] = 0;

  //Run animation
  struct APA102_Animation* anim = APA102_MultiStripesAnimation(strip, colors, 50, 4, 2, -1);
  delay(5000);
  APA102_KillAnimation(anim);
}