Matrix

The LEGO 3x3 LED matrix

The LEGO® SPIKE™ 3x3 LED matrix has individual elements that can be set individually or as a whole.

Colours may be passed as string or integer parameters.

LED Matrix colours

Number

Name

0

1

pink

2

lilac

3

blue

4

cyan

5

turquoise

6

green

7

yellow

8

orange

9

red

10

white

class buildhat.Matrix(port)

LED Matrix

Parameters:

port – Port of device

Raises:

DeviceError – Occurs if there is no LED matrix attached to port

callback(func)

Set callback function

Parameters:

func – Callback function

clear(pixel=None)

Clear matrix or set all as the same pixel

Parameters:

pixel – tuple of colour (0–10) or string and brightness (0–10)

property connected

Whether device is connected or not

Returns:

Connection status

static desc_for_id(typeid)

Translate integer type id to something more descriptive than the device name

Parameters:

typeid – Type of device

Returns:

Description of device

property description

Device on port info

Returns:

Device description

deselect()

Unselect data from mode

get()

Extract information from device

Returns:

Data from device

Raises:

DeviceError – Occurs if device not in valid mode

property interval

Interval between data points in milliseconds

Getter:

Gets interval

Setter:

Sets interval

Returns:

Device interval

Return type:

int

isconnected()

Whether it is connected or not

Raises:

DeviceError – Occurs if device no longer the same

level(level)

Use the matrix as a “level” meter from 0-9

(The level meter is expressed in green which seems to be unchangeable)

Parameters:

level – The height of the bar graph, 0-9

Raises:

MatrixError – Occurs if invalid level specified

mode(modev)

Set combimode or simple mode

Parameters:

modev – List of tuples for a combimode, or integer for simple mode

property name

Determine name of device on port

Returns:

Device name

static name_for_id(typeid)

Translate integer type id to device name (python class)

Parameters:

typeid – Type of device

Returns:

Name of device

static normalize_pixel(pixel)

Validate a pixel tuple (color, brightness) and convert string colors to integers

Parameters:

pixel – tuple of colour (0–10) or string (ie:”red”) and brightness (0–10)

Returns:

(color, brightness) integers

Return type:

tuple

Raises:

MatrixError – Occurs if invalid pixel specified

off()

Pretends to turn matrix off

Never send the “off” command to the port a Matrix is connected to Instead, just turn all the pixels off

on()

Turn on sensor

reverse()

Reverse polarity

select()

Request data from mode

Raises:

DeviceError – Occurs if device not in valid mode

set_pixel(coord, pixel, display=True)

Write pixel to coordinate

Parameters:
  • coord – (0,0) to (2,2)

  • pixel – tuple of colour (0–10) or string and brightness (0–10)

  • display – Whether to update matrix or not

set_pixels(matrix, display=True)

Write pixel data to LED matrix

Parameters:
  • matrix – 3x3 list of tuples, with colour (0–10) and brightness (0–10) (see example for more detail)

  • display – Whether to update matrix or not

Raises:

MatrixError – Occurs if invalid matrix height/width provided

set_transition(transition)

Set the transition mode between pixels

Use display=False on set_pixel() or use set_pixels() to achieve desired results with transitions.

Setting a new transition mode will wipe the screen and interrupt any running transition.

Mode 0: No transition, immediate pixel drawing

Mode 1: Right-to-left wipe in/out

If the timing between writing new matrix pixels is less than one second the transition will clip columns of pixels from the right.

Mode 2: Fade-in/Fade-out

The fade in and fade out take about 2.2 seconds for full fade effect. Waiting less time between setting new pixels will result in a faster fade which will cause the fade to “pop” in brightness.

Parameters:

transition – Transition mode (0-2)

Raises:

MatrixError – Occurs if invalid transition

static strtocolor(colorstr)

Return the BuldHAT’s integer representation of a color string

Parameters:

colorstr – str of a valid color

Returns:

(0-10) representing the color

Return type:

int

Raises:

MatrixError – Occurs if invalid color specified

property typeid

Type ID of device

Returns:

Type ID

property typeidcur

Type ID currently present

Returns:

Type ID

static validate_coordinate(coord)

Validate an x,y coordinate for the 3x3 Matrix

Parameters:

coord – tuple of 0-2 for the X coordinate and 0-2 for the Y coordinate

Raises:

MatrixError – Occurs if invalid coordinate specified

Example

"""Example driving LED matrix"""

import random
import time

from buildhat import Matrix

matrix = Matrix('C')

matrix.clear(("red", 10))
time.sleep(1)

matrix.clear()
time.sleep(1)

matrix.set_pixel((0, 0), ("blue", 10))
matrix.set_pixel((2, 2), ("red", 10))
time.sleep(1)

while True:
    out = [[(int(random.uniform(0, 9)), 10) for x in range(3)] for y in range(3)]
    matrix.set_pixels(out)
    time.sleep(0.1)