rgbmatrix – Low-level routines for bitbanged LED matrices
For more information about working with RGB matrix panels in CircuitPython, see the dedicated learn guide.
Available on these boards
- class rgbmatrix.RowAddressMode
The protocol used to select rows on the matrix.
- BINARY: RowAddressMode
Use parallel binary row addresses.
- ABC: RowAddressMode
Use serial A, B, and C row selection.
- class rgbmatrix.RGBMatrix(*, width: int, bit_depth: int, rgb_pins: Sequence[digitalio.DigitalInOut], addr_pins: Sequence[digitalio.DigitalInOut], clock_pin: digitalio.DigitalInOut, latch_pin: digitalio.DigitalInOut, output_enable_pin: digitalio.DigitalInOut, doublebuffer: bool = True, framebuffer: circuitpython_typing.WriteableBuffer | None = None, height: int = 0, tile: int = 1, serpentine: bool = True, row_address_mode: RowAddressMode = RowAddressMode.BINARY)
Displays an in-memory framebuffer to a HUB75-style RGB LED matrix.
Create a RGBMatrix object with the given attributes. The height of the display is determined by the number of rgb and address pins and the number of tiles:
len(rgb_pins) // 3 * 2 ** len(address_pins) * abs(tile). With 6 RGB pins, 4 address lines, and a single matrix, the display will be 32 pixels tall. If the optional height parameter is specified and is not 0, it is checked against the calculated height. Withrow_address_mode=RowAddressMode.ABC,heightmust be specified. Each panel must have a power-of-two height, from 2 through 64 pixels. Supply exactly threeaddr_pinsin A, B, C order: A is the row clock, B enables shifting, and C is serial row-selection data. This protocol is separate from the panel’s RGB pixel driver; an FM6126A chip or HUB75E connector label does not identify the row mode.Tiled matrices, those with more than one panel, must be laid out in a specific order, as detailed in the guide.
At least 6 RGB pins and 5 address pins are supported, for common panels with up to 64 rows of pixels. Some microcontrollers may support more, up to a soft limit of 30 RGB pins and 8 address pins.
The RGB pins must be within a single “port” and performance and memory usage are best when they are all within “close by” bits of the port. The clock pin must also be on the same port as the RGB pins. See the documentation of the underlying protomatter C library for more information. Generally, Adafruit’s interface boards are designed so that these requirements are met when matched with the intended microcontroller board. For instance, the Feather M4 Express works together with the RGB Matrix Feather.
The framebuffer is in “RGB565” format.
“RGB565” means that it is organized as a series of 16-bit numbers where the highest 5 bits are interpreted as red, the next 6 as green, and the final 5 as blue. The object can be any buffer, but
array.arrayandulab.ndarrayobjects are most often useful. To update the content, modify the framebuffer and call refresh.If a framebuffer is not passed in, one is allocated and initialized to all black. In any case, the framebuffer can be retrieved by passing the RGBMatrix object to memoryview().
If doublebuffer is False, some memory is saved, but the display may flicker during updates.
A RGBMatrix is often used in conjunction with a
framebufferio.FramebufferDisplay.On boards designed for use with RGBMatrix panels,
board.MTX_ADDRESSis a tuple of all the address pins, andboard.MTX_COMMONis a dictionary withrgb_pins,clock_pin,latch_pin, andoutput_enable_pin. For panels that use fewer than the maximum number of address pins, “slice”MTX_ADDRESSto get the correct number of address pins. Using these board properties makes calling the constructor simpler and more portable:matrix = rgbmatrix.RGBMatrix(..., addr_pins=board.MTX_ADDRESS[:4], **board.MTX_COMMON)
- Parameters:
width (int) – The overall width of the whole matrix in pixels. For a matrix with multiple panels in row, this is the width of a single panel times the number of panels across.
tile (int) – In a multi-row matrix, the number of rows of panels
bit_depth (int) – The color depth of the matrix. A value of 1 gives 8 colors, a value of 2 gives 64 colors, and so on. Increasing bit depth increases the CPU and RAM usage of the RGBMatrix, and may lower the panel refresh rate. The framebuffer is always in RGB565 format regardless of the bit depth setting
serpentine (bool) – In a multi-row matrix, True when alternate rows of panels are rotated 180°, which can reduce wiring length
rgb_pins (Sequence[digitalio.DigitalInOut]) – The matrix’s RGB pins in the order
(R1,G1,B1,R2,G2,B2...)addr_pins (Sequence[digitalio.DigitalInOut]) – The matrix’s address pins in the order
(A,B,C,D...)clock_pin (digitalio.DigitalInOut) – The matrix’s clock pin
latch_pin (digitalio.DigitalInOut) – The matrix’s latch pin
output_enable_pin (digitalio.DigitalInOut) – The matrix’s output enable pin
doublebuffer (bool) – True if the output is double-buffered
framebuffer (Optional[WriteableBuffer]) – A pre-allocated framebuffer to use. If unspecified, a framebuffer is allocated
height (int) – The overall height of the whole matrix in pixels. Required for ABC addressing; otherwise optional and checked against the calculated height.
row_address_mode (RowAddressMode) –
RowAddressMode.BINARYfor parallel row addresses, orRowAddressMode.ABCfor serial row selection using A, B and C.
- deinit() None
Free the resources (pins, timers, etc.) associated with this rgbmatrix instance. After deinitialization, no further operations may be performed.