GlowBit Matrix 4x4 - Python and MicroPython Guide

Introduction

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

To follow along, it's best to have:

• A GlowBit Matrix 4x4
• A Raspberry Pi Pico or Raspberry Pi
• Some Pin Headers
• Three jumper wires (eg Female-Female, Male-Male,  or Female-Male, as appropriate)

Function Listing

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

Soldering a Pin Header

Connecting the GlowBit Matrix 4x4

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.matrix4x4() object contains all the functionality required to create fun projects with your GlowBit Matrix 4x4 module.

For greater flexibility, the matrix4x4() 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.matrix4x4()

matrix.demo()

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

matrix.fireworks()
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 other functions exist 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 matrix4x4.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.matrix4x4()

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 4x4:

import glowbit

matrix = glowbit.matrix4x4()

for x in range(4):
    for y in range(4):
        c = matrix.wheel(36*(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. 

Filling All Pixels With a Solid Colour

If you're after an RGB light source with a single colour the matrix4x4.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.matrix4x4(rateLimitFPS = 80)

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

Note that the argument to matrix4x4.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 4x4 module:

import glowbit

matrix = glowbit.matrix4x4()

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