Your board has multiple built-in RGB DotStar LEDs. You can use CircuitPython code to control the color and brightness of these LEDs. They are also used to indicate the bootloader status.

A DotStar refers to any 2-wire serial LED, typically APA102, but also possibly SK9822. Along side a driver chip, DotStars have have three LEDs: RGB DotStars have a red LED, a blue LED and a green LED, and white DotStars have three white LEDs. The LEDs on your microcontroller are RGB DotStars! DotStars operate over a generic 2-wire SPI bus, which means they aren't as strict about timing. They allow for extremely fast data and PWM rates so they're suitable for POV displays. They can be used individually (as in the built-in LED on your board), or chained together in strips or other creative form factors. DotStars do not light up on their own; they must be connected to a microcontroller. They require two pins, data and clock, to operate. The response time is faster when connected to a hardware SPI pair of pins, but will work connected to any two digital pins. You do not need to worry about connecting the DotStars because they're built into your microcontroller!

This page will cover using CircuitPython to control the RGB DotStars built into your microcontroller. You'll learn how to change the color and brightness, and how to make a rainbow. Time to get started!

DotStar Location

On the FunHouse, the DotStar LEDs (indicated by red boxes in the image) are spread out evenly along the top edges of the board, beginning at the top center, and then along the two edges to the mounting holes.

DotStar Color and Brightness

To use the built-in DotStars on your board, you need to first install the DotStar library into the lib folder on your CIRCUITPY drive.

Then you need to update code.py.

Click the Download Project Bundle button below to download the necessary libraries and the code.py file in a zip file. Extract the contents of the zip file, and copy the entire lib folder and the code.py file to your CIRCUITPY drive.

"""CircuitPython DotStar red, green, blue example for FunHouse"""
import time
import board
import adafruit_dotstar

dots = adafruit_dotstar.DotStar(board.DOTSTAR_CLOCK, board.DOTSTAR_DATA, 5)
dots.brightness = 0.3

while True:
    dots.fill((255, 0, 0))
    time.sleep(0.5)
    dots.fill((0, 255, 0))
    time.sleep(0.5)
    dots.fill((0, 0, 255))
    time.sleep(0.5)

Your CIRCUITPY drive should resemble the image.

You should have in / of the CIRCUITPY drive:

  • code.py

And in the lib folder on your CIRCUITPY drive:

  • adafruit_dotstar.mpy
  • adafruit_pypixelbuf.mpy

The DotStar LEDs being flashing red, green and blue!

If your DotStars do not start flashing red, green and blue, make sure you've copied all the necessary files and folders to the CIRCUITPY drive!

First you import the necessary modules, time and board, and the necessary library, adafruit_dotstar. This makes these modules and libraries available for use in your code. The first two are modules built-in to CircuitPython, so you don't need to download anything to use those. The adafruit_dotstar library is separate, which is why you needed to install it before getting started.

Next, you set up the Dotstar LEDs. To interact with hardware in CircuitPython, your code must let the board know where to look for the hardware and what to do with it. So, you create a adafruit_dotstar.DotStar() object, provide it the DotStar LED pins using the board module, and tell it the number of LEDs. You save this object to the variable pixels.

Then, you set the DotStar brightness using the brightness attribute. brightness expects float between 0 and 1.0. A float is essentially a number with a decimal in it. The brightness value represents a percentage of maximum brightness; 0 is 0% and 1.0 is 100%. Therefore, setting pixel.brightness = 0.3 sets the brightness to 30%. The default brightness, which is to say the brightness if you don't explicitly set it, is 1.0. The default is really bright! That is why there is an option available to easily change the brightness.

Inside the loop, you turn the DotStars red for 0.5 seconds, green for 0.5 seconds, and blue for 0.5 seconds.

To turn the DotStars red, you "fill" them with an RGB value. Check out the section below for details on RGB colors. The RGB value for red is (255, 0, 0). Note that the RGB value includes the parentheses. The fill() attribute expects the full RGB value including those parentheses. That is why there are two pairs of parentheses in the code.

You can change the RGB values to change the colors that the DotStars cycle through. Check out the list below for some examples. You can make any color of the rainbow with the right RGB value combination!

That's all there is to changing the color and setting the brightness of the built-in DotStar LEDs!

RGB LED Colors

RGB LED colors are set using a combination of red, green, and blue, in the form of an (RG, B) tuple. Each member of the tuple is set to a number between 0 and 255 that determines the amount of each color present. Red, green and blue in different combinations can create all the colors in the rainbow! So, for example, to set an LED to red, the tuple would be (255, 0, 0), which has the maximum level of red, and no green or blue. Green would be (0, 255, 0), etc. For the colors between, you set a combination, such as cyan which is (0, 255, 255), with equal amounts of green and blue. If you increase all values to the same level, you get white! If you decrease all the values to 0, you turn the LED off.

Common colors include:

  • red: (255, 0, 0)
  • green: (0, 255, 0)
  • blue: (0, 0, 255)
  • cyan: (0, 255, 255)
  • purple: (255, 0, 255)
  • yellow: (255, 255, 0)
  • white: (255, 255, 255)
  • black (off): (0, 0, 0)

DotStar Rainbow

You should have already installed the library necessary to use the built-in DotStar LEDs. If not, follow the steps at the beginning of the DotStar Color and Brightness section to install it.

Update your code.py to the following, and save.

"""CircuitPython DotStar rainbow example for FunHouse"""
import time
import board
import adafruit_dotstar
from _pixelbuf import colorwheel

dots = adafruit_dotstar.DotStar(board.DOTSTAR_CLOCK, board.DOTSTAR_DATA, 5, auto_write=False)
dots.brightness = 0.3


def rainbow(delay):
    for color_value in range(255):
        for led in range(5):
            pixel_index = (led * 256 // 5) + color_value
            dots[led] = colorwheel(pixel_index & 255)
        dots.show()
        time.sleep(delay)


while True:
    rainbow(0.01)

The DotStars display a rainbow cycle!

This example builds on the previous example.

First, you import the same three modules and libraries. In addition to those, you import colorwheel.

The DotStar hardware setup is similar, but you now also set auto_write to False. This means that now the DotStar won't change unless you explicitly tell it to by calling show(). This is necessary for this example to speed up the rainbow animation. Brightness setting is the same.

Next, you have the rainbow() helper function. This helper displays the rainbow cycle. It expects a delay in seconds. The higher the number of seconds provided for delay, the slower the rainbow will cycle. The helper cycles through the values of the color wheel to create a rainbow of colors.

Inside the loop, you call the rainbow helper with a 0.01 second delay, by including rainbow(0.01).

That's all there is to making rainbows using the built-in DotStar LEDs!

This guide was first published on Apr 20, 2021. It was last updated on 2021-05-04 15:26:05 -0400.

This page (Built-In DotStar LEDs) was last updated on May 13, 2021.

Text editor powered by tinymce.