DokuWiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
//Traduction de [[http://arduino.cc/en/Hacking/LibraryTutorial]]//

Ce document explique commenter créer une librairie pour arduino. Il commence par un sketch pour afficher (flashing) du code Morse et explique comment convertir ses fonctions dans une librairie (how to convert its functions into a library). Cela permet aux autres personne d'utiliser le code que vous avez écrit et de le mettre à jour facilement lorsque vous améliorez la librairie.

Pour plus d'information, référez-vous à l'API Style Guide ( http://arduino.cc/en/Reference/APIStyleGuide ) pour obtenir des informations sur les bonnes pratiques pour créer une bonne API Arduino pour votre librairie.

Commençons par un sketch qui produit du code morse simple :

<code>int pin = 13;

void setup()
{
  pinMode(pin, OUTPUT);
}

void loop()
{
  dot(); dot(); dot();
  dash(); dash(); dash();
  dot(); dot(); dot();
  delay(3000);
}

void dot()
{
  digitalWrite(pin, HIGH);
  delay(250);
  digitalWrite(pin, LOW);
  delay(250);
}

void dash()
{
  digitalWrite(pin, HIGH);
  delay(1000);
  digitalWrite(pin, LOW);
  delay(250);
}</code>

Si vous éxécutez ce code, un code SOS (un signal de détresse) sera envoyé sur le pin 13.

Le sketch a différentes parties que nous avons besoin d'amener dans notre librairie. tout d'abord, nous avons bien sûr les fonctions dot() et dash() qui procèdent au clignotement. En second, nous avons la variable ledPin que les fonctions utilisent pour déterminer que pin utiliser. Et finalement, il y a un appel à pinMode() qui initialise le pin comme sortie (output).

Commençons à transformer notre sketch en librairie !

nous avons besoin de deux fichiers dans une librairie : le fichier header (avec l'exetension .h) et le fichier source (avec l'extension .cpp). Le fichier header comporte des définitions pour la librairie : basiquement une liste de tout ce qu'elle contient; tandis que le fichier source contient le code lui-même. Appelons notre librairie « Morse », ainsi, notre header sera Morse.h. Jetons un œil à ce qui va dedans. Cela peut sembler un peu étrange de prime abord, mais cela fera davantage sens lorsque vous aurez vu le fichier source qui y est associé.

Le cœur du fichier header consiste en une ligne pour chaque fonction de la librairie, enveloppées dans une classe avec toutes les variables nécéssaires :

<code>class Morse
{
  public:
    Morse(int pin);
    void dot();
    void dash();
  private:
    int _pin;
};</code>

Une classe est simplement une collection de fonctions et de variables qui sont conservées toutes au même endroit. Ces fonctions peuvent être publiques, cela signifiant qu'elles peuvent être accédées par les utilisateurs de votre librairie, ou privées, signifiant qu'elles peuvent seulement être accédées depuis la fonction elle-même. Chaque class a une fonction spéciale appelée constructeur, qui est utilisée pour créer une instance de la classe. Chaque constructeur à le même nom que la classe, et ne dispose pas de type retour.

Quelques autres éléments sont nécéssaires dans le fichier header. L'un est l'instruction #include qui vous donne accès aux types standards et aux constantes du langage Arduino (il est automatiquement ajouté aux sketchs, mais pas aux librairies). Il ressemble à ce qui suit (et se place au-dessus de la définition de classe vue précédemment) :

<code>#include "Arduino.h"</code>

Et finalement, il est commun  d'inclure l'ensemble du fichier header dans cette condition bizarre :

<code>#ifndef Morse_h
#define Morse_h

// l'instruction #include et le code vont ici

#endif</code>

Cela évite des problèmes si quelqu'un inclue votre librairie plus d'une fois.

Enfin, vous pouvez habituellement mettre un commentaire en haut de votre librairie avec son nom, une courte description de ce qu'elle fait, qui la écrite, la date et la licence.

Regardons un fichier header complet :

<code>/*
  Morse.h - Library for flashing Morse code.
  Created by David A. Mellis, November 2, 2007.
  Released into the public domain.
*/
#ifndef Morse_h
#define Morse_h

#include "Arduino.h"

class Morse
{
  public:
    Morse(int pin);
    void dot();
    void dash();
  private:
    int _pin;
};

#endif</code>

Maintenant, regardons les différentes parties de notre fichier source, Morse.cpp.

Tout d'abord, deux instructions #include. Celles-ci donnent à votre code l'accès aux fonctions Arduino standards, et à la définition de votre fichier header :

<code>#include "Arduino.h"
#include "Morse.h"</code>

Ensuite vient le constructeur. À nouveau, cela explique ce qui devrait advenir lorsque quelqu'un créé une instance de votre classe. Dans ce cas-ci, l'utilisateur spécifie quel pin il veut utiliser. On configure ce pin comme sortie et on sauve cela dans une variable private pour l'utiliser dans d'autres fonctions :

<code>Morse::Morse(int pin)
{
  pinMode(pin, OUTPUT);
  _pin = pin;
}</code>

Il y a plusieurs choses étranges dans ce code. Premièrement le Morse:: devant le nom de la fonction. cela indique que la fonction fait partie de la class Morse. Vous verrez cela à nouveau pour les autres fonctions de la classe. La seconde chose inhabituelle et l'underscore sous le nom de la variable privée _pin. Cette variable peut en réalité avoir n'importe quel nom que vous souhaiteriez lui donner, tant qu'elle correspond à la définition dans le fichier header. Ajouter un underscore à son début est simplement une convention pour expliciter quelles sont les variables privées, et aussi pour distinguer les noms des arguments des fonctions (pin dans ce cas).

Ensuite arrive le code lui-même, du sketch que nous transformons (enfin!) en librairie. Il est quasiment identique, hormis les préfixes Morse:: devant les noms des fonctions, et _pin au lieu de pin :

<code>void Morse::dot()
{
  digitalWrite(_pin, HIGH);
  delay(250);
  digitalWrite(_pin, LOW);
  delay(250);  
}

void Morse::dash()
{
  digitalWrite(_pin, HIGH);
  delay(1000);
  digitalWrite(_pin, LOW);
  delay(250);
}</code>

Pour finir il est commun d'inclure un bloc commentaire en haut du fichier, comme dans le fichier header. Regardons l'ensemble final :

<code>/*
  Morse.cpp - Library for flashing Morse code.
  Created by David A. Mellis, November 2, 2007.
  Released into the public domain.
*/

#include "Arduino.h"
#include "Morse.h"

Morse::Morse(int pin)
{
  pinMode(pin, OUTPUT);
  _pin = pin;
}

void Morse::dot()
{
  digitalWrite(_pin, HIGH);
  delay(250);
  digitalWrite(_pin, LOW);
  delay(250);  
}

void Morse::dash()
{
  digitalWrite(_pin, HIGH);
  delay(1000);
  digitalWrite(_pin, LOW);
  delay(250);
}</code>

C'est tout ce dont vous avez besoin (il existe quelques éléments optionnels intéressants, mais nous en parlerons plus tard). Regardons comment utiliser votre librairie.

D'abord, créez un répertoire Morse dans le sous-dossier libraries de votre dossier sketchbook. Copiez ou déplacer Morse.h et Morse.cpp dans ce répertoire. Maintenant démarrez l'environnement Arduino. Si vous ouvrez le menu Croquis -> Importer bibliothèque, vous devriez voir Morse à l'intérieur. La librairie sera compilée avec le sketch qui l'utilise. Si la librairie ne semble pas se compiler, soyez sûrs que les fichiers finissent bien par .h et .cpp (sans suffixe .pde ou .txt par exemple).

Regardons comment répliquer notre premier sketch en utilisant notre nouvelle librairie :

<code>#include <Morse.h>

Morse morse(13);

void setup()
{
}

void loop()
{
  morse.dot(); morse.dot(); morse.dot();
  morse.dash(); morse.dash(); morse.dash();
  morse.dot(); morse.dot(); morse.dot();
  delay(3000);
}</code>

Il y a quelques différences avec le sketch d'origine (hormis le fait qu'une partie du code a été déplacé dans une librairie).

D'abord, on a ajouté une instruction #include en haut du sketch. Cela permet de rendre lal librairie Morse disponible dans le sketch et l'inclue dans le code envoyé à la board. Cela signifie que si vous n'avez plus besoin d'une librairie à un moment ou un autre, vous devriez effacer l'instruction #include afin d'économiser la mémoire.

ensuite, nous créons une instance de la classe Morse appelée morse :

<code>Morse morse(13);</code>

Lorsque cette ligne est exécutée (ce qui en réalité est fait avant le fonction setup()), le constructeur de la classe Morse est appelé, et l'argument passé (ici 13).

Notez que notre setup est maintenant vide; c'est parce que l'appel à pinMode() est fait dans la librairie (lorsque le constructeur est exécuté).

Enfin, pour appeler les fonctions dot() et dash(), nous avons besoin de les préfixer avec morse –le nom de l'instance que nous souhaitons utiliser–. Nous pourrions avoir plusieurs instances de la classe morse, chacune sur leur propre pin stocké dans la variable privée _pin. En appelant ces fonctions sur une instance particulière, nous spécifions la variable de quelle instance doit être utilisée durant l'appel de la fonction. Par exemple, si nous avions :

<code>Morse morse(13);
Morse morse2(12);</code>

Lors d'un appel a morse2.dot(), _pin serait ainsi égal à 12.

Si vous avez essayé un nouveau sketch, vous avec probablement noté que rien de notre librairie n'était reconnu par l'environnement Arduino et que celui-ci ne produisait aucune coloration syntaxique. Malheureusement, Arduino ne peut automatiquement déduire ce que vous avez défini dans votre librairie (quoique cela aurait été une fonctionnalité intéressante), vous devez pour cela lui donner un petit coup de main. Pour cela créez une fichier appelé keywords.txt dans le dossier Morse. Il doit ressembler à ceci :

Morse   KEYWORD1
dash    KEYWORD2
dot     KEYWORD2

Chaque ligne est le nom, suivi par un TAB (pas d'espace), suivi par le type de mot-clé. Les classes devraient être indiquées comme KEYWORD1 et colorées en orange; les fonctions devraient être KEYBOARD2 et sont marrons. Vous devrez redémarrer l'environnement Arduino pour lui permettre de reconnaître les nouveaux mots-clés.

Il est aussi intéressant de fournir aux utilisateurs des sketch d'exemples utilisant votre librairie. Pour cela, créez un dossier exemples dans le dossier Morse. Copiez alors, ou déplacez le dossier contenant notre sketch SOS écrit plus haut dans ledit dossier. (Vous pouvez le retrouver en utilisant le menu Croquis -> Afficher un fichier). Si vous redémarrez Arduino (cette fois c'est la dernière, promis!), vous verrez une entrée Library-Morse dans le menu Fichier-> exemples et contenant votre exemple. Il peut être nécessaire d'ajouter quelques commentaires pour mieux expliquer comment utiliser votre librairie.

Si vous souhaitez regarder la librairie en entier (avec les mots-clés et exemples), vous pouvez la télécharger ici : http://arduino.cc/en/uploads/Hacking/Morse.zip

C'est tout pour le moment mais j'écrirais probablement un tutoriel avancé sur le développement de librairies bientôt. En attendant, si vous rencontrez un problème ou si vous avez une suggestion, merci des les poster sur le forum développement : http://www.arduino.cc/cgi-bin/yabb2/YaBB.pl?board=dev

Pour plus d'informations, référez-vous à l'API Style Guide ( http://arduino.cc/en/Reference/APIStyleGuide ) pour des information sur comment produire une bonne API pour votre librairie.