ArduMenu: Crear menús en Arduino o ESP8266

Hoy os traigo un módulo que he creado, el cual te permitirá crear menús para tu Arduino y compatibles, como por ejemplo el ESP8266. Actualmente sólo es compatible con dos pantallas: Nokia 5510 (PCD8544) y las que usen el chip ST77XX, con las librerías de Adafruit. En el futuro intentaré hacerlo compatible con más pantallas, pero es probable que funcione con cualquier pantalla que use una librería Adafruit.

Esta librería nace de la intención de que sea fácil de usar, que funcione con varias pantallas, y por varias funcionalidades que no vi en otras librerías.

Funcionalidades

• No es bloqueante, puedes mostrar el menú y manejarlo sin parar el loop principal del programa
• Se controla con tres funciones (enter, up y down), por lo que puede controlarse con cualquier método: botones, encoder, puerto serie, bluetooth…
• Cuatro tipos de objetos: Menu, Function, Toggle y Range (hablo de ellos más abajo)
• Niveles infinitos de menú (con objetos del tipo Menu), limitados por la memoria del microcontrolador.
• Icono de selección personalizado, pudiendo seleccionar también texto invertido
• Tamaño de letra personalizado (basado en los tamaños de la librería).

Cómo puedo crear menús

Esta librería dispone de cuatro funciones principales: drawMenu, enter, up y down.

drawMenu

Esta función es la usada para mostrar el menú. Para que su funcionamiento sea correcto el resto de la aplicación debe dejar de escribir en el display, por lo que la recomendación es poner una función que desactive el resto de actualizaciones y que ejecute esta función.

enter

Esta función hace las funciones de un botón de aceptar. Es por eso que dependiendo del item, realizará una acción u otra:

• Menu: Dibuja el submenu
• Function: Llama la función asociada al item. Si esta función devuelve true, se vuelve al menú superior
• Toggle: Llama la función toggle asociada al item, y actualiza el icono de la derecha dependiendo del resultado de esta.
• Range: Muestra un pequeño cuadro para seleccionar un número dentro de un rango. El rango debe ser controlado por la función callback

up

Esta función selecciona el item anterior en el menu, y en el caso de estar en un range, llama la función callback con 1 como argumento.

down

Esta función selecciona el item siguiente en el menu, y en el caso de estar en un range, llama la función callback con -1 como argumento.

Tipos de objetos para crear menús

Para crear los menús la librería dispone de cuatro tipos de objetos:

• AM_ITEM_TYPE_HEADER
• AM_ITEM_TYPE_MENU
• AM_ITEM_TYPE_COMMAND
• AM_ITEM_TYPE_RANGE
• AM_ITEM_TYPE_TOGGLE
• AM_ITEM_TYPE_EOM

AM_ITEM_TYPE_HEADER

Este objeto se muestra el primero en el menú y siempre está ahí. No tiene funciones ni es seleccionable, sólo puede haber uno por menú (los demás son ignorados), y tiene que estar el primero.

AM_ITEM_TYPE_MENU

Este objeto permite contener menús en él, lo cual permite crear submenús. Al seleccionarlo simplemente se dibuja el submenú.

AM_ITEM_TYPE_COMMAND

Este objeto tiene una función callback asociada a él, la cual es llamada cuando es seleccionado. Dicha función tiene que devolver un boolean (true o false), volviendo al menú anterior si es true o manteniéndose en el actual si es false.

AM_ITEM_TYPE_RANGE

Muestra un cuadro (opcional) con un selector de rango, el cual te permite seleccionar un número dentro de un rango específico. La función callback tiene que gestionar el rango, y recibe una llamada por cada llamada a las funciones up/down. Esta llamada contiene un argumento int, el cual es 0 cuando se quiere recuperar el estado actual, 1 cuando se ha llamado la función up, -1 cuando se ha llamado la función down, y 2 cuando se ha llamado a enter para cerrar el selector. Esta función callback tiene que devolver el número actual con motivo de que el menú actualice el selector.

AM_ITEM_TYPE_TOGGLE

Un objeto del tipo toggle que muestra un icono de estado a la derecha en el menú. Este objeto llama a una función callback cuando es seleccionado y dependiendo de si dicha función devuelve true o false, el icono de la derecha estará hueco o lleno. La función callback es llamada con un argumento boolean, el cual es true para indicar que hay un cambio de estado (el objeto ha sido seleccionado), o false cuando el menú simplemente necesita recuperar el estado actual.

AM_ITEM_TYPE_EOM

Este objeto le sirve al menú para detectar que se ha acabado el menú. Es muy importante añadirlo y que sea el último, ya que sino el menú no sabrá cuando parar de mostrar objetos y por lo tanto la aplicación fallará.

El funcionamiento de esta función es similar al del objeto del tipo AM_ITEM_TYPE_COMMAND, con la diferencia de que siempre vuelve al menú superior independientemente de lo que devuelva la función callback. Si dicho menú no existe, sólo la función callback será llamada, la cual podrá ser usada para ocultar el menú por ejemplo y reactivar el funcionamiento normal de la aplicación.

Descarga e instalación de la librería para crear menús

La librería puede ser descargada desde Bitbucket en donde posiblemente añadiré nuevas funcionalidades. La instalación es como la de cualquier librería, descomprime el zip descargado y copia el contenido a la carpeta C:\Users\<usuario>\Documents\Arduino\libraries\ArduMenu

Para saber cómo usarla, echa un vistazo a la carpeta examples, en dónde tendré ejemplos actualizados acerca de cómo usar la librería.

Espero que os haya gustado. ¡Saludos!