This will help you:
Create a desktop light display.
As a neat first project to do with a Raspberry Pi, you can create an LED matrix display that shows an image, the time, a color-morphing pattern, or anything else you want. You can hang the display on your wall, or put it on your desk or next to your bed. With the right electronic parts, you can make a functional piece of art that’s high-tech, looks cool, and is completely customizable by you.
Time: 1-2 hours / Level: B1
You should already:
Be familiar with running programs in the command line
You Will Need:
Raspberry Pi
Power supply (ideally 5.1V / 2.5A, 3.0A for RasPi 4)
USB mouse & keyboard
Computer or TV monitor and cable to connect to RasPi
Female-to-female jumper wires (if you don't use a bonnet)
Step 1: Connect the LED matrix
If you are not using a bonnet or HAT to connect the RasPi to the LED matrix panel, follow these instructions from Adafruit to wire up the display.
Otherwise, just plug the bonnet or HAT into the 40-pin GPIO on your RasPi.
Step 2: Download RGB LED Matrix library
Set up your RasPi (connect mouse, keyboard and screen, and plug it in to power).
In the terminal, run the following command to install the library for working with the LED matrix.
$ mkdir matrixdisplay
$ cd matrixdisplay
$ git clone https://github.com/hzeller/rpi-rgb-led-matrix
Step 3: Test the LED matrix
There are a few different programs you can run to test the display. Start off by compiling the programs in the examples-api-use directory, and then try running them.
$ cd rpi-rgb-led-matrix/examples-api-use
$ make
Step 4: Learn to use flags
Programs are run by typing sudo path/to/program <flags> <arguments>. The <flags> bit can be any number of flags or options, which are letters or words preceded by dashes. A one-letter flag starts with a single dash -, while a multi-letter flag (or one with dashes in it) starts with a double dash --. Some flags change what the program does just by being there, but some have a parameter (value) after them. So for example, you could run:
$ sudo ./demo -D 1
To run demo number 1. However, this won't work because this program also needs an image file as an argument, so we should also specify a file name after the flags.
$ sudo ./demo -D 1 runtext.ppm
That's better. We can add more flags, like the Time to run the demo for, in seconds:
$ sudo ./demo -D 1 -t 10 runtext.ppm
If you're using a 16x32 matrix, you'll need to adjust the number of rows for the program, because they assume by default that you have a 32x32 display. You can do this with the --led-rows flag:
$ sudo ./demo -D 1 -t 10 --led-rows=16 runtext.ppm
And, if you're using a bonnet or HAT, you'll need to specify the different pin mapping, using the --led-gpio-mapping flag:
$ sudo ./demo -D 1 -t 10 --led-rows=16 --led-gpio-mapping="adafruit-hat" runtext.ppm
In the documentation for the demos, you'll see a lot about how to use flags. It's a lot of information in a small space, so read carefully, and try lots of different things out. Don't worry about mistyping things; if you have the command or program name right, it will just throw and error if you make a mistake.
Step 5: Run a demo
The GitHub repository for the LED Matrix has a lot of demo and utility programs, which you can use without having to write much or any code. Click here to read about the use of these programs.
From the examples-api-use directory, try these commands:
$ sudo ./demo -D 1 -t 10 runtext.ppm # scrolls runtext for 10 seconds
$ sudo ./demo -D 2 -t 10 runtext.ppm # scrolls runtext backward for 10 seconds
$ sudo ./demo -D 4 -t 10 # pulsing color
$ sudo ./text-example -f ../fonts/8x13.bdf
$ hello
$ sudo ./clock -f ../fonts/7x13.bdf --led-chain=2 -d "%H:%M:%S"
Step 6: Create your own images
Images need to be in ppm format, which can be created with some image editors, GIMP being one of them. Find an editor or online converter and create some images to display. Save them in a folder called "images", either in examples-api-use or in rpi-rgb-led-matrix. The first will probably be more convenient when running demos. To show an image, specify its file location as an argument to a display program. For example:
$ sudo ./demo -D 1 -t 10 --led-rows=16 --led-gpio-mapping="adafruit-hat" images/my_image.ppm
Going further: show a GIF, video or slideshow
One of the programs in utils, led-image-viewer.cc, allows you to display images or GIFs. Click here to read about the use of this program. To compile it, run the following:
$ cd rpi-rgb-led-matrix/utils
$ sudo apt-get update
$ sudo apt-get install libgraphicsmagick++-dev libwebp-dev -y
$ make led-image-viewer
There are some examples about how to use different flags when running the program, and you should read them. Here are the first few examples. Get an image and a GIF to test out, and try running these. (If you save images in another folder, make sure to use the file path with the image file name.)
$ sudo ./led-image-viewer some-image.jpg # Display an image.
$ sudo ./led-image-viewer animated.gif # Show an animated gif
$ sudo ./led-image-viewer -t5 animated.gif # Show an animated gif for 5 seconds
$ sudo ./led-image-viewer -l2 animated.gif # Show an animated gif for 2 loops
$ sudo ./led-image-viewer -D16 animated.gif # Play animated gif, use 16ms frame delay
# If you want to have an even frame rate, that is depending on your
# refresh rate, use the following. Note, your refresh rate is dependent on
# factors such as chain length and rows; use --led-show-refresh to get an idea.
$ sudo ./led-image-viewer -D0 -V12 animated.gif # Frame rate = 1/12 refresh rate
Make it your own
You can play around with and modify these demos to display whatever you want. Some projects may require special configuration, but reading documentation can help you figure these things out.
As inspiration, here's a little project that runs a Python script making use of the demo programs.
