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.

To use with CircuitPython, you need to first install a few libraries, into the lib folder on your CIRCUITPY drive. Then you need to update code.py with the example script.

Thankfully, we can do this in one go. In the example below, 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, open the directory CircuitPython_Essentials/CircuitPython_Internal_RGB_LED_colors/ and then click on the directory that matches the version of CircuitPython you're using and copy the contents of that directory to your CIRCUITPY drive.

Your CIRCUITPY drive should now look similar to the following image:

CIRCUITPY
# SPDX-FileCopyrightText: 2018 Kattni Rembor for Adafruit Industries
#
# SPDX-License-Identifier: MIT

"""CircuitPython Essentials Internal RGB LED red, green, blue example"""
import time
import board

if hasattr(board, "APA102_SCK"):
    import adafruit_dotstar

    led = adafruit_dotstar.DotStar(board.APA102_SCK, board.APA102_MOSI, 1)
else:
    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.

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.

QT Py M0, 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).

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

To use with CircuitPython, you need to first install a few libraries, into the lib folder on your CIRCUITPY drive. Then you need to update code.py with the example script.

Thankfully, we can do this in one go. In the example below, 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, open the directory CircuitPython_Essentials/CircuitPython_Internal_RGB_LED_rainbow/ and then click on the directory that matches the version of CircuitPython you're using and copy the contents of that directory to your CIRCUITPY drive.

Your CIRCUITPY drive should now look similar to the following image:

CIRCUITPY
# SPDX-FileCopyrightText: 2018 Kattni Rembor for Adafruit Industries
#
# SPDX-License-Identifier: MIT

"""CircuitPython Essentials Internal RGB LED rainbow example"""
import time
import board
from rainbowio import colorwheel

if hasattr(board, "APA102_SCK"):
    import adafruit_dotstar

    led = adafruit_dotstar.DotStar(board.APA102_SCK, board.APA102_MOSI, 1)
else:
    import neopixel

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

led.brightness = 0.3

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

We add the colorwheel 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 colorwheel() 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 May 12, 2019. It was last updated on Mar 29, 2024.

This page (CircuitPython Internal RGB LED) was last updated on Mar 29, 2024.

Text editor powered by tinymce.