max7219

README

Max7219 7-Segment/Matrix LED Driver

Introduction

The Maxim 7219 LED driver is an SPI chip that simplifies driving 7-Segment LED displays. It's also commonly used to create 8x8 LED matrixes. The datasheet is available at:

https://www.analog.com/media/en/technical-documentation/data-sheets/MAX7219-MAX7221.pdf

You can find 8 digit, 7-segment LED boards on Ebay for $1-2. You can find inexpensive matrixes in various sizes from 1 - 8 segments as well.

For matrixes, the driver provides a basic CP437 font that can be used to display characters on 8x8 matrixes. If desired, you can supply your own glyph set, or special characters for your specific application.

Driver Functions

This driver provides simplified handling for using either 7-segment numeric displays, or 8x8 matrixes.

It provides methods for scrolling data across either one or multiple displays. For example, you can pass an IP address of "10.100.10.11" to the scroll function and it will automatically scroll the display a desired number of times. The scroll feature also works with matrixes, and scrolls characters one LED column at a time for a smooth, even display.

Notes About Daisy-Chaining

The Max7219 is specifically designed to handle larger displays by daisy chaining units together. Say you want to write to digit 8 on the 3rd unit chained together. You would make one SPI write. The first write would be the register number (8), and the data value. Next, you would write a NOOP. The first record would then be shifted to the second device. Finally, you write another NOOP. The first record is shifted from the second device to the 3rd device, the first NOOP is shifted to the second device. When the ChipSelect line goes low, each unit applies the last data it received.

Documentation

Overview

Copyright 2024 The Periph Authors. All rights reserved. Use of this source code is governed under the Apache License, Version 2.0 that can be found in the LICENSE file.

The max7219 package provides a simple interface for displaying data on numeric 7-segment displays, or on matrix displays. It simplifies writes and provides useful features like scrolling characters on either type of display unit.

Example

basic test program. To do a numeric display, set matrix to false and matrixUnits to 1.

// basic test program. To do a numeric display, set matrix to false and
// matrixUnits to 1.
matrix := false
matrixUnits := 1
if _, err := host.Init(); err != nil {
	log.Fatal(err)
}

s, err := spireg.Open("")
if err != nil {
	log.Fatal(err)
}
defer s.Close()

dev, err := max7219.NewSPI(s, matrixUnits, 8)
if err != nil {
	log.Fatal(err)
}

_ = dev.TestDisplay(true)
time.Sleep(time.Second * 1)
_ = dev.TestDisplay(false)

_ = dev.SetIntensity(1)
_ = dev.Clear()

if matrix {
	dev.SetGlyphs(max7219.CP437Glyphs, true)
	dev.SetDecode(max7219.DecodeNone)
	dev.ScrollChars([]byte("0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"), 1, 100*time.Millisecond)
} else {
	dev.SetDecode(max7219.DecodeB)
}
for i := -128; i < 128; i++ {
	dev.WriteInt(i)
	time.Sleep(100 * time.Millisecond)
}
var tData []byte
// Continuously display a clock
for {
	t := time.Now()
	if matrix {
		// Assumes a 4 unit matrix
		tData = []byte(fmt.Sprintf("%2d%02d", t.Hour(), t.Minute()))
	} else {
		// 8 digit 7-segment LED display
		tData = []byte(t.Format(time.TimeOnly))
		tData[2] = max7219.ClearDigit
		tData[5] = max7219.ClearDigit
	}
	_ = dev.Write(tData)
	// Try to get the iteration exactly on time. FWIW, on a Pi Zero this loop
	// executes in ~ 2-3ms.
	dNext := time.Duration(1000-(t.UnixMilli()%1000)) * time.Millisecond
	time.Sleep(dNext)
}

Index

• Constants
• Variables
• type DecodeMode
• type Dev
  • func NewSPI(p spi.Port, units, numDigits int) (*Dev, error)
  • func (d *Dev) Clear() error
  • func (d *Dev) ScrollChars(data []byte, scrollCount int, updateInterval time.Duration)
  • func (d *Dev) SetDecode(mode DecodeMode) error
  • func (d *Dev) SetGlyphs(glyphs [][]byte, reverse bool)
  • func (d *Dev) SetIntensity(intensity byte) error
  • func (d *Dev) TestDisplay(on bool) error
  • func (d *Dev) Write(bytes []byte) error
  • func (d *Dev) WriteCascadedUnit(offset int, data []byte) error
  • func (d *Dev) WriteCascadedUnits(bytes [][]byte) error
  • func (d *Dev) WriteInt(value int) error

Examples

• Package

Constants

const (

	// Value to write to a Code B Font decoded register to blank out the
	// digit.
	ClearDigit byte = 0x0f
	// Value to write for a minus sign symbol
	MinusSign byte = 0x0a
	// To turn the decimal point on for a digit display, OR the value of the
	// digit with DecimalPoint
	DecimalPoint byte = 0x80

	// DecodeB is used for numeric segment displays. E.G. given a binary 0,
	// it would turn on the appropriate segments to display the character 0.
	DecodeB DecodeMode = 0xff
	// DecodeNone is RAW mode, or not decoded. For each byte, bits that are
	// one are turned on in the matrix, and bits that are 0 turn off the
	// led at that row/column.
	DecodeNone DecodeMode = 0
)

Variables

var CP437Glyphs = [][]byte{} //	0xff

/* 256 elements not displayed */

A really basic 8x8 raster font in CP437. Used to display characters on matrix type displays.

Refer to: https://www.ascii-codes.com/

Types

type DecodeMode

type DecodeMode byte

DecodeMode is the mode for handling data. Refer to the datasheet for more information.

type Dev

type Dev struct {
	// contains filtered or unexported fields
}

Type for a Maxim MAX7219/MAX7221 device.

func NewSPI

func NewSPI(p spi.Port, units, numDigits int) (*Dev, error)

NewSPI creates a new Max7219 using the specified spi.Port. units is the number of Max7219 chips daisy-chained together. numDigits is the number of digits displayed.

func (*Dev) Clear

func (d *Dev) Clear() error

Clear erases the content of all display segments or matrix LEDs.

func (*Dev) ScrollChars

func (d *Dev) ScrollChars(data []byte, scrollCount int, updateInterval time.Duration)

ScrollChars takes a character array and scrolls it from right-to-left, one led column at a time. This can be used to scroll a matrix display of glyphs, or digits on a seven-segment display. If the length of data is less than the number of display units, it writes that directly without scrolling.

func (*Dev) SetDecode

func (d *Dev) SetDecode(mode DecodeMode) error

SetDecode tells the Max7219 whether values should be decoded for a 7 segment display, or if they should be interpreted literally. Refer to the datasheet for more detailed information.

func (*Dev) SetGlyphs

func (d *Dev) SetGlyphs(glyphs [][]byte, reverse bool)

SetGlyphs allows you to set the character set for use by the matrix display. If the endianness of the charset doesn't match that used by the max7219, pass true for reverse and it will change the endianness of the raster values.

You only have to supply glyphs for values you intend to write. So if you're just writing digits, you just need 0-9 and whatever punctuation marks you need.

func (*Dev) SetIntensity

func (d *Dev) SetIntensity(intensity byte) error

SetIntensity controls the brightness of the display. The allowed range for intensity is from 0-15. Keep in mind that the brighter display, the more current drawn.

func (*Dev) TestDisplay

func (d *Dev) TestDisplay(on bool) error

TestDisplay turns on the 7219 display mode which set all segments (or LEDs) on, and the intensity to maximum. If you're using multiple units, you should be aware of the current draw, and limit how long you leave this on.

func (*Dev) Write

func (d *Dev) Write(bytes []byte) error

Write sends data to the display unit.

If decode is DecodeNone, then it's assumed we're writing to a matrix. If a glyph set has been set, then bytes are treated as offsets into the character table.

If decode is DecodeB, then any ASCII characters are converted into their supported CodeB values and written. If units are cascaded, this method automatically handles re-formatting the data, and writing it to the cascaded 7219 units.

func (*Dev) WriteCascadedUnit

func (d *Dev) WriteCascadedUnit(offset int, data []byte) error

WriteCascadedUnit writes data to a single display unit in a set of cascaded 7219 chips. offset is the 0 based number of the unit to write to. You could use this to update one segment of a cascaded matrix. Imagine rolling a digit upwards to bring in a new one...

func (*Dev) WriteCascadedUnits

func (d *Dev) WriteCascadedUnits(bytes [][]byte) error

WriteCascadedUnits writes a 2D array of raster characters to a a set of cascaded max7219 devices. For example, a 4 unit 8*8 matrix, or two eight digit 7-segment LEDs. This handles the complexities of how data is shifted from one 7219 to the next in a chain.

func (*Dev) WriteInt

func (d *Dev) WriteInt(value int) error

WriteInt provide a convenience method that displays the specified integer value on the display. It will work for either matrixes (with a glyph set) or numeric displays.