# RGB LED Matrices with CircuitPython

## Overview

![](https://cdn-learn.adafruit.com/assets/assets/000/090/494/medium800thumb/led_matrices_ezgif-6-abebf4def3a4.jpg?1587399351)

Bring a little bit of Times Square into your home with our RGB LED matrix panels. These panels are normally used to make video walls — here in New York we see them on the sides of buses and on bus stops — to display animations or short video clips. We thought they looked really cool so we picked up a few boxes from the factory. They come in a variety of sizes from 16x32 pixels and up.

Using the new RGBMatrix library, CircuitPython can blast pixels to these displays really quickly. Use it with [DisplayIO](https://learn.adafruit.com/circuitpython-display-support-using-displayio) for showing text, bitmaps, animations, and more. Not familiar with DisplayIO? [There's a guide for that.](https://learn.adafruit.com/circuitpython-display-support-using-displayio)

**This guide is for select CircuitPython boards — ones based on the SAMD51 (Feather M4, ItsyBitsy M4, Metro M4 etc) and nRF52840 (Feather nRF52840, ItsyBitsy nRF52840, etc).**

**We have a [different guide for Raspberry Pi](https://learn.adafruit.com/adafruit-rgb-matrix-plus-real-time-clock-hat-for-raspberry-pi) and [Arduino](https://learn.adafruit.com/32x16-32x32-rgb-led-matrix/overview).**

Primary: 

Info: On the 64x32 2.5mm panels (product ID [5036](https://www.adafruit.com/product/5036)), the green and blue channels are swapped compared to the standard HUB75 pinout. When using with libraries, simply swap the pin numbers for G1, G2 with B1, B2 in software to flip them back around.

If you are using the MatrixPortal library, you do not need to swap pins explicitly. Instead, add this argument to the constructor: `MatrixPortal(..., color_order="RBG")`. The default order is `"RGB"`, and this argument will swap the pins to match the specified `"RBG"` order.

![](https://cdn-learn.adafruit.com/assets/assets/000/002/935/medium800/led_matrix_rgbmatrix.jpg?1396789179)

![](https://cdn-learn.adafruit.com/assets/assets/000/002/936/medium800/led_matrix_rgbmatrix3232_lrg.jpg?1396789186)

These panels require 12 or 13 digital pins (6 bit data, 6 or 7 bit control) and a good 5V power supply, at least a couple amps per panel. We suggest our 2A (or larger) regulated 5V adapters and either a terminal block DC jack, or solder a jack from our DC extension cord. Please read the rest of our tutorial for more details!  
  
Keep in mind that these displays are normally designed to be driven by FPGAs or other high speed processors; they do not have built in PWM control of any kind. Instead, you're supposed to redraw the screen over and over to 'manually' PWM the whole thing.  RGBMatrix takes care of that for you, offering up to thousands of bright colors.  Depending on settings (width, height, and color depth) and microcontroller, RGBMatrix takes from 10% to 60% of the processing power away from CircuitPython.

![](https://cdn-learn.adafruit.com/assets/assets/000/002/937/medium800/led_matrix_plasma.jpg?1396789196)

Of course, we wouldn't leave you with a datasheet and a "good luck!" We have a full wiring diagrams and working CircuitPython code.

# RGB LED Matrices with CircuitPython

## Connecting with Feather M4 Express & FeatherWing

![](https://cdn-learn.adafruit.com/assets/assets/000/059/612/medium800/adafruit_products_3036_demo_02_ORIG_2018_08.jpg?1534964893)

The easiest way to get started with RGBMatrix is with the **RGB Matrix FeatherWing**. Now you can quickly and easily create projects featuring your favorite 16 or 32-pixel tall matrix boards.

### Adafruit RGB Matrix Featherwing Kit

[Adafruit RGB Matrix Featherwing Kit](https://www.adafruit.com/product/3036)
Ahoy! It's time to create a dazzling light up project with our new **RGB Matrix FeatherWing**. Now you can quickly and easily create projects featuring your favorite 16 or 32-pixel tall matrix boards. Using our RGB Matrix library is easy and...

In Stock
[Buy Now](https://www.adafruit.com/product/3036)
[Related Guides to the Product](https://learn.adafruit.com/products/3036/guides)
![Video of a woman with a turquoise manicure attaching a driver board to the back of a LED matrix panel. She flips the matrix panel around reveal it lit up text in rainbow colors: "Ada
fruit
32x32
*RGB* ](https://cdn-shop.adafruit.com/product-videos/640x480/3036-05.jpg)

### Adafruit RGB Matrix FeatherWing Kit - For nRF52840 Feathers

[Adafruit RGB Matrix FeatherWing Kit - For nRF52840 Feathers](https://www.adafruit.com/product/4702)
Ahoy! It's time to create a dazzling light up project with our new **RGB Matrix FeatherWing for nRF52840**. Now you can quickly and easily create projects featuring your favorite 16 or 32-pixel tall matrix boards. Using our RGB Matrix library...

In Stock
[Buy Now](https://www.adafruit.com/product/4702)
[Related Guides to the Product](https://learn.adafruit.com/products/4702/guides)
![White woman wearing blue gloved rotating an RGB LED matrix. The LED animation resembles falling colored sand.](https://cdn-shop.adafruit.com/product-videos/640x480/4702-09.jpg)

 **Please note:** This wing is only tested/designed to work with the SAMD51 M4 Feather or the nRF52840 Feather.  It may be possible to use the extra holes as a prototyping area to adapt it to other Feathers, but that's beyond the scope of this guide.

![adafruit_products_3036-06.jpg](https://cdn-learn.adafruit.com/assets/assets/000/059/624/medium640/adafruit_products_3036-06.jpg?1587399786)

This wing can be assembled in one of two ways. You can either solder in a 2x8 IDC shrouded header on the top, then plug in the IDC cable that came with your matrix. This makes it easy to stack on top of your Feather. Or, you can solder in the 2x10 socket header on the _bottom_ of the Wing, and then stack your Feather on top. That way you can _plug it directly into the back of the matrix_ \*mind blown\*

![adafruit_products_3036_iso_ORIG_2018_08.jpg](https://cdn-learn.adafruit.com/assets/assets/000/059/623/medium640/adafruit_products_3036_iso_ORIG_2018_08.jpg?1587399744)

This FeatherWing will work great with any of our [16x32](https://www.adafruit.com/?q=16x32), [32x32](https://www.adafruit.com/?q=32x32) or [64x32](https://www.adafruit.com/?q=64x32) RGB matrices, and is definitely the easiest way to glow and go.

![adafruit_products_3036_demo.gif](https://cdn-learn.adafruit.com/assets/assets/000/059/627/medium640thumb/adafruit_products_3036_demo.jpg?1534970310)

Either way you decide to go, you can plug a 5V DC power pack into the 2.1mm DC jack. That 5V is polarity protected and then output on the other side to a 5.08mm terminal block. An onboard regulator will provide 3.3V power to your Feather, so you don't need a separate USB or battery. This makes for a very compact build!

Each 'Wing kit comes with one FeatherWing PCB with surface mount parts attached, a 2x8 IDC header, a 2x10 female socket, 2.1mm DC jack, 5.08mm terminal block, and some male header. You may also want some [Feather stacking headers](https://www.adafruit.com/product/2830) or [female headers](https://www.adafruit.com/product/2886) depending on how you plan to attach/stack your Feather.

Use the following block of code to initialize a 64x32 matrix.

```python
displayio.release_displays()
matrix = rgbmatrix.RGBMatrix(
    width=64, bit_depth=4,
    rgb_pins=[board.D6, board.D5, board.D9, board.D11, board.D10, board.D12],
    addr_pins=[board.A5, board.A4, board.A3, board.A2],
    clock_pin=board.D13, latch_pin=board.D0, output_enable_pin=board.D1)
display = framebufferio.FramebufferDisplay(matrix)
```

Use the following block of code to initialize a 32x16 matrix. In this mode, you may **not** use pin A2 unless you cut the trace connecting it to the header, because it is connected to GND on the RGB matrix. 

```python
displayio.release_displays()
matrix = rgbmatrix.RGBMatrix(
    width=32, bit_depth=4,
    rgb_pins=[board.D6, board.D5, board.D9, board.D11, board.D10, board.D12],
    addr_pins=[board.A5, board.A4, board.A3],
    clock_pin=board.D13, latch_pin=board.D0, output_enable_pin=board.D1)
display = framebufferio.FramebufferDisplay(matrix)
```

# RGB LED Matrices with CircuitPython

## Connecting with Feather RP2040 & FeatherWing

![](https://cdn-learn.adafruit.com/assets/assets/000/100/730/medium800thumb/led_matrices_ezgif-1-a2a44c6e2995.jpg?1615675873)

The easiest way to get started with RGBMatrix is with the **RGB Matrix FeatherWing**. Now you can quickly and easily create projects featuring your favorite 16 or 32-pixel tall matrix boards.

### Adafruit RGB Matrix Featherwing Kit

[Adafruit RGB Matrix Featherwing Kit](https://www.adafruit.com/product/3036)
Ahoy! It's time to create a dazzling light up project with our new **RGB Matrix FeatherWing**. Now you can quickly and easily create projects featuring your favorite 16 or 32-pixel tall matrix boards. Using our RGB Matrix library is easy and...

In Stock
[Buy Now](https://www.adafruit.com/product/3036)
[Related Guides to the Product](https://learn.adafruit.com/products/3036/guides)
![Video of a woman with a turquoise manicure attaching a driver board to the back of a LED matrix panel. She flips the matrix panel around reveal it lit up text in rainbow colors: "Ada
fruit
32x32
*RGB* ](https://cdn-shop.adafruit.com/product-videos/640x480/3036-05.jpg)

### Adafruit RGB Matrix FeatherWing Kit - For nRF52840 Feathers

[Adafruit RGB Matrix FeatherWing Kit - For nRF52840 Feathers](https://www.adafruit.com/product/4702)
Ahoy! It's time to create a dazzling light up project with our new **RGB Matrix FeatherWing for nRF52840**. Now you can quickly and easily create projects featuring your favorite 16 or 32-pixel tall matrix boards. Using our RGB Matrix library...

In Stock
[Buy Now](https://www.adafruit.com/product/4702)
[Related Guides to the Product](https://learn.adafruit.com/products/4702/guides)
![White woman wearing blue gloved rotating an RGB LED matrix. The LED animation resembles falling colored sand.](https://cdn-shop.adafruit.com/product-videos/640x480/4702-09.jpg)

 **Please note:** This wing is only tested/designed to work with the SAMD51 M4 Feather or the nRF52840 Feather.  It may be possible to use the extra holes as a prototyping area to adapt it to other Feathers, but that's beyond the scope of this guide.

![adafruit_products_3036-06.jpg](https://cdn-learn.adafruit.com/assets/assets/000/059/624/medium640/adafruit_products_3036-06.jpg?1587399786)

This wing can be assembled in one of two ways. You can either solder in a 2x8 IDC shrouded header on the top, then plug in the IDC cable that came with your matrix. This makes it easy to stack on top of your Feather. Or, you can solder in the 2x10 socket header on the _bottom_ of the Wing, and then stack your Feather on top. That way you can _plug it directly into the back of the matrix_ \*mind blown\*

![adafruit_products_3036_iso_ORIG_2018_08.jpg](https://cdn-learn.adafruit.com/assets/assets/000/059/623/medium640/adafruit_products_3036_iso_ORIG_2018_08.jpg?1587399744)

This FeatherWing will work great with any of our [16x32](https://www.adafruit.com/?q=16x32), [32x32](https://www.adafruit.com/?q=32x32) or [64x32](https://www.adafruit.com/?q=64x32) RGB matrices, and is definitely the easiest way to glow and go.

![adafruit_products_3036_demo.gif](https://cdn-learn.adafruit.com/assets/assets/000/059/627/medium640thumb/adafruit_products_3036_demo.jpg?1534970310)

Either way you decide to go, you can plug a 5V DC power pack into the 2.1mm DC jack. That 5V is polarity protected and then output on the other side to a 5.08mm terminal block. An onboard regulator will provide 3.3V power to your Feather, so you don't need a separate USB or battery. This makes for a very compact build!

Each 'Wing kit comes with one FeatherWing PCB with surface mount parts attached, a 2x8 IDC header, a 2x10 female socket, 2.1mm DC jack, 5.08mm terminal block, and some male header. You may also want some [Feather stacking headers](https://www.adafruit.com/product/2830) or [female headers](https://www.adafruit.com/product/2886) depending on how you plan to attach/stack your Feather.

Use the following block of code to initialize a 64x32 matrix.

```python
displayio.release_displays()
matrix = rgbmatrix.RGBMatrix(
    width=64, bit_depth=4,
    rgb_pins=[board.D6, board.D5, board.D9, board.D11, board.D10, board.D12],
    addr_pins=[board.D25, board.D24, board.A3, board.A2],
    clock_pin=board.D13, latch_pin=board.D0, output_enable_pin=board.D1)
display = framebufferio.FramebufferDisplay(matrix)
```

Use the following block of code to initialize a 32x16 matrix. In this mode, you may **not** use pin A2 unless you cut the trace connecting it to the header, because it is connected to GND on the RGB matrix. 

```python
displayio.release_displays()
matrix = rgbmatrix.RGBMatrix(
    width=32, bit_depth=4,
    rgb_pins=[board.D6, board.D5, board.D9, board.D11, board.D10, board.D12],
    addr_pins=[board.D25, board.D24, board.A3],
    clock_pin=board.D13, latch_pin=board.D0, output_enable_pin=board.D1)
display = framebufferio.FramebufferDisplay(matrix)
```

Info: 

## Complete example: RP2040 Feather Scroller

Save the below file (called **rp2040.py** to **CIRCUITPY** as **code.py** and also save the bitmap image file [**pi-logo32b.bmp**](https://github.com/adafruit/Adafruit_Learning_System_Guides/raw/main/CircuitPython_RGBMatrix/pi-logo32b.bmp) to **CIRCUITPY.** The 64x32 matrix will scroll the text "RP2040 Feather" over a Raspberry Pi logo.

https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/CircuitPython_RGBMatrix/rp2040/code.py

# RGB LED Matrices with CircuitPython

## Connecting Using a Proto Shield

Your LED matrix display needs 12 or 13 digital pins, and only specific combinations will work.  If this much custom wiring worries you, [choose the Feather M4 Express with an](https://learn.adafruit.com/led-matrices-with-circuitpython/m4-featherwing)[RGB Matrix Featherwing Kit](https://learn.adafruit.com/led-matrices-with-circuitpython/m4-featherwing), because just by connecting the headers you get everything in the right place!

If you hold a ribbon cable flat — no folds — and with both connectors facing you, keys pointed the same direction — there’s is a 1:1 correlation between the pins. The top-right pin on one plug links to the top-right on the other plug, and so forth. This holds true even if the cable has a doubled-over strain relief. **As long as the keys point the same way and the plugs face the same way, pins are in the same positions at both ends.**

![](https://cdn-learn.adafruit.com/assets/assets/000/023/924/medium800/led_matrix_cable1.png?1426546582)

 **Either end of the ribbon cable can be plugged into the matrix INPUT socket.**

The free end of the ribbon can point toward the center of the matrix, or hang off the side…the pinout is still the same. Notice below the direction of the “key” doesn’t change.

![](https://cdn-learn.adafruit.com/assets/assets/000/023/928/medium800/led_matrix_ribbon-2ways.png?1426548204)

A dual-row header gets installed on the prototyping area, similar to the connector on the matrix. Just like the ribbon cable lying flat, as long as these two headers are _aligned the same way,_ they’ll  **match pin-for-pin**.

![](https://cdn-learn.adafruit.com/assets/assets/000/023/939/medium800/led_matrix_aligned.png?1426554087)

Wires are then soldered from the header to specific microcontroller pins. Try to keep wire lengths reasonably short to avoid signal interference.

Using color-coded wires helps a _lot!_ If you don’t have colored wires, that’s okay, just pay close attention where everything goes. Our goal is a proto shield something like this (but this is just an example; refer to the following pages for specific information for your board):

![](https://cdn-learn.adafruit.com/assets/assets/000/023/930/medium800/led_matrix_proto-example.jpg?1426549088)

 **You can also use a plain 2x8-pin male header, or two 1x8 sections** installed side-by-side (as in the photo above). Since there’s no alignment key with this setup, you might want to indicate it with some tape or a permanent marker.

Depending on the make and model of proto shield, some pins are designed to connect in short rows. Others don’t. For the latter, strip a little extra insulation and bend the wire to wrap around the leg of the socket from behind, then solder.

![led_matrix_backside.jpg](https://cdn-learn.adafruit.com/assets/assets/000/023/940/medium640/led_matrix_backside.jpg?1426560083)

## Connect Ground Wires
 **32x32** and **64x32** matrices require **three ** ground connections. **32x16** matrices have **four**.

 

Most proto shields have _tons_ of grounding points, so you shouldn’t have trouble finding places to connect these.

![led_matrix_header-gnds.png](https://cdn-learn.adafruit.com/assets/assets/000/023/942/medium640/led_matrix_header-gnds.png?1426568010)

## Upper RGB Data
Pins **R1** , **G1** and **B1** (labeled R0, B0 and G0 on some matrices) deliver data to the **top half** of the display.

 

![led_matrix_header-rgb1.png](https://cdn-learn.adafruit.com/assets/assets/000/023/943/medium640/led_matrix_header-rgb1.png?1426565078)

## Lower RGB Data
Pins **R2** , **G2** and **B2** (labeled R1, G1 and B1 on some matrices) deliver data to the **bottom half ** of the display. 

![led_matrix_header-rgb2.png](https://cdn-learn.adafruit.com/assets/assets/000/023/944/medium640/led_matrix_header-rgb2.png?1426580512)

## Row Select Lines
Pins **A** , **B** , **C** and **D** select which two rows of the display are currently lit. ( **32x16 matrices don’t have a “D” pin** — it’s connected to **ground ** instead.)

![led_matrix_header-rows.png](https://cdn-learn.adafruit.com/assets/assets/000/023/945/medium640/led_matrix_header-rows.png?1426580569)

## LAT Wire
The **LAT** (latch) signal marks the end of a row of data.

![led_matrix_header-lat.png](https://cdn-learn.adafruit.com/assets/assets/000/023/946/medium640/led_matrix_header-lat.png?1426565395)

## OE Wire
 **OE** (output enable) switches the LEDs off when transitioning from one row to the next.

![led_matrix_header-oe.png](https://cdn-learn.adafruit.com/assets/assets/000/023/948/medium640/led_matrix_header-oe.png?1426565436)

## CLK Wire

Last one!

The **CLK** (clock) signal marks the arrival of each bit of data.

![led_matrix_header-clk.png](https://cdn-learn.adafruit.com/assets/assets/000/023/947/medium640/led_matrix_header-clk.png?1426565431)

Want to use a breadboard?  We've got you covered too.  With the Breakout Helper, the 16-pin header can straddle that big gap in the middle.

### IDC Breakout Helper - 2x8 (16 pin)

[IDC Breakout Helper - 2x8 (16 pin)](https://www.adafruit.com/product/2104)
This **2x8 (16 pin - 0.1" spaced) IDC Breadboard Helper **is great in conjunction with any 16-pin IDC cables. It comes in two parts, a 'pin-through' socket and...

In Stock
[Buy Now](https://www.adafruit.com/product/2104)
[Related Guides to the Product](https://learn.adafruit.com/products/2104/guides)
![16 Pin IDC Breakout Helper Soldered into perma-proto](https://cdn-shop.adafruit.com/640x480/2104-05.jpg)

# RGB LED Matrices with CircuitPython

## Feather M4 Express

The easiest way to connect a LED matrix to the Feather M4 Express is using the RGB Matrix FeatherWing kit. This board works **only** with the Feather M4 Express, not other Feather boards like the nRF Feathers. If you've got the FeatherWing, [jump over to this page](https://learn.adafruit.com/led-matrices-with-circuitpython/m4-featherwing). Otherwise, read on and get wiring!

### Adafruit RGB Matrix Featherwing Kit

[Adafruit RGB Matrix Featherwing Kit](https://www.adafruit.com/product/3036)
Ahoy! It's time to create a dazzling light up project with our new **RGB Matrix FeatherWing**. Now you can quickly and easily create projects featuring your favorite 16 or 32-pixel tall matrix boards. Using our RGB Matrix library is easy and...

In Stock
[Buy Now](https://www.adafruit.com/product/3036)
[Related Guides to the Product](https://learn.adafruit.com/products/3036/guides)
![Video of a woman with a turquoise manicure attaching a driver board to the back of a LED matrix panel. She flips the matrix panel around reveal it lit up text in rainbow colors: "Ada
fruit
32x32
*RGB* ](https://cdn-shop.adafruit.com/product-videos/640x480/3036-05.jpg)

To hook an LED matrix to the Feather M4 Express, make the connections on the left.  Remember that for a 16-line matrix, connect 4 GND wires and address wires A, B, and C.  For a 32-line matrix, connect 3 GND wires and address wires A, B, C, and D.

![led_matrices_protomatter-featherm4express_bb.png](https://cdn-learn.adafruit.com/assets/assets/000/094/791/medium640/led_matrices_protomatter-featherm4express_bb.png?1600440806)

Use the following block of code to initialize a 64x32 matrix. Remember to connect all 4 address pins: A, B, C, and D.

Warning: 

```python
displayio.release_displays()
matrix = rgbmatrix.RGBMatrix(
    width=64, bit_depth=4,
    rgb_pins=[board.D6, board.D5, board.D9, board.D11, board.D10, board.D12],
    addr_pins=[board.A5, board.A4, board.A3, board.A2],
    clock_pin=board.D13, latch_pin=board.D0, output_enable_pin=board.D1)
display = framebufferio.FramebufferDisplay(matrix)
```

Use the following block of code to initialize a 32x16 matrix. Remember to connect just 3 address pins: A, B, and C. Hook a fourth GND wire instead of A3.

```python
displayio.release_displays()
matrix = rgbmatrix.RGBMatrix(
    width=32, bit_depth=4,
    rgb_pins=[board.D6, board.D5, board.D9, board.D11, board.D10, board.D12],
    addr_pins=[board.A5, board.A4, board.A3],
    clock_pin=board.D13, latch_pin=board.D0, output_enable_pin=board.D1)
display = framebufferio.FramebufferDisplay(matrix)
```

# RGB LED Matrices with CircuitPython

## Feather nRF52840

Warning: 

To hook an LED matrix to the Feather nRF52840 Express or Sense, make the connections on the left. Remember that for a 16-line matrix, connect 4 GND wires and address wires A, B, and C. For a 32-line matrix, connect 3 GND wires and address wires A, B, C, and D.

![led_matrices_protomatter-nrf52840feather_bb.png](https://cdn-learn.adafruit.com/assets/assets/000/094/724/medium640/led_matrices_protomatter-nrf52840feather_bb.png?1600099808)

Use the following block of code to initialize a 64x32 matrix. Remember to connect all 4 address pins: A, B, C, and D.

Warning: 

```python
displayio.release_displays()
matrix = rgbmatrix.RGBMatrix(
    width=64, bit_depth=4,
    rgb_pins=[board.D6, board.A5, board.A1, board.A0, board.A4, board.D11],
    addr_pins=[board.D10, board.D5, board.D13, board.D9],
    clock_pin=board.D12, latch_pin=board.RX, output_enable_pin=board.TX)
display = framebufferio.FramebufferDisplay(matrix)
```

Use the following block of code to initialize a 32x16 matrix. Remember to connect just 3 address pins: A, B, and C. Hook a fourth GND wire instead of A3.

```python
displayio.release_displays()
matrix = rgbmatrix.RGBMatrix(
    width=32, bit_depth=4,
    rgb_pins=[board.D6, board.A5, board.A1, board.A0, board.A4, board.D11],
    addr_pins=[board.D10, board.D5, board.D13],
    clock_pin=board.D12, latch_pin=board.RX, output_enable_pin=board.TX)
display = framebufferio.FramebufferDisplay(matrix)
```

# RGB LED Matrices with CircuitPython

## ItsyBitsy M4

To hook an LED matrix to the ItsyBitsy M4, make the connections on the left. Remember that for a 16-line matrix, connect 4 GND wires and address wires A, B, and C. For a 32-line matrix, connect 3 GND wires and address wires A, B, C, and D.

![led_matrices_itsybitsym4express_bb.png](https://cdn-learn.adafruit.com/assets/assets/000/097/153/medium640/led_matrices_itsybitsym4express_bb.png?1605798512)

Use the following block of code to initialize a 64x32 matrix. Remember to connect all 4 address pins: A, B, C, and D.

Warning: 

```python
displayio.release_displays()
matrix = rgbmatrix.RGBMatrix(
    width=64, bit_depth=4,
    rgb_pins=[board.MOSI, board.SCK, board.A5, board.A4, board.A0, board.A1],
    addr_pins=[board.D5, board.D7, board.D9, board.D10],
    clock_pin=board.D13, latch_pin=board.D12, output_enable_pin=board.D11)
display = framebufferio.FramebufferDisplay(matrix)
```

Use the following block of code to initialize a 32x16 matrix. Remember to connect just 3 address pins: A, B, and C. Hook a fourth GND wire instead of A3.

```python
displayio.release_displays()
matrix = rgbmatrix.RGBMatrix(
    width=32, bit_depth=4,
    rgb_pins=[board.MOSI, board.SCK, board.A5, board.A4, board.A0, board.A1],
    addr_pins=[board.D5, board.D7, board.D9],
    clock_pin=board.D13, latch_pin=board.D12, output_enable_pin=board.D11)
display = framebufferio.FramebufferDisplay(matrix)
```

# RGB LED Matrices with CircuitPython

## ItsyBitsy nRF52840

To hook an LED matrix to the ItsyBitsy nRF52840, make the connections on the left. Remember that for a 16-line matrix, connect 4 GND wires and address wires A, B,  and C. For a 32-line matrix, connect 3 GND wires and address wires A, B, C, and D.

![led_matrices_itsybitsynrf52840express_bb.png](https://cdn-learn.adafruit.com/assets/assets/000/094/719/medium640/led_matrices_itsybitsynrf52840express_bb.png?1600099263)

Use the following block of code to initialize a 64x32 matrix. Remember to connect all 4 address pins: A, B, C, and D.

Warning: 

```python
displayio.release_displays()
matrix = rgbmatrix.RGBMatrix(
    width=64, bit_depth=4,
    rgb_pins=[board.A3, board.A2, board.A1, board.RX, board.TX, board.D5],
    addr_pins=[board.D7, board.D9, board.D10, board.D12],
    clock_pin=board.D2, latch_pin=board.D11, output_enable_pin=board.MISO)
display = framebufferio.FramebufferDisplay(matrix)
```

Use the following block of code to initialize a 32x16 matrix. Remember to connect just 3 address pins: A, B, and C. Hook a fourth GND wire instead of A3.

```python
displayio.release_displays()
matrix = rgbmatrix.RGBMatrix(
    width=32, bit_depth=4,
    rgb_pins=[board.A3, board.A2, board.A1, board.RX, board.TX, board.D5],
    addr_pins=[board.D7, board.D9, board.D10],
    clock_pin=board.D2, latch_pin=board.D11, output_enable_pin=board.MISO)
display = framebufferio.FramebufferDisplay(matrix)
```

# RGB LED Matrices with CircuitPython

## Metro M4 Express

To hook an LED matrix to the Metro M4 Express or Metro M4 Airlift Lite, make the connections on the left. Remember that for a 16-line matrix, connect 4 GND wires and address wires A, B, and C. For a 32-line matrix, connect 3 GND wires and address wires A, B, C, and D.

![led_matrices_metrom4express_bb.png](https://cdn-learn.adafruit.com/assets/assets/000/094/714/medium640/led_matrices_metrom4express_bb.png?1600098818)

Use the following block of code to initialize a 64x32 matrix. Remember to connect all 4 address pins: A, B, C, and D.

Warning: 

```python
displayio.release_displays()
matrix = rgbmatrix.RGBMatrix(
    width=64, bit_depth=4,
    rgb_pins=[board.D8, board.D9, board.D10, board.D11, board.D12, board.D13],
    addr_pins=[board.D4, board.D5, board.D6, board.D7],
    clock_pin=board.D1, latch_pin=board.D3, output_enable_pin=board.D2)
display = framebufferio.FramebufferDisplay(matrix)
```

Use the following block of code to initialize a 32x16 matrix. Remember to connect just 3 address pins: A, B, and C. Hook a fourth GND wire instead of A3.

```python
displayio.release_displays()
matrix = rgbmatrix.RGBMatrix(
    width=32, bit_depth=4,
    rgb_pins=[board.D8, board.D9, board.D10, board.D11, board.D12, board.D13],
    addr_pins=[board.D4, board.D5, board.D6],
    clock_pin=board.D1, latch_pin=board.D3, output_enable_pin=board.D2)
display = framebufferio.FramebufferDisplay(matrix)
```

## Shields Up

If you're using the [RGB Matrix Shield](https://www.adafruit.com/product/2601) with the Metro M4 Express, you will need to make a hardware modification.

![](https://cdn-learn.adafruit.com/assets/assets/000/096/141/medium800/led_matrices_2601-05.jpg?1603206071)

The RGB Matrix Shield is designed so that you can customize it to the requirements of your board.  We need to change which pin is used for the "CLK" (clock) signal.

There is a small copper trace between the two larger pads.  Using a razor blade, cut or scrape away this trace.  (Young people, please have an adult do this step!)  Then, use your multimeter in continuity mode to verify that there is no connection between the two rectangular pads.

Next, make a connection from the A4 pin to the CLK pin by soldering in a new wire as shown.  The wire can be on the top or on the bottom.

![led_matrices_PXL_20201020_144723169.jpg](https://cdn-learn.adafruit.com/assets/assets/000/096/139/medium640/led_matrices_PXL_20201020_144723169.jpg?1603205675)

![led_matrices_Screenshot_2020-10-20_09-46-52.png](https://cdn-learn.adafruit.com/assets/assets/000/096/140/medium640/led_matrices_Screenshot_2020-10-20_09-46-52.png?1603205857)

Once that's done, use the following block of code to initialize a 64x32 matrix:

```python
matrix = rgbmatrix.RGBMatrix(
    width=64,
    height=32,
    bit_depth=1,
    rgb_pins=[board.D2, board.D3, board.D4, board.D5, board.D6, board.D7],
    addr_pins=[board.A0, board.A1, board.A2, board.A3],
    clock_pin=board.A4,
    latch_pin=board.D10,
    output_enable_pin=board.D9,
)
```

Use the following block of code to initialize a 32x16 matrix:

```python
matrix = rgbmatrix.RGBMatrix(
    width=32,
    height=16,
    bit_depth=1,
    rgb_pins=[board.D2, board.D3, board.D4, board.D5, board.D6, board.D7],
    addr_pins=[board.A0, board.A1, board.A2],
    clock_pin=board.A4,
    latch_pin=board.D10,
    output_enable_pin=board.D9,
)
```

# RGB LED Matrices with CircuitPython

## Feather STM32F405

Primary: 

To hook an LED matrix to the Feather STM32F405, make the connections on the left. Remember that for a 16-line matrix, connect 4 GND wires and address wires A, B, and C. For a 32-line matrix, connect 3 GND wires and address wires A, B, C, and D.

![led_matrices_protomatter-featherstm32_bb.png](https://cdn-learn.adafruit.com/assets/assets/000/094/795/medium640/led_matrices_protomatter-featherstm32_bb.png?1600443262)

Use the following block of code to initialize a 64x32 matrix. Remember to connect all 4 address pins: A, B, C, and D.

Warning: 

```python
displayio.release_displays()
matrix = rgbmatrix.RGBMatrix(
    width=64, bit_depth=4,
    rgb_pins=[board.D13, board.D12, board.D11, board.A4, board.A5, board.D6],
    addr_pins=[board.A0, board.A1, board.A2, board.A3],
    clock_pin=board.D5, latch_pin=board.D9, output_enable_pin=board.D10)
display = framebufferio.FramebufferDisplay(matrix)
```

Use the following block of code to initialize a 32x16 matrix. Remember to connect just 3 address pins: A, B, and C. Hook a fourth GND wire instead of A3.

```python
displayio.release_displays()
matrix = rgbmatrix.RGBMatrix(
    width=32, bit_depth=4,
    rgb_pins=[board.D13, board.D12, board.D11, board.A4, board.A5, board.D6],
    addr_pins=[board.A0, board.A1, board.A2],
    clock_pin=board.D5, latch_pin=board.D9, output_enable_pin=board.D10)
display = framebufferio.FramebufferDisplay(matrix)
```

# RGB LED Matrices with CircuitPython

## Metro ESP32S2

![](https://cdn-learn.adafruit.com/assets/assets/000/102/150/medium800/led_matrices_2601-05.jpg?1621006139)

A great way to get started with RGBMatrix is with the **RGB Matrix Shield** and the **Metro ESP32-S2**. Now you can quickly and easily create projects featuring your favorite 16 or 32-pixel tall matrix boards.

### Adafruit Metro ESP32-S2

[Adafruit Metro ESP32-S2](https://www.adafruit.com/product/4775)
What's Metro shaped and has an ESP32-S2 WiFi module? What has a STEMMA QT connector for I2C devices, and a Lipoly charger circuit? What has your favorite Espressif WiFi microcontroller and lots of memory for your next IoT project?

That's right - its the new Adafruit Metro...

In Stock
[Buy Now](https://www.adafruit.com/product/4775)
[Related Guides to the Product](https://learn.adafruit.com/products/4775/guides)
![Angled shot of Adafruit Metro esp32-s2 ](https://cdn-shop.adafruit.com/640x480/4775-06.jpg)

### Adafruit RGB Matrix Shield for Arduino

[Adafruit RGB Matrix Shield for Arduino](https://www.adafruit.com/product/2601)
Our RGB matrices are dazzling, with their hundreds or even _thousands_ of individual RGB LEDs. Compared to NeoPixels, they've got great density, power usage and the price-per-LED can't be beat. But...(isn't there always a _but_?) You need to use our special library to...

In Stock
[Buy Now](https://www.adafruit.com/product/2601)
[Related Guides to the Product](https://learn.adafruit.com/products/2601/guides)
![Adafruit RGB Matrix Shield for Arduino connected to a LED Matrix that reads "Adafruit Industries LED MATIX! 32x64 *RGB*"](https://cdn-shop.adafruit.com/640x480/2601-02.jpg)

For a small panel, you can use the screw terminals on the Adafruit RGB Matrix Shield together with a an appropriate DC power adapter on the Metro. For a larger panel, you'll need an independent 5V supply at several amps.

In any case, using USB power alone is not recommended, as the RGB Matrix can draw a lot of current.

Each Shield kit comes with one Shield PCB, a 2x8 IDC header, 5.08mm terminal block, and some male header.

Use the following block of code to initialize a 64x32 matrix.

```python
displayio.release_displays()
matrix = rgbmatrix.RGBMatrix(
    width=32,
    bit_depth=6,
    rgb_pins=[board.IO7, board.IO8, board.IO9, board.IO10, board.IO11, board.IO12],
    addr_pins=[board.A0, board.A1, board.A2, board.A3],
    clock_pin=board.IO13,
    latch_pin=board.IO15,
    output_enable_pin=board.IO14,
)
display = framebufferio.FramebufferDisplay(matrix)
```

Use the following block of code to initialize a 32x16 matrix. In this mode, you may **not** use pin A3 unless you cut the trace connecting it to the header, because it is connected to GND on the RGB matrix. 

```python
displayio.release_displays()
matrix = rgbmatrix.RGBMatrix(
    width=32,
    bit_depth=4,
    rgb_pins=[board.IO7, board.IO8, board.IO9, board.IO10, board.IO11, board.IO12],
    addr_pins=[board.A0, board.A1, board.A2],
    clock_pin=board.IO13,
    latch_pin=board.IO15,
    output_enable_pin=board.IO14,
)
display = framebufferio.FramebufferDisplay(matrix)
```

# RGB LED Matrices with CircuitPython

## Connecting Using a MatrixPortal

To hook an LED matrix to the MatrixPortal M4 board, just connect the power wires and press it on. Check out the **Prep the MatrixPortal** page for more detailed information. You can learn more about using the MatrixPortal in our [Adafruit MatrixPortal M4](https://learn.adafruit.com/adafruit-matrixportal-m4) guide.

![led_matrices_4745-12.jpg](https://cdn-learn.adafruit.com/assets/assets/000/095/288/medium640/led_matrices_4745-12.jpg?1601500759)

## 64x32 Matrix

Use the following block of code to initialize a 64x32 matrix.

```python
displayio.release_displays()
matrix = rgbmatrix.RGBMatrix(
    width=64, bit_depth=4,
    rgb_pins=[
        board.MTX_R1,
        board.MTX_G1,
        board.MTX_B1,
        board.MTX_R2,
        board.MTX_G2,
        board.MTX_B2
    ],
    addr_pins=[
        board.MTX_ADDRA,
        board.MTX_ADDRB,
        board.MTX_ADDRC,
        board.MTX_ADDRD
    ],
    clock_pin=board.MTX_CLK,
    latch_pin=board.MTX_LAT,
    output_enable_pin=board.MTX_OE
)
display = framebufferio.FramebufferDisplay(matrix)
```

## 32x16 Matrix

Use the following block of code to initialize a 32x16 matrix.

```python
displayio.release_displays()
matrix = rgbmatrix.RGBMatrix(
    width=32, bit_depth=4,
    rgb_pins=[
        board.MTX_R1,
        board.MTX_G1,
        board.MTX_B1,
        board.MTX_R2,
        board.MTX_G2,
        board.MTX_B2
    ],
    addr_pins=[
        board.MTX_ADDRA,
        board.MTX_ADDRB,
        board.MTX_ADDRC
    ],
    clock_pin=board.MTX_CLK,
    latch_pin=board.MTX_LAT,
    output_enable_pin=board.MTX_OE
)
display = framebufferio.FramebufferDisplay(matrix)
```

## 64x64 Matrix

Use the following block of code to initialize a 64x64 matrix. **Don't forget to close the Address E Line jumper with solder.** You'll need to check the datasheet for your matrix to determine whether to connect it to Pin 8 or 16.

Warning: 

```python
displayio.release_displays()
matrix = rgbmatrix.RGBMatrix(
    width=64, height=64, bit_depth=4,
    rgb_pins=[
        board.MTX_R1,
        board.MTX_G1,
        board.MTX_B1,
        board.MTX_R2,
        board.MTX_G2,
        board.MTX_B2
    ],
    addr_pins=[
        board.MTX_ADDRA,
        board.MTX_ADDRB,
        board.MTX_ADDRC,
        board.MTX_ADDRD,
        board.MTX_ADDRE
    ],
    clock_pin=board.MTX_CLK,
    latch_pin=board.MTX_LAT,
    output_enable_pin=board.MTX_OE
)
display = framebufferio.FramebufferDisplay(matrix)
```

# RGB LED Matrices with CircuitPython

## Prep the MatrixPortal

## Power Prep

The MatrixPortal supplies power to the matrix display panel via two standoffs. These come with protective tape applied (part of our manufacturing process) which MUST BE REMOVED!

Use some tweezers or a fingernail to remove the two amber circles.

![adafruit_io_mxprtl-3866.jpg](https://cdn-learn.adafruit.com/assets/assets/000/094/902/medium640/adafruit_io_mxprtl-3866.jpg?1600706317)

![adafruit_io_mxprtl-3867.jpg](https://cdn-learn.adafruit.com/assets/assets/000/094/903/medium640/adafruit_io_mxprtl-3867.jpg?1600706324)

## Power Terminals

Next, screw in the spade connectors to the corresponding standoff.

- **red** wire goes to **+5V**  
- **black** wire goes to **GND**

![adafruit_io_mxprtl-3869.jpg](https://cdn-learn.adafruit.com/assets/assets/000/094/907/medium640/adafruit_io_mxprtl-3869.jpg?1600706432)

![adafruit_io_mxprtl-3871.jpg](https://cdn-learn.adafruit.com/assets/assets/000/094/908/medium640/adafruit_io_mxprtl-3871.jpg?1600706551)

## Panel Power

Plug either one of the four-conductor power plugs into the power connector pins on the panel. The plug can only go in one way, and that way is marked on the board's silkscreen.

![adafruit_io_mxprtl-3872.jpg](https://cdn-learn.adafruit.com/assets/assets/000/094/910/medium640/adafruit_io_mxprtl-3872.jpg?1600706597)

![adafruit_io_mxprtl-3873.jpg](https://cdn-learn.adafruit.com/assets/assets/000/094/911/medium640/adafruit_io_mxprtl-3873.jpg?1600706672)

## Dual Matrix Setup

If you're planning to use a 64x64 matrix, [follow these instructions on soldering the Address E Line jumper](https://learn.adafruit.com/adafruit-matrixportal-m4/pinouts#address-e-line-jumper-3072815).

## Board Connection

Now, plug the board into the left side shrouded 8x2 connector as shown. The orientation matters, so take a moment to confirm that the **white indicator arrow on the matrix panel is oriented pointing up and right** as seen here and the MatrixPortal overhangs the edge of the panel when connected. This allows you to use the edge buttons from the front side.

 

Check nothing is impeding the board from plugging in firmly. If there's a plastic nub on the matrix that's keeping the Portal from sitting flat, cut it off with diagonal cutters

![adafruit_io_mxprtl-3874.jpg](https://cdn-learn.adafruit.com/assets/assets/000/094/912/medium640/adafruit_io_mxprtl-3874.jpg?1600706721)

![adafruit_io_mxprtl-3875.jpg](https://cdn-learn.adafruit.com/assets/assets/000/094/913/medium640/adafruit_io_mxprtl-3875.jpg?1600706732)

![](https://cdn-learn.adafruit.com/assets/assets/000/094/914/medium800/adafruit_io_mxprtl-3876.jpg?1600706891)

![](https://cdn-learn.adafruit.com/assets/assets/000/094/915/medium800/adafruit_io_mxprtl-3877.jpg?1600706894)

Info: 

# RGB LED Matrices with CircuitPython

## Example: Simple two-line text scroller

![](https://cdn-learn.adafruit.com/assets/assets/000/090/542/medium800thumb/led_matrices_JEpler.jpg?1587498342)

This example creates two lines of scrolling text on a 64x32 matrix using [CircuitPython Display Text](https://learn.adafruit.com/circuitpython-display-support-using-displayio/text). It's designed for the FeatherWing M4 Express, but you can adapt it to other boards by changing the lines that create the RGBMatrix object. We've thoroughly commented this example so it's a great place to start if you're not familiar with displayio.

For this example make sure to install the following library:

- [CircuitPython Display Text](https://github.com/adafruit/Adafruit_CircuitPython_Display_Text) - for displaying text

If you want to customize the example to use a different font, you'll also need

- [CircuitPython Bitmap Font Library](https://github.com/adafruit/Adafruit_CircuitPython_Bitmap_Font/) - for bitmap font support

Here's how the code will work:

- Create the RGBMatrix and FramebufferDisplay objects
- Create the two text labels to scroll
- Put them in a Group, and then show that Group
- Repeatedly scroll each label to the left, returning it to the far right hand side when it has gone all the way

https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/CircuitPython_RGBMatrix/simple_scroller/code.py

# RGB LED Matrices with CircuitPython

## Example: Two-line colorful text scroller

![](https://cdn-learn.adafruit.com/assets/assets/000/090/343/medium800thumb/led_matrices_ezgif.com-optimize.jpg?1586897902)

This example creates two lines of scrolling text on a 64x32 matrix. It's designed for the FeatherWing M4 Express, but you can adapt it to other boards by changing the lines that create the RGBMatrix object.

Because each letter is set to a different color, this example doesn't use the adafruit\_display\_text library.

To customize the text, simply make sure you keep the lines in pairs of equal length, and don't miss the comma at the end of each line.

https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/CircuitPython_RGBMatrix/scroller/code.py

# RGB LED Matrices with CircuitPython

## Example: (Ada)Fruit Machine

https://youtu.be/oTJibE0OcBQ

![](https://cdn-learn.adafruit.com/assets/assets/000/090/493/medium800thumb/led_matrices_ezgif-6-abebf4def3a4.jpg?1587399175)

This example simulates a "fruit machine", similar to a slot machine, using emoji from the Adafruit Discord server.  It's designed for the FeatherWing M4 Express, but you can adapt it to other boards by changing the lines that create the RGBMatrix object. The code is also designed for the 64x32 LED displays.

You'll also need the **[emoji.bmp](https://github.com/adafruit/Adafruit_Learning_System_Guides/raw/main/CircuitPython_RGBMatrix/emoji.bmp)** file on your **CIRCUITPY** drive.

https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/CircuitPython_RGBMatrix/fruit/code.py

# RGB LED Matrices with CircuitPython

## Example: Conway's "Game of Life"

https://youtu.be/x8MAx_PMnN4

According to Wikipedia, "[John Horton Conway](https://en.wikipedia.org/wiki/John_Horton_Conway) was an English mathematician active in the theory of finite groups, knot theory, number theory, combinatorial game theory and coding theory. He also made contributions to many branches of recreational mathematics, most notably the invention of the cellular automaton called the [Game of Life](https://en.wikipedia.org/wiki/Conway%27s_Game_of_Life)."

Web comic [XKCD](https://m.xkcd.com/2293/) memorialized his passing with a comic which showed a stick person turning into a "glider", a construct in the Game of Life which will continue moving indefinitely into empty space.

This example opens with a recreation of XKCD's tribute to Conway, then from time to time refreshes the display with a random state. It's designed for the FeatherWing M4 Express, but you can adapt it to other boards by changing the lines that create the RGBMatrix object.  The code is also designed for the 64x32  LED displays.  Unlike the other demos, it will adapt to other display sizes like 16x32 by changing the lines that create the RGBMatrix object.

https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/CircuitPython_RGBMatrix/life/code.py

# RGB LED Matrices with CircuitPython

## Intro to displayio

# RGB LED Matrices with CircuitPython

## Advanced: Multiple Panels

Primary: 

If you have multiple identical panels, you can extend a single display across them, vertically, horizontally, or both.

![](https://cdn-learn.adafruit.com/assets/assets/000/099/083/medium800/led_matrices_matrices-tiled-from-back.jpg?1611889371 Back view of four 64x32 panels in a 2x2 arrangement. The MatrixPortal controller is at top left.)

Inspect the rear of your panel. There are two 10-pin connectors. You can "chain" multiple displays by using a ribbon cable to hook the "OUT" of one panel to the "IN" of the next panel.

Many of Adafruit's panels include a ribbon cable; check the description.

![led_matrices_PXL_20210128_142039379.jpg](https://cdn-learn.adafruit.com/assets/assets/000/098/995/medium640/led_matrices_PXL_20210128_142039379.jpg?1611843815)

Next, you'll need to power all your panels. Each panel has a 4-pin power connector, and most of Adafruit's panels include a Y-splitter power cable which can be connected to 2 panels. **The power supply current requirement increases according to the number of panels, but the voltage requirement is always 5V**. Remember that we recommend a **5V 4A** supply for a single 64x32 pixel panel, so our recommendation becomes 4×2= **8A** for 2 panels and 4×4= **16A** for 4 panels.  By using dimmer colors and avoiding big solid areas on the display, you may be able to get by with a smaller power supply.

Danger: 

More displays also means more memory (RAM) usage. Using `bit_depth=6`, approximate RAM usage is as follows:

- one 64×32 panel uses 17kB
- two 64×32 panels use 33kB
- four 64×32 panels use 65kB

Using `bit_depth=3`, approximate RAM usage is as follows:

- one 64×32 panel uses 11kB
- two 64×32 panels use 21kB
- four 64×32 panels use 42kB

Using `bit_depth=1`, approximate RAM usage is as follows:

- one 64×32 panel uses 7kB
- two 64×32 panels use 13kB
- four 64×32 panels use 25kB

The total number of panels is limited by RAM usage, CPU usage and refresh rate. Other arrangements than those shown, such as 1×3, 3×1, 2x3, 3x2, etc., are possible.

## Chaining and Tiling
This script for MatrixPortal will be used to demonstrate the different chaining and tiling options:

```python
import displayio
import board
import rgbmatrix
import framebufferio

bit_depth = 1
base_width = 64
base_height = 32
chain_across = 1
tile_down = 1
serpentine = True

width = base_width * chain_across
height = base_height * tile_down

addr_pins = [board.MTX_ADDRA, board.MTX_ADDRB, board.MTX_ADDRC, board.MTX_ADDRD]
rgb_pins = [
    board.MTX_R1,
    board.MTX_G1,
    board.MTX_B1,
    board.MTX_R2,
    board.MTX_G2,
    board.MTX_B2,
]
clock_pin = board.MTX_CLK
latch_pin = board.MTX_LAT
oe_pin = board.MTX_OE

displayio.release_displays()
matrix = rgbmatrix.RGBMatrix(
                width=width,
                height=height,
                bit_depth=bit_depth,
                rgb_pins=rgb_pins,
                addr_pins=addr_pins,
                clock_pin=clock_pin,
                latch_pin=latch_pin,
                output_enable_pin=oe_pin,
                tile=tile_down, serpentine=serpentine,
            )
display = framebufferio.FramebufferDisplay(matrix)
```

We'll focus on the effect of these 3 settings:

- `chain_across`
- `tile_down`
- `serpentine`

Note how `chain_across` is used to calculate the `width` from the `base_width` and similarly that `tile_down` is used to calculate the `height` from the `base_height`.

The total number of displays is `chain_across * tile_down`.

Primary: 

## Purely horizontal arrangements
- `chain_across` = 1
- `tile_down` = 1
- `serpentine` doesn't matter

Uses a single panel, size is 64x32

![led_matrices_ksnip_20210128-084950.png](https://cdn-learn.adafruit.com/assets/assets/000/098/996/medium640/led_matrices_ksnip_20210128-084950.png?1611845407)

- `chain_across` = 2
- `tile_down` = 1
- `serpentine` doesn't matter

Uses two panels, total display size is 128x32

![led_matrices_ksnip_20210128-111853.png](https://cdn-learn.adafruit.com/assets/assets/000/099/019/medium640/led_matrices_ksnip_20210128-111853.png?1611854406)

- `chain_across` = 4
- `tile_down` = 1
- `serpentine` doesn't matter

Uses four panels, total display size is 256x32

![led_matrices_ksnip_20210128-111752.png](https://cdn-learn.adafruit.com/assets/assets/000/099/017/medium640/led_matrices_ksnip_20210128-111752.png?1611854296)

## Purely vertical arrangements

The value called "serpentine" controls whether every alternate row of panels is rotated 180 degrees. This is generally more convenient, due to the positions of the connectors. The approximate path of the ribbon cables are shown with the arrows.

- `chain_across` = 1
- `tile_down` = 4
- `serpentine` = `True`

Uses four panels, total display size is 64x128. Notice how displays 2 and 4 are rotated 180 degrees to minimize the length of ribbon cables required.

![led_matrices_ksnip_20210128-121507.png](https://cdn-learn.adafruit.com/assets/assets/000/099/033/medium640/led_matrices_ksnip_20210128-121507.png?1611857733)

- `chain_across` = 1
- `tile_down` = 4
- `serpentine` = `False`

Uses four panels, total display size is 64x128. Note how the ribbon cables are longer than with `serpentine`=`True`. This is usually less convenient.

![led_matrices_ksnip_20210128-121509.png](https://cdn-learn.adafruit.com/assets/assets/000/099/034/medium640/led_matrices_ksnip_20210128-121509.png?1611857760)

## Rectangular arrangements
- `chain_across` = 2
- `tile_down` = 2
- `serpentine` = `True`

Uses four panels, total display size is 128x64. Note how displays 3 and 4 are rotated 180 degrees to minimize the length of ribbon cables required.

![led_matrices_ksnip_20210128-112345.png](https://cdn-learn.adafruit.com/assets/assets/000/099/023/medium640/led_matrices_ksnip_20210128-112345.png?1611854645)

- `chain_across` = 2
- `tile_down` = 2
- `serpentine` = `False`

Uses four panels, total display size is 128x64.

Note how long the ribbon cable is from panel 2 to 3. This is why the "serpentine" arrangement is usual preferable to the non-serpentine arrangement.

![led_matrices_ksnip_20210128-112516.png](https://cdn-learn.adafruit.com/assets/assets/000/099/025/medium640/led_matrices_ksnip_20210128-112516.png?1611854775)

## The effect of display rotation

All of the above examples show a display with `rotation=0`. You can change the rotation of a screen by passing in a `rotation=` parameter to the `FramebufferDisplay` constructor, or by setting the `.rotation` property of the `display` object at any time.

This rotation, which can be any of 0, 90, 180, or 270 degrees counterclockwise, affects the whole display rather than the individual panels.

`display.rotation = 90`

![led_matrices_ksnip_20210128-112842.png](https://cdn-learn.adafruit.com/assets/assets/000/099/027/medium640/led_matrices_ksnip_20210128-112842.png?1611854964)

`display.rotation = 180`

![led_matrices_ksnip_20210128-113133.png](https://cdn-learn.adafruit.com/assets/assets/000/099/030/medium640/led_matrices_ksnip_20210128-113133.png?1611855126)

`display.rotation = 270`

![led_matrices_ksnip_20210128-113040.png](https://cdn-learn.adafruit.com/assets/assets/000/099/029/medium640/led_matrices_ksnip_20210128-113040.png?1611855067)

# RGB LED Matrices with CircuitPython

## Advanced Example: Big, big flag of Wales

![](https://cdn-learn.adafruit.com/assets/assets/000/099/031/medium800/led_matrices_protomatter-tiled-dragon.jpg?1611855624)

This example uses 4 64×32 matrices attached to a single MatrixPortal using the "serpentine" wiring style.

Place [the code below](https://raw.githubusercontent.com/adafruit/Adafruit_Learning_System_Guides/master/CircuitPython_RGBMatrix/tiled.py) on **CIRCUITPY** (as **code.py** ) and the [bitmap image](https://raw.githubusercontent.com/adafruit/Adafruit_Learning_System_Guides/master/CircuitPython_RGBMatrix/wales.bmp) (as **wales.bmp** ). You can change the bitmap to any other file that works with `OnDiskBitmap`, up to 128x64 pixels. No additional libraries are required. You can adapt it to other boards by changing the lines that create the `RGBMatrix` object.

![led_matrices_ksnip_20210128-105234.png](https://cdn-learn.adafruit.com/assets/assets/000/099/015/medium640/led_matrices_ksnip_20210128-105234.png?1611852777)

![led_matrices_ksnip_20210128-112345.png](https://cdn-learn.adafruit.com/assets/assets/000/099/032/medium640/led_matrices_ksnip_20210128-112345.png?1611857152)

https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/CircuitPython_RGBMatrix/tiled/code.py


## Featured Products

### Adafruit Matrix Portal - CircuitPython Powered Internet Display

[Adafruit Matrix Portal - CircuitPython Powered Internet Display](https://www.adafruit.com/product/4745)
Folks love our [wide selection of RGB matrices](https://www.adafruit.com/category/327) and accessories, for making custom colorful LED displays... and our RGB Matrix Shields and FeatherWings can be quickly soldered together to make the wiring much easier. But what if we made it...

In Stock
[Buy Now](https://www.adafruit.com/product/4745)
[Related Guides to the Product](https://learn.adafruit.com/products/4745/guides)
### Adafruit RGB Matrix Featherwing Kit

[Adafruit RGB Matrix Featherwing Kit](https://www.adafruit.com/product/3036)
Ahoy! It's time to create a dazzling light up project with our new **RGB Matrix FeatherWing**. Now you can quickly and easily create projects featuring your favorite 16 or 32-pixel tall matrix boards. Using our RGB Matrix library is easy and...

In Stock
[Buy Now](https://www.adafruit.com/product/3036)
[Related Guides to the Product](https://learn.adafruit.com/products/3036/guides)
### Adafruit Feather M4 Express - Featuring ATSAMD51

[Adafruit Feather M4 Express - Featuring ATSAMD51](https://www.adafruit.com/product/3857)
It's what you've been waiting for, the Feather M4 Express featuring ATSAMD51. This Feather is fast like a swift, smart like an owl, strong like a ox-bird (it's half ox, half bird, OK?) This feather is powered by our new favorite chip, the **ATSAMD51J19** -  with...

In Stock
[Buy Now](https://www.adafruit.com/product/3857)
[Related Guides to the Product](https://learn.adafruit.com/products/3857/guides)
### 5V 4A (4000mA) switching power supply - UL Listed

[5V 4A (4000mA) switching power supply - UL Listed](https://www.adafruit.com/product/1466)
Need a lot of 5V power? This switching supply gives a clean regulated 5V output at up to **4 Amps** (4000mA). 110 or 240 input, so it works in any country. The plugs are "US 2-prong" style so you may need a plug adapter, but you can pick one up at any hardware store for $1 or so,...

In Stock
[Buy Now](https://www.adafruit.com/product/1466)
[Related Guides to the Product](https://learn.adafruit.com/products/1466/guides)
### Medium 16x32 RGB LED matrix panel - 6mm Pitch

[Medium 16x32 RGB LED matrix panel - 6mm Pitch](https://www.adafruit.com/product/420)
Bring a little bit of Times Square into your home with this 16 x 32 RGB LED matrix panel. These panels are normally used to make video walls, here in New York we see them on the sides of busses and bus stops, to display animations or short video clips. We thought they looked really cool so we...

In Stock
[Buy Now](https://www.adafruit.com/product/420)
[Related Guides to the Product](https://learn.adafruit.com/products/420/guides)
### 64x32 Flexible RGB LED Matrix - 5mm Pitch

[64x32 Flexible RGB LED Matrix - 5mm Pitch](https://www.adafruit.com/product/3803)
If you've played with multiplexed RGB matrices, you may have wondered "hey, could we possibly manufacture these on a thin enough PCB so it's flexible?" and the answer is **Yes!** [T](http://www.adafruit.com/?q=64x32%20RGB)<a...></a...>

No Longer Stocked
[Buy Now](https://www.adafruit.com/product/3803)
[Related Guides to the Product](https://learn.adafruit.com/products/3803/guides)
### 64x32 RGB LED Matrix - 5mm pitch

[64x32 RGB LED Matrix - 5mm pitch](https://www.adafruit.com/product/2277)
Bring a little bit of Times Square into your home with this sweet 64x32 square RGB LED matrix panel. These panels are normally used to make video walls, here in New York we see them on the sides of busses and bus stops, to display animations or short video clips. We thought they looked really...

In Stock
[Buy Now](https://www.adafruit.com/product/2277)
[Related Guides to the Product](https://learn.adafruit.com/products/2277/guides)
### 64x32 RGB LED Matrix - 4mm pitch

[64x32 RGB LED Matrix - 4mm pitch](https://www.adafruit.com/product/2278)
Bring a little bit of Times Square into your home with this sweet 64 x 32 square RGB LED matrix panel. These panels are normally used to make video walls, here in New York we see them on the sides of busses and bus stops, to display animations or short video clips. We thought they looked...

In Stock
[Buy Now](https://www.adafruit.com/product/2278)
[Related Guides to the Product](https://learn.adafruit.com/products/2278/guides)

## Related Guides

- [Adafruit Feather M4 Express](https://learn.adafruit.com/adafruit-feather-m4-express-atsamd51.md)
- [Adafruit RGB Matrix FeatherWings](https://learn.adafruit.com/rgb-matrix-featherwing.md)
- [Adafruit MatrixPortal M4](https://learn.adafruit.com/adafruit-matrixportal-m4.md)
- [Daily Cheer Automaton](https://learn.adafruit.com/daily-cheer-automaton.md)
- [CircuitPython Motorized Camera Slider](https://learn.adafruit.com/circuitpython-motorized-camera-slider.md)
- [Adafruit Protomatter RGB Matrix Library](https://learn.adafruit.com/adafruit-protomatter-rgb-matrix-library.md)
- [TVA Pruning Baton from Loki](https://learn.adafruit.com/tva-pruning-baton-from-loki.md)
- [Lego Neon NeoPixel Sign with CircuitPython](https://learn.adafruit.com/lego-neon-sign.md)
- [itsaSNAP Daily Weather Forecast Board](https://learn.adafruit.com/itsasnap-daily-weather-forecast-board.md)
- [Creating MatrixPortal Projects with CircuitPython](https://learn.adafruit.com/creating-projects-with-the-circuitpython-matrixportal-library.md)
- [RGB LED Matrix Basics](https://learn.adafruit.com/32x16-32x32-rgb-led-matrix.md)
- [DIY Robotic Sky Tracking Astrophotography Mount with CircuitPython](https://learn.adafruit.com/diy-robotic-sky-tracking-astrophotography-mount.md)
- [NeoPixel Bike Light](https://learn.adafruit.com/neopixel-headlight.md)
- [Spinning Disc Step Sequencer](https://learn.adafruit.com/spinning-disc-step-sequencer.md)
- [AdaBox 016](https://learn.adafruit.com/adabox016.md)
- [Adafruit VCNL4040 Proximity Sensor](https://learn.adafruit.com/adafruit-vcnl4040-proximity-sensor.md)
- [CircuitPython 101: Basic Builtin Data Structures](https://learn.adafruit.com/basic-datastructures-in-circuitpython.md)
- [Tombstone Matrix Portal](https://learn.adafruit.com/tombstone-matrix-portal.md)