Aprender

Funciones de Arduino: escríbelo una vez, úsalo donde quieras

O mira todas las lecciones.

  • 526componentes en el banco de trabajo
  • 46placas funcionando ahora
  • 1.00xtiempo real, en todas las placas
Arduino Uno: tres lámparas, una función de destelloen vivo0.000 s 0.00x
Presiona Ejecutar y observa las lámparas
flash(pin, times, onMs) se escribe una vez y se llama tres veces con números distintos.

Una función es un bloque de código con nombre que puedes ejecutar desde cualquier parte de tu sketch escribiendo su nombre. void flash(int pin, int times) es una función que hace destellar cualquier pin cualquier número de veces, así que en lugar de copiar las mismas cuatro líneas para cada LED, escribes flash(13, 1), flash(12, 2) y flash(11, 3). setup() y loop() también son funciones; las has estado escribiendo todo este tiempo.

El circuito de arriba tiene tres lámparas en los pines 13, 12 y 11, controladas exactamente por esa función. Presiona Ejecutar. El monitor serie imprime "three lamps, one flash function", luego "pin 13 flashes 1 times", "pin 12 flashes 2 times" y "pin 11 flashes 3 times", y cada lámpara hace lo que dice su línea.

Abajo está la forma de una función, las funciones que devuelven una respuesta, por qué cambiar un parámetro no afecta a quien llama, dónde pueden y no pueden ir las funciones, y los mensajes de error de cada equivocación.

¿Quieres la versión paso a paso? La lección "Escríbelo una vez" recorre esto con puntos de control.

Abrir la lección

La forma de una función

Una función tiene un tipo de retorno, un nombre y sus parámetros entre paréntesis, luego su cuerpo entre llaves. En void flash(int pin, int times, int onMs), void dice que no devuelve nada, flash es el nombre, y los tres int son los números que quien la llama debe darle. Dentro, pin, times y onMs son variables comunes que contienen lo que pasó quien llamó.

Las dos funciones pequeñas que siguen responden a una pregunta en lugar de hacer un trabajo. lampFor(round) devuelve el pin de una ronda y timesFor(round) devuelve cuántos destellos, y loop() usa sus respuestas. Cambia return round + 1; por return round + 2; y cada lámpara destella una vez más.

firmware/uno/examples/cppfunc (las funciones que se ejecutan arriba)
void flash(int pin, int times, int onMs) {
  for (int i = 0; i < times; i++) {
    digitalWrite(pin, HIGH);
    delay(onMs);
    digitalWrite(pin, LOW);
    delay(onMs);
  }
}

int lampFor(int round) {
  if (round == 0) return LAMP_A;
  if (round == 1) return LAMP_B;
  return LAMP_C;
}

int timesFor(int round) {
  return round + 1;
}

Devolver un valor

Cualquier tipo distinto de void significa que la función devuelve un valor de ese tipo, y return es cómo. Quien la llama puede imprimirlo, guardarlo o usarlo en una suma. Abajo, twice(21) imprimió 42.

Fíjate que twice() está escrita después de setup(), que la llama. En C++ puro eso es un error, porque el compilador lee de arriba hacia abajo y todavía no ha visto twice. El IDE de Arduino agrega silenciosamente una declaración de cada función de un archivo .ino al inicio antes de compilar, y Mokxi hace lo mismo, así que en tu sketch el orden no importa.

Una función que responde
void setup() {
  Serial.begin(9600);
  Serial.println(twice(21));
}

void loop() {
}

int twice(int x) {
  return x * 2;
}

Abrir este sketch en el editorSolo el código: el editor coloca la placa y los componentes que puede leer del sketch.

Los parámetros son copias

Un parámetro es una copia de lo que pasó quien llamó. addOne(score) abajo suma uno a su propia copia y la descarta, así que score siguió imprimiendo 5 después. La mayoría de las veces eso es exactamente lo que quieres: una función no puede cambiar tus variables sin que te enteres.

Cuando sí lo quieres, pon & después del tipo. void addOneRef(int &n) recibe una referencia, que es la propia variable de quien llama con otro nombre, y después de addOneRef(score) imprimió 6. Una referencia también es la forma habitual de obtener dos respuestas de una sola función: minMax(7, 3, lo, hi) llenó ambas e imprimió "3 7".

Una copia, y una referencia
void addOne(int n) {
  n = n + 1;
}

void addOneRef(int &n) {
  n = n + 1;
}

void setup() {
  Serial.begin(9600);
  int score = 5;
  addOne(score);
  Serial.println(score);
  addOneRef(score);
  Serial.println(score);
}

void loop() {
}

Abrir este sketch en el editorSolo el código: el editor coloca la placa y los componentes que puede leer del sketch.

Dónde van las funciones, y los errores cuando no

Una función va fuera de todas las demás funciones, en el nivel superior del archivo, normalmente después de loop() o antes de setup(). Mantén cada una corta y dale un nombre que diga qué hace, como readTemperature() o flashError(), y loop() empieza a leerse como una lista de pasos. Escribe una dentro de setup() y la compilación se detiene. Mokxi compila con clang, cuyas palabras son function definition is not allowed here; el GCC del IDE de Arduino dice a function-definition is not allowed here before '{' token. Casi siempre significa que falta una llave de cierre arriba, así que el compilador cree que sigues dentro de setup(). Cuenta tus llaves.

Una función que promete un valor debe devolverlo en todos los caminos. int f(int x) { if (x > 0) return 1; } compila, con una advertencia: non-void function does not return a value in all control paths. Llama f(-5) y obtienes lo que haya quedado por ahí, que aquí imprimió 1. Agrega un return al final, aunque sea return 0;.

Las funciones en una pestaña .cpp aparte no reciben las declaraciones automáticas que sí recibe un archivo .ino. Movimos una función a una pestaña llamada more.cpp y el sketch se detuvo con use of undeclared identifier 'helper'. Pon una declaración, void helper();, en un header como more.h y #include "more.h" al inicio del sketch, y compila.

Abre este circuito en el editor. Arduino Uno: tres lámparas, una función de parpadeo, conectado tal como se ejecuta en la parte superior de esta página. Cambia un componente o un valor y ejecútalo de nuevo.

Preguntas

¿Qué significa void en Arduino?

Que una función no devuelve nada. void setup() y void loop() hacen un trabajo y no regresan ningún valor. Una función que responde una pregunta tiene un tipo, como int o float, y termina con return.

¿Tengo que declarar una función antes de usarla en Arduino?

No en un archivo .ino: el IDE de Arduino agrega las declaraciones por ti antes de compilar, y Mokxi también lo hace, así que una función puede escribirse debajo del código que la llama. En un archivo .cpp sí debes hacerlo, normalmente en un header.

¿Cómo regreso dos valores desde una función?

Pasa dos variables por referencia, con & después del tipo, y asigna sus valores dentro de la función. O devuelve un struct que contenga ambos. El ejemplo minMax() de esta página llena un mínimo y un máximo de esta forma.

¿Por qué cambiar un parámetro no cambia mi variable?

Porque un parámetro es una copia. Cambiarlo modifica solo la copia. Declara el parámetro como referencia, int &n en lugar de int n, si la función debe modificar la variable de quien la llama.

¿Qué significa "a function-definition is not allowed here"?

Que se está definiendo una función dentro de otra, casi siempre porque falta una llave de cierre arriba. Busca la función anterior al error y verifica que cada { tenga su }.

¿Puede una función de Arduino devolver un arreglo?

No como arreglo. Una función puede devolver un puntero, pero regresar la dirección de un arreglo local es un bug: la compilación pasa con la advertencia address of stack memory associated with local variable 'a' returned, porque el arreglo ya no existe cuando termina la función. Pasa el arreglo como parámetro y llénalo, o devuelve un struct que contenga los valores.

Ármalo en la vida real

Abre el editor, cambia un valor y mira cómo cambia el número con él. Nada que instalar y sin necesidad de cuenta.