For LEDStrip setup, skip to Channel Order.

When using the LEDMatrix class, it currently assumes that the matrix is built from a single, continuous strip of LEDs arranged in a matrix. Future versions will directly support true matrix displays with native (X,Y) coordinates.

By default, it is assumed that a serpentine pattern is used and coordinate (0,0) is the top left corner of the matrix and that the data input of the LED strip starts from there, moving to the right across the top row, and then moving back towards the left on the second row, continuing to alternate from there. The indices of each pixel on the strip would then map to the (x,y) coordinates of the matrix, as shown below.

If, however, the minimum row index is always on the left of the matrix; the LEDMatrix serpentine parameter should be set to False. In this case, the coordinate map will be generated as follows:

As long as the matrix follows either of these general layouts, other than by rotation or being mirrored, the coordinate map will be automatically generated by LEDMatrix based on the supplied width, height, and serpentine parameters.

The coordinate mapping can, however, be overridden by passing a new coordinate map to the coordMap parameter of the LEDMatrix [[init|LEDMatrix#__init__driver-width--0-height--0-coordmap--none-rotation--matrixrotationrotate_0-vert_flip--false]] method. The coordinate map should be in the form of a list of lists, like the following:

coords = [
    [0,1,2],
    [3,4,5],
    [6,7,8]
]

This would define coordinates where the indicies always start back on the left side as opposed to alternating direction throughout the matrix.

This is particularly useful when combining multiple matrix displays into one, such as a 16x16 matrix comprised of four NeoPixel 8x8 Matricies. These displays use a non-serpentine pattern as described above, but connecting four of them in a square will mean that pattern only applies to each quadrant. A simplified version of this is shown in the table below:

The indices in the table correspond the actual order of the LEDs in the display, but this will allow given (X,Y) coordinates to map to the correct LED. In python it would look like this:

coords = [
    [0,1,2,9,10,11],
    [3,4,5,12,13,14],
    [6,7,8,15,16,17],
    [18,19,20,27,28,29],
    [21,22,23,30,31,32]
    [24,25,26,33,34,35]
]

led = LEDMatrix(driver, width = 6, height = 6, coordMap = coords)

If rotation or flip parameters are supplied, those transforms will also be applied to a supplied coordMap.

For LEDStrip setup, skip to Channel Order.

The LEDMatrix class also accepts rotation and flip parameters which allow reorienting the display in software so that the (0,0) coordinate is in the top-left corner.

The following enumeration is provided for setting the rotation of a matrix:

class MatrixRotation:
    ROTATE_0 = 0   #no rotation
    ROTATE_90 = 1  #rotate 90 degrees
    ROTATE_180 = 2 #rotate 180 degrees
    ROTATE_270 = 3 #rotate 270 degrees

To complete any needed orientation transforms there is also the vert_flip parameter which will mirror the display along the x-axis if set to True. There is no horizontal flip parameter provided as this can be achieved by setting rotation to 180° and vertical flip to True.

To help through figuring out any needed rotation or flip, the MatrixOrientationTest animation is provided in the animation module.

from bibliopixel.led import *
from bibliopixel.animation import MatrixCalibrationTest
from bibliopixel.drivers.LPD8806 import *

#create driver for a 12x12 grid, use the size of your display
driver = DriverLPD8806(12*12)
led = LEDMatrix(driver)

anim = MatrixCalibrationTest(led)
anim.run()

If the display is physically oriented correctly, you should see an animation starting from the top left and the colored lines should be vertical, like this:

But if, for example, you saw this:

The display needs to be rotated 90° clockwise, so the LEDMatrix instance needs to be configured like this:

led = LEDMatrix(driver, rotation = MatrixRotation.ROTATE_90)

But if, instead, what you see looks like this:

The display needs to be rotated 180° and flipped on the vertical:

led = LEDMatrix(driver, rotation = MatrixRotation.ROTATE_180, vert_flip = True)

To aid in the process, match what your display looks like running MatrixCalibrationTest with the table below. Then use the provided rotation and flip parameters on your LEDMatrix init.

rotation = MatrixRotation.ROTATE_0	rotation = MatrixRotation.ROTATE_90
rotation = MatrixRotation.ROTATE_180	rotation = MatrixRotation.ROTATE_270
rotation = MatrixRotation.ROTATE_0, vert_flip = True	rotation = MatrixRotation.ROTATE_90, vert_flip = True
rotation = MatrixRotation.ROTATE_180, vert_flip = True	rotation = MatrixRotation.ROTATE_270, vert_flip = True

Note: To achieve a horizontal flip, rotate 180° and flip vertically.

rotation = MatrixRotation.ROTATE_180, vert_flip = True

The last step is to check that the color channel order is correct (if supported by your chosen driver). Two animations are provided for this purposed; MatrixCalibrationTest (shown above) and StripChannelTest.

For LEDMatrix run the following test code.

from bibliopixel.led import *
from bibliopixel.animation import MatrixCalibrationTest
from bibliopixel.drivers.LPD8806 import *

#create driver for a 12x12 grid, use the size of your display
driver = DriverLPD8806(12*12)
led = LEDMatrix(driver)

anim = MatrixCalibrationTest(led)
anim.run()

It should display something like this:

For LEDStrip run the following test code.

from bibliopixel.led import *
from bibliopixel.animation import StripChannelTest
from bibliopixel.drivers.LPD8806 import *

#create driver for a 12 pixels
driver = DriverLPD8806(12)
led = LEDStrip(driver)

anim = StripChannelTest(led)
anim.run()

It should display something like this:

If the RGB ordering is correct, the pattern should start with 1 red led, 2 green leds, and 3 blue leds. If you see different colors, the count of each color tells you what the position for that color in the channel order. So, for example, if you see 1 Blue, and 2 Red, and 3 Green leds then the channel order should be BRG (Blue, Red, Green) and the driver should be configured as such:

driver = DriverLPD8806(num, c_order = ChannelOrder.BRG)

The ChannelOrder enumeration lives in bibliopixel.drivers.driver_base and contains options for all six possible channel orders.