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¶

# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT

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 -> 192
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(0.25)

`adafruit_dotstar` - DotStar strip driver (for CircuitPython 5.0+ with _pixelbuf)¶

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

adafruit_dotstar.BGR = 'PBGR'¶: Blue Green Red

adafruit_dotstar.BRG = 'PBRG'¶: Blue Red Green

class adafruit_dotstar.DotStar(clock, data, n, *, brightness=1.0, auto_write=True, pixel_order='PBGR', 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 (str) – 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)

show()¶

Shows the new colors on the dotstars 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.

fill(color)¶: Colors all dotstars the given *color*.

brightness¶: Overall brightness of all dotstars (0 to 1.0)

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

n¶: The number of dotstars in the chain (read-only)

adafruit_dotstar.GBR = 'PGBR'¶: Green Blue Red

adafruit_dotstar.GRB = 'PGRB'¶: Green Red Blue

adafruit_dotstar.RBG = 'PRBG'¶: Red Blue Green

adafruit_dotstar.RGB = 'PRGB'¶: Red Green Blue