Controlar tu arduino desde la PC mediante comandos de texto

En muchas ocasiones durante el desarrollo de proyectos con arduino te habrás topado con la necesidad de controlar tu arduino desde la PC. Ya sea desde una aplicación realizada a la medida o simplemente desde el monitor serial de arduino. Por ejemplo podemos realizar acciones tan sencillas como encender un led y llegar a cosas más complejas como cambiar la dirección IP de nuestro ethernet shield sin necesidad de reprogramar el sketch o cambiar los parámetros de un algoritmo de control en tiempo de ejecución, etc.

Existen varios enfoques para controlar tu arduino desde la PC, sin embargo en esta entrada presentamos un método que permite la mayor flexibilidad desde nuestro punto de vista. Te presentamos una librería que  hemos desarrollado y que nos permite emular la experiencia de la “consola” o “terminal” de un sistema operativo en un PC de escritorio, pero esta vez ejecutandose dentro de cualquier microcontrolador que disponga de un compilador de C. Esto permite cambiar parámetros, solicitar la ejecución de programas (funciones) y cambiar configuraciones y parámetros del programa mientras este se ejecuta. Para comprobar y entender el funcionamiento básico de esta librería controlaremos un led RGB desde el puerto serie de la PC.

En la foto de portada vemos el circuito de prueba de un led RGB conectado al arduino. Podemos controlar arduino desde la PC mediante comandos de texto y cambiar el color mostrado en el LED RGB a voluntad.

Conceptos básicos

Un LED RGB es un dispositivo que en un solo encapsulado contiene 3 diodos emisores de luz. Cada uno de estos emisores de luz corresponde a uno de los colores básicos (Rojo, Verde y Azul). Por lo que podemos representar prácticamente todos los colores conocidos.

Este tipo de led se encuentran en varias configuraciones. Nosotros vamos a requerir un led RGB con cátodo común, es decir que la tierra o negativo de cada led esta conectado a un único pin. Por lo tanto debemos aplicar un voltaje positivo a cada uno de los otros pines para encender cada led individual. Existe la configuración opuesta, en la que el ánodo es común y por lo tanto debemos conectar a tierra los otros pines para encender cada diodo.

La librería “shell” para arduino

Esta librería permite controlar nuestros programas y dispositivos con simples comandos de texto de manera similar a la terminal en Mac OSX o linux y la linea de comandos de Windows. Los comandos pueden transmitirse al microcontrolador mediante un puerto serie, un socket TCP/IP o una conexión USB CDC.

La librería puede descargarse desde github en el enlace que se muestra a continuación. Si deseas saber como se realiza la instalación de una librería de arduino puedes consultar este otro tutoríal.

Descarga de la librería Shell

Uso de la librería “Shell” para controlar tu arduino desde la PC

Para utilizar la librería debemos llamar al principio de nuestro programa o sketch a la función de inicialización shell_init() que le dice a la librería que funciones debe usar para leer y escribir sobre el medio (serial, TCP/IP, etc.) Estas funciones deben ser provistas por el usuario (programador). En el caso de arduino, creamos unas funciones (wrappers ) que “envuelven” a los métodos write() y read() de la clase Serial y simplemente redirigen los datos desde y hacia nuestra librería. El ultimo parámetro (nulo o 0 en este caso) permite definir un mensaje personalizado de bienvenida, que aparece al principio de la terminal, antes de que se solicite cualquier comando.

1 2 3 4

// Initialize command line interface (CLI) // We pass the function pointers to the read and write functions that we implement below // We can also pass a char pointer to display a custom start message shell_init(shell_reader, shell_writer, 0);

Luego, el usuario debe asociar los comandos y las funciones, es decir, indicamos una cadena que al recibirse en el puerto serie causará que la librería invoque a la función correspondiente. Esto se hace llamando a la función shell_register() que acepta por una parte un apuntador a función y la cadena correspondiente al comando. Se hace de la siguiente forma:

1 2 3

// Add commands to the shell shell_register(command_mycommand, "mycommand"); shell_register(command_othercommand, "othercommand");

Finalmente, dentro del ciclo principal de cada aplicación, el programador debe asegurarse de llamar a la función shell_task(), ya que dentro de esta se procesan los caracteres recibidos y es la encargada de ejecutar las funciones que asociamos a cada cadena.

1 2	// This should always be called to process user input shell_task();

Los programas (funciones) que implementan cada uno de los comandos se deben escribir con el prototipo estándar de C para una utilidad de linea de comandos y reciben los parámetros para realizar su función de manera análoga. Por ejemplo esta es la función que ejecutaríamos al escribir “mycommand” y presionar la tecla enter:

1 2 3 4 5 6

int command_mycommand(int argc, char** argv) {   shell_println("Running \"mycommand\" now");   shell_println("Exit...");   return SHELL_RET_SUCCESS; }

Como podemos ver la función solamente imprime la cadena “Ejecutando mycommand” y luego retorna, sin embargo, podemos crear funciones que afecten prácticamente cualquier aspecto del funcionamiento del programa o que realicen cualquier acción. El resultado del ejemplo mostrado aquí es el siguiente:

Este ejemplo lo podemos encontrar listo para compilarse y probarse en la carpeta “Ejemplos>Shell>Shell_Basic” una vez que hemos instalado nuestra librería.

Por ejemplo podemos crear comandos para prender/apagar un led, mover un motor, o leer un sensor. A continuación estudiaremos un ejemplo que nos permite controlar un led RGB con la PC.

Materiales necesarios.

• Arduino UNO R3
• Cable USB para Arduino
• Cables para conexión en el protoboard
• Protoboard Miniatura
• Resistencias 330 Ohms
• Led RGB cátodo común

Diagrama de conexiones Controlar LED RGB desde la PC

La siguiente ilustración muestra como debemos efectuar las conexiones para el ejemplo que vamos a cargar en nuestro arduino a continuación. Utilizamos un LED RGB de cátodo común con sus respectivas resistencias de 330 ohms.

La vista detallada de las conexiones y el circuito armado es la siguiente:

Considera lo siguiente al armar el circuito:

• El pin más largo del led es el común.
• El pin más largo se conecta a tierra (pin GND de Arduino).
• Se utilizan los pines de conexión 3, 5 y 6 por que son salidas PWM de la tarjeta Arduino UNO

Ejemplo: Controlar led RGB desde la PC

Este sketch de ejemplo controla un led RGB para cambiar el color y brillo del led enviamos el comando:

rgbled 100 100 100

Al finalizar de escribir el comando debemos enviar los caracteres CR y LF (ASCII). Con esto controlamos las componentes RGB del led. El primer número es el componente rojo, el segundo el verde y el tercero el azul. El sketch que implementa el control del led RGB mediante comandos de texto es el siguiente:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95

/** * GeekFactory - "Construye tu propia tecnologia" * Distribucion de materiales para el desarrollo e innovacion tecnologica * www.geekfactory.mx * * Ejemplo de libreria Shell. Este ejemplo permite controlar el color mostrado * en un led RGB conectado a los pines PWM mediante comandos de texto. El programa * admite 3 parametros de 0 a 255 que representan la intensidad de cada led (RGB). * * Example for Shell library. This example controls the color displayed on the RGB * led connected to PWM pins using text commands. The program accepts 3 parameters * in a range from 0 to 255 that represent the intensity of each led. */   #include <Shell.h>   void setup() {   // Prepare serial communication   Serial.begin(9600);   // Wait after reset or power on...   delay(1000);     // Pins to connect RGB led (PWM outputs)   pinMode(3,OUTPUT);   pinMode(5,OUTPUT);   pinMode(6,OUTPUT);     // Initialize command line interface (CLI)   // We pass the function pointers to the read and write functions that we implement below   // We can also pass a char pointer to display a custom start message   shell_init(shell_reader, shell_writer, 0);     // Add commands to the shell   shell_register(command_rgbled, "rgbled"); }   void loop() {   // This should always be called to process user input   shell_task(); }   /** * This function implements the rgbled command and parses the required args * Type: rgbled 255 255 255 to set led to maximum brigtness * Type: rgbled 0 0 0 to set led to minimum brightess */ int command_rgbled(int argc, char** argv) {   // Variables that store parameter values   uint8_t val_R, val_G, val_B;     // Parse RGB values and write to PWM pins   val_R = strtol(argv[1],NULL,0);   analogWrite(3, val_R);     val_G = strtol(argv[2],NULL,0);   analogWrite(5, val_G);     val_B = strtol(argv[3],NULL,0);   analogWrite(6, val_B);     // Print the received falues to the terminal screen   shell_printf("#RGB-COMPONENTS:%d,%d,%d\r\n", val_R, val_G, val_B);     // Return success code   return SHELL_RET_SUCCESS; }   /** * Function to read data from serial port * Functions to read from physical media should use this prototype: * int my_reader_function(char * data) */ int shell_reader(char * data) {   // Wrapper for Serial.read() method   if (Serial.available()) {     *data = Serial.read();     return 1;   }   return 0; }   /** * Function to write data to serial port * Functions to write to physical media should use this prototype: * void my_writer_function(char data) */ void shell_writer(char data) {   // Wrapper for Serial.write() method   Serial.write(data); }

Nótese que hemos omitido todas las comprobaciones sobre los datos recibidos, incluso si se han proporcionado las 3 componentes de color, todo esto en favor de la simplicidad. Sin embargo, si hemos mostrado algunas características de la librería “Shell” como la capacidad de imprimir texto con formato usando la función shell_printf(). Hemos destacado esto en color amarillo en el código más arriba.

El resultado del ejemplo anterior es el siguiente visto en el monitor serial de arduino:

Conclusiones

La librería shell.h permite controlar tu arduino desde la PC mediante el puerto serial o  ethernet fácilmente. En esta entrada hemos realizado un proyecto básico que nos permite saber como funciona la librería y los pasos necesarios para asociar comandos con las cadenas de texto. También pudimos observar que los parámetros pasados a las funciones invocadas por la librería, son exactamente iguales que el estándar para una utilidad de linea de comandos en C o C++. Por lo que para muchos programadores más experimentados será fácil acostumbrarse a escribir programas para la plataforma arduino y microcontroladores.