Téléchargement de la bibliothèque CmdrArduino

On commence par récupérer le dossier de cette bibliothèque à cette adresse :
https://github.com/Railstars/CmdrAr...

Le dossier contient les éléments suivants :

Attention, sur Mac, on prendra soin de renommer le dossier "CmdrArduino-master" en supprimant l’extension "-master", sinon l’environnement de programmation Arduino refusera d’installer la bibliothèque à cause du signe "-".

Installation de la bibliothèque CmdrArduino

Les détails d’installation d’une bibliothèque sont décrits sur le site Arduino et aussi dans l’article Installation de l’IDE Arduino.

Pour mémoire, il suffit de sélectionner le dossier CmdrArduino dans le menu Croquis/Importer Bibliothèque/ajouter Bibliothèque (mais pas le fichier CmdrArduino-master.zip téléchargé).

Initialisation de la bibliothèque CmdrArduino

Pour avoir accès aux fonctions de la bibliothèque,

1) il faut placer les 3 fichiers d’entête (.h) en début de programme :

// LIBRAIRIE CMDRARDUINO
#include <DCCPacket.h> // types et données utilisées
#include <DCCPacketQueue.h> // cuisine interne
#include <DCCPacketScheduler.h> // fonctions pour notre programme

2) il faut déclarer une variable globale qui sera manipulée par la librairie

// DCC handler
DCCPacketScheduler dps; // structure de donnée pour la bibliothèque

3) il faut placer la fonction d’initialisation dans la fonction setup()

 
// init CmdrArduino
  dps.setup(); // initialise les Pins 9 et 10

Cette fonction va programmer les broches 9 et 10 d’un Arduino Uno, Nano, Mini ou les broches 11 et 12 d’un Arduino Mega 2560 (je complèterai dès que j’aurai testé la librairie sur Arduino Due), ces broches OC1A et OC1B étant différents sur les processeurs 328 et 2560. Elles sont toutes les deux associées au Timer 1, le plus précis (16 bits).

Il n’est donc pas nécessaire de les déclarer par des instructions de ce type :

pinMode(PinXX, OUTPUT);

D’autre part, seule la broche 9 (328) ou 11 (2560) est utilisée pour générer le signal DCC, mais l’autre broche (10/328 ou 12/2560) étant connectée au Timer 1, est inutilisable pour autre chose.

4) il faut placer la fonction d’actualisation des données de la bibliothèque dans la fonction loop()

 // Execution CmdrArduino à chaque LOOP
  dps.update();

Cette fonction doit être appelée le plus souvent possible pour permettre au code de la bibliothèque de mettre à jour ses données internes, notamment la gestion de la file des paquets à émettre sous interruption, la répétition des paquets, c’est à dire toutes les 5 à 10 milli-secondes environ.

Il est donc important de ne pas gaspiller le temps dans la fonction loop();

Quelles sont les fonctions proposées par la bibliothèque CmdrArduino ?

Les fonctions qui nous intéressent sont déclarées seulement dans le fichier DCCPacketScheduler.h, dont en particulier :

• la fonction d’initialisation
  void setup(void);
• la fonction de rafraichissement
  void update(void);

1) Commande de vitesse 14, 28 ou 128 pas

Dans la pratique, on n’utilisera qu’une seule des 3 fonctions suivantes, selon que les locos seront programmées en 14 ou 28 (par défaut sur les décodeurs neufs) ou 128 pas de vitesse.

bool setSpeed14(uint16_t address, uint8_t address_kind, int8_t new_speed, bool F0=true); //new_speed: [-13,13], and optionally F0 settings.

bool setSpeed28(uint16_t address, uint8_t address_kind, int8_t new_speed); //new_speed: [-28,28]

bool setSpeed128(uint16_t address, uint8_t address_kind, int8_t new_speed); //new_speed: [-127,127]

Les paramètres de chaque fonction sont :

• address : l’adresse DCC de la loco
• address_kind : le type d’adresse DCC_SHORT_ADDRESS ou DCC_LONG_ADDRESS
• new_speed : la vitesse, en sachant que :
  • la valeur 0 sera interprétée comme un arrêt immédiat (arrêt du moteur)
  • la valeur 1 sera interprétée comme un arrêt normal (avec inertie)
  • les vitesses négatives sont pour la marche avant et les vitesses positives pour la marche arrière
• F0 dans le seul cas de setSpeed14 pour commander l’éclairage en même temps que la vitesse : true ou false.

bool eStop(void);

Cette fonction commandera un arrêt immédiat de tous les trains.

bool eStop(uint16_t address, uint8_t address_kind);

Cette fonction commandera un arrêt immédiat d’un seul train, désigné par son adresse DCC. Elle fait donc double emploi avec les commandes de vitesse ci-dessus.

2) Commandes des fonctions des locos

On a 3 fonctions différentes pour traiter les fonctions locos 0 (FL, éclairage) à 4, 5 à 8 et 9 à 12. On se reportera à la notice du décodeur pour savoir si les fonctions existent et à quoi elles correspondent.

Les paramètres de chaque fonction sont :

• address : l’adresse DCC de la loco
• address_kind : le type d’adresse DCC_SHORT_ADDRESS ou DCC_LONG_ADDRESS
• functions : les valeurs des fonction (1 active, 0 inactive), chacune étant codée sur un bit situé dans les bits de poids faible de l’octet functions qui doit prendre la forme binaire 000SDDDD.

bool setFunctions0to4(uint16_t address, uint8_t address_kind, uint8_t functions);

Cette command permet d’actionner 5 fonctions (fonctions FL and F1 à F4) du groupe 1 de la norme NMRA [1].

Les bits 0-3 (DDDD) définissent les fonctions F1-F4 où la fonction F1 est commandée par le bit 0 et la fonction F4 par le bit 3. Une valeur "1" indique que la fonction est "en service" tandis que "0" indique qu’elle est "hors service".
Si le bit 1 du CV29 a pour valeur "1" (en général il l’est par défaut), alors le bit 4 (S) commande la fonction FL (lumière), sinon il est ignoré par le décodeur.

Les deux instructions suivantes permettent de commander jusqu’à 8 functions auxiliaires (F5-F12) dites "Function du Groupe 2" [2].

bool setFunctions5to8(uint16_t address, uint8_t address_kind, uint8_t functions);

Les bits 0-3 (DDDD) de l’octet functions définissent les functions F5-F8 : F5 correspond au bit 0 et F8 correspond au bit 3. Une valeur "1" indique que la fonction est "en service" tandis que "0" indique qu’elle est "hors service".

bool setFunctions9to12(uint16_t address, uint8_t address_kind, uint8_t functions);

Les bits 0-3 (DDDD) de l’octet functions définissent les functions F9-F12 : F9 correspond au bit 0 et F12 correspond au bit 3. Une valeur "1" indique que la fonction est "en service" tandis que "0" indique qu’elle est "hors service".

3) Commandes d’accessoires

Activation
bool setBasicAccessory(uint16_t address, uint8_t function);

Désactivation
bool unsetBasicAccessory(uint16_t address, uint8_t function);

Les paramètres de ces fonctions sont :

• address : l’adresse DCC de l’accessoire.
• function : les valeurs de la commande d’accessoire. On se reportera bien évidemment à la notice du décodeur d’accessoire visé, celui-ci permettant de piloter plusieurs organes en même temps (aiguilles, feux, etc..).

4) Commande de programmation de CV

bool opsProgramCV(uint16_t address, uint8_t address_kind, uint16_t CV, uint8_t CV_data);

Les paramètres de cette fonction sont :

• address : l’adresse DCC de la loco
• address_kind : le type d’adresse DCC_SHORT_ADDRESS ou DCC_LONG_ADDRESS
• CV : le numéro de CV
• CV_data : la valeurs du CV.

Conclusion

Cette bibliothèque permet de piloter les fonctions principales de la norme DCC, mais elle n’est pas exhaustive. La norme DCC est complexe et couvre de nombreuses situations. Les constructeurs de décodeurs de locos et d’accessoires adaptent cette norme à leurs produits : il faut donc consulter la documentation soigneusement.

Lors de la mise au point d’un projet de modélisme ferroviaire basé sur cette bibliothèque (ou une autre), il est hautement recommandé de visualiser ce qui se passe en sortie de la centrale pour vérifier que ce qui sort correspond à ce qu’on espère.

Il existe une autre bibliothèque Arduino qui permet de décoder les paquets DCC : Il s’agit de DCC_Decoder qui se trouve ici [3] : DCC_Decoder

Une série d’article lui est consacré, décrivant un décodeur d’accessoire universel « Un décodeur d’accessoires universel (1) » et « Un décodeur d’accessoires universel (2) ». Un autre à venir, DCC Monitor permettra de voir les paquets DCC qui circulent sur les rails.