Getting Help - AlbertGBarber/PixelSpork GitHub Wiki

Jump to

• My Code Doesn't Compile.
• My Code Compiles But Nothing Happens.
• My LEDs Light Up But The Output Doesn't Look Right or Crashes.
• Reaching Out.

Overview:

This page is intended to serve as a general debugging and troubleshooting guide. The goal of this guide is more to help you pin-point where a bug is occurring rather than to provide specific fixes, as it's impossible to cover every circumstance.

While I am happy to help personally, please use this guide before posting to Discord, DM'ing me on Discord or on Reddit, etc, or opening an issue on Github. Likewise, I'm going to be most helpful about Pixel Spork specific issues, and not general programming (I just end up Googling most stuff!).

When asking for help online, please include your code, either by using a Gist, Pastebin, or some other text host.

When opening an issue on Github, please use the search to check if the issue has already been reported.

In General:

• Always start your code small and scale up bit by bit. Complex pieces of code can have multiple bugs, so solving one won't necessarily get your code running. Starting small helps you tackle issues one at a time, saving you time overall.

• The Arduino compiler CANNOT catch runtime errors. You code may compile just fine, but then still break when running. Such issues can be tricky to de-bug, but are often caused by things like: reading off then end of an array, trying to use a object before it is initialized (entries are null), various pointer issues.

• Many effects dynamically allocate objects, which requires RAM. The Arduino compiler's memory report doesn't include dynamic allocations, so if you are close to the memory cap and experiencing crashes, an effect may be overflowing the RAM.

• If you a newer to addressable LEDs, taking a look at Adafruit's Neopixel uber-guide may help you with hardware issues.

My Code Doesn't Compile:

Generally the Arduino compiler will give you an error message about why your code won't compile. The messages can be pretty esoteric, but usually it's a syntax issue. If you can't guess at the issue, try googling parts of the statement. When working with Pixel Spork, I usually get errors about pointers. These usually come in the form of "xyz type doesn't match ijk argument". In these cases try adding/removing "*" or "&" from the start of the argument. You should also read up on pointers 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!

My Code Compiles But Nothing Happens:

• If your code is simple, this is usually due to a wiring or config issue.

  Try:

  1. Running the Arduino "Blink" example. This will confirm if your micro-controller is working/being programmed correctly. If nothing happens, you'll need to get Googling, as this is outside the spec of this guide.

  2. Run one of the basic FastLED examples. If nothing happens, then your issue is probably with wiring or communicating with the LEDs. You can read more about wiring here and FastLED's supported micro-controllers and LED chipsets here.

3. Try running the "Basic Setup" Pixel Spork example. If this doesn't work (unlikely if the FastLED example worked), then there's possibly a problem with your Pixel Spork install? If the install seems correct, shoot me a note either on Discord or by opening an issue on Github.

• My micro-controller runs the basic examples, but nothing happens when I run my own code:

  Try:

  1. Double check your segment set(s). It's possible to create a segment set that is longer than your physical strip, which can cause your program to crash. Try using the "mainSegments" segment set from the "Basic Setup" starter example; if your code runs, then your segment set is probably the issue.

  2. Try to pin-point which effect or utility is causing the issue by paring back your code. Try running each effect separately using the "Simple Effect Tester" example. If your effects are using inputs from a utility (such as a blending palette), try running the effects with a pre-built palette or fixed input. When testing utilities, try testing them with the Streamer effect in the example.

     • If each effect works independently, then your issue is somewhere in your own code's logic. Unfortunately that's out of the scope of this guide, but you are welcome to seek help on Reddit or Discord. If you are using a Pixel Spork utility class with an output, you may have a pointer argument miss-match when you input it into you effect; double check the utility's wiki page for an example of using the utility's output.

     • If an effect doesn't work, try to adjust the input arguments or settings to pin-point which setting is causing the issue and/or try running the effect's examples from its wiki page. All effects should work as long as their inputs/settings are reasonable (not out of range, un-initlized, etc). If you find an input/setting combo that should work, but doesn't, you may have found a bug, please open an issue using Github.

My LEDs Light Up But The Output Doesn't Look Right or Crashes:

1. If your colors are wrong, you may have the wrong RGB order for your LEDs. Check the FastLED "RGBCalibrate" example for more info.

2. If your LEDs flicker or display random colors, you probably have a wiring, data transmission, or power issue. You can read more about wiring here. Confusingly, some effects seem to cause these issues more than others, so don't immediately assume it's a bug with a specific effect!

   • Note that when using WS2811 "bullet" pixels with an ESP8266 and version 3.0.0+ of the ESP8266 Arduino board's library, there is a know FastLED data transmission bug that causes flickering. To fix this, revert to ESP8266 boards version 2.7.4 in the Arduino IDE. See here for more info.

3. Double check your segment set configuration. You can confirm its layout using the Segment Set Check utility. Try removing any segment set settings changes you may be making during runtime (if you find a settings change that causes a crash/bug, please open an issue on Github).

4. If your code is crashing, try to pin-point where, and with what effect or utility.

   • Make sure all effect inputs are initialized (not null or undefined) when you create the effect (not when you start drawing it!).

   • Make sure any array/object lengths are correct so you aren't writing/reading off the end of an array.

   • Likewise, if you are changing any effect settings during run-time, make sure you don't need to use one of the effect's functions to do so.

   • If one of your effect's inputs is from a utility, try running the effect without. Confirm that the input argument is formed correctly using examples from the utility's wiki page (using the correct pointer form, etc).

5. If a specific effect runs, but looks wrong, try to adjust its settings or inputs. Some settings can have strange/complex effects, so make sure you double check the effect's wiki page. If you cannot adjust/correct the output please open an issue on Github (including a video if possible).

Reaching Out:

If nothing above has helped, try reaching out for help on Discord or DM me here. Remember to include your code using Gist, Pastebin, etc.