APA102 LEDs - pixelmatix/SmartMatrix GitHub Wiki

SmartLED Shield can drive APA102-compatible LEDs in addition to HUB75 panels. See the FastLed_Panel_Plus_Apa102 example for details on driving APA102 LEDs with SmartMatrix Library, on their own, or in parallel with a HUB75 panel.

The ESP32 port currently doesn't support driving APA102 LEDs.

APA102-compatible LEDs have a per-LED Global Brightness Control (GBC) setting that controls the overall brightness of the Red, Green, and Blue channels in addition to per-color RGB control. The 5-bit GBC value can be used as a way to approximate 13-bit color (5 bits GBC + 8 bits per color channel) to get higher depth color out of the LEDs when used at high brightness, and to avoid loss of color depth when used at low brightness. SmartMatrix Library expands the color depth using GBC by default, but the GBC mode can be changed or disabled.

There are many types of APA102-compatible LEDs available, most seem to be clones of each other with different names. These LEDs have been tested with SmartMatrix Library. Please let us know, or feel free to edit the wiki add add your results if you test a new type or have different results

  • APA102
    • More information on APA102 LEDs here and here
    • GBC has a low PWM rate, with visible flickering in a slow motion or moving phone camera with GBC < 100%
    • Minimal stepping when used with SM_APA102_OPTIONS_GBC_MODE_DEFAULT
  • SK9822
    • More information on SK9822 LEDs here
    • GBC uses current control and not PWM, and doesn't show flickering on camera
    • Minor visible stepping when used with SM_APA102_OPTIONS_GBC_MODE_DEFAULT to fade between single low brightness colors. In practice when displaying a typical pattern, the stepping isn't visible.

SmartMatrix Library can drive LEDs in a serpentine matrix pattern (where every row reverses direction), or a single strip of LEDs. There's work on a solution for mapping tiled smaller panels or arbitrarily mapped LEDs being discussed on SmartMatrix Community[https://community.pixelmatix.com/t/apa102-large-matrix-of-multiple-8x8-panels/819/].

The default clock frequency is 5MHz, a value that is supported by most lengths of LEDs. APA102-compatible LEDs claim to support high frequencies, but high frequencies will fail at longer lengths. See the FastLed_Panel_Plus_Apa102 example for details on how to change the frequency.

APA102 Controller Options

SM_APA102_OPTIONS_NONE - This is the default option, GBC is set to SM_APA102_OPTIONS_GBC_MODE_DEFAULT, and RGB order is set to SM_APA102_OPTIONS_COLOR_ORDER_BGR

Set multiple options like this:

const uint32_t kApaMatrixOptions = (SM_APA102_OPTIONS_GBC_MODE_NONE | SM_APA102_OPTIONS_COLOR_ORDER_RGB);

GBC Modes

These modes set how the GBC bits are used to expand the color depth beyond 24-bits

  • SM_APA102_OPTIONS_GBC_MODE_DEFAULT
    • The default mode uses GBC in the most compatible - but not the most efficient - way to expand the color depth
  • SM_APA102_OPTIONS_GBC_MODE_SIMPLE
    • Simple mode assumes the LEDs are behaving ideally and that the GBC brightness maps linearly with the color PWM brightness so more efficient math can be used. In practice you'll likely see stepping when fading between two colors in this mode as these LEDs don't behave ideally
  • SM_APA102_OPTIONS_GBC_MODE_BRIGHTONLY
    • This mode only uses GBC to set the overall brightness, and doesn't try to expand the color depth of the LEDs. In this mode the brightness you set with matrix.setBrightness() is applied to the GBC bits.
  • SM_APA102_OPTIONS_GBC_MODE_NONE
    • This mode disables GBC, it's always set to 100% so there's no low PWM artifacts, and the LEDs just use 24-bit color

RGB Order

LEDs sometimes come with unexpected color order inside the LED frame (data sent out to the LEDs). The default is SM_APA102_OPTIONS_COLOR_ORDER_BRG based on what's listed in the APA102 and SK9822 datasheets, but some suppliers don't follow the datasheet.

  • SM_APA102_OPTIONS_COLOR_ORDER_BGR
  • SM_APA102_OPTIONS_COLOR_ORDER_RBG
  • SM_APA102_OPTIONS_COLOR_ORDER_GRB
  • SM_APA102_OPTIONS_COLOR_ORDER_GBR
  • SM_APA102_OPTIONS_COLOR_ORDER_RGB
  • SM_APA102_OPTIONS_COLOR_ORDER_BRG