Arduino : Hacking / Library Tutorial

http://arduino.cc/es/Hacking/LibraryTutorial?action=print

Arduino : Hacking / Library Tutorial

Learning Examples | Foundations | Hacking | Links

Escribir una librera para Arduino Este documento explica cmo crear una librera para Arduino. Se inicia con un programa de cdigo Morse y explica cmo convertir sus funciones en una librera. Esto permite que otras personas usen el cdigo que has escrito y puedan actualizarlo facilmente a medida que mejora la librera. Comenzamos con un programa de cdigo Morse: int pin = 13; void setup() { pinMode(pin, OUTPUT); } void loop() { punto(); punto(); punto(); raya(); raya(); raya(); punto(); punto(); punto(); delay(3000); } void punto() { digitalWrite(pin, HIGH); delay(250); digitalWrite(pin, LOW); delay(250); } void raya() { digitalWrite(pin, HIGH); delay(1000); digitalWrite(pin, LOW); delay(250); } Si ejecuta este programa, se representar el cdigo de SOS (llamada de auxilio) en el pin 13. El programa tiene unas pocas partes que tendremos que poner en nuestra librera. En primer lugar, tenemos las funciones punto() y raya() que hacen el parpadeo. En segundo lugar, tenemos la variable ledPin que indica el pin a utilizar. Por ltimo, est la llamada a pinMod () que inicializa el pin como salida. Vamos a empezar a convertir el programa en una librera! Para una librera necesita al menos dos arcivos: un archivo de cabecera (w / con extensin. H) y el cdigo fuente (w / extensin. cpp). El archivo de cabecera contiene definiciones para la librera: bsicamente un listado de todo lo que hay dentro, mientras que el archivo del cdigo fuente tiene el cdigo real. Vamos a llamar a nuestra librera "Morse", por lo que nuestro archivo de cabecera ser Morse.h. Echemos un vistazo a lo que contiene. Puede parecer un poco extrao al principio, pero tendr ms sentido una vez que vea el cdigo fuente que lo acompaa. El archivo de cabecera consiste bsicamente en una clase con una lnea para cada funcin de la librera, junto con las variables que se van a usar: class Morse {

1 of 5

24/05/2012 16:24

Arduino : Hacking / Library Tutorial

http://arduino.cc/es/Hacking/LibraryTutorial?action=print

public: Morse(int pin); void punto(); void raya(); private: int _pin; }; Una clase es simplemente una coleccin de funciones y variables agrupadas en un mismo lugar. Estas funciones y variables pueden ser pblicas, lo que significa que las podrn usar las personas que estn utilizando la librera, o privada, lo que significa que slo se puede acceder a ellas desde la propia clase. Cada clase tiene una funcin especial conocida como constructor, que se utiliza para crear una instancia de la clase (o sea, un objeto). El constructor tiene el mismo nombre que la clase, y no devuelve nada. Se necesitan un par cosas ms en el archivo de encabezado. Una de ellas es una instruccin # include que da acceso a los tipos estndar y las constantes del lenguaje Arduino (esto se agrega automticamente a los programas normales, pero no a las libreras). Se parece a esto (y se coloca antes de la definicin de la clase mostrada anteriormente): 1. Include "WProgram.h" Por ltimo, es comn aadir las siguientes lineas de cdigo : 1. Ifndef Morse_h 2. Define Morse_h // La declaracin # include y el cdigo van aqu ... 1. endif Bsicamente, esto evita problemas si alguien accidentalmente usa dos veces el #include con la librera que estamos construyendo, evitando que se declaren las variables y funciones ms de una vez. Por ltimo, se suele poner un comentario en la parte superior de la librera con su nombre, una breve descripcin de lo que hace, quin lo escribi, la fecha y el tipo de licencia. Echemos un vistazo a la cabecera completa: /* Morse.h - Library for flashing Morse code. Created by David A. Mellis, November 2, 2007. Released into the public domain. / 1. ifndef Morse_h 2. define Morse_h 3. include "WProgram.h" class Morse { public: Morse(int pin); void punto(); void raya(); private: int _pin; }; 1. endif

2 of 5

24/05/2012 16:24

Arduino : Hacking / Library Tutorial

http://arduino.cc/es/Hacking/LibraryTutorial?action=print

Vamos a repasar las distintas partes del cdigo fuente de Morse.cpp. Lo primero son un par de # include. Con esto el resto del cdigo tendr acceso a las funciones estndar de Arduino, y a las definiciones definidas en Morse.h: 1. Include "WProgram.h" 2. Include "Morse.h" A continuacin viene el constructor. Una vez ms, en el constructor se establece lo que debe ocurrir cuando alguien crea una instancia de la clase. En este caso, el usuario especifica el pin que le gustara utilizar. Configuramos el pin como salida en una variable privada para su uso en las otras funciones: MORSE:: Morse (pin int) ( pinMode (pin, OUTPUT); _pin = pin; )

Hay un par de cosas extraas en este cdigo. La primera es el Morse:: antes del nombre de la funcin. Esto indica que la funcin es parte de la clase Morse. Vers esto en otras funciones de la clase. Lo segundo es el subrayado en el nombre de nuestra variable privada, _pin. Esta variable puede tener cualquier nombre, siempre y cuando coincida con la definicin que figura en el archivo de encabezado. Agregar un subrayado al inicio del nombre es una convencin comn para dejar claro que las variables son privadas, y tambin para diferenciarlas del argumento de la funcin (el pin en este caso). Despus viene el cdigo del programa que estamos convirtiendo en una librera (por fin!). Se ve ms o menos lo mismo, salvo Morse:: delante de los nombres de las funciones, y en lugar de _pin pin: void Morse::punto() { digitalWrite(_pin, HIGH); delay(250); digitalWrite(_pin, LOW); delay(250); } void Morse::raya() { digitalWrite(_pin, HIGH); delay(1000); digitalWrite(_pin, LOW); delay(250); } Por ltimo, es tpico incluir un comentario en la parte superior del cdigo fuente. Vamos a ver el cdigo: /* Morse.cpp - Library for flashing Morse code. Created by David A. Mellis, November 2, 2007. Released into the public domain. / 1. include "WProgram.h" 2. include "Morse.h" Morse::Morse(int pin) { pinMode(pin, OUTPUT); _pin = pin; } void Morse::punto() { digitalWrite(_pin, HIGH);

3 of 5

24/05/2012 16:24

Arduino : Hacking / Library Tutorial

http://arduino.cc/es/Hacking/LibraryTutorial?action=print

delay(250); digitalWrite(_pin, LOW); delay(250); } void Morse::raya() { digitalWrite(_pin, HIGH); delay(1000); digitalWrite(_pin, LOW); delay(250); } Y eso es todo lo que necesita (hay algunas otras cosas opcionales, pero hablaremos de eso ms adelante). Vamos a ver cmo usar la librera. En primer lugar, hay que crear el directorio Morse dentro del subdirectorio de libreras . Copia o mueve los archivos Morse.h y Morse.cpp a ese directorio. Ahora ejecuta el IDE de Arduino. Si vas al men Sketch > Import Library deberas ver el una opcin Morse. La librera ser compilada con los programas que la utilizan. Si no aparece la librera, asegrate de que los nombres de los archivos terminan realmente ten .cpp y .h (y no en .pde o .txt, por ejemplo). Vamos a ver cmo podemos modificar nuestro programa de SOS para hacer uso de la nueva librera: 1. include <Morse.h> Morse morse(13); void setup() { } void loop() { morse.punto(); morse.punto(); morse.punto(); morse.raya(); morse.raya(); morse.raya(); morse.punto(); morse.punto(); morse.punto(); delay(3000); } Hay algunas diferencias con el programa original (aparte del hecho de que parte del cdigo se ha trasladado a la librera). En primer lugar, hemos aadido una declaracin # include al principio del programa. Esto hace que la librera Morse est disponible para el programa y que se enve a la placa de Arduino. Cuando ya no necesite una librera en un programa, debe eliminar la sentencia # include para ahorrar espacio. En segundo lugar, creamos una instancia de la clase Morse llamada morse: Morse morse(13); Cuando esta lnea se ejecute ( esto sucede incluso antes de que se ejecute la funcin setup () ), se llamar al constructor de la clase Morse, y se le pasar un parmetro (en este caso, el valor 13). Tenga en cuenta que nuestro setup() est vaco, esto se debe a que la llamada a pinMode () se produce dentro de la librera (cuando se construye la instancia). Por ltimo, para llamar a las funciones punto() y raya(), tenemos que precederlas del prefijo morse (que es el nombre de la instancia que hemos creado). Podramos tener varias instancias de la clase Morse, cada una con su propio PIN almacenado en la variable privada _pin de esa instancia. Al llamar a una funcin se indica que instancia de la clase se debe utilizar. Es decir, si tuviramos: Morse morse (13); Morse morse2 (12);

4 of 5

24/05/2012 16:24

Arduino : Hacking / Library Tutorial

http://arduino.cc/es/Hacking/LibraryTutorial?action=print

la llamada a morse2.dot (), hace que la salida sea por el pin 12. Si pruebas el nuevo programa, probablemente te dars cuenta de que el IDE de Arduino no reconoce las funciones de la librera y no resalta el cdigo. Por desgracia, por ahora el software de Arduino no puede averiguar lo que hay definido en la librera (aunque sera una buena caracterstica a tener en cuenta), as que tienes que ayudarle un poco. Para ello, crea un archivo llamado keywords.txt en el directorio de Morse.. Que debe tener este aspecto: Morse KEYWORD1 raya KEYWORD2 punto KEYWORD2 Cada lnea tiene el nombre de la palabra clave, seguido de un tabulador (no espacios), seguido por el tipo de palabra clave. Las clases deben ser del tipo KEYWORD1 y se muestran de color naranja; las funciones deben ser del tipo KEYWORD2 y sern de color marrn. Tendr que reiniciar el entorno Arduino para conseguir que reconozca las nuevas palabras clave. Es conveniente acompaar las libreras con algn programa de ejemplo que haga uso las mismas. Para ello, cree un directorio examples dentro del directorio Morse. A continuacin, copie el directorio que contiene el programa de ejemplo que escribimos arriba (lo llamaremos SOS) en el directorio de ejemplos. (Puedes encontrar el programa de ejemplo con la opcin Sketch > Show Sketch Folder) Si reinicias el entorno Arduino (esta es la ltima vez, lo prometo) vers la opcin Library-Morse dentro de File > Sketchbook > Examples que contiene su ejemplo. Es posible que quieras agregar algunos comentarios para explicar mejor cmo usar la librera. Si quieres echa un vistazo a la librera completa (con palabras clave y el ejemplo), puede descargarlo: Morse.zip. Eso es todo por ahora, pero probablemente voy a escribir una coleccin de tutoriales avanzados pronto. Mientras tanto, si tienes cualquier problema o sugerencia, por favor escribe en el foro de desarrollo de software.
(Printable View of http://arduino.cc/es/Hacking/LibraryTutorial)

5 of 5

24/05/2012 16:24