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

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)