CircuitPython Internal RGB LED

Every board has a built in RGB LED. You can use CircuitPython to control the color and brightness of this LED. There are two different types of internal RGB LEDs: DotStar and NeoPixel. This section covers both and explains which boards have which LED.

circuitpython_NeoPixelDotStar.jpg
NeoPixel on the left, DotStar on the right. Not to scale... onboard DotStars are tiny!

The first example will show you how to change the color and brightness of the internal RGB LED.

Copy and paste the code into code.py using your favorite editor, and save the file.

import time
import board

# For Trinket M0, Gemma M0, ItsyBitsy M0 Express, and ItsyBitsy M4 Express
import adafruit_dotstar
led = adafruit_dotstar.DotStar(board.APA102_SCK, board.APA102_MOSI, 1)
# For Feather M0 Express, Metro M0 Express, Metro M4 Express, and Circuit Playground Express
# import neopixel
# led = neopixel.NeoPixel(board.NEOPIXEL, 1)

led.brightness = 0.3

while True:
    led[0] = (255, 0, 0)
    time.sleep(0.5)
    led[0] = (0, 255, 0)
    time.sleep(0.5)
    led[0] = (0, 0, 255)
    time.sleep(0.5)

Create the LED

First, we create the LED object and attach it to the correct pin or pins. In the case of a NeoPixel, there is only one pin necessary, and we have called it NEOPIXEL for easier use. In the case of a DotStar, however, there are two pins necessary, and so we use the pin names APA102_MOSI and APA102_SCK to get it set up. Since we're using the single onboard LED, the last thing we do is tell it that there's only 1 LED!

Trinket M0, Gemma M0, ItsyBitsy M0 Express, and ItsyBitsy M4 Express each have an onboard Dotstar LED, so no changes are needed to the initial version of the example.

Feather M0 Express, Feather M4 Express, Metro M0 Express, Metro M4 Express, and Circuit Playground Express each have an onboard NeoPixel LED, so you must comment out import adafruit_dotstar and led = adafruit_dotstar.DotStar(board.APA102_SCK, board.APA102_MOSI, 1), and uncomment import neopixel and led = neopixel.NeoPixel(board.NEOPIXEL, 1).

Remember: To "comment out" a line, put a # and a space before it. To "uncomment" a line, remove the # + space from the beginning of the line.

Brightness

To set the brightness you simply use the brightness attribute. Brightness is set with a number between 0 and 1, representative of a percent from 0% to 100%. So, led.brightness = (0.3) sets the LED brightness to 30%. The default brightness is 1 or 100%, and at it's maximum, the LED is blindingly bright! You can set it lower if you choose.

Main Loop

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 the 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.

The main loop is quite simple. It sets the first LED to red using (255, 0, 0), then green using (0, 255, 0), and finally blue using (0, 0, 255). Next, we give it a time.sleep() so it stays each color for a period of time. We chose time.sleep(0.5), or half a second. Without the time.sleep() it'll flash really quickly and the colors will be difficult to see!

Note that we set led[0]. This means the first, and in the case of most of the boards, the only LED. In CircuitPython, counting starts at 0. So the first of any object, list, etc will be 0!

Try changing the numbers in the tuples to change your LED to any color of the rainbow. Or, you can add more lines with different color tuples to add more colors to the sequence. Always add the time.sleep(), but try changing the amount of time to create different cycle animations!

Making Rainbows (Because Who Doesn't Love 'Em!)

Coding a rainbow effect involves a little math and a helper function called wheel. For details about how wheel works, see this explanation here!

The last example shows how to do a rainbow animation on the internal RGB LED.

Copy and paste the code into code.py using your favorite editor, and save the file. Remember to comment and uncomment the right lines for the board you're using, as explained above.

import time
import board

# For Trinket M0, Gemma M0, ItsyBitsy M0 Express and ItsyBitsy M4 Express
import adafruit_dotstar
led = adafruit_dotstar.DotStar(board.APA102_SCK, board.APA102_MOSI, 1)
# For Feather M0 Express, Metro M0 Express, Metro M4 Express and Circuit Playground Express
# import neopixel
# led = neopixel.NeoPixel(board.NEOPIXEL, 1)


def wheel(pos):
    # Input a value 0 to 255 to get a color value.
    # The colours are a transition r - g - b - back to r.
    if pos < 0 or pos > 255:
        return 0, 0, 0
    if pos < 85:
        return int(255 - pos * 3), int(pos * 3), 0
    if pos < 170:
        pos -= 85
        return 0, int(255 - pos * 3), int(pos * 3)
    pos -= 170
    return int(pos * 3), 0, int(255 - (pos * 3))


led.brightness = 0.3

i = 0
while True:
    i = (i + 1) % 256  # run from 0 to 255
    led.fill(wheel(i))
    time.sleep(0.1)

We add the wheel function in after setup but before our main loop.

And right before our main loop, we assign the variable i = 0, so it's ready for use inside the loop.

The main loop contains some math that cycles i from 0 to 255 and around again repeatedly. We use this value to cycle wheel() through the rainbow!

The time.sleep() determines the speed at which the rainbow changes. Try a higher number for a slower rainbow or a lower number for a faster one!

Circuit Playground Express Rainbow

Note that here we use led.fill instead of led[0]. This means it turns on all the LEDs, which in the current code is only one. So why bother with fill? Well, you may have a Circuit Playground Express, which as you can see has TEN NeoPixel LEDs built in. The examples so far have only turned on the first one. If you'd like to do a rainbow on all ten LEDs, change the 1 in:

led = neopixel.NeoPixel(board.NEOPIXEL, 1)

to 10 so it reads:

led = neopixel.NeoPixel(board.NEOPIXEL, 10).

This tells the code to look for 10 LEDs instead of only 1. Now save the code and watch the rainbow go! You can make the same 1 to 10 change to the previous examples as well, and use led.fill to light up all the LEDs in the colors you chose! For more details, check out the NeoPixel section of the CPX guide!

This guide was first published on Aug 23, 2017. It was last updated on Aug 23, 2017. This page (CircuitPython Internal RGB LED) was last updated on Jul 13, 2018.