SmartMatrix APA102 Library / Open Hardware Photon APA102 Shield


I’ve made a first sketch to see if I could match GBC with the normal RGB values.

What happens is that the SK9822 seems to change the hue a bit. The green pixel with GBC seems more lime then without GBC. This make it impossible to match, or I have some strange bug.

Maybe this happens because power is different (because of the addition PWM).

Any suggestions or idea’s are welcome.


Kasper, you might want to try what Tim tried here, and hook up the power rails to a scope. Try changing the global brightness with a LED set to (255,255,255) and see what it looks like on a scope. I haven’t tried your code yet.


@kasper I just tried for an hour to reproduce Tim’s APA102 experimental setup, and couldn’t get anything to show up on my scope that looked like PWM. I thought I was missing a part of the setup or was using my scope improperly, but if I substitute an APA102 LED I see the GBC PWM in my scope. I’m guessing the SK9822 is using a much higher PWM frequency for GBC, so at least with my 50MHz Rigol scope, and cheap probes, I’m not going to be able to get anything out of it. (I used a 10ohm LED in series with the power line to get a good voltage drop between LED off and on, at least with the APA102)

I’ll try match colors by eyeball later, but I’m not sure how successful that will be. My next idea for figuring out the GBC PWM method with measurements is to use a color sensor. Here’s a blog post with a similar setup. I can’t find the sensor breakout board, but maybe something like this could work (if the white LED was disabled).


I think I don’t have the skills either to work with a scope. In my opinion using GBC on the SK9822 causes a hue shift instead of brightness. I tried a lot of values, but I couldn’t get a visual match.


It’s worth mentioning that the SK9822 also requires a different “end frame” than the APA102. I sent a SK9822 panel I was testing to Daniel Garcia (FastLED author) once I realized my menus were displaying “one frame behind” the one that was sent to He ascertained that the end frame for SK9822 needs to be all zeros in order to force the LEDs to latch & show their data. The end frame for APA102 is 32 ones, whereas the start frame is 32 zeros – hence the one frame behind behavior.

As for the GBC support, I’m told by a friend who develops commercial APA102-based lighting solutions that it is totally broken in the SK9822. Scary stuff that it is being marketed as completely APA102-compatible.


Thanks for the feedback. I’ll try the different end frame, however it think this doesn’t matter. I’m comparing pixels within the SK9822 strip, so they would have all a delay then.

I’ve read somewhere (couldn’t find where) that the GBC is totally broken. My first impression confirms that. If you have more info about what is exactly broken or what the experiences of your friend are please let us know.


Hmm, I’m not sure about that.
The end frame for APA102 can be zeros too - AFAIK that’s also preferable since all 1 would make any non-set LEDs go all white, while all 0 would just be interpreted as (dummy) start frame till the first high bit is seen.
But actually it’s not fix 32bit but should be something like LEDCOUNT/2 +1 bits to ensure enough clock cycles to shift all the data through, since you lose 1/2 clock per LED on the strips.
So 32bit works for strips up to 64 LEDs, but beyond the strip will show inconsistent frame numbers.

A more elaborate discussion about this can be found here


You’re right, @ScruffR… you need LEDCOUNT/2 + 1. It has been too long since i reviewed that site. But as for the end frame, the fact is the two chips are not 1:1 compatible. “Ones” work for the APA102 but not for the SK9822, and the site you linked suggests using ones is acceptable. This is why FastLED added a new class for the SK9822.

I have not seen the effect of non-set frames going all white, but perhaps that’s because I’ve always relied on libraries.

@kasper I’ll ask my friend to chime in here about GBC.


Hi - I’m the friend who has used APA102s (and tried to use SK9822s) in several large installations. As far as I can tell, the GBC on the SK9822 seems to not only effect the brightness, but it also influences the color output. In other words, if you display a “bright green” color (RGB:20,240,70) and ramp the GBC from 0x0 to 0x1f, the perceived color shifts quite drastically. The APA102s don’t do this.


@zachr Thanks for chiming in. Good to hear another confirmation of the color shift.


I added initial SK9822 support to the SmartMatrix Library, it’s on GitHub now. You need to edit SmartMatrix_Impl.h and change #define LEDTYPE at the top. Later I’ll make it able to select the LED type from the sketch using template parameters.

APA102 LEDs don’t follow their datasheet, and appear to use /32 math for GBC instead of /31. I didn’t verify that with a scope, but using /32 math got rid of the stepping. /31 math makes no sense on an embedded platform, it should be a power of two. The SK9822 engineers must have wanted to follow the APA102 datasheet to the letter, and used /31 math for GBC. I have GBC working without stepping, but the unoptimized code uses four division operations per pixel, where with the APA102 you could just use bitwise math and shifts which are much more efficient.

The SmartMatrix Library code isn’t easy to follow because it combines the overall matrix brightness value with the RGB pixel scaling calculation, I’ll have to add comments explaining the math later. This code should be easy to use in a non-SmartMatrix project (though it still doesn’t have comments):

        uint16_t maxrgb = max(max(led16bit_r, led16bit_g), led16bit_b);
        value = maxrgb * 0x10000 / 31;

        // load pixels with 8-bit color plus 5-bit global brightness
        src[spilength++] = 0xE0 | (value + 1);                //  Pixel start with global brightness
        src[spilength++] = ((led16bit_b * 31) / (value + 1)) >> 8;
        src[spilength++] = ((led16bit_g * 31) / (value + 1)) >> 8;
        src[spilength++] = ((led16bit_r * 31) / (value + 1)) >> 8;

I’m not seeing the hue shift with the SK9822s. I didn’t directly trying ramping the GBC from 0x0 to 0x1f, but ran this code with the SmartMatrix Library using 48-bit math, and it should have taken care of changing the GBC in the background:

  buffer = backgroundLayer.backBuffer();
  for(int i=0; i<64; i++) {
    buffer[i] = rgb48(20*4*i,240*4*i,70*4*i);

I get this on an 8x8 matrix diffused with a sheet of paper. It’s admittedly not a great photo, but I don’t see any dramatic hue shifts.

Here’s a SK9822 and APA102 side by side running the same sketch.

And here’s a slow motion video recording (iPhone 6) of the two with the lower speed PWM on the APA102s showing. The whole frame flickering is because I was shining a fluorescent lamp above the diffuser.


I’m trying out iPixel as a distributor and they have just a few (at this point there are probably only 3 left) SmartMatrix APA Shields for sale in their Aliexpress store:

iPixel makes LED strips and matrices and Adafruit and SparkFun are some of their customers. I haven’t fully evaluated the LED samples I ordered from them but I was happy with the packaging (better than most Chinese companies). The LED strip/matrix pinout unfortunately doesn’t match the SmartMatrix APA Shield (or the pictures on their site), but that should be easy enough to fix with a knife or resoldering the wires. Eventually I’d like iPixel to carry strips and matrices with pinout and colors matching the SmartMatrix APA Shield cable, and to price their shipping so you get a discount if you order a shield and LEDs at the same time, but we’re not there yet.

If you want a SmartMatrix APA Shield in the next month or so, I suggest ordering ASAP as I only gave iPixel a few of these and there are only a few days left until shipping companies shut down for Chinese New Year. I won’t be able to make more available for sale until after Chinese New Year.


The iColor LED store claims to have 9998 devices left :wink:
Have they made a “blind batch” for their own pockets :sunglasses:?


Haha, very unlikely but I guess it’s possible in China. More likely they just put the max number (10000) in for qty available so they could be lazy with inventory management. Add 5-10000 to the number if you want to see how many are likely left.


Tim posted an analyses of the SK9822 in his blog. He found that GBC controls the current instead of PWM (like the APA102).


Just an FYI to anyone interested in the APA102 Shield: I’m working on an updated version of the SmartMatrix Shield for Teensy, and that took priority as I ran out of stock of the Teensy shield. The Photon APA102 shield is my next priority. I’m not officially releasing it until I finalize the library and make sure it’s compatible with Particle Libraries 2.0.

iColor LED sold out of the 5x shields I sent them, and they should have another 10x in stock shortly. I’m not convinced the “APA102” products I ordered from them are actually APA102 and not SK9822, so be cautious if you order from them. Here’s the link again:

I may have gone a little overboard with the test fixture for this shield. I designed a reusable Arduino shield and firmware to do the testing (adds 64 GPIO at 3.3-5V and 64 ADC pins to an Arduino). For hardware customization, a very simple application-specific board sits on top of the testing shield and switches a few mosfets needed to test the power supply portion of the APA shield. For firmware customization, the test vectors are all set using a spreadsheet and fed into the Arduino app as a header file. (end result: you can customize the test fixture for another board without serious board layout or writing firmware) For the mechanical fixture, I worked with a vendor in China that sells a generic test fixture, and I had some of the parts customized. I sent instructions to two vendors, and it was assembled in China and they used it for testing without me needing to be there. I plan to reuse this system for my projects and clients’ projects and hopefully release parts of it as open source in the future.


For anyone ordering APA102 strips or panels to go along with the SmartMatrix Shield, I made a diagram of cable pinout that you could send to the vendor.

Download PDF Version

If you place an order, please specify to use this cable pinout, and to use APA102 LEDs not SK9822 LEDs for best compatibility with SmartMatrix. YMMV if they actually follow your instructions, it’s at least worth a shot.


how about APA107? can you test APA107 as a substitution for the APA102?


APA107 are supposed to be a drop-in substitute for the APA102 series.


yes, it shoud be…but I saw the datasheet, seems good choice…