GlowBit Matrix 8x8 - Python and MicroPython Guide

Introduction

This guide will cover the basic functionality of the GlowBit Python library when driving a GlowBit Matrix 8x8 module.

To follow along, it's best to have:

• A GlowBit Matrix 8x8
• A Raspberry Pi Pico or Raspberry Pi
• Some Pin Headers
• Three jumper wires (eg Female-Female, Male-Male,  or Female-Male, as appropriate)
• Appropriate wire for a power cable, rated to at least 2A per GlowBit Matrix 8x8 module

• Function Listing
• Soldering a Pin Header and Pinout
• Connecting the GlowBit Matrix 8x8
• Download MicroPython Modules
• Creating a GlowBit Matrix "Object"
• Running a Test Demo
• GlowBit Colours
• Lighting up Individual Pixels
• The Colour Wheel
• Scrolling Static Text
• Filling All Pixels With a Solid Colour
• Lines, Rectangles, Triangles, and Circles
• Bar Graphs
• Plots
• Animation Guidelines
• Tiling Multiple GlowBit Matrix 8x8 Modules

Function Listing

A full listing of the available functions can be found in the documentation.

Soldering a Pin Header and Pinout

Connecting the GlowBit Matrix 8x8

Download MicroPython Modules

The GlowBit MicroPython module requires two files:

glowbit.py (right-click, "save link as")

petme128.py (right-click, "save link as")

The GlowBit module can also be installed through the Thonny package manager.

If you are running from a Raspberry Pi you will also need the low-level rpi-ws281x module. It can be found through Thonny's package manager or you can install it from the console with sudo pip3 install rpi-ws281x.

Creating a GlowBit Matrix "Object"

The glowbit.matrix8x8() object contains all the functionality required to create fun projects with your GlowBit Matrix 8x8 module.

For greater flexibility, the glowbit.matrix8x8() object takes several keyword arguments which modify how the GlowBit behaves. The most crucial ones, with their default values, are:

• brightness = 20
• rateLimitFPS = 30
• pin = 18

The brightness argument can either be an integer between 1 and 255 or a decimal value between 0.0 and 1.0. The brightness of the entire display is scaled by this value.

The rateLimitFPS argument allows the update rate of the display to be limited so that delays don't need to be manually programmed.

For example, to drive a GlowBit at full brightness with an update rate of 5 frames per second the following code can be used:

import glowbit

matrix = glowbit.matrix4x4(brightness = 255, rateLimitFPS = 5)

Running a Test Demo

To make sure the GlowBit module and Python libraries are all configured correctly you can run this 3-line program to display a series of demonstration patterns:

import glowbit

matrix = glowbit.matrix8x8()

matrix.demo()

While executing, the following output will be printed to the Python shell:

matrix.fireworks()
matrix.textDemo()
matrix.circularRainbow()
matrix.rain()
matrix.lineDemo()
matrix.bounce()

These functions can be called individually and you can study their code in glowbit.py by searching for fireworks(), circularRainbow(), etc.

GlowBit Colours

When specifying colours for GlowBit library functions a 32-bit GlowBit colour value is required. This is an integer which contains the red, green, and blue intensity "packed" into a single number.

In order to easily create colour values the function stick.rgbColour(r,g,b) is provided. It accepts red, green, and blue (RGB) intensity values scaled from 0 to 255 (inclusive) and returns a GlowBit colour value which can be used wherever colour is needed in the GlowBit library.

For convenience, the following functions are provided and return commonly used colours:

matrix.red()
matrix.green()
matrix.blue()
matrix.yellow()
matrix.purple()
matrix.cyan()
matrix.white()
matrix.black()

Lighting up Individual Pixels

The GlowBit Matrix library contains the function matrix.pixelSetXY(x,y,colour) for setting the colour of individual pixels at a particular location on the display.

The x and y coordinates start at x=0, y=0 in the upper left corner of the display. Increasing x moves to the right and increasing y moves downwards. 

For example, the following code sets the upper left pixel to white and the pixel at x=1, y=2 to a custom RGB value:

import glowbit

matrix = glowbit.matrix8x8()

colour = matrix.white()
x = 0
y = 0
matrix.pixelSetXY(x,y, colour)

matrix.pixelSetXY(1,2,matrix.rgbColour(100,200,50))

matrix.pixelsShow()

Note the use of the function matrix.pixelsShow(). The GlowBit drawing functions only change an internal frame buffer which only exists in memory until matrix.pixelsShow() copies the frame buffer data to the physical LEDs.

The Colour Wheel

The GlowBit library provides the function matrix.wheel() which returns a full-intensity pure colour from the colour wheel. The function takes a single argument which is a colour wheel "angle" from 0 to 255. Both 0 and 255 are aligned with red, with the wheel returning red-yellow-green-cyan-blue-magenta-red for other values.

The following example uses the matrix.wheel() and matrix.putPixelXY() functions to display a colour gradient on the GlowBit Matrix 8x8:

import glowbit

matrix = glowbit.matrix8x8()

for x in range(8):
    for y in range(8):
        c = matrix.wheel(18*(x y))
        matrix.pixelSetXY(x, y, c)

matrix.pixelsShow()

You don't need to be too careful about keeping the matrix.wheel() argument between 0 and 255 - if it is outside this range it will still "wrap" to an angle within the [0,255] range. 

Scrolling Text

The GlowBit Matrix 8x8 is large enough to display a single 8x8 pixel text character. The GlowBit library supports static text display with matrix.drawChar() and matrix.printTextWrap() along with animated scrolling text with matrix.addTextScroll() and matrix.updateTextScroll().

Scrolling text is perhaps the most useful of these functions as it allows the display of long strings of text on a single GlowBit Matrix 8x8 display.

Producing scrolling text, as with most animated GlowBit library objects, is a two step process:

1. Call matrix.addTextScroll(string) to add a scrolling text string to an internal list inside the matrix object
2. Call matrix.updateTextScroll() each time the scrolling text animation needs to be updated

Separating scrolling text into these two steps allows text scrolling to be synchronised with other animated elements using matrix.pixelsShow().

There also exists the variable matrix.scrollingText which is set to True while at least one scrolling text object is still animating and False otherwise.

Given all this, we can now look at a full example:

import glowbit

matrix = glowbit.matrix8x8(rateLimitCharactersPerSecond = 1)

matrix.addTextScroll("Hello there!")

while matrix.scrollingText == True:
    matrix.updateTextScroll()
    matrix.pixelsShow()

Note the use of the keyword argument rateLimitCharactersPerSecond=1 when creating the matrix object. Scrolling text moves one pixel each frame, and each character is 8 pixels wide, so this argument sets the frame rate so that 1 character scrolls past the screen each second.

Common keyword arguments to use with matrix.addTextScroll(), with their default values, are:

• colour = matrix.white() - Specifies the colour of the text characters; a GlowBit colour value
• blocking = False - If this is set to True the scrolling text animation will happen automatically and the function will "block" (ie: not return) until it is finished

For example, the following code displays light green scrolling text and animates automatically:

import glowbit

matrix = glowbit.matrix8x8(rateLimitCharactersPerSecond = 1)

matrix.addTextScroll("Hello there!", colour = matrix.rgbColour(100, 250, 0), blocking = True)

Automatic animations are convenient, but prohibit other graphical elements to be drawn while the text is animating.

Filling All Pixels With a Solid Colour

If you're after an RGB light source with a single colour the matrix8x8.pixelsFill(colour) function can be used to avoid needing to set every pixel individually.

The following example uses a single loop, and a frame rate limit of 80 frames per second, to create an animated "rainbow" light source:

import glowbit

matrix = glowbit.matrix8x8(rateLimitFPS = 80)

for i in range(512):
    c = matrix.wheel(i)
    matrix.pixelsFill(c)
    matrix.pixelsShow()

Note that the argument to matrix.wheel(i) can be larger than 255 and the colour wheel just repeats itself. In this example it goes all the way to 512 so colour wheel is cycled twice.

Lines, Rectangles, Triangles, and Circles

Drawing basic shapes is done with the GlowBit library functions shown in the table below.

All x and y arguments are in units of pixels and all colour arguments are GlowBit colour values.

For example, the following code uses matrix.drawRectangle() to draw an outline around the edges of a single GlowBit Matrix 8x8 module:

import glowbit

matrix = glowbit.matrix8x8()

matrix.drawRectangle(0,0, 7,7, matrix.white())
matrix.pixelsShow()

Bar Graphs

The matrix.graph1D() object allows drawing of a single pixel wide bar graph with a length set by some given value.

When creating a new graph object you will typically need to specify several keyword arguments which control how the graph is drawn. The object is optimised for the GlowBit Matrix 8x8 module but also works with the GlowBit Matrix 4x4.

You can think of a graph1D() object as a section of the "number line" with left and right edges specified by the minValue and maxValue keyword arguments. When plotting a new value it will illuminate all pixels less than where that value falls on the number line.

The commonly required keyword arguments, with their default values, are as follows: