Displays

`import max7219`

The max7219 module drives MAX7219/MAX7221 LED display modules using DIN, CLK, and CS GPIO pins. It works with common 8-digit 7-segment boards and cascaded 8x8 LED matrix modules. Use ``max7219.Display(...)`` to create an independent display object. Each object owns one native display slot, so multiple MAX7219 chains can run at once.

Quick example

import max7219
import system

score = max7219.Display(din=23, clk=18, cs=5)
status = max7219.Display(din=13, clk=14, cs=15, brightness=3)

score.show_number(12345678)

def tick():
    status.show_text("done")

system.schedule("display", 1000, 1000, -1, tick)

import max7219

heart = [
    0b00000000,
    0b01100110,
    0b11111111,
    0b11111111,
    0b01111110,
    0b00111100,
    0b00011000,
    0b00000000,
]

matrix = max7219.Display(din=23, clk=18, cs=5, devices=1, brightness=3)
matrix.show_rows(heart)

import`max7219`

MAX7219 LED display driver module.

API 33 available

`max7219.Display(din: int, clk: int, cs: int, devices: any = None, brightness: int = None, scan_limit: any = None, decode_mode: any = None, delay_us: int = None) -> max7219_display`

Create an independent MAX7219 display chain object.

Parameters

Name	Type	Pass as	Required	Description
`din`	`int`	positional or keyword	Yes	GPIO output pin connected to DIN.
`clk`	`int`	positional or keyword	Yes	GPIO output pin connected to CLK.
`cs`	`int`	positional or keyword	Yes	GPIO output pin connected to CS/LOAD.
`devices`	`any`	positional or keyword	No	Optional number of chained MAX7219 chips. Defaults to 1. Supported values are 1 through 8.
`brightness`	`int`	positional or keyword	No	Optional intensity from 0 through 15. Defaults to 8.
`scan_limit`	`any`	positional or keyword	No	Optional highest active digit or row from 0 through 7. Defaults to 7, which enables all 8 positions.
`decode_mode`	`any`	positional or keyword	No	Optional MAX7219 decode-mode register value. Defaults to 0, which means raw segment/matrix mode.
`delay_us`	`int`	positional or keyword	No	Optional bit-bang delay in microseconds. Defaults to 1.

Returns

max7219_display max7219_display object.

`max7219.Display().set_brightness(value) -> bool`

Set display intensity from 0 through 15.

Parameters

Name	Type	Pass as	Required	Description
`value`	`any`	positional or keyword	Yes	Required value.

`max7219.Display().display(enabled) -> bool`

Turn visible output on or off.

Parameters

Name	Type	Pass as	Required	Description
`enabled`	`bool`	positional or keyword	Yes	Required value.

`max7219.Display().test(enabled) -> bool`

Enable or disable display-test mode.

Parameters

Name	Type	Pass as	Required	Description
`enabled`	`bool`	positional or keyword	Yes	Required value.

`max7219.Display().set_decode(mode) -> bool`

Set the native decode-mode register.

Parameters

Name	Type	Pass as	Required	Description
`mode`	`str`	positional or keyword	Yes	Required value.

`max7219.Display().show_number(value, leading_zero=False, device=0) -> bool`

Display an integer.

Parameters

Name	Type	Pass as	Required	Description
`value`	`any`	positional or keyword	Yes	Required value.
`leading_zero`	`bool`	positional or keyword	No	Optional value. Defaults to False.
`device`	`any`	positional or keyword	No	Optional value. Defaults to 0.

`max7219.Display().show_text(text, position=0, device=0) -> bool`

Display simple 7-segment text.

Parameters

Name	Type	Pass as	Required	Description
`text`	`str`	positional or keyword	Yes	Required value.
`position`	`int`	positional or keyword	No	Optional value. Defaults to 0.
`device`	`any`	positional or keyword	No	Optional value. Defaults to 0.

`max7219.Display().set_digit(position, value, dot=False, device=0) -> bool`

Set one hex digit.

Parameters

Name	Type	Pass as	Required	Description
`position`	`int`	positional or keyword	Yes	Required value.
`value`	`any`	positional or keyword	Yes	Required value.
`dot`	`bool`	positional or keyword	No	Optional value. Defaults to False.
`device`	`any`	positional or keyword	No	Optional value. Defaults to 0.

`max7219.Display().show_segments(segments, position=0, device=0) -> bool`

Write raw segment bytes.

Parameters

Name	Type	Pass as	Required	Description
`segments`	`any`	positional or keyword	Yes	Required value.
`position`	`int`	positional or keyword	No	Optional value. Defaults to 0.
`device`	`any`	positional or keyword	No	Optional value. Defaults to 0.

`max7219.Display().set_row(row, value, device=0) -> bool`

Set one raw matrix row.

Parameters

Name	Type	Pass as	Required	Description
`row`	`int`	positional or keyword	Yes	Required value.
`value`	`any`	positional or keyword	Yes	Required value.
`device`	`any`	positional or keyword	No	Optional value. Defaults to 0.

`max7219.Display().show_rows(rows, device=0) -> bool`

Write up to 8 raw matrix rows.

Parameters

Name	Type	Pass as	Required	Description
`rows`	`int`	positional or keyword	Yes	Required value.
`device`	`any`	positional or keyword	No	Optional value. Defaults to 0.

`max7219.Display().set_pixel(x, y, enabled=True, device=0) -> bool`

Set one 8x8 matrix pixel.

Parameters

Name	Type	Pass as	Required	Description
`x`	`int`	positional or keyword	Yes	Required value.
`y`	`int`	positional or keyword	Yes	Required value.
`enabled`	`bool`	positional or keyword	No	Optional value. Defaults to True.
`device`	`any`	positional or keyword	No	Optional value. Defaults to 0.

`max7219.Display().write(reg, value, device=-1) -> bool`

Write a raw MAX7219 register.

Parameters

Name	Type	Pass as	Required	Description
`reg`	`any`	positional or keyword	Yes	Required value.
`value`	`any`	positional or keyword	Yes	Required value.
`device`	`any`	positional or keyword	No	Optional value. Defaults to -1.

`max7219.Display().clear(device=-1) -> bool`

Clear one device or the whole chain.

Parameters

Name	Type	Pass as	Required	Description
`device`	`any`	positional or keyword	No	Optional value. Defaults to -1.

`max7219.Display().info() -> dict`

Return this display chain's configuration.

`max7219.Display().close() -> bool`

Release this display slot and reset its pins.

`max7219.begin(din: int, clk: int, cs: int, devices: any = None, brightness: int = None, scan_limit: any = None, decode_mode: any = None, channel: int = None, delay_us: int = None) -> bool`

Legacy: initialize one module-level MAX7219 display channel.

Prefer ``display = max7219.Display(...)`` for new code. The legacy default API remains for older scripts that manage display chains through ``channel``.

Parameters

Name	Type	Pass as	Required	Description
`din`	`int`	positional or keyword	Yes	GPIO output pin connected to DIN.
`clk`	`int`	positional or keyword	Yes	GPIO output pin connected to CLK.
`cs`	`int`	positional or keyword	Yes	GPIO output pin connected to CS/LOAD.
`devices`	`any`	positional or keyword	No	Optional number of chained MAX7219 chips. Defaults to 1. Supported values are 1 through 8.
`brightness`	`int`	positional or keyword	No	Optional intensity from 0 through 15. Defaults to 8.
`scan_limit`	`any`	positional or keyword	No	Optional highest active digit or row from 0 through 7. Defaults to 7, which enables all 8 positions.
`decode_mode`	`any`	positional or keyword	No	Optional MAX7219 decode-mode register value. Defaults to 0, which means raw segment/matrix mode.
`channel`	`int`	positional or keyword	No	Optional display channel. Defaults to 0. Supported channels are 0 through 3.
`delay_us`	`int`	positional or keyword	No	Optional bit-bang delay in microseconds. Defaults to 1.

Returns

bool True when the GPIO pins are configured and the display chain is ready.

`max7219.set_brightness(value: any, channel: int = None) -> bool`

Set display brightness.

Parameters

Name	Type	Pass as	Required	Description
`value`	`any`	positional or keyword	Yes	Intensity from 0 through 15.
`channel`	`int`	positional or keyword	No	Optional display channel. Defaults to 0.

Returns

bool True when the command was transmitted.

`max7219.display(enabled: bool, channel: int = None) -> bool`

Turn visible output on or off without clearing the buffer.

Parameters

Name	Type	Pass as	Required	Description
`enabled`	`bool`	positional or keyword	Yes	Boolean. True shows the display; False puts the chip in shutdown mode.
`channel`	`int`	positional or keyword	No	Optional display channel. Defaults to 0.

Returns

bool True when the command was transmitted.

`max7219.test(enabled: bool, channel: int = None) -> bool`

Enable or disable MAX7219 display-test mode.

Parameters

Name	Type	Pass as	Required	Description
`enabled`	`bool`	positional or keyword	Yes	Boolean. True lights every LED segment; False returns to normal display output.
`channel`	`int`	positional or keyword	No	Optional display channel. Defaults to 0.

Returns

bool True when the command was transmitted.

`max7219.set_decode(mode: str, channel: int = None) -> bool`

Set the MAX7219 decode-mode register.

Parameters

Name	Type	Pass as	Required	Description
`mode`	`str`	positional or keyword	Yes	Decode-mode register value from 0 through 255. Use 0 for raw segment/matrix mode.
`channel`	`int`	positional or keyword	No	Optional display channel. Defaults to 0.

Returns

bool True when the command was transmitted.

`max7219.show_number(value: any, leading_zero: bool = None, device: any = None, channel: int = None) -> bool`

Display an integer on one 8-digit device.

Parameters

Name	Type	Pass as	Required	Description
`value`	`any`	positional or keyword	Yes	Integer value to show. Long values are clipped from the left.
`leading_zero`	`bool`	positional or keyword	No	Optional zero padding. Defaults to False.
`device`	`any`	positional or keyword	No	Optional chained device index. Defaults to 0.
`channel`	`int`	positional or keyword	No	Optional display channel. Defaults to 0.

Returns

bool True when the frame was transmitted.

`max7219.show_text(text: str, position: int = None, device: any = None, channel: int = None) -> bool`

Display simple 7-segment text.

Parameters

Name	Type	Pass as	Required	Description
`text`	`str`	positional or keyword	Yes	Text to display. Supported characters include digits, common 7-segment letters, dash, underscore, space, and decimal points.
`position`	`int`	positional or keyword	No	Optional starting digit position from 0 through 7. Defaults to 0.
`device`	`any`	positional or keyword	No	Optional chained device index. Defaults to 0.
`channel`	`int`	positional or keyword	No	Optional display channel. Defaults to 0.

Returns

bool True when the frame was transmitted.

`max7219.set_digit(position: int, value: any, dot: bool = None, device: any = None, channel: int = None) -> bool`

Set one 7-segment digit and write it immediately.

Parameters

Name	Type	Pass as	Required	Description
`position`	`int`	positional or keyword	Yes	Zero-based digit position from 0 through 7.
`value`	`any`	positional or keyword	Yes	Hex digit value from 0 through 15.
`dot`	`bool`	positional or keyword	No	Optional decimal point on this digit. Defaults to False.
`device`	`any`	positional or keyword	No	Optional chained device index. Defaults to 0.
`channel`	`int`	positional or keyword	No	Optional display channel. Defaults to 0.

Returns

bool True when the digit command was transmitted.

`max7219.show_segments(segments: list, position: int = None, device: any = None, channel: int = None) -> bool`

Write raw segment bytes to one device.

Parameters

Name	Type	Pass as	Required	Description
`segments`	`list`	positional or keyword	Yes	One integer segment byte or a list of segment bytes.
`position`	`int`	positional or keyword	No	Optional starting digit position. Defaults to 0.
`device`	`any`	positional or keyword	No	Optional chained device index. Defaults to 0.
`channel`	`int`	positional or keyword	No	Optional display channel. Defaults to 0.

Returns

bool True when at least one segment byte was written and transmitted.

`max7219.set_row(row: int, value: any, device: any = None, channel: int = None) -> bool`

Set one raw matrix row or digit register.

Parameters

Name	Type	Pass as	Required	Description
`row`	`int`	positional or keyword	Yes	Row/register position from 0 through 7.
`value`	`any`	positional or keyword	Yes	Raw 8-bit row value from 0 through 255.
`device`	`any`	positional or keyword	No	Optional chained device index. Defaults to 0.
`channel`	`int`	positional or keyword	No	Optional display channel. Defaults to 0.

Returns

bool True when the row command was transmitted.

`max7219.show_rows(rows: int, device: any = None, channel: int = None) -> bool`

Write up to 8 raw rows to one matrix device.

Parameters

Name	Type	Pass as	Required	Description
`rows`	`int`	positional or keyword	Yes	List of 8-bit row values. Missing rows are cleared.
`device`	`any`	positional or keyword	No	Optional chained device index. Defaults to 0.
`channel`	`int`	positional or keyword	No	Optional display channel. Defaults to 0.

Returns

bool True when the rows were transmitted.

`max7219.set_pixel(x: int, y: int, enabled: bool = None, device: any = None, channel: int = None) -> bool`

Set one pixel in an 8x8 matrix device.

Parameters

Name	Type	Pass as	Required	Description
`x`	`int`	positional or keyword	Yes	Pixel column from 0 through 7.
`y`	`int`	positional or keyword	Yes	Pixel row from 0 through 7.
`enabled`	`bool`	positional or keyword	No	Optional boolean pixel state. Defaults to True.
`device`	`any`	positional or keyword	No	Optional chained device index. Defaults to 0.
`channel`	`int`	positional or keyword	No	Optional display channel. Defaults to 0.

Returns

bool True when the row containing the pixel was transmitted.

`max7219.write(reg: any, value: any, device: any = None, channel: int = None) -> bool`

Write a raw MAX7219 register.

Parameters

Name	Type	Pass as	Required	Description
`reg`	`any`	positional or keyword	Yes	Register address from 0 through 15.
`value`	`any`	positional or keyword	Yes	Register value from 0 through 255.
`device`	`any`	positional or keyword	No	Optional chained device index. Defaults to -1, which writes the same register value to all devices.
`channel`	`int`	positional or keyword	No	Optional display channel. Defaults to 0.

Returns

bool True when the raw command was transmitted.

`max7219.clear(device: any = None, channel: int = None) -> bool`

Clear one device or the whole chain.

Parameters

Name	Type	Pass as	Required	Description
`device`	`any`	positional or keyword	No	Optional chained device index. Defaults to -1, which clears all devices.
`channel`	`int`	positional or keyword	No	Optional display channel. Defaults to 0.

Returns

bool True when the blank frame was transmitted.

`max7219.encode(value: any, dot: bool = None) -> int`

Return a raw 7-segment byte for a character.

Parameters

Name	Type	Pass as	Required	Description
`value`	`any`	positional or keyword	Yes	Character or digit to encode.
`dot`	`bool`	positional or keyword	No	Optional decimal point bit. Defaults to False.

Returns

int Integer segment byte.

`max7219.info(channel: int = None) -> dict`

Return display-chain configuration.

Parameters

Name	Type	Pass as	Required	Description
`channel`	`int`	positional or keyword	No	Optional display channel. Defaults to 0.

Returns

dict Dict with initialized, channel, din, clk, cs, devices, brightness, scan_limit, decode_mode, enabled, test, and delay_us fields.

`max7219.deinit(channel: int = None) -> bool`

Release a display channel and reset its pins.

Parameters

Name	Type	Pass as	Required	Description
`channel`	`int`	positional or keyword	No	Optional display channel. Defaults to 0.

Returns

bool True when an initialized display channel was released.

max7219

import max7219

Quick example

importmax7219

max7219.Display(din: int, clk: int, cs: int, devices: any = None, brightness: int = None, scan_limit: any = None, decode_mode: any = None, delay_us: int = None) -> max7219_display

max7219.Display().set_brightness(value) -> bool

max7219.Display().display(enabled) -> bool

max7219.Display().test(enabled) -> bool

max7219.Display().set_decode(mode) -> bool

max7219.Display().show_number(value, leading_zero=False, device=0) -> bool

max7219.Display().show_text(text, position=0, device=0) -> bool

max7219.Display().set_digit(position, value, dot=False, device=0) -> bool

max7219.Display().show_segments(segments, position=0, device=0) -> bool

max7219.Display().set_row(row, value, device=0) -> bool

max7219.Display().show_rows(rows, device=0) -> bool

max7219.Display().set_pixel(x, y, enabled=True, device=0) -> bool

max7219.Display().write(reg, value, device=-1) -> bool

max7219.Display().clear(device=-1) -> bool

max7219.Display().info() -> dict

max7219.Display().close() -> bool

max7219.begin(din: int, clk: int, cs: int, devices: any = None, brightness: int = None, scan_limit: any = None, decode_mode: any = None, channel: int = None, delay_us: int = None) -> bool

max7219.set_brightness(value: any, channel: int = None) -> bool

max7219.display(enabled: bool, channel: int = None) -> bool

max7219.test(enabled: bool, channel: int = None) -> bool

max7219.set_decode(mode: str, channel: int = None) -> bool

max7219.show_number(value: any, leading_zero: bool = None, device: any = None, channel: int = None) -> bool

max7219.show_text(text: str, position: int = None, device: any = None, channel: int = None) -> bool

max7219.set_digit(position: int, value: any, dot: bool = None, device: any = None, channel: int = None) -> bool

max7219.show_segments(segments: list, position: int = None, device: any = None, channel: int = None) -> bool

max7219.set_row(row: int, value: any, device: any = None, channel: int = None) -> bool

max7219.show_rows(rows: int, device: any = None, channel: int = None) -> bool

max7219.set_pixel(x: int, y: int, enabled: bool = None, device: any = None, channel: int = None) -> bool

max7219.write(reg: any, value: any, device: any = None, channel: int = None) -> bool

max7219.clear(device: any = None, channel: int = None) -> bool

max7219.encode(value: any, dot: bool = None) -> int

max7219.info(channel: int = None) -> dict

max7219.deinit(channel: int = None) -> bool

`import max7219`

import`max7219`

`max7219.Display(din: int, clk: int, cs: int, devices: any = None, brightness: int = None, scan_limit: any = None, decode_mode: any = None, delay_us: int = None) -> max7219_display`

`max7219.Display().set_brightness(value) -> bool`

`max7219.Display().display(enabled) -> bool`

`max7219.Display().test(enabled) -> bool`

`max7219.Display().set_decode(mode) -> bool`

`max7219.Display().show_number(value, leading_zero=False, device=0) -> bool`

`max7219.Display().show_text(text, position=0, device=0) -> bool`

`max7219.Display().set_digit(position, value, dot=False, device=0) -> bool`

`max7219.Display().show_segments(segments, position=0, device=0) -> bool`

`max7219.Display().set_row(row, value, device=0) -> bool`

`max7219.Display().show_rows(rows, device=0) -> bool`

`max7219.Display().set_pixel(x, y, enabled=True, device=0) -> bool`

`max7219.Display().write(reg, value, device=-1) -> bool`

`max7219.Display().clear(device=-1) -> bool`

`max7219.Display().info() -> dict`

`max7219.Display().close() -> bool`

`max7219.begin(din: int, clk: int, cs: int, devices: any = None, brightness: int = None, scan_limit: any = None, decode_mode: any = None, channel: int = None, delay_us: int = None) -> bool`

`max7219.set_brightness(value: any, channel: int = None) -> bool`

`max7219.display(enabled: bool, channel: int = None) -> bool`

`max7219.test(enabled: bool, channel: int = None) -> bool`

`max7219.set_decode(mode: str, channel: int = None) -> bool`

`max7219.show_number(value: any, leading_zero: bool = None, device: any = None, channel: int = None) -> bool`

`max7219.show_text(text: str, position: int = None, device: any = None, channel: int = None) -> bool`

`max7219.set_digit(position: int, value: any, dot: bool = None, device: any = None, channel: int = None) -> bool`

`max7219.show_segments(segments: list, position: int = None, device: any = None, channel: int = None) -> bool`

`max7219.set_row(row: int, value: any, device: any = None, channel: int = None) -> bool`

`max7219.show_rows(rows: int, device: any = None, channel: int = None) -> bool`

`max7219.set_pixel(x: int, y: int, enabled: bool = None, device: any = None, channel: int = None) -> bool`

`max7219.write(reg: any, value: any, device: any = None, channel: int = None) -> bool`

`max7219.clear(device: any = None, channel: int = None) -> bool`

`max7219.encode(value: any, dot: bool = None) -> int`

`max7219.info(channel: int = None) -> dict`

`max7219.deinit(channel: int = None) -> bool`