
Image by @blenster

GETTING STARTED

Hello! You've just recieved Pixie Chromas in the mail, and if you're as excited as we are to begin, there's only a few steps ahead of you before they light up. You may even have some steps complete already, feel free to skip ahead!

NOTE: Please see the current list of supported microcontrollers in the README - ESP32 is currently the most powerful option for Pixie Chroma projects, and is quite cheap too!

1. Download Arduino IDE

Visit www.arduino.cc/downloads and download the latest version of the IDE for your operating system.

NOTE: Only Arduino IDE versions >= 1.8.10 will correctly install the Pixie Chroma library in one click. Earlier versions will need to manually search for and install FastLED, ArduinoJSON, and WiFiManager libraries in a later step for full support.

Once downloaded and installed, proceed to Step 2.

NOTE: This tutorial will center around the 1.X version of Arduino IDE. A guide for the upcoming 2.X version is planned for a future date when that version finishes its Release Candidate period.

2. Installing Board Definitions

Arduino IDE is where you'll be writing code to control your Pixie Chromas, but it first has to know which type of microcontroller you're using! This is where Board Definitions come in. These allow Arduino IDE to translate your code into instructions that your specific controller can understand.

You can add new board definitions under: File > Preferences > Additional Boards Manager URLs.

This will open a window where you can copy / paste in the following URLs, depending on the micocontroller you are using:

ESP8266:
https://arduino.esp8266.com/stable/package_esp8266com_index.json
	
ESP32:
https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_dev_index.json
	
Teensy 3.X:
Teensy controllers use a more custom set up, follow the instructions on this page to install Teensy support:
https://www.pjrc.com/teensy/td_download.html

Once a new Board Definition is pasted in, open Tools > Board > Boards Manager.

Another window will pop up, and once the list loads you'll now see an entry that matches your microcontroller and you can click "Install" to enable support in Arduino IDE for your microcontroller type.

3. Installing the Pixie Chroma Arduino Library

Now that Arduino IDE supports your microcontroller, you need to install the Pixie Chroma "Library". Libraries are a way to package pre-made code in a simple way. There are thousands of lines of code inside the Pixie Chroma library, but because it is packaged as a library, the code you write only needs an #include "Pixie_Chroma.h" line at the top to use it all!

Open the menu again: Sketch > Include Library > Manage Libraries...

When this window appears (it may take some time to unfreeze after opening) you can use the search box to find "pixie chroma", with Lixie Labs listed as the author. Install the latest version, then proceed to Step 4!

NOTE: If using an Arduino IDE version older than 1.8.10, you'll need to manually search for and install FastLED, ArduinoJSON, and WiFiManager libraries in the Library Manager window at this step while you're at it.

4. Wiring

Almost there! This part is quite important. LEDs are happy to burn themselves out if wired incorrectly, so follow along carefully!

Begin by inserting your displays into a breadboard like so:

NOTE: Pixie Chroma PCBs will only work when installed right-side-up! There is a small gold arrow on each PCB that should always point towards the top of your display!

Take care to space them so that each LED matrix is equally spaced apart! Once the Pixies are laid out, we'll start with power wiring.

NOTE: DO NOT LEAVE THE MICROCONTROLLER CONNECTED TO USB WHILE WIRING POWER, JUST IN CASE SOMETHING COMES LOOSE OR YOU MAKE A MISTAKE!

Using the included Pinout Card as a reference, wire up your power lines like so:

You can also use standard breadboard jumpers that aren't cut to size like these, but custom wires help to reduce the likelihood of accidentally snagging a loose one while improving appearances.

Next, you'll connect the data lines from the bottom of each PCB to the top of the next like so: ("OUT" of one board to the "IN" of the next)

NOTE: Pixies are always arranged / wired in western reading order: Left to Right in each row, from Top to Bottom.

Lastly, you'll connect it all to the microcontroller, in this case an ESP8266. The positive (red) rail of the breadboard should be connected to the 3.3V pin of the microcontroller, the negative (black or blue) rail of the breadboard should be connected to a GND pin, and the "IN" pin of your first Pixie Chroma in the chain should be connected to the GPIO of your choice. In this case, you'll use GPIO 5 (stupidly, confusingly marked "D1" on this microcontroller) like so:

After double checking that your set up is identical to this photo (ESPECIALLY power lines), you can now plug in the USB cable to the microcontroller. If nothing went 'zap', you did it!!! The hardest part is over and you're ready to proceed to Step 5, where we'll see them light up for the first time!

5. Uploading Example Code

Wipe the sweat from your forehead, you're almost done! Next you'll upload example code to the microcontroller to have it show a sort of "HELLO" as a first test.

Back in the Arduino IDE, open File > Examples > Pixie_Chroma > 01_Basic > 01_Getting_Started.

Before uploading this code, we have three lines to change based on our set up process so far.

#define DATA_PIN  5  // GPIO to use for Pixie Chroma data line
#define PIXIES_X  2  // Total amount and arrangement
#define PIXIES_Y  1  // of Pixie PCBs = 2 x 1

DATA_PIN should be "5" in the case of this tutorial's wiring, and PIXIES_X should match how many Pixie PCBs wide our display is. (PIXIES_Y is for multi-row displays and will be left as "1" for now)

Once this change is made, you need to select the "Serial Port" our microcontroller is on so that the computer knows where to send the code. To do this, first unplug your microcontroller again. Now, open the Tools > Port menu and look at the entries, if any. There is a chance that although your microcontroller is unplugged, you'll still see ports available such as "COM1" on Windows, and "/dev/TTY*****" on Mac/Linux.

These are likely virtual serial ports from your OS, or other devices attached to your computer. We don't want to work with these, so take note of their names.

Now, plug the microcontroller back in and check the Ports menu again. Whatever new entry that wasn't there before is your microcontroller, such as "COM16".

Select this port, and hit the "Upload" button in the top left of the IDE:

This first upload will likely take a few minutes to complete, as the IDE has to compile tons of new data that it will keep around for subsequent runs. After this, uploading will only take about 30-60 seconds.

Did it work? If it did, CONGRATULATIONS! You should see "HI <3" on the displays, written in pink! If not, skip ahead to Step 7 to begin diagnosing the issue.

6. Writing your own Pixie Chroma code

While we have an extensive Pixie Chroma Software Documentation site which details every single bit of the library available for you to use, there are only 4 basic functions to learn for 99% of projects. (This list is also in the order they are likely to be used in.)

pix.begin()
pix.clear()
pix.print()
pix.show()

pix.begin( DATA_PIN, PIXIES_X, PIXIES_Y ); // DOCS LINK

pix.begin() is a necessary function you need in the setup() of your Arduino Sketch. This initializes the library and helps it to understand the size of display you have built.

Pixie Chroma allows for multi-row displays, which are wired in western reading order (left to right, top to bottom) and their shape is defined here. For example, a 16-Pixie display with two rows of eight:

data_pin
   |
+--+-+   +----+   +----+   +----+   +----+   +----+   +----+   +----+
|  1 |-->|  2 |-->|  3 |-->|  4 |-->|  5 |-->|  6 |-->|  7 |-->|  8 | 
+----+   +----+   +----+   +----+   +----+   +----+   +----+   +--+-+
                                                                  |
   +--------------------------------------------------------------+
   |
+----+   +----+   +----+   +----+   +----+   +----+   +----+   +----+
|  9 |-->| 10 |-->| 11 |-->| 12 |-->| 13 |-->| 14 |-->| 15 |-->| 16 | 
+----+   +----+   +----+   +----+   +----+   +----+   +----+   +----+

The corresponding setup for this display layout would be:

#include "Pixie_Chroma.h"
PixieChroma pix;

#define DATA_PIN 5
#define PIXIES_X 8
#define PIXIES_Y 2

void setup() {
    pix.begin( DATA_PIN, PIXIES_X, PIXIES_Y );
}

pix.clear(); // DOCS LINK

Clears (blackens) the entire display and resets the cursor to 0,0.

NOTE: This action does not immediately show the cleared display, you still need to call pix.show()

pix.print( MESSAGE ); // DOCS LINK

MESSAGE can be any of the following data types:

char | Single char
char* | char* string / array
int16_t | Signed 16-bit integer
uint16_t | Unsigned 16-bit integer
int32_t | Signed 32-bit integer
uint32_t | Unsigned 32-bit integer
float (extra parameter: uint8_t places = 2) | Single-precision floating point number
double (extra parameter: uint8_t places = 2) | Double-precision floating point number

Pixie Chroma's print() function allows easy writing to the displays. It automatically tracks cursor position (where text will print next) meaning you can chain print calls like this:

pix.print( "Sales to date: [:EURO:]" ); // Descriptor with currency symbol
pix.print( sales_in_euros );            // Variable storing value

// This will print:
// "Sales to date: €X.YZ"

To reset your printing position to 0,0 (top left), use either pix.clear() or pix.set_cursor(0,0).

pix.show(); // DOCS LINK

Takes the display data gathered so far (clears, prints, animation, etc.) since the last call to show(), and immediately sends it out through the DATA_PIN to the physical displays to be shown.

Minimal Sketches

Even better than writing some these functions out, an easy time saver is to use the Minimal Sketches.

These templates (included as library examples) cover all of the basic setup necessities to write code for Pixie Chroma, leaving only the fun parts!

There are two templates, one for "Standard Mode" and one for "Quad Mode". (QUAD MODE DOCS LINK) Quad Mode is for power users with experience and requires more complex wiring, so most for most projects "Standard Mode" will do.

7. Shortcodes

Shortcodes are a super simple way to show icons beyond the alphanumeric ASCII set and easily create animations! We have an extensive library of 230+ built-in icons that are accessible by name within other strings. (See the example above.) Whether you want global currency symbols, weather states, schematic symbols, diacritics (àãåâä), or various mathematical typography such as pi, we probably have you covered. And if we don't, you can make your own with the magical Shortcode Editor:

Shortcode Editor

Our favorite part of these icons is how easy it is to make your own! With our online/offline editor, you can create any shape or image (so long as it fits in a 5x7 grid) and the editor will directly show the code that would print that shape!

This is one of the most creative outlets for cool display enthusiasts, since you can easily make custom frame-by-frame animations of your own! We are currently working on a way to create looping animations directly within the editor, and are excited to show it when it is complete.

8. Color Palettes / Animations

If you want a super easy cheat to get a unique color animation running on your displays is to use Color Palettes and Animations.

Color Palettes

When used, Color Palettes take over the color data of the Chromas and replace it with a solid color or pre-defined gradients. For example:

pix.set_palette(RAINBOW); // Forces rainbow color on the displays

We're looking to add more pre-defined palettes, but here are some we have so far:

RAINBOW
GRADIENT_RED_BLACK
GRADIENT_BLACK_RED_BLACK
GRADIENT_GREEN_BLACK
GRADIENT_BLACK_GREEN_BLACK
GRADIENT_BLUE_BLACK
GRADIENT_BLACK_BLUE_BLACK

If you'd like to use your own colors, there is a function: make_gradient(CRGB color_1, CRGB color_2, etc...).

For example:

pix.set_palette(      // Makes the palette a gradient from (255,255,0) to (0,0,255)
	make_gradient(
		CRGB::Yellow,
		CRGB::Blue
	)
);

Once pix.set_palette() is called, any future calls to show() will use the color palette you defined.

Color Animations

Color Animations allow you to modify the usage of the Color Palette over time. This means that you either need to call pix.show() as often as possible, or read up on pix.set_update_mode( AUTOMATIC ); (DOCS LINK) which will make pix.show() called automatically in the background at up to 60 FPS.

For example:

pix.set_palette( RAINBOW );                              // Set palette to RAINBOW
pix.set_color_animation( ANIMATION_PALETTE_SHIFT_LEFT ); // Shift palette to the left every frame, wrapping it wround

This will show the RAINBOW palette slowly shifting to the left at constant rate if show() is called often enough.

Other built-in Color Animations include:

ANIMATION_NULL | It does nothing, but it does nothing REALLY WELL! You can enable this empty function with pix.set_animation(ANIMATION_NULL) to fully manually control LEDs when you want using pix.show()
ANIMATION_STATIC | Shows the current color palette without animation
ANIMATION_PALETTE_SHIFT_LEFT | Shows the current color palette, while constantly shifting it to the left
ANIMATION_PALETTE_SHIFT_RIGHT | Shows the current color palette, while constantly shifting it to the right
ANIMATION_GLITTER | Shows the current color palette with a sparkling effect
ANIMATION_PENDULUM | Sways the current color palette left and right with a sine function at 1Hz intervals
ANIMATION_PENDULUM_WIDE | Sways the current color palette left and right with a sine function at 1Hz intervals. Wider travel than ANIMATION_PENDULUM

You can also create your own function that manipulates color and give that function as a parameter to pix.set_color_animation( your_function ).

9. Diagnosing Issues

Below are a few types of issues you may face if something wasn't configured / wired / soldered properly.

PCB DOES NOT LIGHT UP

Here are a few steps to take if your Pixie Chroma PCB isn't functioning as expected. There are two types of failure:

PCB DOES NOT LIGHT UP AT ALL

This may be nerve-wracking, but a few easy mistakes can cause this:

Are your Pixie Chromas powered with the same voltage level your GPIO pins operate at?

GLOSSARY

These are some terms you'll need to know for this guide:

Breadboard

A prototyping tool that allows you to easily make connections between electronics without using solder. See the above diagram to understand how the holes are electrically connected. Basically: anything inserted in the same column of holes is connected. The top and bottom rows are for power, and are (almost always) connected through the entire length of the breadboard.

Microcontroller

A small, simple processor capable of running custom code and physically interfacing with other electronics

IDE

Integrated Development Environment - the software used to write code, which (in this case) also handles uploading it to a microcontroller.

Arduino

An open-source ecosystem for designing electronic circuits based around microcontrollers. Annoyingly, this term is used interchangably to describe both the Arduino IDE and informally describe many microcontrollers that work with it.

Sketch

The even more annoying name Arduino chose to describe code written by users. You "Write a sketch" and upload the "sketch" to your microcontroller. (This term actually originates from Processing, a motion graphics software that Arduino IDE is forked from, as is the very old ".pde" file extension Arduino used to use a decade ago.)

GPIO

General-Purpose Input/Output - These are physical pins on the microcontroller that can be selectively given/denied power by users' code. They can also act as inputs, measuring the outside world for changes such as a button press.

Files

getting_started.md

Latest commit

History