5. Using the PixelPi Python Library

The PixelPi Library is intended to be used with the PixelPi PCB from Hut 8 Designs.

If you have not already installed the library, see Installing the Python Library

5.1. Creating a Strip Object

class pixelpi.Strip(terminal, size, shape='straight', ledtype='WS2812', brightness=255)[source]

Creates an led Strip with the provided configuration.

Parameters:
  • terminal (int) – Which terminal the terminal is attached to (1-4).
  • size (int or tuple) – The size of the LED string or matrix. Either the number of LEDs for a string, or (width, height) for a matrix.
  • shape (str, optional) –

    The ‘shape’ of the LEDs attached:

    • straight - A LED string (default)
    • reverse - A LED string which starts at the opposite end.
    • zmatrix - A matrix where the LEDs in the first row go left to right, the next one right to left. i.e:
      1 2 3 4
      8 7 6 5
      9 …
    • matrix - a normal matrix where the led order goes left to right. i.e:
      1 2 3 4
      5 6 7 8
      9 …
  • ledtype (str) –

    One of the supported LED types:

    WS2812 (default), SK6812, SK6812W, SK6812_RGBW, SK6812_RBGW, SK6812_GRBW, SK6812_GBRW, SK6812_BRGW, SK6812_BGRW, WS2811_RGB, WS2811_RBG, WS2811_GRB, WS2811_GBR, WS2811_BRG, WS2811_BGR
  • brightness (int) – The default brightness for all LEDs (0-255).
getHeight

Returns the height of the matrix (or length of an LED string).

getLength

Returns how many LEDs are in the strip/matrix.

getStripNumber

Returns the terminal the LEDs are attached to.

getStripType

Returns the set LED type.

getWidth

Returns the width of the matrix (1 if an LED string).

updateStatus

Returns or sets whether output is currently enabled for the LEDs.

When set to False, the current LED pattern will remain unchanged even if the pattern is changed and showLEDs() is called.

Getter:Returns the status.
Setter:Sets the status.
Type:bool

5.2. Setting LED Colours and Brightness

Strip.setLEDs(led=None, rgb=None, brightness=None, image=None, pattern=None)[source]

Sets the RGB value, and optionally brightness, of one or more LEDs.

If led is not supplied or set to None, all LEDs will be set to the defined colour and brightness.

If a matrix is being used, led can either be the LED count from the first LED, or the (x, y) location.

If a brightness value is not supplied, or set to None, the current LED brightness will be kept.

If an image is supplied, then it must be in RGB format (see Pillow image file formats)

If a pattern is supplied, it must be a list consisting of a tuple with four elements, (red, green, blue, brightness).

Parameters:
  • led (int, tuple or None) – The LED location or None to set all LEDs to the desired colour.
  • rgb (tuple or None) – A tuple consisting of 3 elements, (red, green, blue), with each value being between 0 and 255.
  • brightness (int or None) – A value between 0 (dim) to 255 (very bright) or None to take the default.
  • image (image or None) – An image object (see PIL or Pillow libraries) containing an RGB formatted image.
  • pattern (list or None) – A list of the RGB and brightness values for each LED, in numerical order from the start of the strip/matrix.
Strip.getLEDs(led=None)[source]

If led is supplied, returns the RGB and brightness values of a specific LED.

If led is not supplied or set to None a list of red, green, blue and brightness values for each LED is returned in a list.

Parameters:led (int, tuple or None) – The led location, either the LED count from the start, or the x,y matrix location, or if None, a list of all LEDs will be returned
Returns:(red, green, blue, brightness) or a list of (red, green, blue, brightness)
Strip.clearLEDs()[source]

Clears the LEDs (sets them to black), leaving the brightness as it is.

5.3. Manipulating LED Colours

Strip.shift(direction='UP', shift=1)[source]

Shifts the LEDs on the matrix or string by shift LEDs in the direction specified.

Parameters:
  • direction (str) – The direction the LEDs should shift (LEFT, RIGHT, UP, DOWN)
  • shift (int) – The number of LEDs the matrix/string should be moved in the specified direction.
Strip.mirror(mirror='VERTICAL')[source]

Mirrors the matrix LEDs either in the VERTICAL or HORIZONTAL plane.

Reverses the LED colours on an LED string. The mirror parameter is not required for strings.

Parameters:mirror (str) – VERTICAL (default) or HORIZONTAL

5.4. Updating LEDs

Strip.showLEDs()[source]

Once you have set the colours of the string/matrix LEDs, use showLEDs to update the LEDs.