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
Nous appelons cette disposition ("layout") rangée/ligne majeure et progressive ("row major and progressive"). Ligne Majeure (row major) signifie que les pixels sont arrangés en ligne horizontale... à l'opposé des lignes verticales qui sont identifiées comme colonne majeure ("column major"). Progressive signifie que chacune des lignes est dans la même direction que la précédente. Certaines matrices inverse le sens des pixels à chaque ligne (car c'est plus facile à câbler)... la disposition de ces matrices est appelé zigzag.
Cependant... pour cet exemple, nous voulons utiliser le shield en hauteur, de sorte que l'Arduino est debout sur le bureau avec le cable USB au dessus. Lorsque l'on tourne la carte dans ce sens, la disposition de la matrice (le "layout") change.
Crédit: AdaFruit Industries www.adafruit.com
Maintenant, le premier pixel est en haut à droite. Les pixels s'incrémente de haut-en-bas — C'est maintenant une disposition colonne majeure ("column major"). L'ordre des colonne est toujours en "progressive".
Nous pouvons déclarer la matrice comme suit:
Adafruit_NeoMatrix matrix = Adafruit_NeoMatrix(5, 8, 6, NEO_MATRIX_TOP + NEO_MATRIX_RIGHT + NEO_MATRIX_COLUMNS + NEO_MATRIX_PROGRESSIVE, NEO_GRB + NEO_KHZ800);
Les deux premiers arguments — 5 et 8 — représentent la largeur (width) et hauteur (height) de la matrice, en pixelsin pixels.
Le troisième argument — 6 — est le numéro de broche (de donnée) sur laquelle les NéoPixels sont connéctés. Sur le shield, il s'agit de la broche digital 6 mais les autres matrices peuvent être utilisées avec n'importe quelle broche.
Le quatrième argument est le plus intéressant. Il indique où est positionné le premier Pixel sur la matrice et l'organisation en ligne ou en colonne. Le premier pixel doit impérativement se trouver dans l'un des quatres coins; coin qui peut être identifié à l'aide des constantes NEO_MATRIX_TOP (en haut) ou NEO_MATRIX_BOTTOM (en bas) à laquel il faut ajouter NEO_MATRIX_LEFT (à gauche) ou NEO_MATRIX_RIGHT (à droite). La disposition en ligne (row) et colonne (column ) est indiqué à l'aide de la contante NEO_MATRIX_COLUMNS (en colonne, vertical) ou NEO_MATRIX_ROWS (en ligne, horizontal). Pour finir, il faut indiquer comment les pixels s'enchainent à avec NEO_MATRIX_PROGRESSIVE (arrangement progressif, tous les pixels dans la même direction) ou NEO_MATRIX_ZIGZAG (inversion de sens à chaque ligne). Ces constantes sont additionnées en une seule valeur... dans la cas de notre shield, nous obtenons:
NEO_MATRIX_TOP + NEO_MATRIX_RIGHT + NEO_MATRIX_COLUMNS + NEO_MATRIX_PROGRESSIVE
Le dernier argument est identique à celui utilisé avec la librairie NéoPixel... il indique le type de NéoPixel utilisé dans le montage. Dans la plupart des cas, avec les deniers produits NéoPixels, vous pouvez laisser cet argument vide... cet exemple de code inclus le paramètre pour être le plus complet possible.
 |
Le but de cette phase de configuration est permettre au reste du croquis/sketch de ne pas avoir à ce soucier des détails techniques et disposition de la matrice. La coordonnée (0,0) utilisée pour les opérations graphiques sera toujours en haut à gauche, peut importe la position physique du premier NéoPixel. |
Pourquoi ne pas utiliser la capacité de rotation de d'Adafruit_GFX?
Adafruit_GFX sait uniquement gérer la rotation. Cela gérerait le cas de notre exemple ci-dessus, mais ne prendra pas en charge les permutation de rotation et effet miroir qui peuvent se présenter dans certaines disposition de matrice (matrix layouts), sans oublier le support "zig-zag" capability, ou encore ce que nous allons aborder dans la section suivante…
Matrices en damier (tiled)
Une matrice en damier (tiled matrix) est composé de plusieurs matrices NéoPixel plus petites. C'est parfois plus simple à assembler ou permet de distribuer l'alimentation plus facilement. Toutes les sous-matrices doivent avoir la même taille et sont positionnées de façon prévisible. Le constructeur Adafruit_NeoMatrix() reçoit alors des arguments supplémentaires:
Adafruit_NeoMatrix matrix = Adafruit_NeoMatrix( matrixWidth, matrixHeight, tilesX, tilesY, pin, matrixType, ledType);
- matrixWidth, matrixHeight: Les deux premiers arguments sont la largeur (width) et la hauteur (height) en pixel de chacune des sous-matrices composant le damier, et non la taille de l'afficheur dans sa totalité.
- tilesX, tilesY: Les deux arguments suivants représente le nombre de dalles du damier dans les deux directions. TilesX représente le nombre de dalles horizontales et TilesY à la verticale. La dimension totale de l'affichage est donc un multiple de la dimension des sous-matrices.
- pin: ce 5ième argument est le même qu'avant et identique à celui de la bibliothèque NeoPixel. C'est l'identification de la broche de donnée.
- matrixType: ce paramètre est plus compliqué... et donc abordé séparément ci-dessous.
- 'ledType: le dernier argument permet d'identifier le type de NéoPixel utilise. Voir la description plus haut dans cet article.
Le paramètre matrixType
Avec un seule matrice, il y avait un coin de départ, un axe majeur (principal) 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.