NeoPixel-UserGuide-NeoMatrix
Introduction
Crédit: AdaFruit Industries www.adafruit.com
La bibliothèque Adafruit_NeoMatrix réalisée sur les fondations d'Adafruit_NeoPixel permet de créer des afficheurs graphique à deux dimensions en utilisant des NéoPixels. Vous pouvez alors dessiner facilement des formes, du texte et animations sans avoir à calculer la position X/Y de chaque pixel. Vous pouvez trouver de petites matrices sur le WebShop. Il est possible de réaliser de plus grand afficheurs en utilisant des sections de ruban NéoPixels, comme présenté sur la photo ci-dessus.
En plus de la bibliothèque Adafruit_NeoPixel (qui a déjà été téléchargée et installée à une étape précédente), NeoMatrix nécessite deux autres bibliothèques complémentaires:
Si vous avez déjà installé une LCD ou écran OLED AdaFruit, vous devriez déjà avoir utilisé la bibliothèque Adafruit_GFX.
L'installation des deux bibliothèques est similaire à celle d'Adafruit_NeoPixel. Décompressez les archives zip, assurez vous que le nom de répertoire correspond au fichiers .cpp et .h qu'il contient, déplacez ensuite le répertoire dans le répertoire des bibliothèques Arduino (nommé "libraries") et redémarrer Arduino IDE.
Les croquis/sketch Arduino doivent inclure les fichiers header suivant pour pouvoir utiliser cette bibliothèque:
#include <Adafruit_GFX.h> #include <Adafruit_NeoMatrix.h> #include <Adafruit_NeoPixel.h> #ifndef PSTR #define PSTR // pour faire plaisir à Arduino Due #endif
Les lignes supplémentaires ifdef/define/endif sont uniquement nécessaire si vous voulez utiliser un Arduino Due. Sinon, vous pouvez les ignorer.
Les dispositions (layouts)
Commençons par une précision utile. En anglais, une disposition (entendez "agencement d'élements") se dit "layout". C'est un terme que vous pourriez retrouver en différents endroits dans le code d'exemple et nom de constantes.
Adafruit_NeoMatrix utilise le même système de coordonnées, fonctions de couleur et commandes graphiques que la bibliothèque/librairie Adafruit_GFX. Si vous ne connaissez pas encore cette dernière, nous disposons d'un tutoriel séparé expliquant l'utilisation d'Adafruit_GFX. Il y a aussi des croquis/sketch d'exemples incluant la bibliothèque Adafruit_NeoMatrix.
Dans cette section, nous allons nous concentrer sur le constructeur — comment déclarer un affichage à deux dimensions réalisé à base de NéoPixels. L'alimentation de de la bête est un point qui est abordé dans une autre section.
La bibliothèque gère deux type de type de matrice:
- Les matrices simples: tous les NéoPixels sur une seule grille uniforme
- Les matrices en damier: de multiples grilles/matrices combinées pour réaliser un plus grand afficheur
Crédit: AdaFruit Industries www.adafruit.com
Commençons avec la déclaration d'une simple matrice, parce que c'est plus simple à expliquer. Nous allons faire une démonstration avec le Shield NéoPixel pour Arduino — qui est une matrice NéoPixel de 8x5 LEDs. En tenant ce shield de façon a pouvoir lire le texte, le premier pixel, #0, est en haut à gauche. Chaque pixel successif sur la droite porte est le pixel suivant... — le pixel 1 est directement à droite du pixel 0, le pixel 2 à droite du pixel 1, et ainsi de suite. A la fin de chaque ligne, le pixel suivant se trouve à gauche (le 1ier pixel) sur la ligne suivante.
Ce n'est pas quelque-chose qui à été décidé dans le code... cela dépend simplement du raccordement NéoPixels sur la carte (les pistes de cuivre).
Crédit: AdaFruit Industries www.adafruit.com
We refer to this layout as row major and progressive. Row major means the pixels are arranged in horizontal lines (the opposite, in vertical lines, is column major). Progressive means each row proceeds in the same direction. Some matrices will reverse direction on each row, as it can be easier to wire that way. We call that a zigzag layout.
However…for this example, we want to use the shield in the “tall” direction, so the Arduino is standing up on the desk with the USB cable at the top. When we turn the board this way, the matrix layout changes…
Crédit: AdaFruit Industries www.adafruit.com
Now the first pixel is at the top right. Pixels increment top-to-bottom — it’s now column major. The order of the columns is still progressive though.
We declare the matrix thusly:
Adafruit_NeoMatrix matrix = Adafruit_NeoMatrix(5, 8, 6,
NEO_MATRIX_TOP + NEO_MATRIX_RIGHT +
NEO_MATRIX_COLUMNS + NEO_MATRIX_PROGRESSIVE,
NEO_GRB + NEO_KHZ800);
The first two arguments — 5 and 8 — are the width and height of the matrix, in pixels. The third argument — 6 — is the pin number to which the NeoPixels are connected. On the shield this is hard-wired to digital pin 6, but standalone matrices are free to use other pins.
The next argument is the interesting one. This indicates where the first pixel in the matrix is positioned and the arrangement of rows or columns. The first pixel must be at one of the four corners; which corner is indicated by adding either NEO_MATRIX_TOP or NEO_MATRIX_BOTTOM to either NEO_MATRIX_LEFT or NEO_MATRIX_RIGHT. The row/column arrangement is indicated by further adding either NEO_MATRIX_COLUMNS or NEO_MATRIX_ROWS to either NEO_MATRIX_PROGRESSIVE or NEO_MATRIX_ZIGZAG. These values are all added to form a single value as in the above code.
NEO_MATRIX_TOP + NEO_MATRIX_RIGHT + NEO_MATRIX_COLUMNS + NEO_MATRIX_PROGRESSIVE
The last argument is exactly the same as with the NeoPixel library, indicating the type of LED pixels being used. In the majority of cases with the latest NeoPixel products, you can simply leave this argument off…the example code is just being extra descriptive.
The point of this setup is that the rest of the sketch never needs to think about the layout of the matrix. Coordinate (0,0) for drawing graphics will always be at the top-left, regardless of the actual position of the first NeoPixel.
Why not just use the rotation feature in Adafruit_GFX?
Adafruit_GFX only handles rotation. Though it would handle our example above, it doesn’t cover every permutation of rotation and mirroring that may occur with certain matrix layouts, not to mention the zig-zag capability, or this next bit…
Tiled Matrices
A tiled matrix is comprised of multiple smaller NeoPixel matrices. This is sometimes easier for assembly or for distributing power. All of the sub-matrices need to be the same size, and must be ordered in a predictable manner. The Adafruit_NeoMatrix() constructor then receives some additional arguments:
Adafruit_NeoMatrix matrix = Adafruit_NeoMatrix( matrixWidth, matrixHeight, tilesX, tilesY, pin, matrixType, ledType);
The first two arguments are the width and height, in pixels, of each tiled sub-matrix, not the entire display.
The next two arguments are the number of tiles, in the horizontal and vertical direction. The dimensions of the overall display then will always be a multiple of the sub-matrix dimensions.
The fifth argument is the pin number, same as before and as with the NeoPixel library. The last argument also follows prior behaviors, and in most cases can be left off.
The second-to-last argument though…this gets complicated…
With a single matrix, there was a starting corner, a major axis (rows or columns) and a line sequence (progressive or zigzag). This is now doubled — similar information is needed both for the pixel order within the individual tiles, and the overall arrangement of tiles in the display. As before, we add up a list of symbols to produce a single argument describing the display format.
The NEO_MATRIX_* symbols work the same as in the prior single-matrix case, and now refer to the individual sub-matrices within the overall display. All tiles must follow the same format. An additional set of symbols work similarly to then describe the tile order.
The first tile must be located at one of the four corners. Add either NEO_TILE_TOP or NEO_TILE_BOTTOM and NEO_TILE_LEFT or NEO_TILE_RIGHT to indicate the position of the first tile. This is independent of the position of the first pixel within the tiles; they can be different corners.
Tiles can be arranged in horizontal rows or vertical columns. Again this is independent of the pixel order within the tiles. Add either NEO_TILE_ROWS or NEO_TILE_COLUMNS.
Crédit: AdaFruit Industries www.adafruit.com
Tiles don’t need to be square! The above is just one possible layout. The display shown at the top of this page is three 10x8 tiles assembled from NeoPixel strip.
Once the matrix is defined, the remainder of the project is similar to Adafruit_NeoPixel. Remember to use matrix.begin() in the setup() function and matrix.show() to update the display after drawing. The setBrightness() function is also available. The library includes a couple of example sketches for reference.
Finally, rows or columns of tiles may be arranged in progressive or zigzag order; that is, every row or column proceeds in the same order, or alternating rows/columns switch direction. Add either NEO_TILE_PROGRESSIVE or NEO_TILE_ZIGZAG to indicate the order. BUT…if NEO_TILE_ZIGZAG order is selected, alternate lines of tiles must be rotated 180 degrees. This is intentional and by design; it keeps the tile-to-tile wiring more consistent and simple. This rotation is not required for NEO_TILE_PROGRESSIVE.
Autres dispositions
For any other cases that are not uniformly tiled, you can provide your own function to remap X/Y coordinates to NeoPixel strip indices. This function should accept two unsigned 16-bit arguments (pixel X, Y coordinates) and return an unsigned 16-bit value (corresponding strip index). The simplest row-major progressive function might resemble this:
uint16_t myRemapFn(uint16_t x, uint16_t y) {
return WIDTH * y + x;
}
That’s a crude example. Yours might be designed for pixels arranged in a spiral (easy wiring), or a Hilbert curve.
The function is then enabled using setRemapFunction():
matrix.setRemapFunction(myRemapFn);
La RAM encore une fois
On a per-pixel basis, Adafruit_NeoMatrix is no more memory-hungry than Adafruit_NeoPixel, requiring 3 bytes of RAM per pixel. But the number of pixels in a two-dimensional display takes off exponentially…a 16x16 display requires four times the memory of an 8x8 display, or about 768 bytes of RAM (nearly half the available space on an Arduino Uno). It can be anywhere from tricky to impossible to combine large displays with memory-hungry libraries such as SD or ffft.
Correction Gamma
Because the Adafruit_GFX library was originally designed for LCDs (having limited color fidelity), it handles colors as 16-bit values (rather than the full 24 bits that NeoPixels are capable of). This is not the big loss it might seem. A quirk of human vision makes bright colors less discernible than dim ones. The Adafruit_NeoMatrix library uses gamma correction to select brightness levels that are visually (though not numerically) equidistant. There are 32 levels for red and blue, 64 levels for green.
The Color() function performs the necessary conversion; you don’t need to do any math. It accepts 8-bit red, green and blue values, and returns a gamma-corrected 16-bit color that can then be passed to other drawing functions.
Source: NeoPixel UserGuide créé par Phillip Burgess pour AdaFruit Industries. Crédit AdaFruit Industries
Traduit par Meurisse D. pour MCHobby.be
Traduit avec l'autorisation d'AdaFruit Industries - Translated with the permission from Adafruit Industries - www.adafruit.com
Toute référence, mention ou extrait de cette traduction doit être explicitement accompagné du texte suivant : « Traduction par MCHobby (www.MCHobby.be) - Vente de kit et composants » avec un lien vers la source (donc cette page) et ce quelque soit le média utilisé.
L'utilisation commercial de la traduction (texte) et/ou réalisation, même partielle, pourrait être soumis à redevance. Dans tous les cas de figures, vous devez également obtenir l'accord du(des) détenteur initial des droits. Celui de MC Hobby s'arrêtant au travail de traduction proprement dit.