Aprender

Funções no Arduino: escreva uma vez, chame em qualquer lugar

Ou veja todas as aulas.

  • 526componentes na bancada
  • 46placas rodando agora
  • 1.00xtempo real, em todas as placas
Arduino Uno: três lâmpadas, uma função de piscarao vivo0.000 s 0.00x
Aperte Rodar e observe as lâmpadas
flash(pin, times, onMs) é escrita uma vez e chamada três vezes com números diferentes.

Uma função é um bloco de código com nome que você pode rodar de qualquer lugar do seu sketch escrevendo o nome dele. void flash(int pin, int times) é uma função que faz qualquer pino piscar qualquer número de vezes, então em vez de copiar as mesmas quatro linhas para cada LED, você escreve flash(13, 1), flash(12, 2) e flash(11, 3). setup() e loop() também são funções; você escreve elas o tempo todo.

O circuito acima tem três lâmpadas nos pinos 13, 12 e 11, controladas exatamente por essa função. Aperte Rodar. O monitor serial imprime "três lâmpadas, uma função de piscar", depois "pino 13 pisca 1 vezes", "pino 12 pisca 2 vezes" e "pino 11 pisca 3 vezes", e cada lâmpada faz o que a sua linha diz.

Abaixo estão o formato de uma função, funções que devolvem uma resposta, por que mudar um parâmetro não afeta quem chamou, onde as funções podem e não podem ficar, e as mensagens de erro de cada erro.

Quer a versão passo a passo? A aula "Escreva uma vez" percorre isso com checkpoints.

Abrir a aula

O formato de uma função

Uma função tem um tipo de retorno, um nome e seus parâmetros entre parênteses, e depois o corpo entre chaves. Em void flash(int pin, int times, int onMs), void diz que ela não devolve nada, flash é o nome, e os três ints são os números que quem chama deve passar. Dentro dela, pin, times e onMs são variáveis comuns que guardam o que quem chamou passou.

As duas funções pequenas logo depois respondem a uma pergunta em vez de fazerem uma tarefa. lampFor(round) devolve o pino de uma rodada e timesFor(round) devolve quantos piscados, e loop() usa as respostas delas. Mude return round + 1; para return round + 2; e cada lâmpada pisca uma vez mais.

firmware/uno/examples/cppfunc (as funções rodando acima)
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;
}

Retornar um valor

Qualquer tipo que não seja void significa que a função devolve um valor desse tipo, e return é como. Quem chamou pode imprimir, guardar ou usar em uma conta. Abaixo, twice(21) imprimiu 42.

Repare que twice() está escrita depois de setup(), que a chama. Em C++ puro isso é um erro, porque o compilador lê de cima para baixo e ainda não viu twice. A IDE do Arduino adiciona silenciosamente uma declaração para cada função de um arquivo .ino no topo antes de compilar, e o Mokxi faz o mesmo, então no seu sketch a ordem não importa.

Uma função que responde
void setup() {
  Serial.begin(9600);
  Serial.println(twice(21));
}

void loop() {
}

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

Abrir este sketch no editorSó o código: o editor posiciona a placa e os componentes que ele consegue ler do sketch.

Parâmetros são cópias

Um parâmetro é uma cópia do que quem chamou passou. addOne(score) abaixo soma um à própria cópia e joga fora, então score ainda imprimiu 5 depois. Na maior parte do tempo isso é exatamente o que você quer: uma função não pode alterar suas variáveis em segredo.

Quando você quiser isso, coloque & depois do tipo. void addOneRef(int &n) recebe uma referência, que é a própria variável de quem chamou com outro nome, e depois de addOneRef(score) imprimiu 6. Uma referência também é a forma usual de obter duas respostas de uma só função: minMax(7, 3, lo, hi) preencheu as duas e imprimiu "3 7".

Uma cópia, e uma referência
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 no editorSó o código: o editor posiciona a placa e os componentes que ele consegue ler do sketch.

Onde as funções ficam, e os erros quando elas não ficam

Uma função fica fora de todas as outras funções, no nível mais alto do arquivo, normalmente depois de loop() ou acima de setup(). Mantenha cada uma curta e dê um nome que diga o que ela faz, como readTemperature() ou flashError(), e loop() começa a parecer uma lista de passos. Escreva uma dentro de setup() e a compilação para. O Mokxi compila com clang, cujas palavras são function definition is not allowed here; o GCC da IDE do Arduino diz a function-definition is not allowed here before '{' token. Quase sempre significa que falta uma chave de fechamento acima, então o compilador acha que você ainda está dentro de setup(). Conte suas chaves.

Uma função que promete um valor deve retornar um em todos os caminhos. int f(int x) { if (x > 0) return 1; } compila, com um aviso: non-void function does not return a value in all control paths. Chame f(-5) e você recebe o que sobrou por acaso, que aqui imprimiu 1. Adicione um return no fim, mesmo que seja return 0;.

Funções em uma aba .cpp separada não recebem as declarações automáticas que um arquivo .ino recebe. Movemos uma função para uma aba chamada more.cpp e o sketch parou com use of undeclared identifier 'helper'. Coloque uma declaração, void helper();, em um header como more.h e #include "more.h" no topo do sketch, e a compilação funciona.

Abra este circuito no editor. Arduino Uno: três lâmpadas, uma função de piscar, ligado como está rodando no topo desta página. Troque um componente ou um valor e rode de novo.

Perguntas

O que significa void no Arduino?

Que a função não devolve nada. void setup() e void loop() fazem um trabalho e não retornam valor. Uma função que responde a uma pergunta tem um tipo, como int ou float, e termina com return.

Preciso declarar uma função antes de usá-la no Arduino?

Não em um arquivo .ino: a IDE do Arduino adiciona as declarações para você antes de compilar, e o Mokxi também faz isso, então uma função pode ser escrita abaixo do código que a chama. Em um arquivo .cpp você precisa, geralmente em um header.

Como faço para retornar dois valores de uma função?

Passe duas variáveis por referência, com & depois do tipo, e defina-as dentro da função. Ou retorne uma struct que guarde as duas. O exemplo minMax() nesta página preenche um valor baixo e um alto dessa forma.

Por que mudar um parâmetro não muda a minha variável?

Porque um parâmetro é uma cópia. Mudá-lo altera só a cópia. Declare o parâmetro como referência, int &n em vez de int n, se a função deve mudar a variável de quem a chamou.

O que significa "a function-definition is not allowed here"?

Que uma função está sendo definida dentro de outra, quase sempre porque falta uma chave de fechamento acima dela. Encontre a função antes do erro e confira se todo { tem seu }.

Uma função do Arduino pode retornar um array?

Não como array. Uma função pode retornar um ponteiro, mas retornar o endereço de um array local é um bug: a compilação passa com o aviso address of stack memory associated with local variable 'a' returned, porque o array deixa de existir quando a função termina. Passe o array como parâmetro e preencha-o, ou retorne uma struct que guarde os valores.

Monte isto de verdade

Abra o editor, mude um valor e veja o número mudar junto. Nada para instalar, e não precisa de conta.