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 principale et progressive ("row major and progressive"). Ligne Principale (row major) signifie que les pixels sont arrangés en ligne horizontale... à l'opposé des lignes verticales qui sont identifiées comme Colonne Principale ("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 Principale ("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", 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 principal (major axis) en ligne ou colonne (rows ou columns) et une séquence de ligne (progressive ou zigzag). Cette information est maintenant nécessaire en double — il faut indiquer la disposition des pixels dans un damier et la disposition générale des damiers dans l'afficheur.
Comme déjà vu précédemment, la disposition des pixels sur une dalle (un damier) de l'afficheur est décrit à l'aide des constantes NEO_MATRIX_*. La disposition des dalles dans l'afficheur utilise le même principe mais avec des symboles NEO_TILE_*. Au final, vous aurez un parametre contenant une somme de NEO_MATRIX_* + NEO_TILE_*.
La première dalle doit être placée dans l'un des 4 coins (de l'afficheur). Ajouter donc NEO_TILE_TOP (en haut) ou NEO_TILE_BOTTOM (en bas) ainsi que NEO_TILE_LEFT (à gauche) ou NEO_TILE_RIGHT (à droite) pour indiquer la première dalle du damier. Cela est indépendant de la position du premier pixel dans la dalle; qui peut être dans un coin différent.
Les dalles peuvent être arrangés en ligne horizontales ou colonnes verticales. Encore une fois, cela est indépendant de l'arrangement des pixels sur une dalle. On ajoute donc l'une des constantes NEO_TILE_ROWS (dalles en lignes) ou NEO_TILE_COLUMNS (dalles en colonnes).
Crédit: AdaFruit Industries www.adafruit.com
Les dalles n'ont pas besoin d'être carrée! Ce que vous voyez ci-dessus est juste une des dispositions (layout) possible. L'afficheur tout en haut de la page est constitué de 3 "dalles" de 10x8 réalisée à partir de ruban NéoPixel.
Une fois la matrice définie, le restant du projet est similaire à un Adafruit_NeoPixel. Rappelez-vous d'utiliser matrix.begin() dans la fonction setup() et matrix.show() pour mettre l'afficheur à jour. La fonction setBrightness() est également disponible. La bibliothèque inclus également quelques croquis/sketch d'exemple en référence.
Pour finir, les lignes (rows) ou les colonnes (columns) du damier doivent être organisés dans un ordre progressif (progressive) ou zigzag; toutes les lignes ou colonnes doivent être positionnés dans le même ordre ou en inversant la direction à chaque nouvelle ligne/colonne. Ajouter donc NEO_TILE_PROGRESSIVE (ordre progressif) ou NEO_TILE_ZIGZAG (ordre en ZigZag) MAIS... si vous choisissez NEO_TILE_ZIGZAG, les lignes alternées doivent avoir des dalles tournées de 180 degrées. C'est conçu et voulu comme tel; cela permet d'avoir un raccordement électrique de dalle en dalle plus simple et plus cohérent. Cette rotation n'est pas nécessaire si vous utilisez NEO_TILE_PROGRESSIVE.
Autres dispositions
Pour tous les autre cas ou les dalles ne sont pas disposées uniformément, vous pouvez fournir votre propre fonction de correspondance des coordonnées X/Y (fonction remap) en indice NeoPixel.
Cette fonction devrait accepter deux argument unsigned 16-bit (entiers 16 bits non signés... pour les coordonnées X, Y du pixel) et retourne un valeur unsigned 16-bit (correspondant à l'indexe du pixel dans le ruban). La fonction la plus simple correspondant à la disposition ligne principale, progressive ressemble à ceci:
uint16_t myRemapFn(uint16_t x, uint16_t y) {
return WIDTH * y + x;
}
C'est un exemple simple... vous pourriez concevoir des pixels disposés en spirale (raccordement plus facile) ou en courbe de Hilbert (voyez surtout la vidéo en 6 itérations sur la version anglaise de l'article).
Vous pouvez ensuite activer la donction en appelant setRemapFunction():
matrix.setRemapFunction(myRemapFn);
La RAM encore une fois
Adafruit_NeoMatrix n'est pas plus gourmand en RAM d'une simple dalle/ruban NéoPixels. Il nécessite donc 3 bytes/octets de RAM par pixels. Cependant, les pixels organisés en afficheur deux dimensions consomme de la RAM de façon.... exponentiel. Un afficheur 16x16 exige 4 fois plus de mémoire qu'un afficheur 8x8, soit environ 768 octets/bytes de RAM (presque la moitié de ce qui est disponible sur un Arduino Uno). Il serait compliqué (voire impossible) de combiner un grand afficheur avec des bibliothèques gourmandes en mémoire tel que SD ou ffft.
Correction Gamma
A l'origine, la librairie/bibliothèque Adafruit_GFX était conçue pour des LCDs (disposant généralement d'une fidélité limitée en ce qui concerne les couleurs). En conséquence, la bibliothèque gère gère les couleurs en valeur 16-bit (plutôt qu'en couleurs 24 bits tel que NeoPixels est capable de le supporter). Cela ne représente pourtant une perte aussi important qu'il n'y parait. Un caprice de la vision humaine fait que les couleurs vives sont moins discernables que les couleurs sombres. La bibliothèque Adafruit_NeoMatrix utilise la correction gamma pour sélectionner le niveau de luminosité pour qu'ils semble visuellement équidistant les uns des autres. Il y a donc 32 niveaux de rouge et bleu et 64 niveaux de vert (car l'oeil est nettement plus sensible au vert).
La fonction Color() réalise la conversion nécessaire; vous n'avez pas besoin de réaliser des opérations mathématiques. Elle accepte des valeurs 8-bits pour le rouge, vert et bleu et retourne une valeur de couleur 16-bits incluant la correction gamma... qui peu ensuite être passée aux différentes fonctions de dessin.
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.