Criando uma biblioteca para o Arduino para facilitar o reuso de suas funções
tags:


<h2 class="mylead">Já criamos a função que usa o led interno para comunicar valores e situações ao programador, agora é hora de entender como criar uma biblioteca para facilitar o uso dessa função em múltiplos programas sem ficar copiando o texto dela.</h2>

No artigo anterior apresentei a minha função <tt>debugLed()</tt>, que eu uso para me transmitir informações de estado (tipo OK, FALHA, AGUARDANDO, etc.) e para acompanhar o estado dos sensores analógicos, dispensando para isso o uso de displays LCD, da serial/tela do computador e mesmo a instalação de leds adicionais: a função apenas controla, de modo bem simples, o número de vezes que o led interno do Arduino pisca.

Durante algum tempo eu simplesmente copiava o código da função a cada novo programa mas, tendo sido programador, logo reconheci que esta é a situação ideal para a criação de uma biblioteca. Quando se cria uma biblioteca, as funções (e variáveis, tipos, etc.) exportadas por ela podem ser usadas em vários outros programas, simplesmente declarando, em cada um deles, que eles devem ser compilados em conjunto com a biblioteca.

<img class=shadow width="517" height="345" src="http://static.efetividade.net/img/captura-de-tela-2014-12-02-as-20.36.42-52962.png">

Acima você vê como fica o programa que faz uso da minha função <tt>debugLed()</tt>, com destaque para o trecho que faz a referência a ela. Abaixo você o vê (à direita, bem menor porque removi os comentários) lado a lado com a versão anterior (à esquerda), que precisa trazer o código completo da função que controla o led.

<img width="680" height="319" src="http://static.efetividade.net/img/sem-21936.png">

O do lado esquerdo define, ao seu final, toda a função, que é chamada (dentro do <tt>loop()</tt>) pelo nome de <tt>debugLed()</tt>. Já o da direita inclui, no seu início, a biblioteca DebugLED (que eu criei para compartilhar a função), e aí chama a mesma função pelo nome de <tt>debugLed.sinaliza()</tt>.

No exemplo acima pode parecer que a única vantagem é o código mais curto e fácil de entender, mas pense em como isso ficaria melhor se eu estivesse encapsulando na minha biblioteca uma função maior e mais complexa, ou mesmo uma coleção de funções usadas em conjunto em vários programas diferentes.

<h4>Criação de uma biblioteca para o Arduino</h4>

Em suma, as vantagens mais visíveis que eu procuro ao colocar em uma biblioteca as funções que eu reuso com frequência[@@rod:E aqui não é o lugar de falar em temas como coesão, acoplamento, orientação a objetos, etc.]: os programas ficam menores e sem complexidade que não diga respeito ao seu funcionamento direto, eventuais melhorias nas funções compartilhadas ficam imediatamente disponíveis para todos os programas que os incluem, a modularização facilita correções e melhorias, etc.

Já criei e mantive muitas bibliotecas na vida, mas no caso do Arduino eu tinha um problema no meu caminho: nunca programei em C++ antes, e é esta a linguagem que serve como base à estruturação do código para o Arduino.

Felizmente não tive dificuldade em encontrar a solução: um <a href="http://arduino.cc/en/Hacking/LibraryTutorial">tutorial oficial explicando como criar uma biblioteca para Arduino</a>. 

O tutorial mencionado acima é o recurso que eu recomendo que você consulte para conhecer os detalhes a respeito da criação das suas próprias bibliotecas, mas para ajudá-lo, e também para me ajudar a fixar os conceitos, <*>vou registrar a seguir o que eu precisei fazer para criar uma biblioteca</*> exportando <a href="http://br-arduino.org/2014/12/usando-o-led-interno-do-arduino-para-exibir-numeros.html">a função mencionada no artigo anterior</a>.

A biblioteca é definida em 2 arquivos obrigatórios, e mais alguns opcionais. Os arquivos obrigatórios são em C++: o de cabeçalhos (headers, extensão .h) e o de definições (o código propriamente dito, extensão .cpp). Eles podem ser editados no bloco de notas ou em qualquer editor de texto puro que você prefira.

A minha biblioteca se chama DebugLED, e por isso será gravada em uma pasta com este nome, dentro da pasta libraries, que fica dentro da pasta em que o ambiente do Arduino  grava os seus programas. No meu computador, o caminho completo é <tt>/Users/augusto/Documents/Arduino/libraries/DebugLED</tt>, mas no seu isso pode variar bastante, dependendo do sistema operacional e de como foi a instalação.

<h4>Arquivo .h: a definição dos cabeçalhos</h4>

O primeiro dos arquivos essenciais é o de cabeçalhos, que vai se chamar <tt>DebugLED.h</tt>. Vou começar mostrando seu conteúdo completo:

<pre><code><font color=darkgray>/*
	DebugLED.h - a library to display debug information using Arduino's 
	onboard led.
	
	Pisca o led proporcionalmente a um valor analogico
	Se o parametro for negativo, pisca de forma diferenciada, corres-
	pondendo ao numero passado como parametro.
	
	(c) Augusto Campos 2014 - BR-Arduino.org
	
	Usage of the works is permitted provided that this instrument is 
	retained with the works, so that any entity that uses the works 
	is notified of this instrument. DISCLAIMER: THE WORKS ARE 
	WITHOUT WARRANTY.
*/</font>
<font color=brown>#ifndef DebugLED_h
#define DebugLED_h</font>

<font color=red>#include "Arduino.h"</font>

<font color=green>class DebugLED
{
  public:
    DebugLED(int pino);
    void sinaliza(int valorAnalogico);
  private:
    int _pino;
}</font>

<font color=brown>#endif</font></code></pre>

Colorizei os trechos para facilitar a explicação, mas peço desculpas se o que eu vou registrar a partir daqui fizer pouco ou nenhum sentido para os não-programadores.

O trecho em cinza, você já deve ter adivinhado, são comentários identificando a biblioteca, sua finalidade, a autoria e a licença de uso. Não existe um formato específico, mas normalmente são essas as 4 informações que constam, total ou parcialmente em inglês (mas poderia ser em qualquer idioma).

Os 2 trechos em marrom (no início e no final) são diretivas de compilação condicional, que usualmente constam nesta mesma forma (alterando apenas o nome da biblioteca) em todos os arquivos de cabeçalho. Sua finalidade é evitar problemas caso um mesmo programa tente incluir indevidamente mais de uma vez a mesma biblioteca.

A linha em vermelho é praticamente obrigatória em toda biblioteca feita para usar recursos do Arduino: ela faz com que a biblioteca possa usar os tipos e outras definições do próprio Arduino.

Finalmente, o trecho em verde é o que tem os cabeçalhos da biblioteca que estou criando. Geralmente ela segue essa mesma estrutura: cria uma classe ("class") com o nome da biblioteca e, na cláusula "public", indica o nome do construtor que será criado para a classe (em termos simples, é o nome da função que será criada para inicializar a nossa biblioteca), seguido das declarações de funções, variáveis e outras definições que serão exportadas pela biblioteca. Neste caso, tenho só a função <tt>sinaliza</tt>.

No caso da minha biblioteca, temos também uma cláusula "private", na qual eu defini uma variável <tt>_pino</tt> cujo valor deve ser mantido pelo sistema entre várias execuções da função da biblioteca, mas que não deve ser acessível globalmente. É costumeiro (mas não obrigatório) iniciar os nomes delas com um "_".

<h4>Arquivo .cpp: a lógica da biblioteca</h4>

Vamos agora à íntegra do segundo arquivo essencial, que é o que terá as definições das nossas funções (no meu caso, apenas de uma): o <tt>DebugLED.cpp</tt>. Ele tende a ser bem maior do que o de cabeçalho:

<pre><code>
<font color=darkgray>/*
	DebugLED.cpp - a library to display debug information using Arduino's 
	onboard led.
	
	Pisca o led proporcionalmente a um valor analogico
	Se o parametro for negativo, pisca de forma diferenciada, corres-
	pondendo ao numero passado como parametro.
	
	(c) Augusto Campos 2014 - BR-Arduino.org
	
	Usage of the works is permitted provided that this instrument is 
	retained with the works, so that any entity that uses the works 
	is notified of this instrument. DISCLAIMER: THE WORKS ARE 
	WITHOUT WARRANTY.
*/</font>

<font color=red>#include "Arduino.h"
#include "DebugLED.h"</font>

<font color=brown><font color=darkgray>// Construtor, chamado na inicializacao da biblioteca/classe</font>
DebugLED::DebugLED(int pino) {
  pinMode(pino, OUTPUT);
  _pino = pino;
}</font>
  
<font color=green><font color=darkgray>// A funcao em si</font>
void DebugLED::sinaliza(int valorAnalogico) {
<font color=darkgray>  // Pisca o led proporcionalmente a um valor analogico
  // Se o parametro for negativo, pisca de forma diferenciada, corres-
  // pondendo ao numero passado como parametro.
  // Augusto Campos 2014 - BR-Arduino.org</font>
  int piscas=0;
  if (valorAnalogico >= 0) {
    piscas=map(valorAnalogico,0,1023,1,10);
  } else {
    piscas=1+abs(valorAnalogico);
    if (piscas>8)  piscas=8;   
    <font color=darkgray>// piscada longa preliminar</font>
    for(int i=0; i<6; i++) {
      digitalWrite(_pino, HIGH);
      delay(5);
      digitalWrite(_pino, LOW);
      delay(30);
    }  
  }
  <font color=darkgray>// serie de piscadas</font>
  for(int i=0; i<piscas; i++) {
    digitalWrite(_pino, HIGH);
    delay(10);
    digitalWrite(_pino, LOW);
    delay(250);
  }
  delay(300);
}</font></code></pre>

De novo, comentando a partir das cores dos trechos. 

As linhas em cinza são comentários, que são costumeiros e úteis mas não interferem na execução, nem no tamanho do executável transferido para o Arduino.

Em vermelho temos 2 diretivas de inclusão de headers que geralmente estarão presentes: os do próprio Arduino, e os da nossa biblioteca. É possível que você tenha mais headers de bibliotecas para incluir, dependendo do seu projeto.

Em marrom temos o construtor da nossa classe, que equivale à função de configuração que é chamada na sua inicialização. Note que o nosso construtor, chamado de <tt>DebugLED::DebugLED</tt> (essa repetição e o sinal de :: são usuais), tem um parâmetro chamado <tt>pino</tt>, pelo qual o programa que fizer uso da biblioteca consegue informar a ela em qual dos pinos do Arduino está conectado o led que ela deve usar (geralmente será o 13, que é o led interno de boa parte dos modelos, mas pode ser em qualquer outro pino de saída).

Finalmente, em verde temos a definição da única função da nossa biblioteca: <tt>DebugLED::sinaliza</tt> (que nossos programas chamarão pelo nome de <tt>DebugLED.sinaliza</tt>). Ela está um pouco maior e mais complexa do que a versão que vimos <a href="http://br-arduino.org/2014/12/usando-o-led-interno-do-arduino-para-exibir-numeros.html">no artigo anterior</a>, mas as explicações dele ainda valem: se a função receber um parâmetro positivo, irá considerar que se trata de um número na faixa entre 0 e 1023 (a faixa usada pelos pinos analógicos do Arduino) e piscar o led até 10 vezes, em um número de vezes <i>proporcional</i> ao parâmetro recebido. Mas se o parâmetro for negativo, a função entenderá que deve piscar diretamente aquele número de vezes indicado no parâmetro. 

<h4>Um programa que faz uso da biblioteca</h4>

Após gravar a biblioteca na pasta apropriada (já mencionado acima) e sua(s) função(ões) em um programa, basta fazer o que já vimos no quadro à direita, lá no início do artigo, e que agora vou mostrar colorizadamente para poder explicar.

O programa a seguir foi feito no editor normal do ambiente de desenvolvimento do Arduino:

<pre><code><font color=darkgray>/*  Sensor-pisca: acompanha o valor retornado por um sensor analogico na porta 3
  
    (c)  Augusto Campos 28.11.2014 - BR-Arduino.org
    Usage of the works is permitted provided that this instrument is retained 
    with the works, so that any entity that uses the works is notified of 
    this instrument. DISCLAIMER: THE WORKS ARE WITHOUT WARRANTY. */</font>
    
<font color=red>#include <DebugLED.h>
DebugLED debugLed(13);</font>

<font color=brown>void setup() {
}</font>

<font color=green>void loop() {
  int sensor=analogRead(3);
  <b>debugLed.sinaliza(sensor);</b>
}</font></code></pre>

No programa acima, o trecho em cinza são comentários de identificação. 

Em vermelho temos a parte crucial do uso de uma biblioteca: a linha que inclui os seus headers, e a linha que instancia a classe DebugLED, criando o objeto debugLED. Complicou? é devido a esta linha que, ao chamar a função definida na biblioteca, nós a chamamos de <tt><b>debugLed</b>.sinaliza()</tt>: o objeto criado ao instanciar é o prefixo utilizado nas referências posteriores.

Ainda na linha da instanciação, há mais um detalhe importante: o parâmetro 13. Lembra de quando foi criado o construtor, no arquivo DebugLED.cpp? É este o momento em que ele é executado, e recebe como parâmetro o número do pino em que está o led interno.

A seguir, em marrom, temos a definição da função <i>setup</i>, obrigatória no Arduino e que, no nosso caso, está vazia: a inicialização necessária no pino do led será feita pela biblioteca, providenciamos para isso ao definir nosso construtor.

Finalmente, em verde, temos o nosso loop do Arduino. Note que ele é bem simples: grava na variável <i>sensor</i> o valor obtido do pino analógico 3, ao qual conectei um resistor fotossensível (detalhes <a href="http://br-arduino.org/2014/12/usando-o-led-interno-do-arduino-para-exibir-numeros.html">no artigo anterior</a>), e em seguida passa essa mesma variável como parâmetro para a função <tt>debugLed.sinaliza</tt>, definida na nossa biblioteca.

<img src="http://static.efetividade.net/img/led-interno-piscando-25506.gif">

Na prática, o que o loop acima realiza é piscar o led interno, proporcionalmente à iluminação do ambiente. Se eu o coloco o sensor diretamente sob a luz do sol, ele pisca 8 a 9 vezes. Com a luz fluorescente do meu escritório, pisca 4 vezes e, no escuro quase completo, pisca apenas uma vez. 

Em complemento aos arquivos acima, você pode ter arquivos opcionais, como os de exemplos de uso da sua biblioteca. Entre os arquivos opcionais, um merece destaque: o arquivo keywords.txt, que contém uma lista das classes e funções definidas na biblioteca, para que elas apareçam em destaque nos seus programas no editor do Arduino. Se tiver interesse, o formato dele é bem simples e pode ser consultado <a href="http://arduino.cc/en/Hacking/LibraryTutorial">no tutorial</a>.



<h4>Compilando o programa que faz uso da biblioteca</h4>

A versão curta: compilar e transferir para o Arduino o programa que faz uso da sua biblioteca usa exatamente o mesmo procedimento com o qual você já compila e transfere outros programas.

A versão longa: é neste momento que a sua biblioteca será compilada, também. Fique atento às mensagens de erro da compilação, porque elas podem fazer referência tanto ao seu programa quanto ao código da biblioteca. 

Lembre-se de rolar para cima o campo das mensagens de erro, pois erros em bibliotecas muitas vezes geram erros também no programa, e geralmente estes são exibidos por último, escondendo as mensagens sobre os erros na biblioteca.



@@POSTTIME:Tue, 02 Dec 2014 20:52:40 -0200
@@POSTNAME:criando-uma-biblioteca-para-o-arduino-para-facilitar-o-reuso-de-suas-funcoes
Para editar o conteúdo do post “Criando uma biblioteca para o Arduino para facilitar o reuso de suas funções”, (1) copie o conteúdo acima em seu editor de texto, (2) altere-o como desejar, (3) grave-o no diretório 'staging' do seu Axe e (4) execute o axe.php com os parâmetros -dU seguidos pelo nome do arquivo em que você o gravou.