NeoPixel-UserGuide-Arduino

Bibliothèque Arduino

Contrôler des NéoPixels à "partir de rien" est un sacré challenge. AdaFruit propose une bibliothèque/librairie permettant avant tout de prendre du plaisir et de se concentrer sur les points intéressants. La bibliothèque fonctionne avec la plupart des cartes Arduino et dérivés: Uno, Mega, Leonardo, Micro, Adafruit Flora, etc. — la plupart des plateformes à base de processeur Atmel AVR 8-bits entre 8 et 16 MHz — elle fonctionne également avec Arduino Due et toute une variété de carte PJRC Teensy.

Etant donné que la bibliothèque utilise le langage assembleur spécifique au processeur, la librairie ne fonctionne pas sur Netduino, ChipKIT ou autres cartes avancées “type-Arduino”. D'autres contributeurs peuvent avoir écrit du code et bibliothèques pour de telles cartes, mais AdaFruit ne saura pas fournir de support technique en cas de bug ou problème sur de telle plateforme.

Vous pouvez installer la bibliothèque comme suit:

• Naviguez sur la page de la bibliothèque Adafruit_NeoPixel sur Github.com.
• Sélectionnez le bouton “Download ZIP” (téléchargement) ou cliquer simplement sur ce liens pour un téléchargement direct.
• Décompressez l'archive ZIP après le téléchargement de celui-ci.
• Il devrait en résulter un répertoire contenant les fichiers “Adafruit_NeoPixel.cpp”, “Adafruit_NeoPixel.h” et un sous-répertoire “examples” (contenant les exemples). Sous Windows, il arrive parfois que vous obteniez un répertoire intermédiaire et vous aurez besoin de déplacer les fichier.
• Renommez le répertoire (celui contenant les fichiers .cpp et .h) en “Adafruit_NeoPixel” (avec l'Underscore et tout le reste), et la placer à côté des autres bibliothèques/librairies Arduino (généralement dans votre répertoire <répertoire_racine>/Documents/Arduino/Libraries.
• Redémarrez votre environnement Arduino IDE (s'il est en cours de fonctionnement).

Vous trouverez ici un tutoriel contenant des informations complémentaire pour installer une bibliothèque/librairie Arduino.

Branchement de base

Pour débuter, considérons que nous avons un microcontroleur Arduino connecté sur le port USB d'un ordinateur. Nous nous attarderons plus tard sur l'alimentation des NéoPixels, mais pour le moment nous allons utiliser une alimentation séparée de 5V continu (ou un accu lithium-ion 3.7V pour un projet fringuable Flora).

Identifiez le bout correspondant à l'entrée ("input") de votre ruban NeoPixel, Pixel(s) ou autre périphérique NéoPixel. Sur certains modèles vous trouverez une partie portant l'indication "DIN" ou "DI" pour data input (entrée de donnée). D'autre modèles porterons une petite flèche indiquant la directions de déplacement des information. L'entrée de donnée du NeoPixel ("data input") peut être connecté sur n'importe quel broche digitale de votre Arduino mais pour ce code d'exemple nous allons la brancher sur la sortie digital 6 (celle utilisée par défaut). Le shield NéoPixel utilise par ailleurs la broche digital 6.

Si vous utilisez un Flora avec un accu lithium-ion: connectez l'entrée +5V du ruban NéoPixel sur la pastille VBATT de Flora, le GND du ruban sur l'une des pastilles GND de Flora et le DIN du ruban sur la pastille D6 de Flora.

Pour les autres cartes Arduino disposant d'une aliment +5V DC séparée pour les NéoPixels: connectez l'entrée +5V du ruban NéoPixel sur la borne + (positive) de l'alimentation (ne pas la connecter sur l'alimentation de votre Arduino), la connexion DIN sur la broche digital 6 de votre Arduino et le "–"/Négatif/GND du ruban NéoPixel sur les deux masses (sur la masse/GND d'Arduino et sur la masse/GND de l'alimentation séparée).

Les rubans NéoPixels 144 pixels/m sont très dense, il n'y a pas beaucoup de place pour y indiquer d'autres libellés que "–", "+" et une flèche indiquant la direction des données. L'entrée/sortie de données ne dipose pas d'une pastille avec un libellé.

Crédit: AdaFruit Industries www.adafruit.com

Est-il possible d'alimenter les NéoPixels directement depuis le +5v d'Arduino?

Parfois. Le régulateur d'Arduino peut continuellement fournir 500 milliampères (environ) sur la broche 5V. Chaque NéoPixel peut consommer jusqu'à 60 milliampères (a pleine luminosité). Il est donc possible de se passer d'une alimentation séparée et d'alimente directement des NéoPixels depuis votre Arduino... mais seulement quelques NéoPixels ou si vous les utilisez en couleur et à faible luminosité. En cas de doute, optez pour une alimentation séparée.

Code d'exemple simple: standtest

Démarrez votre Arduino IDE. Sélectionnez ensuite le programme de démonstration Strandtest via le menu Fichier > Exemple > Adafruit_NeoPixel > strandtest

(Si le point de menu Adafruit_NeoPixel n'est visible, c'est que la bibliothèque/librairie n'a pas été correctement installé ou que votre Arduino IDE n'a pas été redémarré. Vérifiez les étapes d'installation ci-dessus pour vous assurer que l'installation est correctement nommée et placée au bon endroit.)

Sélectionnez le bon type de carte et le bon port série dans le menu Outils et essayez de téléverser/télécharger le programme sur la carte. Si les NéoPixels sont connectés et branchés, vous devriez alors les voir s'illuminer

Il ne se passe rien

Vérifiez vos connexions. L'erreur la plus répandue est d'avoir connecté la broche de donnée d'Arduino sur la sortie du ruban au lieu de l'entrée du ruban.

Inspectons le code

Jetons à présent un petit coup d'oeil sur le code...

Tous les croquis/sketchs NéoPixels commence pas l'inclusion du fichier header (de déclaration):

#include <Adafruit_NeoPixel.h>

Le bloc de code suivant contient principalement des commentaires descriptifs. Seule la dernière ligne réalise vraiment des opérations:

#define PIN 6

// Paramètre 1 = Le nombre de NéoPixels chainés
// Paramètre 2 = No de broche de données (Sur votre Arduino, la plupart convient)
// Paramètre 3 = Type de pixel (flags/drapeaux), a combiner ensemble en fonction du besoin:
//   NEO_KHZ800  flux de données à 800 KHz (plupart des NéoPixel basé sur les LEDs w/WS2812)
//   NEO_KHZ400  flux de données à 400 KHz (Pour les Pixels classiques 'v1' FLORA (pas les V2) pilotés par WS2811)
//   NEO_GRB     Pixels sont raccordés en flux de donnée GRB (GRB=Green,Red,Blue=Vert,Rouge,Bleu - la plupart des produits NéoPixel)
//   NEO_RGB     Pixels sont raccordés en flux de donnée RGB (RGB=Red,Green,Blue=Rouge,Vert,Bleu - Pixels FLORA v1, pas la v2)
Adafruit_NeoPixel strip = Adafruit_NeoPixel(60, PIN, NEO_GRB + NEO_KHZ800);

La première ligne assigne un nombre au symbole "PIN" pour l'utiliser comme référence plus tard. Il n'est pas absolument nécessaire de le faire comme cela, mais cela rend le changement de code plus simple si vous voulez utiliser une autre broche de commande... dans le cas contraire, il serait réviser la totalité du code.

La dernière ligne déclare un objet NéoPixel. Nous nous référerons à ce dernier plus tard dans le code pour contrôler le ruban/strip de pixels. Il y a 3 arguments/paramètres dans les paranthèses:

1. Le nombre de NéoPixel chainés dans le ruban/strip. Dans cet exemple il est fixé à 60, ce qui correspond à un mètre de ruban à densité moyenne. Modifiez ce paramètre pour qu'il corresponde au nombre de pixels que vous utilisez.
2. Le numéro de broche sur-laquelle est connecté le ruban NeoPixel (ou autre périphérique). Cela devrait être un chiffre mais nous pouvons également utiliser le symbole "PIN" récemment déclaré et y faire référence.
3. Une valeur identifiant le type de NéoPixel connecté. Dans la plupart des cas, vous n'avez pas à vous en préoccuper... et vous juste passer deux arguments; Cet exemple de code est juste très méticuleux pour offrir une description complète descriptive. Si vous utiliser des Pixels Flora classique en version "V1", ces derniers nécessite l'usage de NEO_KHZ400 + NEO_RGB en tant que paramètre.

Ensuite, dans la fonction setup(), vous pouvez appeler begin() pour préparer la broche de donnée destinée aux NéoPixels:

void setup() {
  strip.begin();
  strip.show(); // Initialise tous les pixels à 'off' (éteint)
}

La second ligne, strip.show(), n'est pas absolument nécessaire, elle est seulement là pour être méticuleux. La fonction pousse les données vers les pixels... puisque qu'aucune couleur n'est encore donnée aux différents pixels. Ici, ils sont néanmoins initialisé à l'état "off"/éteint... pour éviter d'avoir un état lumineux quelconque initialisé par un programme précédent.

Dans l'exemple strandtest, le fonction loop() ne modifie pas directement la couleur des pixels — elle appelle une autre fonction pour créer un effet animé. Nous pouvons l'ignorer pour le moment et regarder un peu plus loin, dans les différentes fonctions individuelles, pour voir comment le ruban NéoPixel est contrôlé.

Il y a deux façon de contrôler la couleur d'un Pixel. La première est:

strip.setPixelColor(n, red, green, blue);

• n: Le premier argument — n dans cet exemple — est le numéro du pixel le long du ruban, commençant à 0 pour le plus proche d'Arduino. Si vous avez un ruban/chaine de 30 pixels, ils sont numérotés de 0 à 29 (comme c'est couramment le cas en informatique). De nombreux emplacement du code utilise une boucle for, utilisant la variable compteur de la boucle comme argument identifiant le n° de pixel... cela permet de donner une valeur à plusieurs pixels.
• les 3 arguments suivants définissent la couleur du pixel en indiquant le niveau de luminosité en rouge, vert et bleu.
  • red: Niveau de luminosité rouge, 0 est la plus tenue (éteint) et 255 la luminosité maximale.
  • green: Niveau de luminosité vert, 0 est la plus tenue (éteint) et 255 la luminosité maximale.
  • blue: Niveau de luminosité bleu, 0 est la plus tenue (éteint) et 255 la luminosité maximale.

Pour initialiser le 12ième pixel (donc le numéro 11, en comptant depuis 0) a magenta (rouge + bleu), vous devez écrire le code:

strip.setPixelColor(11, 255, 0, 255);

Il existe une syntaxe alternative utlilisant seulement 2 arguments:

strip.setPixelColor(n, color);

Ici, l'argument color est un type 32-bit qui fusionne les valeurs rouge, vert et bleu dans un seule valeur. C'est parfois plus facile et rapide à utiliser pour certains programmes (mais pas pour tous); si vous inspectez le code de strandtest, vous noterez que les deux deux syntaxes sont utilisées (à différentes places).

Vous pouvez également convertir les 3 valeurs séparées Rouge, Vert et Bleu en une seule valeur 32-bits pour l'utiliser plus tard:

uint32_t magenta = strip.Color(255, 0, 255);

Vous pouvez ensuite passer la valeur "magenta" comme argument lors de l'appel à la fonction setPixelColor plutôt que les 3 valeurs de couleur séparément (Rouge, Vertn Bleu) lors de chaque appel.

setPixelColor() does not have an immediate effect on the LEDs. To “push” the color data to the strip, call show():

strip.show();

La fonction show() fait une mise-à-jour de tout le ruban/chaine en une seule fois. Même si cette étape supplémentaire peu paraitre ennuyante, c'est en fait une bonne chose. Si chaque appel à setPixelColor() avait un effet immédiat, votre animation présenterait des sursauts plutôt que faire des mise-à-jours du ruban de façon homogène.

Vous pouvez ré-obtenir la couleuur d'un pixel (précédemment initialisé) en utilisant la fonction getPixelColor():

uint32_t color = strip.getPixelColor(11);

Cette fonction retourne la couleur (sous forme de valeur composée) sous forme d'un entier 32-bit.

Le nombre de pixels déclaré dans le ruban/chaine NéoPixel peut-être retourné en utilisant numPixels():

uint16_t n = strip.numPixels();

La luminosité de toutes les LEDs peuvent être ajuster en utilisant setBrightness(). Cette fonction prend un seul argument, un nombre entre 0 (éteind) et 255 (luminosité maximale). Par exemple, vous pouvez utiliser l'appel suivant pour ajuster la luminosité à 25% (1/4 de luminosité):

strip.setBrightness(64);

Tout comme setPixel(), l'effet de la fonction n'est pas immédiat. l'appel doit être suivit d'un appel à show().

Vous nous pouvez pas passer d'un faible luminosité à une plus haute luminosité sans perte de fidélité. Certaines effets sont d'une meilleure qualité si vous laissez la luminosité au maximum et appelez la fonction setPixel() de façon répétée pour remplir le ruban/chaine NéoPixel.

J'appelle setPixel() mais rien ne se passe!

Il y a deux coupables principaux à cela:

1. Vous avez oublié d'appeller strip.begin() dans la fonction setup().
2. Vous avez oublié d'appeler strip.show() après avoir initialisé la couleur du pixel.

Une autre possibilité (moins courante) c'est de tomber à court de RAM — voyez la section ci-dessous. Si votre programme semble fonctionner mais qu'il produit un résultat non prévisible alors considérez cette option.

Puis-je avoir différents objets NéoPixel sur différente broches?

Evidemment! Chaque broche de commande nécessitant sa propre déclaration avec un nom unique:

Adafruit_NeoPixel ruban_a = Adafruit_NeoPixel(16, 5);
Adafruit_NeoPixel ruban_b = Adafruit_NeoPixel(16, 6);

La déclaration ci-dessis crée deux objets NéoPixel, un sur la broche 5 et l'autre sur la broche 6, chacun contenant 16 pixels et utilisant la configuration NéoPixel implicite (NEO_KHZ800 + NEO_GRB).

Can I connect multiple NeoPixel strips to the same Arduino pin?

In many cases, yes. All the strips will then show exactly the same thing. This only works up to a point though…four strips on a single pin is a good and reliable number. If you need more than that, individual NeoPixels can be used as buffers to “fan out” to more strips: connect one Arduino pin to the inputs of four separate NeoPixels, then connect each pixels’ output to the inputs of four strips (or fewer, if you don’t need quite that many). If the strips are 10 pixels long, declare the NeoPixel object as having 11 pixels. The extra “buffer” pixels will be at position #0 — just leave them turned off — and the strips then run from positions 1 through 10.

Les pixels sont gourmand en RAM

Each NeoPixel requires about 3 bytes of RAM. This doesn’t sound like very much, but when you start using dozens or even hundreds of pixels, and consider that the mainstream Arduino Uno only has 2 kilobytes of RAM (often much less after other libraries stake their claim), this can be a real problem!

For using really large numbers of LEDs, you might need to step up to a more potent board like the Arduino Mega or Due. But if you’re close and need just a little extra space, you can sometimes tweak your code to be more RAM-efficient. This tutorial has some pointers on memory usage.

---

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.