Bibliothèque LightEffect

. Par : Christian. URL : https://www.locoduino.org/spip.php?article276

Avec les cartes Arduino, il devient très facile de concevoir des animations lumineuses pour enrichir le décor d’un réseau de trains miniatures. Il suffit d’enchaîner des digitalWrite et des delay pour créer une animation sur une série de LED (feu tricolore par exemple). Cependant, dès qu’on veut créer une animation un peu sophistiquée (enseigne de commerçant par exemple), il n’est pas toujours facile pour des débutants d’arriver au résultat. La bibliothèque LightEffect a donc été créée pour leur faciliter le travail puisqu’elle propose plusieurs effets lumineux qu’il suffit d’enchaîner les uns à la suite des autres pour obtenir une belle animation lumineuse. Cet article décrit la bibliothèque et comment l’utiliser.

Ce que propose la bibliothèque

La bibliothèque LightEffect permet de créer facilement des animations lumineuses à partir d’une carte Arduino ou d’un microcontrôleur ATtiny (feux tricolores, chenillard, enseigne de commerçant, etc.). Cependant, la bibliothèque utilise des fonctions delay(), ce qui ne permet pas de l’utiliser dans un programme faisant autre chose que gérer les effets lumineux.

Les LED sont reliées aux sorties numériques de la carte Arduino ou du microcontrôleur avec une résistance en série limitant le courant dans la LED. La valeur de la résistance dépend de la couleur de la LED et doit tenir compte de la limitation en courant de la sortie numérique et des possibilités de la carte. Voir à ce sujet l’article Fonctionnement et pilotage d’une DEL ; pour tenir compte de toutes les limitations en courant, il est parfois préférable de choisir des résistances un peu plus fortes que ce que donne le calcul.

Les LED peuvent être connectées aux sorties numériques par leur anode ou bien par leur cathode, mais toutes les LED doivent être connectées de la même manière. De plus, les sorties numériques utilisées doivent se suivre dans l’ordre croissant de leur numérotation.

Ne pas confondre numéro de sortie numérique et numéro de broche du microcontrôleur (voir les documentations des cartes ou des microcontrôleurs comme par exemple la figure 1).
Figure 1
Figure 1
Correspondance entre broches du microcontrôleur et sorties numériques (en bleu)

Le nombre de LED est limité par le nombre de sorties numériques de la carte Arduino ou du microcontrôleur. Si on programme soi-même le microcontrôleur, il peut être nécessaire de ne pas utiliser la broche de RESET comme sortie numérique (voir la série d’articles sur les ATtiny). Sur une carte Arduino Uno, les entrées analogiques A0 à A5 peuvent être utilisées comme sorties numériques pour l’animation lumineuse.

La figure 2 montre comment câbler une enseigne de 6 LED reliées par leur anode à la carte Arduino ou au microcontrôleur alors que la figure 3 montre le même montage mais cette fois les LED sont reliées par leur cathode.

Figure 2
Figure 2
Connexion des LED par leur anode (montage dit à cathodes communes)
Figure 3
Figure 3
Connexion des LED par leur cathode (montage dit à anodes communes)

Une fois le groupe de LED câblé, il faut le déclarer dans le programme comme on le verra ultérieurement et pour cela, il faut préciser sur quelle sortie est connectée la première LED, le nombre total de LED et enfin le niveau logique permettant d’allumer une LED (HIGH si les LED sont connectées par leur anode et LOW si elles le sont par leur cathode).

Ensuite, il n’y a plus qu’à enchaîner différentes séquences d’effets lumineux (décrits ci-dessous) pour créer son animation lumineuse. La bibliothèque permet de créer plusieurs groupes de LED mais les séquences de chaque groupe sont jouées les unes après les autres et doivent être astucieusement choisies pour laisser croire à l’indépendance de chaque effet lumineux (voir l’exemple Electric_sign de la bibliothèque). Le public y croira d’autant plus que les groupes de LED seront éloignés les uns des autres et répartis dans le décor. La bibliothèque est également capable de gérer un ensemble de deux feux tricolores de carrefour routier ou bien un ensemble de deux feux tricolores de circulation alternée en cas de travaux ; la séquence de tels feux étant longue, il est préférable de ne pas créer d’autres animations lumineuses dans le programme.

Les différentes séquences d’effets lumineux

Chaque séquence est appelée par une fonction particulière dont il faut respecter la syntaxe (l’utilisation de la bibliothèque dans un programme est décrite plus loin). Parmi ces séquences, on trouve des possibilités très basiques comme tout allumer ou tout éteindre (ce qui permet de créer des clignotements si on enchaîne ces séquences), mais aussi des choses plus sophistiquées comme propager un flash dans un sens ou dans l’autre (ce qui permet de créer un chenillard) ou bien encore allumer ou éteindre toutes les LED dans un ordre aléatoire.

Les différentes fonctions d’effets lumineux sont décrites plus bas et dans les fichiers README (un en français, l’autre en anglais) qu’on trouve dans le répertoire de la bibliothèque. Six programmes d’exemples sont accessibles via le menu Fichier > Exemples du logiciel de programmation IDE.

Un exemple (Demo_LightEffect) est donné dans la bibliothèque pour démontrer les possibilités de la bibliothèque sur un ensemble de 10 LED. Un autre exemple est donné pour montrer comment on peut gérer deux ensembles de LED en même temps. Enfin, deux autres exemples montrent la gestion de feux tricolores. Ces exemples peuvent être adaptés à vos besoins ou bien vous pouvez créer vos propres programmes d’animations lumineuses.

Installation de la bibliothèque

Ouvrez votre IDE et utilisez le menu Croquis > Inclure une bibliothèque > Gérer les bibliothèques. Dans la fenêtre qui s’ouvre (Gestionnaire de bibliothèque), tapez LightEffect dans la case de recherche en haut à droite. Une fois la bibliothèque trouvée, vous n’avez plus qu’à cliquer sur Installer (Figure 4).

Figure 4
Figure 4
La bibliothèque est gérée par le Gestionnaire de bibliothèque de l’IDE.

En cas de difficultés, reportez-vous à l’article Installer une bibliothèque.

Pour désinstaller la bibliothèque, il suffit de supprimer le répertoire LightEffect qui se trouve dans Arduino > libraries.

On peut trouver la bibliothèque LightEffect sur la page Libraries du site Arduino, en cherchant dans la catégorie Device Control, comme le montre la figure 5 ; elle est située juste après LightDimmer, une autre bibliothèque de Locoduino.

Figure 5
Figure 5
Extrait de page du site arduino.cc dans la catégorie Libraries / Device Control où on trouve les bibliothèques de Locoduino.

Utilisation de la bibliothèque dans un programme

La première chose à faire est d’inclure la bibliothèque au début du programme d’utilisation avec :
#include <LightEffect.h>

Cette ligne sera automatiquement créée avec le menu Croquis > Inclure une bibliothèque puis en allant chercher la bibliothèque LightEffect dans la liste proposée.

Ensuite, il faut instancier un ou plusieurs groupes de LED en donnant un nom à l’objet et en précisant la position de la première LED, le nombre de LED et le niveau logique pour les allumer. Par exemple :
LightEffect monEnseigne(4, 6, LOW);
On rappelle que les sorties numériques utilisées doivent se suivre dans l’ordre croissant de leur numérotation (comme expliqué plus haut).

Ici, le groupe de LED est appelé « monEnseigne » et 6 LEDs sont connectées par leur cathode puisqu’un niveau LOW les allume, la première LED est sur la sortie numérique 4.

Les séquences s’appellent avec la syntaxe suivante : nomObjet.fonction() ;
avec nomObjet le nom qu’on a donné à l’objet (par exemple monEnseigne) et fonction() une des fonctions de la bibliothèque avec ou sans argument. Exemple :
monEnseigne.onRight();

Ceux qui ont déjà utilisé la bibliothèque Servo de l’IDE ne seront pas surpris de cette façon de faire car c’est rigoureusement la même.

Vous verrez dans les exemples donnés qu’on peut enchaîner les effets lumineux avec ou non un certain délai entre chaque pour rythmer l’animation. Vous constaterez également que la gestion de feux tricolores se fait avec une seule ligne de code, la bibliothèque se chargeant de gérer le reste.

Liste des fonctions de la bibliothèque

onAll() : allume toutes les LED d’un coup
offAll() : éteint toutes les LED d’un coup
onLeft() : allume les LED de la droite vers la gauche de l’enseigne
offLeft() : éteint les LED de la droite vers la gauche de l’enseigne
onRight() : allume les LED de la gauche vers la droite de l’enseigne
offRight() : éteint les LED de la gauche vers la droite de l’enseigne
blinkAll(N) : fait clignoter l’ensemble des LED N fois (N est un entier)
movingFlashLeft() : déplace un flash de la droite vers la gauche
movingFlashRight() : déplace un flash de la gauche vers la droite
roundTrip() : effet lumineux constitué d’une LED brillante entourée de deux LED moins brillantes, effectuant des aller-retours (nombre de LED conseillé au moins égal à six)
shiftStopLeft() : les flash se déplacent de la droite vers la gauche et s’accumulent à gauche
shiftStopRight() : les flash se déplacent de la gauche vers la droite et s’accumulent à droite
randomLightOn() : allume les LED de façon aléatoire (entrée analogique A5 sert au seed donc ne pas l’utiliser comme sortie digitale)
randomLightOff() : éteint les LED de façon aléatoire (entrée analogique A5 sert au seed donc ne pas l’utiliser comme sortie digitale)
trafficLight() : simule deux feux tricolores de carrefour routier - Le nombre de LED est forcément 6 et cette animation s’emploie seule à cause de la durée des séquences
alternatingTrafficLight() : simule deux feux de circulation alternée - Le nombre de LED est forcément 6 et cette simulation s’emploie seule à cause de la durée des séquences.

La notion de Left et Right dépend de la façon dont vous regardez votre groupe de LED ; en fait, Left suppose que les sorties sont sollicitées dans l’ordre croissant alors qu’avec Right, elles le sont dans l’ordre décroissant.

Un exemple

Le programme ci-dessous vous montre comment obtenir une enseigne de RESTAURANT comme on peut la voir dans cette vidéo :

// Enseigne_RESTAURANT_LightEffect.ino
// ------------------------------------------------------------------
/* Ce programme utilise la bibliothèque LightEffect pour reproduire 
 * l'enseigne RESTAURANT sur une carte Uno (voir vidéo dans l'article 
 * Le microcontrôleur ATtiny45 (10)). Peut être adapté pour ATtiny84.
 * ------------------------------------------------------------------
 */
 
#include <LightEffect.h>

LightEffect ensRESTO(10, 10, LOW);  // on a utilisé les sorties 10 à
// 13 et les entrées A0 à A5 comme sorties numériques sur la carte Uno

void setup() {
}

void loop() {
  ensRESTO.movingFlashRight();
  ensRESTO.movingFlashRight();
  ensRESTO.movingFlashRight();
  ensRESTO.shiftStopRight();
  ensRESTO.blinkAll(3);
  ensRESTO.offLeft();  
}

Comparez ce programme avec celui qui se trouve dans l’article Le microcontrôleur ATtiny45 (10) ; l’utilisation de la bibliothèque permet de ne plus avoir à écrire le code correspondant à chaque effet lumineux et pour un débutant, c’est plus simple. Dans ce programme, les entrées analogiques A0 à A5 ont été utilisées comme sorties numériques mais ce n’était pas forcément nécessaire (c’était juste pour montrer que cela fonctionne).

Conclusion

Même si vous débutez en Arduino, vous avez sous la main un outil qui vous permettra de créer facilement de jolies animations lumineuses pour votre réseau de trains miniatures. Alors ne vous en privez pas et bonne créativité.