Introduction

Documentation Status Discord Build Status

CircuitPython driver for the MAX7219 LED matrix driver chip.

See here for the equivalent MicroPython driver.

Dependencies

This driver depends on:

Please ensure all dependencies are available on the CircuitPython filesystem. This is easily achieved by downloading the Adafruit library and driver bundle.

Installing from PyPI

On supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally from PyPI. To install for current user:

pip3 install adafruit-circuitpython-max7219

To install system-wide (this may be required in some cases):

sudo pip3 install adafruit-circuitpython-max7219

To install in a virtual environment in your current project:

mkdir project-name && cd project-name
python3 -m venv .env
source .env/bin/activate
pip3 install adafruit-circuitpython-max7219

Usage Example

adafruit_max7219.Matrix8x8 Example

from adafruit_max7219 import matrices
from board import TX, RX, A2
import busio
import digitalio
import time

clk = RX
din = TX
cs = digitalio.DigitalInOut(A2)

spi = busio.SPI(clk, MOSI=din)
display = matrices.Matrix8x8(spi, cs)
while True:
    display.brightness(3)

    display.fill(1)
    display.pixel(3, 3)
    display.pixel(3, 4)
    display.pixel(4, 3)
    display.pixel(4, 4)
    display.show()
    time.sleep(3.0)

    display.clear_all()
    s = 'Hello, World!'
    for c in range(len(s)*8):
        display.fill(0)
        display.text(s,-c,0)
        display.show()
        time.sleep(0.25)

adafruit_max7219.BCDDigits Example

from adafruit_max7219 import bcddigits
from board import TX, RX, A2
import bitbangio
import digitalio

clk = RX
din = TX
cs = digitalio.DigitalInOut(A2)

spi = bitbangio.SPI(clk, MOSI=din)
display = bcddigits.BCDDigits(spi, cs, nDigits=8)
display.clear_all()
display.show_str(0,'{:9.2f}'.format(-1234.56))
display.show()

Contributing

Contributions are welcome! Please read our Code of Conduct before contributing to help this project stay welcoming.

Documentation

For information on building library documentation, please check out this guide.

Table of Contents

Simple test

Ensure your device works with this simple test.

examples/max7219_simpletest.py
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
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
# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT

import time
from board import TX, RX, A1
import busio
import digitalio
from adafruit_max7219 import matrices

mosi = TX
clk = RX
cs = digitalio.DigitalInOut(A1)

spi = busio.SPI(clk, MOSI=mosi)

matrix = matrices.Matrix8x8(spi, cs)
while True:
    print("Cycle start")
    # all lit up
    matrix.fill(True)
    matrix.show()
    time.sleep(0.5)

    # all off
    matrix.fill(False)
    matrix.show()
    time.sleep(0.5)

    # one column of leds lit
    for i in range(8):
        matrix.pixel(1, i, 1)
    matrix.show()
    time.sleep(0.5)
    # now scroll the column to the right
    for j in range(8):
        matrix.scroll(1, 0)
        matrix.show()
        time.sleep(0.5)

    # show a string one character at a time
    adafruit = "Adafruit"
    for char in adafruit:
        matrix.fill(0)
        matrix.text(char, 0, 0)
        matrix.show()
        time.sleep(1.0)

    # scroll the last character off the display
    for i in range(8):
        matrix.scroll(-1, 0)
        matrix.show()
        time.sleep(0.5)

    # scroll a string across the display
    for pixel_position in range(len(adafruit) * 8):
        matrix.fill(0)
        matrix.text(adafruit, -pixel_position, 0)
        matrix.show()
        time.sleep(0.25)
examples/max7219_showbcddigits.py
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
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
80
81
82
83
84
85
86
87
88
89
# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT

import time
import random
from board import TX, RX, A1
import busio
import digitalio
from adafruit_max7219 import bcddigits

mosi = TX
clk = RX
cs = digitalio.DigitalInOut(A1)

spi = busio.SPI(clk, MOSI=mosi)

leds = bcddigits.BCDDigits(spi, cs, nDigits=8)
while True:
    # clear display and dim 0
    leds.brightness(0)
    leds.clear_all()

    # place 8-digit number on display
    value = 12345678
    leds.show_str(0, "{:8}".format(value))
    leds.show()

    # increase the brightness slowly
    for i in range(16):
        leds.brightness(i)
        time.sleep(0.5)

    leds.brightness(3)

    # show "-HELP-90" on display
    leds.show_str(6, "90")  # show 90 starting at position 6
    leds.set_digit(0, 10)  # show - at position 0
    leds.set_digit(1, 12)  # show H at position 1
    leds.set_digit(2, 11)  # show E at position 2
    leds.set_digit(3, 13)  # show L at position 3
    leds.set_digit(4, 14)  # show P at position 4
    leds.set_digit(5, 10)  # show - at position 5

    leds.show()
    time.sleep(1.0)

    leds.clear_all()
    leds.brightness(5)

    # set the two dots and two 4-digit numbers
    leds.show_dot(2, 1)
    leds.show_dot(6, 1)
    leds.show_str(0, " 72.5")
    leds.show_str(4, "-10.8")

    leds.show()
    time.sleep(1.0)

    leds.brightness(10)
    leds.clear_all()
    # show a 4 character numeric string
    leds.show_str(0, "   0")
    leds.show()
    time.sleep(1.0)

    leds.clear_all()
    # show 0->8
    for digit in range(8):
        leds.set_digit(digit, digit)

    leds.show()
    time.sleep(1.0)

    # show random 8-digit numbers via show_str
    for _ in range(10):
        number = random.uniform(-1.0, 1.0)
        number *= 10000.0
        number_string = "{:9.3f}".format(number)
        leds.clear_all()
        leds.show_str(0, number_string)
        leds.show()
        time.sleep(1.0)

    # show the help string
    leds.clear_all()
    leds.show_help(2)
    leds.show()

    time.sleep(1.0)

adafruit_max7219.max7219 - MAX7219 LED Matrix/Digit Display Driver

CircuitPython library to support MAX7219 LED Matrix/Digit Display Driver. This library supports the use of the MAX7219-based display in CircuitPython, either an 8x8 matrix or a 8 digit 7-segment numeric display.

See Also

  • matrices.Maxtrix8x8 is a class support an 8x8 led matrix display
  • bcddigits.BCDDigits is a class that support the 8 digit 7-segment display

Beware that most CircuitPython compatible hardware are 3.3v logic level! Make sure that the input pin is 5v tolerant.

  • Author(s): Michael McWethy

Implementation Notes

Hardware:

Software and Dependencies:

Notes: #. Datasheet: https://cdn-shop.adafruit.com/datasheets/MAX7219.pdf

class adafruit_max7219.max7219.MAX7219(width: int, height: int, spi: busio.SPI, cs: digitalio.DigitalInOut, *, baudrate: int = 8000000, polarity: int = 0, phase: int = 0)[source]

MAX2719 - driver for displays based on max719 chip_select

Parameters:
  • width (int) – the number of pixels wide
  • height (int) – the number of pixels high
  • spi (SPI) – an spi busio or spi bitbangio object
  • chip_select (DigitalInOut) – digital in/out to use as chip select signal
  • baudrate (int) – for SPIDevice baudrate (default 8000000)
  • polarity (int) – for SPIDevice polarity (default 0)
  • phase (int) – for SPIDevice phase (default 0)
brightness(value: int) → None[source]

Controls the brightness of the display.

Parameters:value (int) – 0->15 dimmest to brightest
fill(bit_value: int) → None[source]

Fill the display buffer.

Parameters:bit_value (int) – value > 0 set the buffer bit, else clears the buffer bit
init_display() → None[source]

Must be implemented by derived class (matrices, bcddigits)

pixel(xpos: int, ypos: int, bit_value: int = None) → None[source]

Set one buffer bit

Parameters:
  • xpos (int) – x position to set bit
  • ypos (int) – y position to set bit
  • bit_value (int) – value > 0 sets the buffer bit, else clears the buffer bit
scroll(delta_x: int, delta_y: int) → None[source]

Srcolls the display using delta_x,delta_y.

Parameters:
  • delta_x (int) – positions to scroll in the x direction
  • delta_y (int) – positions to scroll in the y direction
show() → None[source]

Updates the display.

write_cmd(cmd: int, data: int) → None[source]

Writes a command to spi device.

Parameters:
  • cmd (int) – register address to write data to
  • data (int) – data to be written to commanded register

adafruit_max7219.matrices.Matrix8x8

class adafruit_max7219.matrices.Matrix8x8(spi: busio.SPI, cs: digitalio.DigitalInOut)[source]

Driver for a 8x8 LED matrix based on the MAX7219 chip.

Parameters:
  • spi (SPI) – an spi busio or spi bitbangio object
  • cs (DigitalInOut) – digital in/out to use as chip select signal
clear_all() → None[source]

Clears all matrix leds.

init_display() → None[source]

Must be implemented by derived class (matrices, bcddigits)

text(strg: str, xpos: int, ypos: int, bit_value: int = 1) → None[source]

Draw text in the 8x8 matrix.

Parameters:
  • strg (str) – string to place in to display
  • xpos (int) – x position of LED in matrix
  • ypos (int) – y position of LED in matrix
  • bit_value (int) – > 1 sets the text, otherwise resets

adafruit_max7219.bcddigits.BCDDigits

class adafruit_max7219.bcddigits.BCDDigits(spi: busio.SPI, cs: digitalio.DigitalInOut, nDigits: int = 1)[source]

Basic support for display on a 7-Segment BCD display controlled by a Max7219 chip using SPI.

Parameters:
  • spi (SPI) – an spi busio or spi bitbangio object
  • cs (DigitalInOut) – digital in/out to use as chip select signal
  • nDigits (int) – number of led 7-segment digits; default 1; max 8
clear_all() → None[source]

Clear all digits and decimal points.

init_display() → None[source]

Must be implemented by derived class (matrices, bcddigits)

set_digit(dpos: int, value: int) → None[source]

Display one digit.

Parameters:
  • dpos (int) – the digit position; zero-based
  • value (int) – integer ranging from 0->15
set_digits(start: int, values: List[int]) → None[source]

Display digits from a list.

Parameters:
  • start (int) – digit to start display zero-based
  • values (list[int]) – list of integer values ranging from 0->15
show_dot(dpos: int, bit_value: int = None) → None[source]

The decimal point for a digit.

Parameters:
  • dpos (int) – the digit to set the decimal point zero-based
  • bit_value (int) – value > zero lights the decimal point, else unlights the point
show_help(start: int) → None[source]

Display the word HELP in the display.

Parameters:start (int) – start position to show HELP
show_str(start: int, strg: str) → None[source]

Displays a numeric str in the display. Shows digits 0-9, -, and ..

Parameters:
  • start (int) – start position to show the numeric string
  • strg (str) – the numeric string

Indices and tables