Skip to content

Commit 9268695

Browse files
jacobhylenjacobhylen
authored
Merge pull request #402 from arduino/jacobhylen/unor4wifi-led_guide
[UNO-R4-WiFi] LED Matrix guide
2 parents 20c8d60 + ed7f035 commit 9268695

File tree

1 file changed

+334
-0
lines changed
  • content/hardware/02.hero/boards/uno-r4-wifi/tutorials/led-matrix

1 file changed

+334
-0
lines changed

‎content/hardware/02.hero/boards/uno-r4-wifi/tutorials/led-matrix/led-matrix.md

Lines changed: 334 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,334 @@
1+
---
2+
title: 'Using the Arduino UNO R4 WiFi LED matrix.'
3+
description: 'Get off the ground with the Arduino UNO R4 WiFi's built in LED matrix. Learn the different techniques for controlling it, create animations, graphics or even games.'
4+
tags:
5+
- Guide
6+
- LED Matrix
7+
author: 'Jacob Hylén'
8+
hardware:
9+
- hardware/02.hero/boards/uno-r4-wifi
10+
software:
11+
- ide-v1
12+
- ide-v2
13+
- web-editor
14+
---
15+
16+
The **Arduino UNO R4 WiFi** comes with a built in 12x8 LED Matrix, that is available to be programmed to display graphics, animations, act as an interface, or even play games on.
17+
18+
## Goals
19+
20+
The matrix and its' API is developed to be programmed in a few different ways, each suited for different applications. This guide will walk you through the basic concepts for programming the LED matrix, and get you started with creating your own animations. While highlighting two different ways of handling the LEDs to create animations and images. Making it easier for you to decide what method fits your needs best!
21+
22+
## Hardware & Software Needed
23+
To follow along with this guide, you will of course need:
24+
- an [Arduino UNO R4 WiFi](https://store.arduino.cc/products/arduino-uno-r4-wifi),
25+
- The latest version of the [UNO R4 Core](https://github.com/arduino/ArduinoCore-renesas)
26+
- and the [Arduino IDE](https://www.arduino.cc/en/software).
27+
28+
## Initializing Matrix
29+
To use the LED Matrix library, there are a few things that need to be added to your sketch to get off the ground.
30+
31+
First, include the library at the top of your sketch, like this:
32+
33+
```arduino
34+
#include "Arduino_LED_Matrix.h"
35+
```
36+
37+
Then, you'll need to create a LED Matrix object in your sketch, by adding the following line directly underneath the first one:
38+
39+
```arduino
40+
ArduinoLEDMatrix matrix;
41+
```
42+
43+
And then lastly, start the led matrix by adding this line in `void setup()`:
44+
```arduino
45+
matrix.begin();
46+
```
47+
48+
The entire thing should look like this;
49+
50+
```arduino
51+
#include "Arduino_LED_Matrix.h"
52+
53+
ArduinoLEDMatrix matrix;
54+
55+
void setup() {
56+
Serial.begin(115200);
57+
matrix.begin();
58+
}
59+
```
60+
61+
62+
## How to Write a Frame
63+
The LED matrix library for the UNO R4 WiFi works on the principle of creating a frame, and then loading it into a buffer which displays the frame.
64+
65+
A frame is what we call the "image" that is displayed at any given moment on the matrix. If an animation is a series of images, a frame is one of those images in the series.
66+
67+
How this frame is created can vary quite a lot, and you can choose whatever way is the easiest for your application, but most of the time you'll be creating an array that holds the frame in 3 32bit integers. A frame like this is difficult for a person to interpret, but it is efficient and therefore the way to go if you're making animations or graphics to display states of a program or interfaces. You can create frames and animations such as this one by using tools such as [FotogramMatrice](#fotogrammatrice). Such a frame may look similar to this:
68+
69+
```
70+
const uint32_t heart[] = {
71+
0x3184a444,
72+
0x44042081,
73+
0x100a0040
74+
};
75+
```
76+
77+
Now if you've got several different frames, you can load and display them like this:
78+
```
79+
const uint32_t happy[] = {
80+
0x19819,
81+
0x80000001,
82+
0x81f8000
83+
};
84+
85+
const uint32_t heart[] = {
86+
0x3184a444,
87+
0x44042081,
88+
0x100a0040
89+
};
90+
91+
matrix.loadFrame(happy);
92+
delay(500);
93+
matrix.loadFrame(heart);
94+
delay(500);
95+
```
96+
97+
98+
You may also represent your frame with an array of individual bits, where each pixel is represented by a bit, and can be accessed by its row and column(this way being a good choice if you need to generate frames from within a sketch, for instance if you are making a game). This `frame` array contains a representation of each pixel in the matrix laid out in the same 12x8 grid.
99+
100+
```
101+
uint8_t frame[8][12] = {
102+
{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 },
103+
{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 },
104+
{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 },
105+
{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 },
106+
{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 },
107+
{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 },
108+
{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 },
109+
{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 }
110+
};
111+
112+
```
113+
To target an individual pixel you select its' address and change the value, remember that you'll need to start counting at 0. So, the following line will target the third pixel from the left and the second from the top, then turn it on:
114+
```
115+
frame[2][1] = 1;
116+
matrix.renderBitmap(frame, 8, 12);
117+
```
118+
119+
## Testing it Out
120+
121+
Let's apply these concepts, with two basic sketches that display different frames on your board. First, let's load 3x32bit integer frames and load them one by one.
122+
123+
Here's a sketch that will first load a smiley face on your matrix, and then change it to a heart.
124+
125+
```
126+
#include "Arduino_LED_Matrix.h"
127+
ArduinoLEDMatrix matrix;
128+
void setup() {
129+
Serial.begin(115200);
130+
matrix.begin();
131+
}
132+
133+
const uint32_t happy[] = {
134+
0x19819,
135+
0x80000001,
136+
0x81f8000
137+
};
138+
const uint32_t heart[] = {
139+
0x3184a444,
140+
0x44042081,
141+
0x100a0040
142+
};
143+
144+
void loop(){
145+
matrix.loadFrame(happy);
146+
delay(500);
147+
matrix.loadFrame(heart);
148+
delay(500);
149+
}
150+
```
151+
152+
The sketch is pretty simple, and yet the outcome is very expressive and can help you easily indicate states of your projects.
153+
154+
Now let's change approach and create a bitmap that we change in runtime. This sketch includes several functions that each draw part of a face, and then winks the left eye by turning off certain pixels.
155+
156+
```
157+
#include "Arduino_LED_Matrix.h"
158+
ArduinoLEDMatrix matrix;
159+
void setup() {
160+
Serial.begin(115200);
161+
matrix.begin();
162+
}
163+
164+
uint8_t frame[8][12] = {
165+
{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 },
166+
{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 },
167+
{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 },
168+
{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 },
169+
{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 },
170+
{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 },
171+
{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 },
172+
{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 }
173+
};
174+
175+
void leftEye(){
176+
//Left eye
177+
frame[1][3] = 1;
178+
frame[1][4] = 1;
179+
frame[2][3] = 1;
180+
frame[2][4] = 1;
181+
}
182+
183+
void wink(){
184+
//Wink with the left eye
185+
frame[1][3] = 0;
186+
frame[1][4] = 0;
187+
frame[2][3] = 1;
188+
frame[2][4] = 1;
189+
}
190+
191+
void rightEye(){
192+
//Right eye
193+
frame[1][8] = 1;
194+
frame[1][9] = 1;
195+
frame[2][8] = 1;
196+
frame[2][9] = 1;
197+
}
198+
199+
void mouth(){
200+
//Mouth
201+
frame[5][3] = 1;
202+
frame[5][9] = 1;
203+
frame[6][3] = 1;
204+
frame[6][4] = 1;
205+
frame[6][5] = 1;
206+
frame[6][6] = 1;
207+
frame[6][7] = 1;
208+
frame[6][8] = 1;
209+
frame[6][9] = 1;
210+
}
211+
212+
void loop(){
213+
leftEye();
214+
rightEye();
215+
mouth();
216+
217+
matrix.renderBitmap(frame, 8, 12);
218+
219+
delay(1000);
220+
wink();
221+
matrix.renderBitmap(frame, 8, 12);
222+
delay(1000);
223+
}
224+
```
225+
226+
## FotogramMatrice
227+
The FotogramMatrice tool is used to generate frames and animations to be rendered on the LED matrix.
228+
229+
It also features a live preview of the frames you're creating displayed right on the LED matrix of the Arduino UNO R4 WiFi, although this is only supported in Google Chrome.
230+
// THIS PART IS UNFINISHED, waiting to learn where the live preview sketch will be hosted.
231+
232+
With the live preview sketch loaded on your board, connect the port to the browser, and watch as the pixels turn on and off as you edit the grid in your browser.
233+
234+
// waiting for the interface to be developed
235+
236+
## Conclusion
237+
In this article we've gone over the basics of using the LED matrix built in on the Arduino UNO R4 WiFi, we've gone over the different practices for building frames and animations, as well as how to load them onto your board.
238+
239+
Have fun creating interactive interfaces or animation on your UNO R4 WiFi!
240+
241+
## API
242+
243+
To write more advanced sketches on your own, you may use the full API of the library as found below.
244+
245+
Members | Descriptions
246+
--------------------------------|---------------------------------------------
247+
`public ` [`ArduinoLEDMatrix`](#)`()` | The main class for controlling the LED matrix.
248+
`public void` [`autoscroll`](#)`(int32_t interval_ms)` | Sets the time in ms for each frame to be displayed
249+
`public void` [`on`](#)`(size_t pin)` | Turn an individual pixel on.
250+
`public void` [`off`](#)`(size_t pin)` | Turn an individual pixel off.
251+
`public void` [`begin`](#)`()` | Start the LED matrix.
252+
`public void` [`next`](#)`()` | Manually move to the next frame in the sequence.
253+
`public void` [`loadFrame`](#)`(const uint32_t buffer[3])` | Load a new single frame that is not in any sequence.
254+
`public void` [`renderFrame`](#)`(uint8:t frameNumber)` | Render the loaded frame.
255+
`public void` [`play`](#)`(bool loop = false)` | Start playing the sequence of frames, with the option to loop indefinitely or play once.
256+
`public bool` [`sequenceDone`](#)`()` | checks if the sequence has finished playing.
257+
`public void` [`loadPixels`](#)`(uint8_t *arr, size_t size)` |Loads the pixels into the buffer but does not display them.
258+
`public void` [`loadWrapper`](#)`(`[`const uint32_t frames[][4], uint32_t howMany`](#)` callback)` | Sets the current frame to number 0 in the sequence.
259+
260+
## Members
261+
262+
### `public ` [`ArduinoLEDMatrix`](#)`()`
263+
264+
Construct a new [LEDMatrix](#) object.
265+
266+
### `public void` [`autoscroll`](#)`(int32_t interval_ms)`
267+
268+
Enable autoscrolling through the frames in a sequence.
269+
270+
#### Parameters
271+
* `interval_ms` Sets the time in milliseconds that should be spent on a frame before switching to the next frame in the sequence.
272+
273+
274+
### `public void` [`on`](#)`(size_t pin)`
275+
276+
Turn on an individual LED.
277+
278+
#### Parameters
279+
* `pin` Defines which LED should be turned on. Accepted values are 0-95.
280+
### `public void` [`off`](#)`(size_t pin)`
281+
282+
Turn off an individual LED.
283+
284+
#### Parameters
285+
* `pin` Defines which LED should be turned off. Accepted values are 0-95.
286+
287+
### `public void` [`begin`](#)`()`
288+
289+
Starts the LED matrix.
290+
291+
### `public void` [`next`](#)`()`
292+
293+
Manually moves to the next frame in the sequence.
294+
295+
### `public void` [`loadFrame`](#)`(const uint32_t buffer[3])`
296+
297+
loads a single frame that is not part of a sequence.
298+
299+
#### Parameters
300+
* `buffer[3]` an array of three 32bit integers, where each bit represents an LED.
301+
302+
### `public void` [`renderFrame`](#)`(uint8_t frameNumber)`
303+
304+
Render a specific frame from a sequence
305+
306+
#### Parameters
307+
* `frameNumber` Specifies which frame of the sequence should be rendered.
308+
309+
### `public void` [`play`](#)`(bool loop)`
310+
311+
Starts playing the loaded sequence.
312+
313+
#### Parameters
314+
* `loop` true to enable looping the sequence, false to play once.
315+
316+
### `public bool` [`sequenceDone`](#)`()`
317+
318+
Check for if the sequence is finished playing or if the frame should be advanced another step.
319+
320+
#### Returns
321+
false if the sequence is not finished, true if it is.
322+
323+
### `public void` [`loadPixels`](#)`(uint8_t *arr, size_t size)`
324+
325+
Loads the pixels into the frame but does not load them.
326+
327+
#### Parameters
328+
* `arr` Pointer to an array that holds the frame
329+
330+
* `size` the amount of pixels in your frame.
331+
332+
### `public void` [`loadWrapper`](#)`(const uint32_t frames[][4], uint32_t howMany)`
333+
334+
Sets the current frame to frame 0 in the sequence.

0 commit comments

Comments
 (0)