Overview - AlbertGBarber/PixelSpork GitHub Wiki

Welcome to Pixel Spork!

Pixel Spork is an Arduino library for controlling addressable LEDs, such as the popular WS2812/WS2811/Neopixel chips. It features a robust 2D mapping system, over 40 deeply customizable effects, multiple extra utilities, and more! On this page I'll go over the core aspects of Pixel Spork and what you'll need to get yourself going. This page also serves as the starting point to the Starting Guide, which you can follow using the right-hand wiki navigation sidebar. The guide is intended to help introduce you to Pixel Spork's features and includes run-able code examples with explanations. It should give you what you need to start writing your own code, or point you in the right direction at least.

If you're new to Pixel Spork, I recommend going through the whole Starting Guide before jumping off into individual topics or trying to write your own code.

Prerequisites and Expectations:

Before we get started, it's important to discuss what I will and won't cover in this guide. I will go over the most important features of Pixel Spork, but I won't go into full detail for any of them. My objective is to give you just enough to get you going, leaving you to explore topics in more detail at your leisure. This helps keep the guide shorter and more concise (although it's probably still too long!).

Pixel Spork is a big library, featuring over 40 deeply customizable effects, numerous utilities, a segment system for virtually arranging your LEDs, and much more. It is overwhelming for me at times, so I expect the same will be true for you. Thankfully, most of Pixel Spork's features are compartmentalized, so you only need to interact with them if you want to use them. This lets you can build up your code and knowledge at your own pace. I try to provide numerous examples and code snippets, so hopefully, even if you don't completely understand something, you'll be able to copy-and-paste your way to victory!

At the same time, this guide, and wiki in general, expects you to already be familiar with Arduino/C++ programming. I won't be discussing basic things like variables, loops, pins, how to upload programs, etc. Due to its complexity, I don't recommend Pixel Spork as your first foray into embedded programming -- it will probably be a bit overwhelming! If you are totally new, you should probably look up some basic tutorials/guides to get a feel for working with Arduino's and embedded systems in general.

Much of the library is class-based, so some knowledge of object-oriented programming will be helpful. One topic that I have written a guide for is pointers, which you can find here. Pointers can be a tricky subject, and while I try to minimize your interactions with them, you'll occasionally have to use them -- usually as arguments when creating effects. The pointers guide gives you both a general overview of pointers, and examples of how you might need to use them in Pixel Spork specifically.

Finally, to run the code examples in this guide, you'll need some hardware. This is detailed in the next section: Wiring and Prerequisites.

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!

Pixel Spork's Core Features:

The sections below gives you a brief intro into Pixel Spork's core aspects. We'll go over these aspects in more detail in the code examples later.

Segment Sets, Segments, and Sections:

Segment Sets allow you to virtually re-arrange your LEDs into 1 or 2D shapes. For example, lets say I had several equal rows of LEDs arranged into a matrix. However, because addressable LEDs can only be connected one-by-one, without any external intervention, my matrix is just zig-zagging line. I need to use a Segment Set to form it into a fully 2D matrix.

Segment Sets are the core of Pixel Spork; they are very much the reason for this library's existence. Every effect requires a Segment Set to draw on, so any Pixel Spork code will have at least one Segment Set. Understanding the basics of Segment Sets is critical to using Pixel Spork. Combined with effects, they are probably the only two parts of this library that you must understand.

To read about Segment Sets, see the wiki pages under "Segments" in the right-hand sidebar, starting with Segment Basics. For code examples that examine Segment Sets, see Basic Setup and 2D Segment Sets for 2D Effects.

Effects:

Effects are probably why you're here in the first place. As their name implies, effects are what color your LEDs. Each effect has its own look/goal, but I try to add as much customization as possible to each effect, sometimes this means that by tweaking a few settings, you can drastically change an effect's output. All effects are class-based, and keep track of their state internally. When you update an effect it advances its state and draws it. Note that you are free to have as many instances of an effect as you like.

The general goal of Pixel Spork is for you to curate a collection of effects that look good with your particular LED situation, and then cycle through them, either over time or via some other trigger. To that end, they are usually self-contained, and don't interact with the rest of the library (beyond calls to utility functions), which makes it easy to add/remove effects from your code.

To read about effects, see the wiki pages under "Effects" in the right-hand sidebar, starting with Effect Basics. For code examples of effects, see Basic Setup, Cycling Mutiple Effects, and pretty much all of the other examples.

Every effect has its own wiki page, you can find a list by toggling the "Effect List" in the right-hand wiki sidebar. Each page explains the effect in detail including all its inputs, functions, etc. I also include multiple example effect setups, which you can (almost!) plug right into your own code to try out the effect. Likewise, you can view short animated snippets of all the effects on the Effect Samples page.

I do encourage you to experiment and play around with effects! Likweise, I always love seeing LED creations, so if you do happen to use Pixel Spork, you can share via the Pixel Spork Discord Server, or DM me directly on Discord or Reddit. After all, I didn't write this library because I hate looking at twinkling LEDs haha!

Utility Classes:

Utility classes are like modifiers or helpers for your effects. For example, the Palette Blender utility creates a palette that transitions smoothly from one set of colors to another. You can use the blended palette in your effects to have their colors change over time.

Utility classes are state-based just like effects, and update in the same way.

There a bunch of different utility classes in Pixel Spork; like effects, they each have their own wiki page. The pages are separated by their use case, so you can find utility classes under the "Effects", "Palettes", and "Other Utility Classes" sections in the right-hand wiki navigation sidebar. For a general overview of utility classes, see Utility Classes Basics.

For a code example of a utility class, see Palettes and Utility Classes.

Palettes and Patterns:

In Pixel Spork, a Palette is a group of colors. Usually, you use a Palette in an effect to set the colors of the effect. Note that Pixel Spork Palettes are not the same as FastLED Palettes and the two are not compatible, although it is fairly easy to translate a FastLED Palette to Pixel Spork. Palettes are intended to be quick and easy to create, so while Pixel Spork does feature a set of built-in Palettes, you'll probably make them yourself most of the time.

To read more about Palettes, see the wiki pages under "Palettes" in the right-hand sidebar, starting with Palette Basics. For a code example of Palettes, see Palettes and Utility Classes.

Patterns are used to order palette colors for certain effects. For example, lets say I have an effect the draws lengths of colors. Lets also say that I already have a palette, but the colors are in the wrong order, or it has colors that I don't want to use in my effect. Instead of creating a whole new palette just for the effect, I could use a pattern to set the color order (or omit colors) instead. Usually, unless you want a very specific pattern, patterns are automatically created in effect, so you probably won't interact with them very often.

To read more about Patterns, see the wiki pages under "Patterns" in the right-hand sidebar, Pattern Basics.

Color Modes:

Color Modes are a very special Pixel Spork feature -- they allow you to replace the colors of most effects (pretty much any effect where it make sense) with a 1 or 2D rainbow or custom gradient. This means that you can instantly flip an effect to "rainbow mode" by only changing a single setting! You can even configure the rainbow to shift over time! All the math is taken care of in the background by the library, making the whole system simple to operate.

To read more about Color Modes, see Color Modes. For a code example, see Color Modes Example.

Outro:

With the intro out of the way, we're ready to get coding! Hopefully everything has made enough sense so far! Remember, that this is just a quick overview of Pixel Spork, so if you feel like you need more details, the rest of the guide should provide them. Finally, as you work through the code examples, I encourage you to experiment by tweaking effect settings, Segment Sets, etc. You might be surprised at what you come up with!