Librería Arduino: como crear una librería propia

Una de las cosas más útiles que podemos aprender cuando comenzamos a experimentar es a crear una librería Arduino. Muchos de ustedes ya habrán comenzado a experimentar con librerías de otros para hacer andar módulos o Shields, pero poder crear nuestras propias librerías es un recurso que nos permitirá ampliar notablemente nuestra capacidad de programar Arduino, ya que nos permitirá compartir código entre distintos proyectos de manera simple y organizada.

¿Qué es una librería Arduino?

Una librería Arduino es una colección de archivos dispuestos de una manera específica que nos permite agregar fácilmente funcionalidad común a nuestros proyectos sin tener que escribir código repetido cada vez que queremos hacer algo. Un ejemplo es el caso de funciones muy comunes (de eso tratará el ejemplo que les dejaré), o si usted escribe código propio para hacer andar un componente, módulo o Shield, tal vez quiera poner su código en una librería para luego usarlo en otros proyectos que integren el mismo componente.

¿Qué debería poner en librerías?

Mi recomendación es siempre poner en librerías todo código que crear que podrá reutilizar en el futuro. Por supuesto que esto implica que cuando escriba ese código deberá pensar en como debería ser el programa para que pueda usarse en cualqueir lado… Y esto producirá algunos cambios en la manera en que usted programa su código. A continuación enumeraremos algunas recomendaciones pero primero quiero comenzar un ejemplo práctico que podamos ir desarrollando para facilitar el aprendizaje.

Números BCD

En este caso les dejaré 2 funciones que son muy utiles y a la vez es una librería que luego integraré cuando les presente un módulo nuevo que requiere trabajar con BCD. BCD significa Binario Codificado en Decimal, y es una manera muy específica de escribir o codificar números en programación.

Para dar un ejemplo imagínese el número 15 (decimal). Para convertirlo en BCD separamos sus dígitos por lo que tenemos 1 y 5. En binario 1 = 1, y 5 = 101. Ahora como cada dígito debe poder almacenar números del 0 al 9, y para el 9 el binario es 1001, entonces necesitamos 4 dígitos binarios, por lo que BCD se codifica usando SIEMPRE 4 dígitos binarios para cada dígito decimal, asi entonces el 1 = 0001, y el 5 = 0101, entonces el 15 sería 00010101 que si lo convertimos a decimal es 21 por lo que 15 en BCD es 21.

Componentes de la librería Arduino

El archivo .h o header

El header (cabecera) o archivo .h, es el archivo que representará a la librería cuando la integremos a otros trabajos en el futuro. En él se colocan declaraciones, pero no el código en si mismo. En nuestro caso el archivo se llamará bcdlib.h y se vé así:

/*
 * Libreria para convertir numeros de decimal a BCD y viceversa. La libreria
 * esta escrita en C++ en una clase con metodos estaticos para una simple 
 * utilizacion. Las funciones poseen una limitacion de 2 digitos decimales.
 * 
 * Autor: <Ponga su nombre aqui>
 * 
 * Versiones: 
 *   
 * v0.0.1 - Jun 7, 2017 - Versión inicial
 *
 */

#ifndef bcdlib_h
#define bcdlib_h

#include "Arduino.h"
class bcdlib {
    
public:
    static byte bcd2dec(byte data);
    static byte dec2bcd(byte data);
    
};

#endif

No se olvide que usted es quien está escribiendo la librería asi que ponga su nombre como autor del codigo que está escribiendo.

Archivo principal .cpp

Usualmente a todo archivo de cabecera .h lo acompaña un archivo de código que puede tener la extención .c o .cpp. Es una buena práctica tener un archivo con el mismo nombre que la cabecera y por lo tanto el nuestro se llamará bcdlib.cpp, y su código se verá asi:

/*
 * Libreria para convertir numeros de decimal a BCD y viceversa. La libreria
 * esta escrita en C++ en una clase con metodos estaticos para una simple 
 * utilizacion. Las funciones poseen una limitacion de 2 digitos decimales.
 * 
 * Autor: <Ponga su nombre aqui>
 *
 * Version: ver bcdlib.h
 * 
 */
#include "bcdlib.h"

/*
 * Metodo/funcion para convertir numeros BCD de 2 digitos a decimal
 * 
 * La forma de usar este metodo es la siguiente:
 * 
 * numero_decimal = bcdlib::bcd2dec(numero_bcd);
 * 
 */
byte bcdlib::bcd2dec(byte data) {
    return (data/16*10)+(data%16);
}

/*
 * Metodo/funcion para convertir numeros decimales de 2 digitos a BCD
 * 
 * La forma de usar este metodo es la siguiente:
 * 
 * numero_bcd = bcdlib::bcd2dec(numero_decimal);
 * 
 */
byte bcdlib::dec2bcd(byte data) {
    return (data/10*16)+(data%10);
}

Otros archivos comunes en las librerias

Es usual junto con cada libreria ver los siguientes achivos:

LICENSE – Es un archivo que tiene una copia de la licencia con la que se entrega la librería Arduino. Es una buena práctica compartir nuestro trabajo bajo el ampado de alguna licencia conocida. Yo lo hago bajo la licencia del MIT.

README.md – Es un archivo muy comun usado por repositorios de codigo abierto como GitHub. Se usa para compartir una breve descripción de la librería o código que se está compartiendo y cualquier otra información adicional al proyecto.

keywords.txt – Es un archivo secundario que usa el Arduino IDE para reconocer nuestro código cuando integramos la librería en otro trabajo.

examples/ – Es un directorio que Arduino IDE leerá y agregará ejemplos ahi dentro como ejemplos disponibles mediante el menu del IDE.

Compartiendo la librería Arduino con otras personas

La mejor manera de compartir la librería con otras personas es en un archivo empaquetado o comprimido .zip.

Probando la Librería

Para probar la librería debe importarla en su Arduino IDE, y luego puede usar el siguiente código de ejemplo:

// Importamos la libreria primero de todo
#include <bcdlib.h>

void setup() {
  // Inicializamos el Monitor Serial para mostrar resultados de las pruebas
  Serial.begin(9600);
  Serial.println("Ingrese un numero de 0 a 255");
}

void loop() {
  // Uso la clase base String para facilitar el codigo
  String texto;
  byte bcd, dec;
  
  // Espero que ingresen un numero
  if (Serial.available() > 0) { 
    texto = Serial.readString();
  
    // Si el numero está entre 0 y 99 procedo
    if ((byte)texto.toInt() >= 0 && (byte)texto.toInt() <= 99) {
      // Muestro el numero leido  
      Serial.print(String("Numero leido: ") + texto + ", en HEX: 0x");
      Serial.println(texto.toInt(), HEX);
      
      // Convierto el numero a BCD y lo muestro
      bcd = bcdlib::dec2bcd((byte)texto.toInt());
      Serial.println(String("Convertido a BCD: ") + bcd + " o 0x");
      Serial.println(bcd, HEX);
      
      // Convierto el numero BCD de regreso a decimal y lo muestro
      dec = bcdlib::bcd2dec(bcd);
      Serial.println(String("Convertido de regreso a decimal: ") + dec);
      
      // Permito intentar nuevamente 
      Serial.println();
      Serial.println("Ingrese un numero de 0 a 255");
    }
  }
}

Deja un comentario