Coding the Waveshare RP2040 Matrix
![Coding the Waveshare RP2040 Matrix](http://thepihut.com/cdn/shop/articles/Coding_the_Waveshare_RP2040_Matrix_Development_Board.jpg?v=1694779293&width=2048)
The Waveshare RP2040 Matrix development board is an inexpensive, super-compact RP2040 microcontroller with a tiny 5x5 addressable RGB LED matrix on the front. This tiny development board is packed with interesting features including: 25 RGB LEDs (WS2812) in a 5x5 array – very bright! USB-C for power and programming BOOT and RESET buttons RP2040 processor – works like a Raspberry Pi Pico Plenty of GPIO connections with ADC, SPI, I2C and UART available It makes an ideal board for learning about addressable RGB LEDs, and in this tutorial Tony will demonstrate how to program it using MicroPython. Before we start, let's show you a range of possibilities with this great little matrix: Note: this an intermediate/advanced skills project. What you will need We assume that you have installed Thonny on your computer and set up your Raspberry Pi Pico with the most
Official Raspberry Pi reseller. The ultimate Raspberry Pi & maker superstore with all of the biggest brands under one roof. Raspberry Pi Zero stockist. Next Day delivery available.
The Waveshare RP2040 Matrix development board is an inexpensive, super-compact RP2040 microcontroller with a tiny 5x5 addressable RGB LED matrix on the front.
This tiny development board is packed with interesting features including:
25 RGB LEDs (WS2812) in a 5x5 array – very bright!
USB-C for power and programming
BOOT and RESET buttons
RP2040 processor – works like a Raspberry Pi Pico
Plenty of GPIO connections with ADC, SPI, I2C and UART available
It makes an ideal board for learning about addressable RGB LEDs, and in this tutorial Tony will demonstrate how to program it using MicroPython.
Before we start, let's show you a range of possibilities with this great little matrix:
Note: this an intermediate/advanced skills project.
What you will need
We assume that you have installed Thonny on your computer and set up your Raspberry Pi Pico with the most recent MicroPython firmware (UF2). If not, check out our Raspberry Pi Pico Getting Started Guide where this is covered in detail.
For this quick intro and matrix coding, all you'll need are:
Waveshare RP2040 Matrix development board
USB to USB-C cable
Thonny Editor (free)
Board Setup
Install the latest UF2
If you plug the USB-C cable into the socket on the board and power it from your computer you will find that it has a test only UF2 (firmware) installed.
We need to replace the installed UF2 with the current RP2040 MicroPython version which you can download here. As mentioned above, we have assumed that you know how to install a new UF2 file.
Programming the matrix
LED pins (and a warning!)
Our product page for this board provides links Waveshare's wiki and a pinout guide. This wiki tells us that the addressable RGB LEDs are connected to GPIO 16. There are 25 LEDs, numbered 0 to 24 and each can be set to a wide variety of colours by providing red, green and blue (RGB) values in the range 0 to 255. We have found that values in the range 0 to 20 are sufficient for most purposes. Waveshare warn against prolonged use of high values which could damage the device as it overheats - you've been warned!
Code Library
Luckily we can use the Neopixel library which is now built-in to MicroPython.
This makes it very easy to get up and running. The following code imports the library and initialises the LEDs:
# Waveshare RP2040-MATRIX with 5x5 grid of Neopixels
# NB colours (green, red, blue)
# Tony Goodhew for the pihut.com - 25 Aug 2023
import time
from machine import Pin
from neopixel import NeoPixel
# Set up 25 Neopixels on GPIO 16
np = NeoPixel(Pin(16), 25, bpp = 3) # bpp = bytes per pixel (GRB)
These LEDs are slightly different from Adafruit Neopixels and the colour order is green, red, blue (GRB rather than RGB). It doesn't make a lot of difference, we just need to add our colour values in the right places.
We can set the colour of a pixel by adding the line below:
np[2] = (0, 10, 10) # Set the third pixel to MAGENTA
Red and blue (the '10' values) mixed make a purple colour, called magenta, and the LEDs are counted from zero to 24.
This only stores the values in a buffer - the instruction np.write() sends the contents of the buffer to the LEDs which updates the colours. This is very fast!
Try running the code below with the added lines. You should find the centre pixel on the top line lights up purple:
# Waveshare RP2040-MATRIX with 5x5 grid of Neopixels
# NB colours (green, red, blue)
# Tony Goodhew for the pihut.com - 25 Aug 2023
import time
from machine import Pin
from neopixel import NeoPixel
# Set up 25 Neopixels on GPIO 16
np = NeoPixel(Pin(16), 25, bpp = 3) # bpp = bytes per pixel (GRB)
np[2] = (0, 10, 10) # Set the third pixel to MAGENTA
np.write()
Now try the following code and see what happens. Note the extra brackets in the fill instructions. Colour is defined with a tuple and the brackets are essential:
# Waveshare RP2040-MATRIX with 5x5 grid of Neopixels
# NB colours (green, red, blue)
# Tony Goodhew for the pihut.com - 25 Aug 2023
import time
from machine import Pin
from neopixel import NeoPixel
# Set up 25 Neopixels on GPIO 16
np = NeoPixel(Pin(16), 25, bpp = 3) # bpp = bytes per pixel (GRB)
time.sleep(2)
np.fill((0,10,0)) # Fill display with RED
np.write()
time.sleep(2)
np.fill((0,0,0)) # Fill display with BLACK
np.write()
Some things to try
Set pixel[0] green, pixel[21] blue and pixel[24] yellow
Write a procedure to clear the screen and test it
Fill the screen with randomly coloured pixels in a random order
Using coordinates - (x, y) or (col, row) values
Time to step it up a gear! We're now going to use coordinates to drive the LEDs, but before we explain anything, copy the code example below and give it a spin:
# Waveshare RP2040-MATRIX with 5x5 grid of Neopixels
# NB colours (green, red, blue)
# Tony Goodhew for the pihut.com - 25 Aug 2023
import time
from machine import Pin
from neopixel import NeoPixel
# Set up 25 Neopixels on GPIO 16
np = NeoPixel(Pin(16), 25, bpp = 3) # bpp = bytes per pixel (GRB)
def clear():
np.fill((0,0,0))
np.write()
def wait(t): # Delay t seconds
time.sleep(t)
for i in range(25): # 'Natural' order 0-24, as connected on board
np[i] = (10,10,0) # Yellow ON
np.write()
wait(0.15)
np[i] = (0,0,0) # Black OFF - Single blink
wait(0.2)
clear()
wait(0.6)
for row in range(5): # Row at a time
for col in range(5):
np[5 * row + col] = (5,5,5) # White
np.write()
wait(0.15)
wait(0.1)
clear()
for col in range(5): # Column at a time
for row in range(5):
np[5 * row + col] = (0,0,5) # Blue
np.write()
wait(0.15)
wait(0.2)
clear()
def sq(x,y,n,r,g,b):
for col in range(x,x+n): # Top and Bottom
np[5 * y + col] = (g,r,b)
np[5 * (y+n-1) + col] = (g,r,b)
for row in range(y,y+n): # Sides
np[5 * row + x] = (g,r,b)
np[5 * row + x + n -1] = (g,r,b)
np.write()
tt = 0.6
sq(0,0,5,4,0,0)
wait(tt)
sq(0,0,4,0,4,0)
wait(tt)
sq(0,0,3,0,0,4)
wait(tt)
sq (0,0,2,4,4,0)
wait(tt)
sq(0,0,1,0,4,4)
wait(tt)
clear()
So what does it do? Look through the code along with the points below to get an understanding of what it's doing and where:
It sets up the RGB LEDs
Defines procedures to clear the screen and wait a short period
Blinks each of the LEDs in turn with yellow in the ‘natural order’ 0 - 24
Slowly fills the display row by row with white
Slowly fills the display column by column in blue
Defines a procedure to draw squares and then draws a series of squares.
Example coordinate usage
Let's look at a simple example:
col = 3
row = 1
np[5 * row + col] = (0,0,5) # Blue
These instructions will turn LED 8 blue, because we're referencing the LED on column 3, row 1, as you can see from the grid below:
Characters and text
Explaining how characters and scrolling works is probably worthy of an article of its own, so we won't go into the detail of 'how' today, but you can download our example code, which is fully commented and easy to use, and try it for yourself.
You don't need to understand how it works to make use of the of the instructions which follow – just treat the code like a library!
There are two instructions:
display(n,rr,gg,bb) # (ASCII value, red, green, blue) = Single stationary character
scroll(s,rr,gg,bb) # (message string, red, green, blue) = Scrolled message
Check out the video to see it in action.
Things to try
Scroll your name across the display
Use a 10k potentiometer as an input device (range 0 to 9) and display the value on the LEDs
Draw a red heart shape on a blue background
Use 3 potentiometers to control the red, green and blue values of pixels at three corners of the display and their mixed colour on a square in the centre
Bonus Game – Zap it
Let's have a little fun! This is a hand and eye co-ordination game and just needs a simple button/switch (momentary type) connecting GPIO 14 to GND.
How to play
A white target runs round the edge of the display
A player has three goes in a game
The player starts with 100 points and tries to zap the target while it is to the right of the red target marker by pressing the button
If the player hits the button too early, too late or misses a rotation past the target position a point is lost
A hit is registered with the target turning yellow and a green, go counter, pixel is lit
A point lost by a missed hit is indicated by a short blue flash
The score is shown at the end of the game
Can you score 100?
Zap it code
Here's the code for the game. As usual, copy it over to Thonny (use the copy button on the right, it's easier!) and run it like any other code:
# WS RP2040 'Zap it' Game
# Needs a button switch between GPIO 14 and GND
# Tony Goodhew 28th Aug 2023 (Author)
# How to play:
# A white target runs round the edge of the display.
# The player starts with 100 points and tries zap the target while it is
# to the right of the red target marker.
# If the player hits the button too early, too late or misses a rotation
# past the target position a point is lost.
# A hit is registered with the target turning yellow and a green pixel is lit.
# A point lost is indicated by a short blue flash.
# The score is shown at the end of the go.
import time
from machine import Pin
from neopixel import NeoPixel
# Set up 25 Neopixels on GPIO 16
np = NeoPixel(Pin(16), 25, bpp = 3) # bpp = bytes per pixel (GRB)
def clear():
np.fill((0,0,0))
np.write()
def wait(t): # Delay t seconds
time.sleep(t)
# =========== START OF FONT LIBRARY ===========
# Instructions:
# display(n,rr,gg,bb) # (ASCII value, red, green, blue) = stationary character
# scroll(s,rr,gg,bb) # (string, red, green, blue) = Scrolled message
# Character codes ASCII 32 - 127 5x5 pixels
# 5x5 font - Tony Goodhew 26th August 2023 (author)
# 5 columns of 5 bits = LSBs [@ == 00000]
q = [
@@@@@, # 32
@@]@@, # ! 33
@X@X@, # 34
J_J_J, # # 35
IU_UR, # $ 36
QBDHQ, # % 37
JUJA@, # & 38
@@X@@, # ' 39
@NQ@@, # ( 40
@@QN@, # ) 41
@J~J@, # * 42
@DND@, # + 43
@@BC@, # , 44
@DDD@, # - 45
@@A@@, # . 46
ABDHP, # / 47
NQQN@, # 0 48
@I_A@, # 1 49
IS_I@, # 2 50
UUUJ@, # 3 51
^BGB@, # 4 52
]UUR@, # 5 53
NUUF@, # 6 54
PSTX@, # 7 55
JUUJ@, # 8 56
LUUN@, # 9 57
@@E@@, # : 58
@@BC@, # ; 59
DJQ@@, # < 60
@JJJ@, # = 61
@QJD@, # > 62
HPUH@, # ? 63
_QUU], # @ 64
OTTO@, # A 65
_UUJ@, # B 66
NQQQ@, # C 67
_QQN@, # D 68
_UUQ@, # E 69
_TTP@, # F 70
NQUV@, # G 71
_DD_@, # H 72
@@_@@, # I 73
BAA^@, # J 74
_DJQ@, # K 75
_AAA@, # L 76
_HDH_, # M 77
_HD_@, # N 78
NQQN@, # O 79
_TTH@, # P 80
NQSO@, # Q 81
_TVI@, # R 82
IUUR@, # S 83
PP_PP, # T 84
^AA^@, # U 85
XFAFX, # V 86
~C~C~, # W 87
QJDJQ, # X 88
PHGHP, # Y 89
QSUY@, # Z 90
@_Q@@, # [ 91
PHDBA, # \ 92
@Q_@@, # ] 93
@HPH@, # ^ 94
AAAA@, # _ 95
@@X@@, # ` 96
BUUO@, # a 97
_EEB@, # b 98
FIII@, # c 99
BEE_@, # d 100
NUUH@, # e 101
@_TP@, # f 102
HUUN@, # g 103
@_DG@, # h 104
@@W@@, # i 105
@AAV@, # j 106
_DJA@, # k 107
@_A@@, # l 108
OHDHO, # m 109
@GDG@, # n 110
FIIF@, # o 111
OJJD@, # p 112
DJJG@, # q 113
OHHD@, # r 114
IUUR@, # s 115
@H_I@, # t 116
NAAN@, # u 117
HFAFH, # v 118
LCLCL, # w 119
@JDJ@, # x 120
@LEO@, # y 121
@KMI@, # z 122
@DNQ@, # { 123
@_@@@, # | 124
@QND@, # } 125
HPHP@, # ~ 126
@HTH@, # 127
]
# This procedure converts the font codes to a string
# of 25 ones and zeros characters - 5 cols of 5 rows
def decode(qq):
powers = [16,8,4,2,1]
str25 =
for p in range(5):
n = ord(qq[p])
if n == 126:
n = 92 # replace ~ with \
str5 =
for c in range(5):
if ((powers[c] & n)/powers[c]) == 1:
str5 = str5 + 1
else:
str5 = str5 + 0
str25 = str25 + str5
return str25
# Display a single character
def display(n,rr,gg,bb): # ASCII value, red, green blue
qq = decode(q[n]) # get coded character pattern
clear() # Clear the display to BLACK
for c in range(5): # Loop through the 5 columns
for r in range(5): # Loop through the rows
cc = qq[r + 5 * c] # current 'bit' at (c, r) coordinate
if cc == 1: # Is current 'bit' a one?
np[5 * r + c] = (gg,rr,bb) # If so, set to colour
np.write() # Update the display
# Display a 'frame' of 25 bits - Used in scroll
def display_frame(ss,rr,gg,bb): # Message string of chars and colour
clear()
for c in range(5): # Columns
for r in range(5): # Rows
cc = ss[r + 5 * c] # Get the 'bit' at (c,r)
if cc == 1: # Is it a one?
np[5 * r + c] = (gg,rr,bb) # If so, set to colour
np.write() # Update display
def scroll(s,rr,gg,bb):
long =
s = + s + # Add a space character at the end
l = len(s) # Length of string
for p in range(l): # Loop through the characters
i = ord(s[p])-32 # Adjusted ASCII No of character
temp = decode(q[i]) # get coded character code
long = long + temp # Concatenate char to long string
last5 = temp[-5:] # Get last 5 characters
if last5 != 00000: # Is there a 1 in last column?
long = long +00000 # If so, add an extra space column (W and M are wider)
# We now have a very long string of ones and zeros to send to
# the display in small 'frames' of 25 bits each to fill the pixels
p = 0
# print(s, Buffer: ,len(long))
while p < len(long)-25: # Have we reached the end?
frame = long[p:p + 25] # Extract the 'frame' of 25 bits
display_frame(frame,rr,gg,bb) # Show the frame on the Neopixels
p = p + 5 # Move pointer forward by 1 column
wait(0.17) # Short delay - reduce to speed up scrolling
# ========== END OF FONT LIBRARY =============
# ======= MAIN ===================
sw = Pin(14, Pin.IN,Pin.PULL_UP) # Set up button - Zero when pressed
# Title
scroll(Zap it,5,5,0)
clear()
np.write()
score = 0 # Targets zapped!
opps = 0 # Zap opportunities = pass the target area
p = 0 # Position of target on circuit (0-15)
errors = 0
err = 0
running = True # Loop control variable
loops = 4000 # Delay loop variable - reduce to increase speed - harder!
route = [10,5,0,1,2,3,4,9,14,19,24,23,22,21,20,15] # By pixel numbers
p = 0
err = 0
while score < 3: # You have 3 goes
running = True
display(17 + score,0,0,5) # Display the 'Go' number - 1 to 3
np.write()
time.sleep(0.3)
clear()
np[13] = (0,5,0) # Display Red 'Target marker'
if score > 0:
np[6] = (3,0,0)
if score == 2:
np[7] =(3,0,0)
np.write
while running:
np[route[p]] = (3,3,3) # White target
np.write()
for w in range(loops):
if sw.value() == 0: # Read switch
if p != 8 : # Off target ?
# Missed! - too early or too late
err = 1 # Increment errors
np[16] = (0,0,5) # Err Flag set - blue
np.write()
if (p == 8) and (err == 0):# On target?
# Zapped!
w = loops+10 # # Halt w loop
running = False # Halt outer loop
np[14] = (5,5,0) # Hit flag set = yellow
score = score + 1 # Increment score
np[score + 5] = (3,0,0) # Hit score incremented - green
np.write()
time.sleep(1)
if p == 8:
opps = opps + 1 # Increment opportunities counter
np[route[p]] = (0,0,0) # Clear current target position
np.write()
p = (p + 1) % 16 # Increment loop pointer
if p == 0:
errors = errors + err # Update errors
err = 0
np[16] = (0,0,0) # Turn off blue err flag
np.write()
print(score, opps, errors)
result = 103 - opps - errors
print(result)
scroll(Score: + str(result),5,5,0)
About the Author
This article was written by Tony Goodhew. Tony is a retired teacher of computing who starting writing code back in 1968 when it was called programming - he started with FORTRAN IV on an IBM 1130! An active Raspberry Pi community member, his main interests now are coding in MicroPython, travelling and photography.
![](https://www.waveshare.com/img/devkit/RP2040-Matrix/RP2040-Matrix-details-11.jpg)
Waveshare RP2040-Matrix Development Board, Onboard 5×5 RGB LED Matrix, Based On Official RP2040 Dual Core Processor
![](https://ae01.alicdn.com/kf/Se513e13dde514bf88bbd8e21ddc596a4V.jpg_640x640Q90.jpg_.webp)
Waveshare RP2040-Matrix Development Board, Onboard 5×5 RGB LED Matrix, Based On Official RP2040 Dual Core Processor - AliExpress
![](https://www.waveshare.com/w/upload/7/7b/RP2040-Matrix02.jpg)
RP2040-Matrix - Waveshare Wiki
![](https://electropeak.com/pub/media/catalog/product/cache/95f75205f3b943f313b30831421df8c2/m/i/min-01-154.jpg)
Buy WaveShare RP2040 MCU Board, With 1.28inch Round LCD, Accelerometer and Gyroscope Sensor at Best Price
![](http://cdn.static.spotpear.com/uploads/picture/product/raspberry-pi/raspberry-pi-pico/rp2040-matrix/rp2040-matrix-01-250.jpg)
Raspberry Pi Pico RP2040-Matrix User Guide
Raspberry Pi Pico is a low-cost, high-performance microcontroller board with flexible digital interfaces. The Pico is programmable in MicroPython and C++.
![](https://i.ebayimg.com/images/g/UAkAAOSwVsZjaNe6/s-l1200.webp)
Raspberry Pi Pico
![](https://europe1.discourse-cdn.com/arduino/original/4X/5/d/6/5d6b8752f306bfd67e197b4bb7fefac1bf3da05a.jpeg)
Weird issue with 64x64 Waveshare LED panel and Arduino Mega 2560 - LEDs and Multiplexing - Arduino Forum
![](https://thepihut.com/cdn/shop/articles/Coding_the_Waveshare_RP2040_Matrix_Development_Board_1024x1024.jpg?v=1694779293)
Coding the Waveshare RP2040 Matrix
![](https://www.waveshare.com/media/catalog/product/cache/1/image/264x/9df78eab33525d08d6e5fb8d27136e95/r/p/rp2040-zero-2.jpg)
Waveshare RP2040-Matrix Development Board, Onboard 5×5 RGB LED Matrix, Based On Official RP2040 Dual Core Processor
![](https://m.media-amazon.com/images/I/61IL6ORlKKL._AC_UF350,350_QL50_.jpg)
Waveshare RP2040-Matrix Development Board, Onboard 5×5 RGB LED Matrix, Based On Official RP2040 Dual Core Processor : Electronics
![](https://d3ry4o1su9a59w.cloudfront.net/private/53cae3a9daafd05c1900005c/articles/556d85b9daafd00d0e000066/6549f5b4f3335b001f74ca40/654e0d8ad366a29b41658eb8/1/article_42-1/images/img_42-2.jpg?Key-Pair-Id=APKAI4N3XFJRYPYGWUVA&Policy=eyJTdGF0ZW1lbnQiOlt7IlJlc291cmNlIjoiaHR0cHM6Ly9kM3J5NG8xc3U5YTU5dy5jbG91ZGZyb250Lm5ldC9wcml2YXRlLzUzY2FlM2E5ZGFhZmQwNWMxOTAwMDA1Yy9hcnRpY2xlcy81NTZkODViOWRhYWZkMDBkMGUwMDAwNjYvNjU0OWY1YjRmMzMzNWIwMDFmNzRjYTQwLzY1NGUwZDhhZDM2NmEyOWI0MTY1OGViOC8xL2FydGljbGVfNDItMS8qIiwiQ29uZGl0aW9uIjp7IkRhdGVMZXNzVGhhbiI6eyJBV1M6RXBvY2hUaW1lIjoxNzAzMzg1MTc1fX19XX0_&Signature=RzaEtWQFRRot~oZEfLGi3~rkcaB036dPzDznBeCgMbhecyqtevlN2chBc5G~T7WMndgMpXiUXVGt169qb3Tbt05BhpWRx7Ctnvqda1pjeZ0UhBNh35JtamDVg2gikWy7Tjf0~NTIixIcU6DJpnXknWK0jsVdfSDCyw5zxBPV~ZE_)
Rp2040 matrix - 14 Nov 2023 - Linux Format Magazine - Readly
![](https://cdn11.bigcommerce.com/s-2fbyfnm8ev/images/stencil/500x659/products/2131/7608/rp2040-eth-2__73302.1684951941.1280.1280__78201.1684954454.jpg?c=2)
Waveshare RP2040-ETH Mini Development Board, RP2040 Ethernet Port Module
![](https://www.waveshare.com/media/catalog/product/r/p/rp2040-matrix-6.jpg)
Waveshare RP2040-Matrix Development Board, Onboard 5×5 RGB LED Matrix, Based On Official RP2040 Dual Core Processor
![](https://www.waveshare.com/media/catalog/product/cache/1/image/264x/9df78eab33525d08d6e5fb8d27136e95/r/p/rp2040-lcd-0.99-b-1.jpg)
Waveshare RP2040-Matrix Development Board, Onboard 5×5 RGB LED Matrix, Based On Official RP2040 Dual Core Processor