Adafruit DotStar LEDs Created by Phillip Burgess Last updated on 2019-04-06 11:01:29 PM UTC
Overview NeoPixel LEDs are the bee's knees, but in a few scenarios they come up short…connecting odd microcontrollers that can’t match their strict timing, or fast-moving persistence-of-vision displays. Adafruit DotStar LEDs deliver high speed PWM and an easy-to-drive two-wire interface, bridging the gaps in the spectrum of awesome. DotStars vs NeoPixels The basic idea behind DotStars and NeoPixels is the same: a continuous string of individually-addressable RGB LEDs, driven by a microcontroller.
Form Factors DotStar products are available in numerous form factors…from individual tiny pixels to huge matrices…plus strips, FeatherWings and a few surprises. Pick a category from the left column for product links and tips & tricks specific to each type of DotStar offering. © Adafruit Industries https://learn.adafruit.
DotStar Strips The most popular type of DotStars are these flexible LED strips…they can be cut to length and fit into all manner of things. There are many varieties! Two vital things to be aware of: Though strips are described as “flexible,” they do not tolerate continuous and repeated bending. “Formable” might be a better word. A typical application is architecture, where they can be curved around columns and then stay put. Repeated flexing (as on costumes) will soon crack the solder connections.
© Adafruit Industries https://learn.adafruit.
White DotStar Strips A recent addition is White DotStar strips. Rather than red, green and blue, these contain three identical white LED elements — either “cool” or “warm” white. For monochrome applications, white DotStars are more “true” and pleasing to the eye than white mixed from red+green+blue. Like the RGB strips, they’re available in different pixel densities. 30 Cool White LEDs per meter (https://adafru.it/CIq) 30 Warm White LEDs per meter (https://adafru.
© Adafruit Industries https://learn.adafruit.
Finer Details About Flexible DotStar Strips 144 pixel/m DotStar strips are sold in one meter (RGB or white) and half meter (RGB only) lengths. Each of these is a separate strip with end connectors. Longer contiguous lengths are not offered in 144 pixels/m. 30 and 60 pixel/m DotStar strips are sold in one meter multiples. Orders for multiple meters will be a single contiguous strip, up to a limit: 4 meters for 60 pixels/m strip, 5 meters for 30 pixels/m.
Another linear form factor similar to a strip, but this one is not flexible. It features 128 tiny DotStar LEDs packed into a 400 millimeter bar with wires at each end with 4pin JST connectors. The aluminum-backed PCB is rigid but requires support so it doesn't droop and crack. It's not intended to be bent or curved at all. Also unlike strips, this bar is not weatherproof. Ultra High Density DotStar LED PCB Bar - 128 LEDs (https://adafru.it/CIw) © Adafruit Industries https://learn.adafruit.
DotStar Matrices DotStar matrices are two-dimensional grids of DotStar LEDs, all controlled from two microcontroller pins. Flexible DotStar Matrices Flexible DotStar matrices are available in three different sizes: 8x8 RGB pixels (https://adafru.it/CIy) 16x16 RGB pixels (https://adafru.it/CIz) 8x32 RGB pixels (https://adafru.it/CIA) © Adafruit Industries https://learn.adafruit.
Size Dimensions Total # of LEDs Max Power Draw (approx) 8x8 80 mm / 3.15" square 64 19 Watts (3.8 Amps at 5 Volts) 16x16 160 mm / 6.3" square 256 77 Watts (15 Amps at 5 Volts) 8x32 320 mm x 80 mm / 12.6" x 3" 256 77 Watts (15 Amps at 5 Volts) Flex matrices are about 2 millimeters (0.08 inches) thick. Though called “flexible,” these matrices do not tolerate continuous and repeated bending. “Formable” might be a better word — they can be bent around a rigid or semi-rigid shape, like a hat.
Adafruit DotStar High Density 8x8 Grid (https://adafru.it/CIB) This is the tiniest little LED grid we could make, with 64 full RGB color pixels in a square that is only 1" by 1" square (25.4mm x 25.4mm). Best of all, these are little DotStar LEDs, with built in PWM drivers, so you only need two digital I/O pins to get a-glowin'. Adafruit DotStar FeatherWing (https://adafru.it/AkQ) Stacks atop any of our Feather microcontroller boards.
If you need a size or shape of DotStar matrix that’s not offered here, it’s possible to create your own using sections of DotStar strip! DotStar matrices don’t enforce any particular “topology” — some may have rows of pixels arranged left-to-right, others may alternate left-to-right and right-to-left rows, or they could be installed in vertical columns instead. This will require some planning in your code. Our DotStarMatrix library supports most matrix topologies. © Adafruit Industries https://learn.
Individual DotStars For advanced users needing fully customized designs, discrete DotStar components are available. You’ll need to provide your own PCB and surface-mount soldering skill. SMT DotStars Surface-mount “5050” (5 millimeter square) DotStars are available in a few varieties: 5050 RGB LED — 10 Pack (https://adafru.it/CIC) 5050 Cool White LED — 10 Pack (https://adafru.it/CID) 5050 Warm White LED — 10 Pack (https://adafru.
Tiny surface-mount “2020” (2.0 millimeters square) DotStars are available in RGB (no pure white option): DotStar Micro LEDs — 10 Pack (https://adafru.it/CIF) Datasheets Includes pinouts for these various types. APA102C Datasheet (https://adafru.it/CJu) (5mm RGB DotStars) SK9822 Datasheet (https://adafru.it/CJv) (5mm White DotStars) APA102-2020 Datasheet (https://adafru.it/CJw) (2mm RGB DotStars) © Adafruit Industries https://learn.adafruit.
Power and Connections Powering DotStar LEDs The power requirements for DotStars are pretty much identical to NeoPixels…in fact, we’ll simply refer you to the relevant page of the NeoPixel Überguide for pointers on estimating and routing power (https://adafru.it/iZe). In summary: Estimate up to 60 milliamps peak for each pixel at full brightness white. A ground connection is required between the microcontroller and strip, in addition to the signal lines.
The simplest wiring is if you can power the strip off of the microcontroller board itself. This is fine for small projects (one or two dozen DotStars max) because we don't light up a lot of LEDs at once. Connect the strip 5V pin to the board 5V Connect the strip GND pin to board GND Connect the strip CI (Clock input) and DI (Data input) to the board’s SPI SCK and MOSI pins (if using an SPI bus) or any two digital pins (if “bitbanging” the signals).
DotStars are 5 Volt devices. They may respond to 3.3V signals, but this is not a guaranteed thing. If using a 3.3V controller (Feather, Raspberry Pi, etc.), add a logic level shifter to boost 3V logic to 5V…something like a 74AHCT125 (https://adafru.it/e5g) on the data and clock pins. © Adafruit Industries https://learn.adafruit.
Software DotStars got their start on Arduino, but have since branched out to other boards and languages. Pick a category from the left column for information specific to each coding environment. © Adafruit Industries https://learn.adafruit.
Arduino Library Installation 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. Install Adafruit_DotStar via Library Manager 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...
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! A Simple Code Example: strandtest 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.
Something happens but the LEDs are blinking in a weird way! © Adafruit Industries https://learn.adafruit.
Another common mistake is getting the data and clock wires reversed. If you get no response from the LEDs, or they © Adafruit Industries https://learn.adafruit.
flash in an unexpected way, try swapping those two wires. © Adafruit Industries https://learn.adafruit.
Arduino Library Use Doxygen-generated documentation for the Adafruit_DotStar library is available here. (https://adafru.it/Etq) It’s assumed at this point that you have the Adafruit_DotStar library for Arduino installed and have run the strandtest example sketch successfully. If not, return to the prior page for directions to set that up.
Adafruit_DotStar strip(NUMPIXELS, DOTSTAR_BRG); The SPI-or-not decision affects the wiring and strip declaration, but after that everything is the same regardless. Now, in the setup() function, call begin() to prepare the data and clock pins for DotStar output: void setup() { strip.begin(); strip.show(); // Initialize all pixels to 'off' } The second line, strip.show() , isn’t absolutely necessary, it’s just there to be thorough.
Multiple pixels can be set to the same color using the fill() function, which accepts one to three arguments. Typically it’s called like this: strip.fill(color, first, count); “color” is a packed 32-bit RGB (or RGBW) color value, as might be returned by strip.Color(). There is no option here for separate red, green and blue, so call the Color() function to pack these into one value. “first” is the index of the first pixel to fill, where 0 is the first pixel in the strip, and strip.
In the DotStar library, hue is expressed as a 16-bit number. Starting from 0 for red, this increments first toward yellow (around 65536/6, or 10922 give or take a bit), and on through green, cyan (at the halfway point of 32768), blue, magenta and back to red. In your own code, you can allow any hue-related variables to overflow or underflow and they’ll “wrap around” and do the correct and expected thing, it’s really nice.
uint32_t rgbcolor = strip.gamma32(strip.ColorHSV(hue, sat, val)); You might notice in some sketches that we never use ColorHSV() without passing the result through gamma32() before setting a pixel’s color. It’s that desirable.
Can I have multiple DotStar objects on different pins? © Adafruit Industries https://learn.adafruit.
Adafruit_DotStar strip_a(16, 3, 4); Adafruit_DotStar strip_b(16, 5, 6); The above declares two distinct DotStar objects, one with data and clock on pins 3 and 4, the other on pins 5 and 5. Each contains 16 pixels and is using the default color order. Can I connect multiple DotStar strips to the same Arduino pins? © Adafruit Industries https://learn.adafruit.
I’m getting the wrong colors. Red and blue are swapped! © Adafruit Industries https://learn.adafruit.
Most NeoPixel Code Adapts Easily to DotStars Nearly any NeoPixel code should compile and run with DotStars, just changing the library #include and the strip declaration…the remaining functions are roughly the same. There may be a few exceptions, but this is usually esoteric code that’s doing NeoPixel-specific hardware trickery. Pixels Gobble RAM Each DotStar requires about 3 bytes of RAM.
© Adafruit Industries https://learn.adafruit.
DotStarMatrix Library The Adafruit_DotStarMatrix library builds upon Adafruit_DotStar to create two-dimensional graphic displays using DotStar LEDs. You can then easily draw shapes, text and animation without having to calculate every X/Y pixel position. Small DotStar matrices are available in the shop. Larger displays can be formed using sections of DotStar strip, as shown above.
Let’s begin with the declaration for a single matrix, because it’s simpler to explain. We’ll be demonstrating the Adafruit DotStar FeatherWing (https://adafru.it/AkQ) in this case — a 12x6 matrix of tiny DotStars. When looking at this FeatherWing with the text in a readable orientation, the first pixel, #0, is at the bottom left. Each successive pixel is right one position — pixel 1 is directly to the right of pixel 0, and so forth.
Now the first pixel is at the top left. Pixels increment top-to-bottom — it’s now column major. The order of the columns is still progressive though. We declare the matrix thusly: Adafruit_DotStarMatrix matrix = Adafruit_DotStarMatrix( 6, 12, // Width, height 11, 13, // Data pin, clock pin DS_MATRIX_TOP + DS_MATRIX_LEFT + DS_MATRIX_COLUMNS + DS_MATRIX_PROGRESSIVE, DOTSTAR_BGR); The first two arguments — 6 and 12 — are the width and height of the matrix, in pixels.
this is hard-wired to digital pins 11 and 13, but on some Feather boards these physical pins have different numeric assignments, and standalone (non-FeatherWing) matrices are free to use other pins. See the dotstar_wing.ino example for pin assignments on other boards. The next argument is the interesting one. This indicates where the first pixel in the matrix is positioned and the arrangement of rows or columns.
Tiled Matrices A tiled matrix is comprised of multiple smaller DotStar matrices. This is sometimes easier for assembly or for distributing power. All of the sub-matrices need to be the same size, and must be ordered in a predictable manner.
The first tile must be located at one of the four corners. Add either DS_TILE_TOP or DS_TILE_BOTTOM and DS_TILE_LEFT or DS_TILE_RIGHT to indicate the position of the first tile. This is independent of the position of the first pixel within the tiles; they can be different corners. Tiles can be arranged in horizontal rows or vertical columns. Again this is independent of the pixel order within the tiles. Add either DS_TILE_ROWS or DS_TILE_COLUMNS.
RAM Again On a per-pixel basis, Adafruit_DotStarMatrix is no more memory-hungry than Adafruit_DotStar, requiring 3 bytes of RAM per pixel. But the number of pixels in a two-dimensional display takes off exponentially…a 16x16 display requires four times the memory of an 8x8 display, or about 768 bytes of RAM (nearly half the available space on an Arduino Uno). It can be anywhere from tricky to impossible to combine large displays with memory-hungry libraries such as SD or ffft. Fortunately 32-bit boards (e.
Python & CircuitPython It's easy to use DotStar LEDs with Python or CircuitPython and the Adafruit CircuitPython DotStar (https://adafru.it/CKG) module. This module allows you to easily write Python code that controls your LEDs. You can use these LEDs with any CircuitPython microcontroller board or with a computer that has GPIO and Python thanks to Adafruit_Blinka, our CircuitPython-for-Python compatibility library (https://adafru.it/BSN).
you cannot share the SPI device since there's no chip select) Pi 5V to LED 5V Pi GND to LED GND Pi MOSI to LED DI Pi SCLK to LED CI Here's the Raspberry PI wired up with bit-bang SPI (you can use any two digital pins, but its not as fast as hardware SPI) Pi 5V to LED 5V Pi GND to LED GND Pi GPIO5 to LED DI Pi GPIO6 to LED CI CircuitPython Installation of DotStar Library You'll need to install the Adafruit CircuitPython DotStar (https://adafru.it/CKG) library on your CircuitPython board.
If your default Python is version 3 you may need to run 'pip' instead. Just make sure you aren't trying to use CircuitPython on Python 2.x, it isn't supported! CircuitPython & Python Usage To demonstrate the usage of the this library with DotStar LEDs, we'll use the board's Python REPL. If you're using a SPI connection run the following code to import the necessary modules and initialize SPI with a strip of 30 DotStars: import board import adafruit_dotstar as dotstar dots = dotstar.DotStar(board.
That's all there is to getting started with CircuitPython and DotStar LEDs! Below is an example that turns all 30 LEDs random colors. To use, download the file, rename it to code.py and copy it to your board! Full Example Code import import import import time random board adafruit_dotstar as dotstar # On-board DotStar for boards including Gemma, Trinket, and ItsyBitsy dots = dotstar.DotStar(board.APA102_SCK, board.APA102_MOSI, 1, brightness=0.
Python Docs Python Docs (https://adafru.
