Arduino + Python + LED Matrix

John Lehmann — Mon, 06 Jan 2020 09:40:09 GMT

An LED Matrix

I went to Jaycar, looking for a WiFi module as I was thinking I'll need one for my e-paper calendar project. I walked out with a number of things including a Duinotech Uno with WiFi and an 8x8 red LED Matrix.

OMG The Pins

This is a little lesson about reading the documentation. I spent hours trying to upload a blink sketch to the Uno. I tried all the boards available in the IDE. I loaded more boards using the IDE Boards Manager. I did rend my clothes and tear my hair. Finally I looked at the Jaycar site to try to find some howto stories.

On the product page linked above I found a note:

Please note: you must upload code to both processors then configure the switches for them to talk to each other

And a manual, and in the manual I found found some very clear instructions explaining that you have to set some dip switches on the board in order to program the Arduino MCU.

As they are two separate processors, you must upload code to both processors for them to function. You can set this by configuring the dip switches as per the table below, so that the USB/programmer can communicate between both processors individually. Once you have finished programming, configure the dip switches so both of the processors can communicate with each other to send messages back and forth.

For the moment I am not using the wireless functionality, so I've just set the dip switches so that I can program the Arduino MCU.

Interactivity

To work with the Arduino you have to be able to program it in C++. But the compile, upload, run loop of C++ can be daunting and time consuming. A more interactive programming cycle can give you more freedom to try out ideas, let you be more creative and is generally helpful for learning. I do a lot of programming in Python and I wanted to see if there was some practical way of working with the Arduino with Python.

Firmata

Firmata is a protocol for communicating with microcontrollers from software on a host computer. The protocol can be implemented in firmware on any microcontroller architecture as well as software on any host computer software package.

You load a general purpose sketch called StandardFirmata (or StandardFirmataPlus in this example) on the Arduino board and then use the host computer exclusively to interact with the Arduino board. In the Arduino IDE the Firmata sketches can be found in File -> Examples -> Firmata.

PyMata

PyMata is a Python library for interacting with an system running Firmata. The library has three flavours, the most straightforward of which lets you interact directly with the Arduino from the python interpreter.

Firmata Hello World

A basic Firmata hello world is to turn the on-board LED on and off.

First you load the Firmata sketch onto the Arduino. I tried StandardFirmataPlus. I quickly became apparent that this would not run on the Duemilanove. The only Firmata sketch the would was the OldStandardFirmata sketch. The python library, however, would not connect to this. In the end I got StandardFirmataPlus running with the Uno.

The python library was easy to install with pip install pymata-aio

Turning the on board LED on and off:

from pymata_aio.pymata3 import PyMata3
from pymata_aio.constants import Constants
board = PyMata3(arduino_wait=5)

BOARD_LED = 13
def setup():
    board.set_pin_mode(BOARD_LED, Constants.OUTPUT)

def loop():
    print("LED On")
    board.digital_write(BOARD_LED, 1)
    board.sleep(1.0)
    print("LED Off")
    board.digital_write(BOARD_LED, 0)
    board.sleep(1.0)

setup()
while True:
    loop()

MaxMatrix

But why just light up one LED when you can use 64? I did some work with the C++ MaxMatrix library and then ported it to python so I could drive the matrix from the python command line.

Wiring The LED: The LED is easy to wire. The VCC and GND pins should be connected to 5V and GND. The remaining pins can be connected to any digital pins on the board. They just have to be correctly identified when using the software.

One nice thing about driving the Arduino interactively is that you don't need to worry about memory as much. I was able to add an additional method to the library to load a Dwarf Fortress tileset and use this as a convenient source of high quality 8x8-bit ascii graphics. I chose the Potash tileset

Some sample code:

from pymata_aio.pymata3 import PyMata3
from pymata_aio.constants import Constants
import maxmatrix

board = PyMata3(arduino_wait=5)
# I wired the LED to 11, 12 and 13
DIN, CLK, CS = 12, 13, 11
mm = maxmatrix.MaxMatrix(board, DIN, CS, CLK)
mm.set_column(0, 0b1011011)

Working with sprites from a tileset:

ts = maxmatrix.Tileset()
sprite = ts.get_sprite('7')
mm.write_sprite(sprite)

maxmatrix.py

Full code listing of my python port of the MaxMatrix library.

maxmatrix.py (Source)

	`"""`
	`A port of the MaxMatrix LED library to python for use with FirmataPlus.`
	`"""`
	`from pymata_aio.pymata3 import PyMata3 # type: ignore`
	`from pymata_aio.constants import Constants # type: ignore`

	`from PIL import Image`

	`MAX7219_REG_NOOP = 0x00`
	`MAX7219_REG_DIGIT0 = 0x01`
	`MAX7219_REG_DIGIT1 = 0x02`
	`MAX7219_REG_DIGIT2 = 0x03`
	`MAX7219_REG_DIGIT3 = 0x04`
	`MAX7219_REG_DIGIT4 = 0x05`
	`MAX7219_REG_DIGIT5 = 0x06`
	`MAX7219_REG_DIGIT6 = 0x07`
	`MAX7219_REG_DIGIT7 = 0x08`
	`MAX7219_REG_DECODEMODE = 0x09`
	`MAX7219_REG_INTENSITY = 0x0a`
	`MAX7219_REG_SCANLIMIT = 0x0b`
	`MAX7219_REG_SHUTDOWN = 0x0c`
	`MAX7219_REG_DISPLAYTEST = 0x0f`

	`LOW, HIGH = 0, 1`
	`LSBFIRST, MSBFIRST = 0, 1`

	`# Following bit shifting functons adapted from https://wiki.python.org/moin/BitManipulation`


	`def test_bit(value: int, offset: int) -> int:`
	`" Returns a 1, if the bit at 'offset' is one, else 0"`
	`mask = 1 << offset`
	`return 1 if (value & mask) else 0`


	`def set_bit(value: int, offset: int) -> int:`
	`" Returns an integer with the bit at 'offset' set to 1"`
	`mask = 1 << offset`
	`return (value \| mask)`


	`def clear_bit(value: int, offset: int) -> int:`
	`" Returns an integer with the bit at 'offset' cleared "`
	`mask = ~(1 << offset)`
	`return (value & mask)`


	`def toggle_bit(value: int, offset: int) -> int:`
	`" Returns an integer with the bit at 'offset' inverted, 0 -> 1 and 1 -> 0 "`
	`mask = 1 << offset`
	`return (value ^ mask)`


	`def write_bit(value: int, offset: int, bit: int) -> int:`
	`if bit == HIGH:`
	`return set_bit(value, offset)`
	`elif bit == LOW:`
	`return clear_bit(value, offset)`
	`else:`
	`raise Exception("bit must be high or low")`


	`class MaxMatrix:`

	`def __init__(self, board, data_pin: int, load_pin: int, clock_pin: int):`
	`self.board = board`
	`self.data_pin = data_pin`
	`self.load_pin = load_pin`
	`self.clock_pin = clock_pin`
	`self.buffer = bytearray(80)`

	`# initialise the LED display`
	`self.board.set_pin_mode(self.data_pin, Constants.OUTPUT)`
	`self.board.set_pin_mode(self.clock_pin, Constants.OUTPUT)`
	`self.board.set_pin_mode(self.load_pin, Constants.OUTPUT)`

	`self.board.digital_write(self.clock_pin, HIGH)`

	`self.set_command(MAX7219_REG_SCANLIMIT, 0x07)`
	`self.set_command(MAX7219_REG_DECODEMODE, 0x00) # using an led matrix (not digits)`
	`self.set_command(MAX7219_REG_SHUTDOWN, 0x01) # not in shutdown mode`
	`self.set_command(MAX7219_REG_DISPLAYTEST, 0x00) # no display test`

	`# empty registers, turn all LEDs off`
	`self.clear()`
	`self.set_intensity(0x0f) # the first 0x0f is the value you can set`

	`def reload(self) -> None:`
	`for col in range(8):`
	`self.board.digital_write(self.load_pin, LOW)`
	`self.shift_out(col + 1)`
	`self.shift_out(self.buffer[col])`
	`self.board.digital_write(self.load_pin, LOW)`
	`self.board.digital_write(self.load_pin, HIGH)`

	`def clear(self):`
	`self.buffer = bytearray(80)`
	`self.reload()`

	`def set_command(self, command: int, value: int):`
	`self.board.digital_write(self.load_pin, LOW)`

	`self.shift_out(command)`
	`self.shift_out(value)`

	`self.board.digital_write(self.load_pin, LOW)`
	`self.board.digital_write(self.load_pin, HIGH)`

	`def shift_out(self, value: int, bit_order: int=MSBFIRST):`
	`# Adapted from hardware/arduino/avr/cores/arduino/wiring_shift.c`
	`for i in range(8):`
	`if bit_order == LSBFIRST:`
	`b = HIGH if ~~(value & (1 << i)) else LOW`
	`else:`
	`b = HIGH if ~~(value & (1 << (7 - i))) else LOW`
	`self.board.digital_write(self.data_pin, b)`
	`self.board.digital_write(self.clock_pin, HIGH)`
	`self.board.digital_write(self.clock_pin, LOW)`

	`def set_intensity(self, intensity: int):`
	`self.set_command(MAX7219_REG_INTENSITY, intensity)`

	`def set_column(self, col: int, value: int):`
	`"""`
	`set the column to the value, for example:`
	`>>> mm.set_column(0, 0b11011001)`
	`"""`
	`self.board.digital_write(self.load_pin, LOW)`
	`self.shift_out(col + 1)`
	`self.shift_out(value)`
	`self.board.digital_write(self.load_pin, LOW)`
	`self.board.digital_write(self.load_pin, HIGH)`
	`self.buffer[col] = value`

	`def set_row(self, row: int, value: int):`
	`"""`
	`set the row to the value, for example:`
	`>>> mm.set_row(0, 0b11011001)`
	`"""`
	`for i in range(8):`
	`b = test_bit(value, i)`
	`self.buffer[i] = write_bit(self.buffer[i], row, b)`
	`self.reload()`

	`def set_dot(self, col: int, row: int, value: int):`
	`self.buffer[col] = write_bit(self.buffer[col], row, value)`
	`self.board.digital_write(self.load_pin, LOW)`
	`self.shift_out(col + 1)`
	`self.shift_out(self.buffer[col])`
	`self.board.digital_write(self.load_pin, LOW)`
	`self.board.digital_write(self.load_pin, HIGH)`

	`def shift_left(self, fill_zero: bool = False):`
	`if fill_zero:`
	`self.buffer = self.buffer[-1:] + bytearray(1)`
	`else:`
	`self.buffer = self.buffer[-1:] + self.buffer[:-1]`
	`self.reload()`

	`def shift_right(self, fill_zero: bool = False):`
	`if fill_zero:`
	`self.buffer = self.buffer[1:] + bytearray(1)`
	`else:`
	`self.buffer = self.buffer[1:] + self.buffer[:1]`
	`self.reload()`

	`def shift_up(self, fill_zero: bool = False):`
	`for i in range(len(self.buffer)):`
	`if fill_zero:`
	`self.buffer[i] = self.buffer[i] << 1`
	`else:`
	`self.buffer[i] = ((self.buffer[i] << 1) & 0xff) \| test_bit(self.buffer[i], 7)`
	`self.reload()`

	`def shift_down(self, fill_zero = False):`
	`for i in range(len(self.buffer)):`
	`if fill_zero:`
	`self.buffer[i] = self.buffer[i] >> 1`
	`else:`
	`self.buffer[i] = (self.buffer[i] >> 1) \| (test_bit(self.buffer[i], 0) << 7)`
	`self.reload()`

	`def write_sprite(self, sprite: bytearray, x: int = 0, y: int = 0):`
	`if x:`
	`sprite = sprite[:]`
	`for i in range(8):`
	`sprite[i] = sprite[i] >> x`
	`self.buffer[y:y+8] = sprite`
	`self.reload()`

	`def get_matrix(data, row, col):`
	`m = []`
	`for i in range(8):`
	`m.append(data[((i+8col)128) + (row * 8): ((i+8col) 128) + (row * 8) + 8])`
	`return m`


	`def make_sprite(matrix):`
	`ba = bytearray(8)`
	`for r in range(8):`
	`for c in range(8):`
	`bit = matrix[r][c]`
	`ba[7 - c] = write_bit(ba[7 - c], 7 - r, bit)`
	`return ba`


	`class Tileset:`

	`def __init__(self, tileset="Potash_8x8.png"):`
	`im = Image.open(tileset)`
	`data = list(im.getdata())`
	`sprites = {}`
	`for i in range(256):`
	`x, y = i % 16, i // 16`
	`m = get_matrix(data, x, y)`
	`sprites[i] = make_sprite(m)`
	`self.sprites = sprites`

	`def get_sprite(self, ch):`
	`return self.sprites[ord(ch)]`

As I only have the one LED I haven't dealt with the parts of the MaxMatrix library that handle with multiple daisy-chained LEDs.