Adafruit CircuitPython DotStar¶

Higher level DotStar driver that presents the strip as a sequence. It is the same api as the NeoPixel library.

Colors are stored as tuples by default. However, you can also use int hex syntax to set values similar to colors on the web. For example, 0x100000 (#100000 on the web) is equivalent to (0x10, 0, 0).

If you send a tuple with 4 values, you can control the brightness value, which appears in DotStar but not NeoPixels. It should be a float. For example, (0xFF,0,0, 1.0) is the brightest red possible, (1,0,0,0.01) is the dimmest red possible.

Note

The int hex API represents the brightness of the white pixel when present by setting the RGB channels to identical values. For example, full white is 0xffffff but is actually (0xff, 0xff, 0xff) in the tuple syntax.

Dependencies¶

This driver depends on:

Adafruit CircuitPython

Please ensure all dependencies are available on the CircuitPython filesystem. This is easily achieved by downloading the Adafruit library and driver bundle.

Installing from PyPI¶

On supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally from PyPI. To install for current user:

pip3 install adafruit-circuitpython-dotstar

To install system-wide (this may be required in some cases):

sudo pip3 install adafruit-circuitpython-dotstar

To install in a virtual environment in your current project:

mkdir project-name && cd project-name
python3 -m venv .env
source .env/bin/activate
pip3 install adafruit-circuitpython-dotstar

Usage Example¶

This example demonstrates the library with the single built-in DotStar on the Trinket M0 and Gemma M0.

import board
import adafruit_dotstar

pixels = adafruit_dotstar.DotStar(board.APA102_SCK, board.APA102_MOSI, 1)
pixels[0] = (10, 0, 0)

Contributing¶

Contributions are welcome! Please read our Code of Conduct before contributing to help this project stay welcoming.

Documentation¶

For information on building library documentation, please check out this guide.

Table of Contents¶

Simple test¶

Ensure your device works with this simple test.

examples/dotstar_simpletest.py¶

import time
import random
import board
import 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.2)

# Using a DotStar Digital LED Strip with 30 LEDs connected to hardware SPI
# dots = dotstar.DotStar(board.SCK, board.MOSI, 30, brightness=0.2)

# Using a DotStar Digital LED Strip with 30 LEDs connected to digital pins
# dots = dotstar.DotStar(board.D6, board.D5, 30, brightness=0.2)


# HELPERS
# a random color 0 -> 224
def random_color():
    return random.randrange(0, 7) * 32


# MAIN LOOP
n_dots = len(dots)
while True:
    # Fill each dot with a random color
    for dot in range(n_dots):
        dots[dot] = (random_color(), random_color(), random_color())

    time.sleep(.25)

`adafruit_dotstar` - DotStar strip driver¶

Author(s): Damien P. George, Limor Fried & Scott Shawcroft

class adafruit_dotstar.DotStar(clock, data, n, *, brightness=1.0, auto_write=True, pixel_order=(2, 1, 0), baudrate=4000000)[source]¶

A sequence of dotstars.

Parameters:

clock (Pin) – The pin to output dotstar clock on.
data (Pin) – The pin to output dotstar data on.
n (int) – The number of dotstars in the chain
brightness (float) – Brightness of the pixels between 0.0 and 1.0
auto_write (bool) – True if the dotstars should immediately change when set. If False, show must be called explicitly.
pixel_order (tuple) – Set the pixel order on the strip - different strips implement this differently. If you send red, and it looks blue or green on the strip, modify this! It should be one of the values above.
baudrate (int) – Desired clock rate if using hardware SPI (ignored if using ‘soft’ SPI). This is only a recommendation; the actual clock rate may be slightly different depending on what the system hardware can provide.

Example for Gemma M0:

import adafruit_dotstar
import time
from board import *

RED = 0x100000

with adafruit_dotstar.DotStar(APA102_SCK, APA102_MOSI, 1) as pixels:
    pixels[0] = RED
    time.sleep(2)

brightness¶: Overall brightness of the pixel

deinit()[source]¶: Blank out the DotStars and release the resources.

fill(color)[source]¶: Colors all pixels the given *color*.

show()[source]¶

Shows the new colors on the pixels themselves if they haven’t already been autowritten.

The colors may or may not be showing after this function returns because it may be done asynchronously.