Librería SoftTimer

Cuando trabajas con Arduino una de las cosas que más suele hacerse es crear temporizadores, haciéndose necesario el uso de la función millis y de varias variables de tiempo. Si el proceso es repetitivo, conviene encapsular en una librería una forma fácil de usar temporizadores por software.

La librería softTimer encapsula dos clases: SimpleTimer y AdvancedTimer.

SimpleTimer implementa una clase simple que servirá para la mayoría de los casos.

AdvancedTimer es una mejora, al menos en programación, usando punteros a funciones y siendo capaz de poder pausar y reiniciar el temporizador.

Clase SimpleTimer

Crea un temporizador por software con funcionamiento simple.

El constructor acepta como parámetro el tiempo en el que el temporizador devolverá true en la función check, siendo este dado en milisegundos

Ejemplo:

SimpleTimer temporizador(10000);

Método	Descripción
start	Inicia el temporizador.
stop	Para el temporizador.
check	Comprueba si se ha pasado el tiempo.
isRunning	Comprueba si el temporizador está corriendo
remaining	Indica cuanto tiempo le falta para alcanzar el tiempo
getDuration	Indica el tiempo del temporizador.
setDuration	Establece el tiempo del temporizador.

Descripción detallada.

start

Estable el temporizador al estado ST_RUN (corriendo) y guarda el estado de millis para comprobar si ha transcurrido el tiempo con la función check.

stop

Establece el temporizador al estado ST_STOP (parado) y establece la guarda de tiempo a cero.

check

Comprueba el estado del temporizador, devolverá true si el temporizador está corriendo (ST_RUN) y el tiempo actual de millis ha superado la duración del temporizador con respecto a la guarde de este.

Una vez alcanzado el tiempo y check devuelve cierto, conviene para el temporizador o reiniciarlo si no siempre devolverá cierto.

isRunning

Devuelve true si el temporizador está corriendo.

remaining

Devuelve el tiempo que falta para alcanzar el tiempo del temporizador en milisegundos. Si el temporizador está parado, devolverá el tiempo de duración del temporizador.

getDuration

Devuelve el tiempo en milisegundos del temporizador.

setDuration

Establece el tiempo en milisegundos que dura el temporizador.

Ejemplos de uso

/*
 * EJEMPLO SIMPLETIMER 1.
 * 
 * Al pulsar el botón es encenderá el led durante un minuto.
 */
#include <SoftTimer.h>
#include <SimpleButton.h>

// Creamos el botón en el pin 3.
SimpleButton button(3);
// Utilizamos el led de la placa Arduino Uno.
const int led  13
// Creamos el temporizador con un tiempo de 60000 ms ( 60s ).
SimpleTimer  timer(60000L);


void setup() {
  // Iniciamos el puerto Serie.
  Serial.begin(9600);
  // Establecemos el pin del led como salida.
  pinMode(led, OUTPUT);
}

void loop() {
  // Actualizamos el estado del botón.
  button.update();
  if ( button == Press ) {
    // Hemos apretado el botón: encendemos el led e iniciamos el
    // temporizador.
    digitalWrite(led, HIGH);
    timer.start();
  }

  if ( timer.check() ) {
    // Comprobamos si el tiempo ha transcurrido, si es así apagamos
    // el led y paramos el temporizador.
    digitalWrite(led, LOW);
    timer.stop();
  }
  
  // Mostramos por el puerto serie cuanto tiempo nos queda para alcanzar el
  // tiempo del temporizador.
  if ( timer.isRunning() ) {
    Serial.println( timer.remaining() );
  }
}

/*
 * EJEMPLO 2 LIBRERIA SOFTTIMER
 * 
 * Blink del led de la placa.
 */
#include <SoftTimer.h>

#define led 13

// Iniciamos el temporizador a un segundo.
SimpleTimer timer(1000);

void setup() {
  // Ponemos el led como salida.
  pinMode(led, OUTPUT);
  // Iniciamos el temporizador.
  timer.start();
}

void loop() {
  if ( timer.check() ) {
    // Hemos alcanzado el tiempo, cambiamos el estado del led
    // y reiniciamos el temporizador para que vuelva a empezar
    // a contar tiempo.
    digitalWrite(led, !digitalRead(led));
    timer.start();
  }
}

Clase AdvancedTimer

La clase AdvancedTimer proporciona un temporizador avanzado al que podemos indicar acciones al iniciarlo o pararlo, cuando alcanza el valor de tiempo establecido y teniendo la posibilidad de pausar y continuar el temporizador.

Para ello utiliza funciones como puntero en las variables privadas:

• onStart
• onStop
• onPause
• onResume
• onReach

Al ser variables privadas estas solo pueden ser establecidas mediante sus métodos de acceso y deben ser función del tipo STAction. La declaración de este tipo de función es:

typedef void (*STAction)();

Siendo una función que no tiene parámetro y devuelve void.

Tiene dos formas de funcionamiento: solo una vez y repetido. Si el modo es ST_RUNONCE el temporizador se ejecutará solo una vez y alcanzado el tiempo se parará. Sin embargo, si el modo es ST_RUNALWAYS el temporizador al alcanzar el tiempo volverá a reiniciarse y se repetirá el proceso.

El constructor acepta como parámetro el tiempo del temporizador:

AdvancedTimer t(1000);

Método	Descripción
setDuration	Establece la duración del temporizador.
setMode	Establece el modo del temporizador.
setOnStart	Función al iniciar el temporizador.
setOnStop	Función al parar el temporizador.
setOnResume	Función al continuar el temporizador pausado.
setOnPause	Función al pausar el temporizador.
setOnReach	Función al alcanzar el tiempo.
getState	Devuelve el estado del temporizador.
start	Inicia el temporizador.
stop	Para el temporizador.
pause	Pausa el temporizador.
resume	Continua el temporizador si está pausado.
update	Actualiza el temporizador.
remaining	Devuelve el tiempo que falta para alcanzar el temporizador.

Descripción detallada.

setDuration

Establece la duración en milisegundos del temporizador.

setMode

Establece el modo de funcionamiento del temporizador. Los posibles valores son:

• ST_RUNONCE: El temporizador una vez alcanzado el tiempo se parará.
• ST_RUNALWAYS: El temporizador una vez alcanzado el tiempo se reiniciará y empezará el proceso.

setOnStart

Establece la acción tipo STAction que se ejecutará cuando el temporizador se ponga en marcha .

setOnStop

Establece la acción tipo STAction que se ejecutará cuando el temporizador se pare.

setOnResume

Establece la acción tipo STAction que se ejecutará cuando el temporizador se vuelva a poner en marcha después de una pausa.

setOnPause

Establece la acción tipo STAction que se ejecutará cuando el temporizador se ponga en pausa.

setOnReach

Establece la acción tipo STAction que se ejecutará cuando se haya alcanzado el tiempo del temporizador.

getState

Devuelve el estado en el que se encuentra el temporizador. Sus posibles valores son:

• ST_RUN: Corriendo.
• ST_STOP: Parado.
• ST_PAUSE: En pausa.

start

Inicia el temporizador. Se ejecutará la acción STAction indicada en la variable onStart si esta no tiene un valor NULL.

stop

Se para el temporizador. Se ejecutará la acción STAction indicada en la variable onStop si esta no tiene un valor NULL.

pause

Pausa el temporizador. Se ejecutará la acción STAction indicada en la variable onPause si esta no tiene un valor NULL.

resume

Continua la ejecución del temporizador. Se ejecutará la acción STAction indicada en la variable onResume si esta no tiene un valor NULL.

update

Actualiza el temporizador y comprueba el estado en el que está realizando las acciones necesarias según el estado. Es necesario llamar a esta función siempre en el loop del programa ya que es la encargada del correcto funcionamiento de la clase y en ella se comprueba si se ha alcanzado el tiempo o no.

remaining

Devuelve el tiempo que queda para alcanzar el temporizador.

Ejemplo de uso

/*
 *  EJEMPLO BLINK CON ADVANCEDTIMER Y FUNCION LAMBDA.
 */
#include <SoftTimer.h>

#define led 13

// Creamos el temporizador.
AdvancedTimer timer(1000);

void setup() {
  // Ponemos el led como salida.
  pinMode(led, OUTPUT);
  // Iniciamos el modo a repetir siempre.
  timer.setMode(ST_RUNALWAYS);
  // Cuando el temporizador se alcance se cambiará el estado del pin.
  timer.setOnReach( []() { digitalWrite(led, !digitalRead(led)); } );
  // Inicio del temporizador.
  timer.start();
}

void loop() {
  // Actualizar el temporizador.
  timer.update();
}

/*
 *  EJEMPLO BLINK CON ADVANCEDTIMER Y FUNCION LAMBDA.
 *  
 */
#include <SoftTimer.h>
#include <SimpleButton.h>

#define led 13

// Creamos el temporizador.
AdvancedTimer timer(10000);
SimpleButton  button(3);

void apagarLed() { digitalWrite(led, 0); }
void encenderLed() { digitalWrite(led, 1); }

void setup() {
  Serial.begin(9600);
  // Ponemos el led como salida.
  pinMode(led, OUTPUT);
  // Iniciamos el modo a ejecutar una vez.
  timer.setMode(ST_RUNONCE);
  // Establecemos que funciones se hacen durante el inicio y parado del 
  // temporizador.
  timer.setOnStart( encenderLed );
  timer.setOnStop ( apagarLed );
  
}

void loop() {
  // Actualizar el botón.
  button.update();
  // Actualizar el temporizador.
  timer.update();

  if ( button == Press ) {
    timer.start();
  }

  Serial.println(timer.remaining());
}

Funciones útiles

void setMillis(unsigned long ms);

Establece el valor de millis. El uso de está función es peligroso, está por fines educativos.

void millis2timestr(unsigned long ms, char *str);

Dado un valor ms y una cadena str, formatea la cadena en días, horas, minutos y segundos que representa el valor ms. El resultado de la cadena es de la forma:

// Si ms no tiene días.
HH:MM:SS
// Si ms tiene días.
DD HH:MM:SS

uint32_t h2millis(uint32_t h);

Devuelve el número de milisegundos que representa el valor h en horas.

uint32_t m2millis(uint32_t m);

Devuelve el número de milisegundos que representa el valor m en minutos.

uint32_t ms2millis(uint32_t m, uint32_t s);

Dado un tiempo en minutos (m) y en segundo (s) devuelve el número de milisegundos equivalente.

uint32_t hms2millis(uint32_t h, uint32_t m, uint32_t s);

Dado un tiempo en horas (h), minutos(m) y segundos (s) devuelve el tiempo en milisegundos equivalente.

uint32_t dhms2millis(uint32_t d, uint32_t h, uint32_t m, uint32_t s);

Dado un tiempo días (d), horas (h), minutos (m) y segundos (s) devuelve el tiempo en milisegundos equivalente.

void millisStrip(unsigned long ms, int &a, int &b, int &c);

Dado un tiempo en milisegundos (ms) devuelve el número de horas (a), minutos (b) y segundos(c) que representa.

Referencias

Librería softTimer.