Specs and Quick Notes - AlbertGBarber/PixelSpork GitHub Wiki

Below I'll list various specs, limits, and quick notes for Pixel Spork. Use these as a quick reference.

Jump to:

Library Basics:

  • Pixel Spork is an Arduino library for controlling addressable LED's such as the popular WS2812 series.

  • Pixel Spork is programmed using the Arduino IDE, you can install Pixel Spork using the IDE's library manager by searching for "Pixel Spork".

  • Pixel Spork is based on the FastLED library. It uses the library to write to the LEDs. Pixel Spork does not over-write or block any FastLED functions, so you are free to use FastLED alongside Pixel Spork.

  • Pixel Spork uses FastLED's CRGB colors, but has its own palettes.

  • While Pixel Spork inherits all of the benefits of FastLED, it also inherits its limitations, see here, here, and here for FastLEDs notes on known issues.

  • Pixel Spork runs as a companion to FastLED; you are free to use native FastLED code an functions alongside Pixel Spork. This also should extend to other FastLED-based libraries, although you'll have to double check that the library doesn't block/modify any FastLED functions.

  • For a list of all global variables and class names, see the "keywords.txt" file in the code.

Installation:

Compatibility:

  • Micro-controllers:

    • Should support the same micro-controllers as FastLED, listed here, this includes most common Arduinos, Teensy's, ESP8266 boards, and ESP32 boards (but with mixed support for some of the newer variants, check Google or the FastLED sub-reddit). The only exception is the ATtiny family of chips, which don't have enough memory to support Pixel Spork.

    • I heavily recommend using a 32-bit micro-controller over a basic 8-bit Arduino. Not only do 32-bit boards generally have a lot more memory, but they are often multiple magnitudes faster. Pixel Spork can be a heavy duty library, especially when using a lot of LEDs and/or effects. You'll quickly run into limits with a basic Arduino. I recommend a Wemos D1 Mini as a starter 32-bit board.

  • Supported Addressable LED Chipsets:

    • Should support all the same chipsets as FastLED, listed here.

Note: when compiling using the Arduino IDE, if you have your "compiler warnings" (found in "preferences") set to "More" or "All" you may get a few warnings when you first compile a sketch. These should mainly concern the possible non-usage of various static variables, and are expected. They will not prevent the code from running!

Performance:

  • In terms of performance, you mainly want your code to update faster than your effects need. In other words, your code can draw a "frame" before its meant to be drawing the next one.

  • I confess that I've not done a lot of performance testing. That doesn't mean that the library runs slow, just that I've not focused on tracking frame rates, preferring to judge the outputs by eye.

  • For me, a 60-80ms update rate tends to look good with most effects. When using an ESP8266, you can comfortably go to ~1000 or so WS2812 LEDs before you may start to run into slow downs (depending on how complex your effects, code, and Segment Sets are). This is includes running all your LEDS from a single pin, taking up ~30ms just to update the LEDs. Note that Pixel Spork should support parallel outputs to reduce this overhead.

  • Pixel Spork's resource consumption largely scales with how complex your program is and how many LEDs you're using. For example, a program with only a few LEDs, a 1D Segment Set, and a simple effect is always going to need less to run than a program with lots of LEDs, a Segment Set with lots of segments or sections, etc.

    • Segment Sets will become more resource heavy as you add more Segments and Sections because the program has to do more work to find the physical address of each LED. Basically, the more complex a Segment Set is, the bigger the performance demand.

    • Effects can vary a lot in complexity, and it can be hard to tell how much is going on behind the scenes just by observing the effect. A general rule of thumb is that the more LEDs an effect changes during an update, the more work the effect is doing. Note that some effect settings, such as "fillBg", which forces the effect to always re-fill all the LEDs, can also cause a performance hit.

    • "Fast" effects are generally more lightweight than their "non-fast" counterparts, but also come with more restrictions.

    • Effects and Segment Sets can also require large amounts of memory (both RAM and Flash). You'll get a report of your Flash/Ram usage during compile, but some effects require additional dynamic RAM memory. An effect's wiki page will note if uses dynamic memory and what for. You can read about memory management here.

  • As I explained in the previous section, I highly recommend using Pixel Spork with a 32-bit micro-controller such as an ESP8266 or 32. For a basic 8-bit Arduino you may struggle to go over 100 LEDs, and you'll probably only be able to fit a few effects into your code.

Pixel Spork Classes and More:

Segments Sets, Segments, and Sections:

  • Segment Basics wiki page.

  • Segment Sets allow you to virtually arrange your LEDs into 1 and 2D shapes.

  • Segment sets are composed of an array of segments, who are, in turn composed of an array of sections. Sections contain the addresses of a group of LEDs.

  • Any Segment Set with more than one segment is "2D".

  • Segment Sets can have 65,534 segments, however, the maximum total number of LEDs you can have in a set is 65,534.

  • Segments can have 256 sections. The maximum total number of LEDs you can have in a single section is 65,534.

  • Sections come in two types, continuous or mixed:

    • Mixed sections have a minimum length of 0, and a maximum of 32,768 LEDs.

    • Continuous sections have a minimum length of -32,768, and a maximum of 32,768 LEDs (negative length are used to represent reversed sets of LEDs).

  • While the individual size limits of Segment Sets, Segments, and Sections, are quite large, when combined, this limit is reduced because of their 2D aspects. Overall you must keep the ( "number of Segments in your Set" X "The number of LEDs in the longest Segment" ) less than 65,534. This amounts to a 256 x 256 matrix as a maximum size. However, note that I never intended for Pixel Spork to control anything close to that large, so it may become buggy or perform badly.

  • The segDrawUtils namespace contains various helper functions for drawing with Segment Sets.

  • For more segment set notes, see here.

Effects:

  • Effect Basics wiki page.

  • To view a short sample of each effect, see Effect Samples.

  • All effects are class-based.

  • All effects require a Segment Set on which to draw. Multiple effects on the same Segment Set are not supported, but simultaneous effects on different Segment Sets are.

  • The maximum update rate for an effect is 65,535ms (ie updating once every ~65.5sec).

  • Effects tagged with Seg or Seg Line ("Seg" or "SL" in the effect's name in code) will automatically be drawn in 2D when given a 2D Segment Set.

  • Each effect has its own dedicated wiki page, see the drop down "Effect List" in the right-hand wiki sidebar.

Utility Classes:

  • Utility Class Basics wiki page.

  • Utility classes are used to enhance effects or perform other background tasks.

  • They behave almost exactly like effects, but (usually) do not draw.

  • Each utility has its own dedicated wiki page, see the right-hand sidebar.

Palettes:

  • Palette Basics wiki page.

  • Pixel Spork Palettes are not the same as FastLED palettes. Pixel Spork Palettes consist only of CRGB colors, with no gradient transitions. Gradients can be created from palettes either within specific effects, or by using certain palette utility classes.

  • Palettes consist of any array of CRGB colors and a length.

  • The maximum number of colors in a palette is 255.

  • The paletteUtilsPS namespace contains various helper functions for interacting with palettes.

  • Pixel Spork has several built-in palettes, listed here.

Patterns:

  • Pattern Basics wiki page.

  • Patterns consist of an array of indexes (max value 254), and a length.

  • Patterns are usually a sequence of palette color indexes. Ie you could have a pattern with the third color in a palette followed by the first, and then by the second. Effects will generally use patterns to sequence colors.

  • The maximum length of a pattern is 65,535.

  • Avoid using 255 as a pattern value because it is used by some effects to mark a background color.

  • Many effects will automatically build basic patterns for you when needed.

  • The patternUtilsPS namespace contains various helper functions for interacting with patterns.

  • The generalUtilsPS namespace has various helper functions for generating patterns.