Controlling DotStars “from scratch” is tedious, so we provide a library letting you focus on the fun and interesting bits. The library works with most mainstream Arduino boards and derivatives: Uno, Mega, Adafruit Feather, etc.
Recent versions of the Arduino IDE (1.6.2 and later) make library installation super easy via the Library Manager interface. From the Sketch menu, > Include Library > Manage Libraries... In the text input box type in "DotStar". Look for "Adafruit DotStar by Adafruit" and select the latest version by clicking on the popup menu next to the Install button. Then click on the Install button. After installation, you can click the "close" button.
If you’re using an older version of the IDE, or just want to set things up manually, “classic” installation of the library is as follows: you can visit the Adafruit_DotStar library page at Github and download from there, or just click this button:
- Uncompress the ZIP file after it’s finished downloading.
- The resulting folder should contain the files Adafruit_DotStar.cpp, Adafruit_DotStar.h and an “examples” sub-folder. Sometimes in Windows you’ll get an intermediate-level folder and need to move things around.
- Rename the folder (containing the .cpp and .h files) to Adafruit_DotStar (with the underscore and everything), and place it alongside your other Arduino libraries, typically in your (home folder)/Documents/Arduino/Libraries folder. Libraries should never be installed in the “Libraries” folder alongside the Arduino application itself…put them in the subdirectory of your home folder!
- Re-start the Arduino IDE if it’s currently running.
Here’s a tutorial that walks through the process of correctly installing Arduino libraries manually.
Another option for Arduino is the FastLED library, featuring cutting-edge code with more color-handling and mathematical support functions. However, it’s a little more tricky to use…so, if connecting DotStars for the first time, we ask that you start with the Adafruit_DotStar library. Once the hardware is confirmed working, you can then graduate to whatever code or library you’d like!
Launch the Arduino IDE. From the File menu, select Sketchbook→Libraries→Adafruit_DotStar→strandtest
(If the Adafruit_DotStar rollover menu is not present, the library has not been correctly installed, or the IDE needs to be restarted after installation. Check the installation steps above to confirm it’s properly named and located.)
The “strandtest” example shows basic library use; declaring a strip object, setting LED colors and pushing this data to the strip via the
show() method. For more advanced examples, nearly any NeoPixel code should compile and run with DotStars, just changing the library #include and the strip declaration.
Select your board type and serial port from the Tools menu, and try uploading to the board. If the DotStars are connected and powered as previously described, you should see a little light show.
If using a one-meter strip or less, it’s usually OK to power off the microcontroller’s 5V pin. Here’s how it might look on an Arduino Uno or Adafruit Metro board:
For longer strips, see the “Power and Connections” page for guidance.
Some microcontroller boards won’t have a pin 4 or 5. Not to worry, we’ll show on the next page how to change the software for different connections.
Check your connections. The most common mistake is connecting to the output end of a strip rather than the input.
99% of the time this is due to not having a shared ground wire connected to the Arduino. Make sure the Ground wire from the DotStars connects to BOTH your power supply ground AND the Arduino ground.
Another common mistake is getting the data and clock wires reversed. If you get no response from the LEDs, or they flash in an unexpected way, try swapping those two wires.