Merge pull request adafruit#1082 from jepler/circuitpython-rgbmatrix-1

CircuitPython_RGBMatrix: Add additional example, comment them

Author: jepler

CircuitPython_RGBMatrix/fruit.py

@@ -15,18 +15,28 @@
     clock_pin=board.D13, latch_pin=board.D0, output_enable_pin=board.D1)
 display = framebufferio.FramebufferDisplay(matrix, auto_refresh=False)
 
+# This bitmap contains the emoji we're going to use. It is assumed
+# to contain 20 icons, each 20x24 pixels. This fits nicely on the 64x32
+# RGB matrix display.
 bitmap_file = open("emoji.bmp", 'rb')
 bitmap = displayio.OnDiskBitmap(bitmap_file)
 
+# Each wheel can be in one of three states:
 STOPPED, RUNNING, BRAKING = range(3)
 
+# Return a duplicate of the input list in a random (shuffled) order.
 def shuffled(seq):
     return sorted(seq, key=lambda _: random.random())
 
-class Strip(displayio.TileGrid):
+# The Wheel class manages the state of one wheel. "pos" is a position in
+# scaled integer coordinates, with one revolution being 7680 positions
+# and 1 pixel being 16 positions. The wheel also has a velocity (in positions
+# per tick) and a state (one of the above constants)
+class Wheel(displayio.TileGrid):
     def __init__(self):
+        # Portions of up to 3 tiles are visible.
         super().__init__(bitmap=bitmap, pixel_shader=displayio.ColorConverter(),
-                         width=1, height=4, tile_width=20, tile_height=24)
+                         width=1, height=3, tile_width=20)
         self.order = shuffled(range(20))
         self.state = STOPPED
         self.pos = 0
@@ -36,62 +46,91 @@ def __init__(self):
         self.stop_time = time.monotonic_ns()
 
     def step(self):
+        # Update each wheel for one time step
         if self.state == RUNNING:
+            # Slowly lose speed when running, but go at least speed 64
             self.vel = max(self.vel * 9 // 10, 64)
             if time.monotonic_ns() > self.stop_time:
                 self.state = BRAKING
         elif self.state == BRAKING:
+            # More quickly lose speed when baking, down to speed 7
             self.vel = max(self.vel * 85 // 100, 7)
+
+        # Advance the wheel according to the velocity, and wrap it around
+        # after 7680 positions
         self.pos = (self.pos + self.vel) % 7680
+
+        # Compute the rounded Y coordinate
         yy = round(self.pos / 16)
+        # Compute the offset of the tile (tiles are 24 pixels tall)
         yyy = yy % 24
+        # Find out which tile is the top tile
         off = yy // 24
+
+        # If we're braking and a tile is close to midscreen,
+        # then stop and make sure that tile is exactly centered
         if self.state == BRAKING and self.vel == 7 and yyy < 4:
             self.pos = off * 24 * 16
             self.vel = 0
             yy = 0
             self.state = STOPPED
-        self.y = yy % 24 - 20
-        for i in range(4):
+
+        # Move the displayed tiles to the correct height and make sure the
+        # correct tiles are displayed.
+        self.y = yyy - 20
+        for i in range(3):
             self[i] = self.order[(19 - i + off) % 20]
 
+    # Set the wheel running again, using a slight bit of randomness.
+    # The 'i' value makes sure the first wheel brakes first, the second
+    # brakes second, and the third brakes third.
     def kick(self, i):
         self.state = RUNNING
         self.vel = random.randint(256, 320)
         self.stop_time = time.monotonic_ns() + 3000000000 + i * 350000000
 
-    def brake(self):
-        self.state = BRAKING
-
+# Our fruit machine has 3 wheels, let's create them with a correct horizontal
+# (x) offset and arbitrary vertical (y) offset.
 g = displayio.Group(max_size=3)
-strips = []
+wheels = []
 for idx in range(3):
-    strip = Strip()
-    strip.x = idx * 22
-    strip.y = -20
-    g.append(strip)
-    strips.append(strip)
+    wheel = Wheel()
+    wheel.x = idx * 22
+    wheel.y = -20
+    g.append(wheel)
+    wheels.append(wheel)
 display.show(g)
 
+# Make a unique order of the emoji on each wheel
 orders = [shuffled(range(20)), shuffled(range(20)), shuffled(range(20))]
 
-for si, oi in zip(strips, orders):
-    for idx in range(4):
+# And put up some images to start with
+for si, oi in zip(wheels, orders):
+    for idx in range(3):
         si[idx] = oi[idx]
 
+# We want a way to check if all the wheels are stopped
 def all_stopped():
-    return all(si.state == STOPPED for si in strips)
+    return all(si.state == STOPPED for si in wheels)
 
-for idx, si in enumerate(strips):
+# To start with, though, they're all in motion
+for idx, si in enumerate(wheels):
     si.kick(idx)
 
+# Here's the main loop
 while True:
+    # Refresh the dislpay (doing this manually ensures the wheels move
+    # together, not at different times)
     display.refresh(minimum_frames_per_second=0)
     if all_stopped():
+        # Once everything comes to a stop, wait a little bit and then
+        # start everything over again.  Maybe you want to check if the
+        # combination is a "winner" and add a light show or something.
         for idx in range(100):
             display.refresh(minimum_frames_per_second=0)
-        for idx, si in enumerate(strips):
+        for idx, si in enumerate(wheels):
             si.kick(idx)
 
-    for idx, si in enumerate(strips):
+    # Otherwise, let the wheels keep spinning...
+    for idx, si in enumerate(wheels):
         si.step()

CircuitPython_RGBMatrix/life.py

@@ -8,6 +8,24 @@
 
 displayio.release_displays()
 
+# Conway's "Game of Life" is played on a grid with simple rules, based
+# on the number of filled neighbors each cell has and whether the cell itself
+# is filled.
+#   * If the cell is filled, and 2 or 3 neighbors are filled, the cell stays
+#     filled
+#   * If the cell is empty, and exactly 3 neighbors are filled, a new cell
+#     becomes filled
+#   * Otherwise, the cell becomes or remains empty
+#
+# The complicated way that the "m1" (minus 1) and "p1" (plus one) offsets are
+# calculated is due to the way the grid "wraps around", with the left and right
+# sides being connected, as well as the top and bottom sides being connected.
+#
+# This function has been somewhat optimized, so that when it indexes the bitmap
+# a single number [x + width * y] is used instead of indexing with [x, y].
+# This makes the animation run faster with some loss of clarity. More
+# optimizations are probably possible.
+
 def apply_life_rule(old, new):
     width = old.width
     height = old.height
@@ -25,31 +43,36 @@ def apply_life_rule(old, new):
             new[x+yyy] = neighbors == 3 or (neighbors == 2 and old[x+yyy])
             xm1 = x
 
-def randomize(output, fraction=0.50):
+# Fill 'fraction' out of all the cells.
+def randomize(output, fraction=0.33):
     for i in range(output.height * output.width):
         output[i] = random.random() < fraction
 
-# after xkcd's tribute to John Conway (1937-2020) https://xkcd.com/2293/
-conway_data = [
-    b'  +++   ',
-    b'  + +   ',
-    b'  + +   ',
-    b'   +    ',
-    b'+ +++   ',
-    b' + + +  ',
-    b'   +  + ',
-    b'  + +   ',
-    b'  + +   ',
-]
 
+# Fill the grid with a tribute to John Conway
 def conway(output):
+    # based on xkcd's tribute to John Conway (1937-2020) https://xkcd.com/2293/
+    conway_data = [
+        b'  +++   ',
+        b'  + +   ',
+        b'  + +   ',
+        b'   +    ',
+        b'+ +++   ',
+        b' + + +  ',
+        b'   +  + ',
+        b'  + +   ',
+        b'  + +   ',
+    ]
     for i in range(output.height * output.width):
         output[i] = 0
     for i, si in enumerate(conway_data):
         y = output.height - len(conway_data) - 2 + i
         for j, cj in enumerate(si):
             output[(output.width - 8)//2 + j, y] = cj & 1
 
+# bit_depth=1 is used here because we only use primary colors, and it makes
+# the animation run a bit faster because RGBMatrix isn't taking over the CPU
+# as often.
 matrix = rgbmatrix.RGBMatrix(
     width=64, height=32, bit_depth=1,
     rgb_pins=[board.D6, board.D5, board.D9, board.D11, board.D10, board.D12],
@@ -68,21 +91,28 @@ def conway(output):
 g2 = displayio.Group(max_size=3, scale=SCALE)
 g2.append(tg2)
 
+# First time, show the Conway tribute
 palette[1] = 0xffffff
 conway(b1)
 display.auto_refresh = True
 time.sleep(3)
 n = 40
 
 while True:
+    # run 2*n generations.
+    # For the Conway tribute on 64x32, 80 frames is appropriate.  For random
+    # values, 400 frames seems like a good number.  Working in this way, with
+    # two bitmaps, reduces copying data and makes the animation a bit faster
     for _ in range(n):
         display.show(g1)
         apply_life_rule(b1, b2)
         display.show(g2)
         apply_life_rule(b2, b1)
 
+    # After 2*n generations, fill the board with random values and
+    # start over with a new color.
     randomize(b1)
-    palette[0] = 0
+    # Pick a random color out of 6 primary colors or white.
     palette[1] = (
         (0x0000ff if random.random() > .33 else 0) |
         (0x00ff00 if random.random() > .33 else 0) |

CircuitPython_RGBMatrix/scroller.py

@@ -1,3 +1,12 @@
+# This example implements a rainbow colored scroller, in which each letter
+# has a different color. This is not possible with
+# Adafruit_Circuitpython_Display_Text, where each letter in a label has the
+# same color
+#
+# This demo also supports only ASCII characters and the built-in font.
+# See the simple_scroller example for one that supports alternative fonts
+# and characters, but only has a single color per label.
+
 import array
 
 from _pixelbuf import wheel
@@ -15,13 +24,18 @@
     clock_pin=board.D13, latch_pin=board.D0, output_enable_pin=board.D1)
 display = framebufferio.FramebufferDisplay(matrix, auto_refresh=False)
 
+# Create a tilegrid with a bunch of common settings
 def tilegrid(palette):
     return displayio.TileGrid(
         bitmap=terminalio.FONT.bitmap, pixel_shader=palette,
         width=1, height=1, tile_width=6, tile_height=14, default_tile=32)
 
 g = displayio.Group(max_size=2)
+
+# We only use the built in font which we treat as being 7x14 pixels
 linelen = (64//7)+2
+
+# prepare the main groups
 l1 = displayio.Group(max_size=linelen)
 l2 = displayio.Group(max_size=linelen)
 g.append(l1)
@@ -31,24 +45,29 @@ def tilegrid(palette):
 l1.y = 1
 l2.y = 16
 
+# Prepare the palettes and the individual characters' tiles
 sh = [displayio.Palette(2) for _ in range(linelen)]
 tg1 = [tilegrid(shi) for shi in sh]
 tg2 = [tilegrid(shi) for shi in sh]
 
+# Prepare a fast map from byte values to
 charmap = array.array('b', [terminalio.FONT.get_glyph(32).tile_index]) * 256
 for ch in range(256):
     glyph = terminalio.FONT.get_glyph(ch)
     if glyph is not None:
         charmap[ch] = glyph.tile_index
 
+# Set the X coordinates of each character in label 1, and add it to its group
 for idx, gi in enumerate(tg1):
     gi.x = 7 * idx
     l1.append(gi)
 
+# Set the X coordinates of each character in label 2, and add it to its group
 for idx, gi in enumerate(tg2):
     gi.x = 7 * idx
     l2.append(gi)
 
+#  These pairs of lines should be the same length
 lines = [
     b"This scroller is brought to you by    CircuitPython & PROTOMATTER",
     b"        .... . .-.. .-.. --- / .--. .-. --- - --- -- .- - - . .-.",
@@ -61,22 +80,30 @@ def tilegrid(palette):
 even_lines = lines[0::2]
 odd_lines = lines[1::2]
 
+# Scroll a top text and a bottom text
 def scroll(t, b):
+    # Add spaces to the start and end of each label so that it goes from
+    # the far right all the way off the left
     sp = b' ' * linelen
     t = sp + t + sp
     b = sp + b + sp
     maxlen = max(len(t), len(b))
+    # For each whole character position...
     for i in range(maxlen-linelen):
+        # Set the letter displayed at each position, and its color
         for j in range(linelen):
             sh[j][1] = wheel(3 * (2*i+j))
             tg1[j][0] = charmap[t[i+j]]
             tg2[j][0] = charmap[b[i+j]]
+        # And then for each pixel position, move the two labels
+        # and then refresh the display.
         for j in range(7):
             l1.x = -j
             l2.x = -j
             display.refresh(minimum_frames_per_second=0)
             #display.refresh(minimum_frames_per_second=0)
 
+# Repeatedly scroll all the pairs of lines
 while True:
     for e, o in zip(even_lines, odd_lines):
         scroll(e, o)