Skip to content

LED Pattern Commands

This page describes the pattern commands that are implemented in the firmware.

range

range (LedRange) - set range of pixels to a color.

This command is used to set a range of one or more pixels to a fixed color. The format is:

$range,<start-pixel>,<num-pixels>,<color1>,<color2>,<color3>
  • start-pixel - the starting pixel number (0-origin) of the range
  • num-pixels - the number of pixels to include in the range
  • color1/2/3 - the value of each of the three color fields, 0-255

The color format is usually RGB or GRB. You can experiment setting each in turn to see how they are mapped with your hardware.

The main purpose of this command is for prototyping and debugging. Once a pattern is defined, it should be implemented as a new command class in this code.

Example

Set pixels 10-19 to blue at half intensity:

$range,10,10,0,0,128

The range command does not have any configuration settings.

meter

meter (LedMeter) - show a level meter over a range of pixels, with gradient.

This command is used to show a "level meter" or "progress meter" over a range of pixels in the LED strip. The command has a "percent" parameter which lights up the corresponding number of pixels over a defined range. There can also be a color gradient. For example all green at the low end and progressively getting redder as the value increases.

The command format is:

$meter,<percent>

where percent is 0-100.

Prior to using, the meter command must be configured to specify the pixels that are part of the meter display, and the color gradient to use. The config command has the following format:

$config,meter,<start-pxel>,<stop-pixel>,<r0>,<rN>,<g0>,<gN>,<b0>,<bN>
  • start-pixel - the beginning pixel of the meter display
  • stop-pixel - the ending pixel of the meter display, inclusive
  • r0 - the beginning value for "red"
  • rN - the ending value for "red"
  • g0/gN - begin/end value for "green"
  • b0/bN - begin/end value for "blue"

NOTES:

  • The colors listed above assume RGB format. Swap values if your order is GRB.
  • The start pixel and stop pixel can be in either increasing or decreasing order
  • the config only need to be done once for a given powered session. If the controller board is repowered or reset, the config command must be sent again

Example

A meter function is defined to go from pixel 0 to pixel 19 (20 pixels), in the increasing direction. It should be fully red at the low end, and fully green at the full end. The colors in mid-scale will be interpolated between the two ends.

$config,meter,0,19,255,0,0,255,0,0

To set the meter display to 50%, half the pixels (10) will be lit ranging from red at the lowest end to yellow-ish in the middle:

$meter,50

There is one meter command built-in, named meter. Additional meter instances can be added using the add command.

$add,meter2,LedMeter

Will create a second meter function, named meter2. It can be configured for a different set of pixels and different gradient so you can have two different meter displays on a single LED strip.

random

random - random pattern commands.

LedRandom

Bases: CommandTemplate

Configurable random pattern generator.

This command generates a pattern similar to randomog. But it has configurable options. Originally, random colors were used for each pixel. But that ends up with most pixels ahve all 3 of RGB turned on which ends up just making mostly pastels. This pattern generates random colors for each channel, but then randomly chooses only one or two of those channels to mix together (there is also a chance of all 3 channels but it is low probability). This results in much brighter colors and more bright reds, greens, and blues. It just looks more colorful.

At some period, a random spot on the LED strip is selected, and a random number of sequential pixels are lit, with a random color as described above. There is also some probability that pixels are set to dark.

The command itself takes no parameters:

$random

But it has a configuration:

$config,random,<dark-threshold>,<max-intensity>,<num-pixels>,<delayus>
  • dark-threshold - a random value from 0-255 is compared to the dark threshold. If it is below the threshold then the color will be dark (off). For example, to make there be a 50% chance of dark pixels, use a value of 128.
  • max-intensity - this is a mask that limits the value of a color channel. It is ANDed with the random color. It should probably be a power of 2, minus 1, or you will get strange results. For example, 127, 63, 31, etc. If you select 127 (the default) then that will force the upper bit to always be off, which limits the max intensity for any channel to 127. The reason for doing this is to reduce the overall power consumed by the LED strip. If you want max intensity without any limit, then set this value to 255.
  • num-pixels - this should 1 or more. It is the maximum number of consecutive pixels that will be lit up. The algorithm uses a random number between 1 and this value. The default is 5.
  • delayus - the repeat period in microseconds. The lower the number, the faster the pattern updates. The default is 100000 which is 100 milliseconds.
Source code in ledstrip/ledrandom.py 
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
class LedRandom(CommandTemplate):
    """Configurable random pattern generator.

    This command generates a pattern similar to *randomog*. But it has
    configurable options. Originally, random colors were used for each pixel.
    But that ends up with most pixels ahve all 3 of RGB turned on which ends up
    just making mostly pastels. This pattern generates random colors for each
    channel, but then randomly chooses only one or two of those channels to
    mix together (there is also a chance of all 3 channels but it is low
    probability). This results in much brighter colors and more bright reds,
    greens, and blues. It just looks more colorful.

    At some period, a random spot on the LED strip is selected, and a random
    number of sequential pixels are lit, with a random color as described
    above. There is also some probability that pixels are set to dark.

    The command itself takes no parameters:

        $random

    But it has a configuration:

        $config,random,<dark-threshold>,<max-intensity>,<num-pixels>,<delayus>

    * dark-threshold - a random value from 0-255 is compared to the dark
      threshold. If it is below the threshold then the color will be dark (off).
      For example, to make there be a 50% chance of dark pixels, use a value of
      128.
    * max-intensity - this is a mask that limits the value of a color channel.
      It is ANDed with the random color. It should probably be a power of 2,
      minus 1, or you will get strange results. For example, 127, 63, 31, etc.
      If you select 127 (the default) then that will force the upper bit to
      always be off, which limits the max intensity for any channel to 127.
      The reason for doing this is to reduce the overall power consumed by the
      LED strip. If you want max intensity without any limit, then set this
      value to 255.
    * num-pixels - this should 1 or more. It is the maximum number of
      consecutive pixels that will be lit up. The algorithm uses a random
      number between 1 and this value. The default is 5.
    * delayus - the repeat period in microseconds. The lower the number, the
      faster the pattern updates. The default is 100000 which is 100
      milliseconds.
    """
    helpstr = "show random colors"
    cfgstr = "dark-threshold(0-255),max-intensity(0-255),num-pixels,delay_us"

    chooser = [0x0000FF, 0x00FF00, 0x00FFFF,
               0xFF0000, 0xFF00FF, 0xFFFF00, 0xFFFFFF]

    def __init__(self):
        super().__init__()
        self._dark_threshold = 77  # 30% chance of dark
        self._max_intensity = 0x7F7F7F
        self._max_pixels = 5
        self._delay = 100000 # 100 ms

    # cfglist[0] - "config"
    # cfglist[1] - "random"
    # cfglist[2] - dark threshold (0-255)
    # cfglist[3] - max intensity (0-255)
    # cfglist[4] - max number of pixels to light
    # cfglist[5] - periodic delay in microseconds
    def config(self, cfglist: list[str]) -> None:
        # do bare minimum error checking
        if len(cfglist) == 6:
            self._dark_threshold = int(cfglist[2]) & 0xff
            intens = int(cfglist[3]) & 0xFF
            self._max_intensity = (intens << 16) + (intens << 8) + intens
            self._max_pixels = int(cfglist[4])
            self._delay = int(cfglist[5])

    def render(self, parmlist, framebuf):
        # get a random color value (all 3 colors)
        color = randrange(0x7FFFFFFF)
        # use upper 8 bits as probability of dark
        dark = color >> 24
        if dark < self._dark_threshold:
            # below dark threshold so set color to 0 (off)
            color = 0
        else:
            # use the lower 3 bytes for the pixel value
            # apply the color chooser, then the intensity cap
            color = color & randchoice(self.chooser)
            color = color & self._max_intensity  # cap the intensity

        # determine number of pixels to light
        numpixels = randint(1, self._max_pixels)

        # determine starting pixel
        startpix = randrange(len(framebuf) - numpixels)

        # set the affected pixels
        for pix in range(numpixels):
            framebuf[startpix+pix] = color

        # return the rerun period
        return self._delay

LedRandomOG

Bases: CommandTemplate

Random pattern based on Bill's pattern 2.

This command lights one or more LEDs in the string at random locations and with random colors. It is based on Bill's original pattern 2 code. This command has no configuration and no parameters. It is just invoked by itself:

$randomog
Source code in ledstrip/ledrandom.py 
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
class LedRandomOG(CommandTemplate):
    """Random pattern based on Bill's pattern 2.

    This command lights one or more LEDs in the string at random locations and
    with random colors. It is based on Bill's original pattern 2 code. This
    command has no configuration and no parameters. It is just invoked by
    itself:

        $randomog
    """
    helpstr = "bill's original pattern2"
    cfgstr = "no configs"

    def __init__(self):
        super().__init__()

    # def config(self, cfglist):

    def render(self, parmlist, framebuf):
        # this is a rewriting of Bill's underhoodLights algorithm for
        # pattern 2. The code looks different but the outcome should be the
        # same or simimlar.
        # TODO rewrite as lookup table or similar

        # determine random elements
        colorChooser = randint(0, 100)
        startPixel = randint(0, 410)
        numPixels = randint(1, 5)
        grn = randint(20, 255) << 16
        red = randint(20, 255) << 8
        blu = randint(20, 255)

        # select which colors to apply
        if colorChooser < 30:
            color = 0
        elif colorChooser < 35:  # green
            color = grn
        elif colorChooser < 40:  # red
            color = red
        elif colorChooser < 45:  # blue
            color = blu
        elif colorChooser < 50:  # red/green
            color = grn + red
        elif colorChooser < 55:  # green/blue
            color = grn + blu
        elif colorChooser < 60:  # red/blue
            color = red + blu
        elif colorChooser < 70:  # more green
            color = grn
        else:
            color = grn + red + blu

        # set the pixels in the frame buffer
        for pix in range(startPixel, startPixel+numPixels+1):
            framebuf[pix] = color

        # rerun every 100 ms
        return 100000

stop

stop - stop running pattern with optional clear.

LedStop

Bases: CommandTemplate

Stop the running pattern with option to clear display.

This command will stop any running pattern. There is an optional parameter, which if '1', will also clear the diplay.

Examples

$stop
$stop,0
$stop,1
Source code in ledstrip/ledstop.py 
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
class LedStop(CommandTemplate):
    """Stop the running pattern with option to clear display.

    This command will stop any running pattern. There is an optional parameter,
    which if '1', will also clear the diplay.

    *Examples*

        $stop
        $stop,0
        $stop,1
    """
    helpstr = "stop running pattern (stop,<clearflag>)"
    cfgstr = "no configs"

    def render(self, parmlist: list[str], framebuf: list[int]):
        clearflag = int(parmlist[1]) if len(parmlist) == 2 else 0
        if clearflag:
            for pix in range(len(framebuf)):
                framebuf[pix] = 0