Guia de Instalação e Utilização das Bibliotecas do Arduino

Veja nesse pequeno guia as principais dicas, conceitos e orientações sobre a seleção, instalação e utilização de bibliotecas com a IDE do Arduino.

Na reportagem de hoje vamos falar sobre as bibliotecas do Arduino: Aonde elas moram? Como elas vivem? Como encontrá-las e conviver com elas…

Brincadeiras a parte, toda vez que compramos um componente novo para usarmos com nossa placa, a primeira coisa em que pensamos é se existe um código pronto, um exemplo ou uma biblioteca que facilite a sua programação.
Neste artigo, vamos mostrar quais os passos que temos que seguir para localizar, instalar e utilizar uma biblioteca nos nossos projetos.
Sempre lembrando: Embora o título do artigo fale Arduino, na verdade serve para qualquer placa compatível com a IDE do Arduino (ESP*.*, Attiny, etc).

Advertência: A palavra BIBLIOTECA vai aparecer umas 500 vezes nesse artigo, pelo menos uma vez em cada parágrafo. Não consegui evitar esse vício de linguagem. Para amenizar, as vezes eu uso o termo lib ou library, indistintamente.

O que é um biblioteca?

Uma Biblioteca ou library nada mais é do que um coleção de arquivos de códigos-fonte em C/C++. No ambiente Arduino, as bibliotecas não são códigos binários (DLLs) e, portanto, não são fechadas, permitindo até que façamos alterações em seus conteúdos.
O uso de uma biblioteca simplifica o desenvolvimento de aplicações pois o código da biblioteca já está pronto e só precisa ser incorporado ao programa para que suas funções possam ser acessadas e utilizadas de forma transparente, sem poluir o código. Isso permite que foquemos apenas no objetivo principal do nosso programa.
No entanto, como existem milhares delas, precisamos conhecer bem o processo de seleção e instalação para não termos dores de cabeça.

Tipos de bibliotecas

No mundo Arduino existem três tipos de bibliotecas:

Core libraries: Também conhecidas como built-in libraries, já vêm instaladas por padrão e agrupam os comandos essenciais que usamos na maioria das aplicações, tais como digitalRead, Serial.begin, analogRead, etc. Não é necessário referenciá-las com a diretiva “include”.
Standard libraries: São as bibliotecas que agrupam funcionalidades comuns, porém menos utilizadas. Elas também já vêm instaladas por padrão junto com a IDE do Arduino, mas necessitam ser referenciadas com a diretiva “include”.
Exemplos: EEPROM, Servo, LiquidCrystal, etc.
Third-party libraries: São bibliotecas externas feitas pela comunidade Arduino. Agrupam funcionalidades específicas e precisam ser baixadas, instaladas e referenciadas no nosso código com “include”.

A diretiva include

A diretiva #include é usada para avisar ao compilador que vamos usar uma biblioteca externa no nosso sketch. Dessa forma, o código dessas bibliotecas é incluído na compilação e seus comandos/funções serão validados e ficarão disponíveis para utilização.

Exemplo:
#include <Servo.h>
#include “MyLibrary.h”

Mas você deve estar se perguntando: Qual a diferença entre usar <> ou “” nos includes?

Quando usamos <>, avisamos ao compilador para procurar os arquivos da biblioteca na pasta padrão das bibliotecas Arduino. Mas qual pasta é essa? É o que veremos no próximo tópico.
Quando usamos “”, avisamos ao compilador para procurar na pasta do sketch primeiro. Podem ser usados caminhos completos, se desejar.

Localização das bibliotecas

Nas máquinas Windows, as bibliotecas de terceiros ficam na pasta abaixo, onde XXXXX é o nome do usuário:

C:\Users\XXXXX\Documents\Arduino\libraries. É aqui que elas vão ser instaladas e procuradas pelas diretivas include. Exceções: Algumas bibliotecas (ESP8266, por exemplo) podem ser instaladas na pasta abaixo:
C:\Users\XXXXX\AppData\Local\Arduino15

As bibliotecas padrão ficam na pasta libraries no local de instalação da IDE do Arduino.

Anatomia de um pacote de biblioteca

A bibliotecas Arduino são organizadas em pacotes com os seguintes arquivos:

keywords.txt → Esse arquivo relaciona os nomes das funções/objetos/tipos de dados/constantes/etc. Esses nomes são usados para validação e para colorização da sintaxe no editor. É útil também para nos guiarmos e vermos quais comandos estão disponíveis;
library.properties → Este arquivo contém uma lista de itens do tipo key-value e é usado pelo gerenciador de bibliotecas para exibir as informações. Contém a versão, o nome do desenvolvedor, a arquitetura, etc.;
Pasta examples –> são arquivos de códigos-fonte com exemplos de utilização;
Pasta src –> Aqui estão os arquivos principais com o código-fonte das bibliotecas (*.c e *.h).

Como instalar

Existem 3 formas de instalar um biblioteca, em ordem de preferência:

Usar o gerenciador de bibliotecas (Library Manager) que fica no Menu Sketch/Include Library da IDE. O gerenciador exibe a relação de bibliotecas separadas em categorias com todas as informações necessárias. Basta escolher a lib desejada através de uma pesquisa e clicar em instalar.
Usar o gerenciador é a melhor prática, pois as libs ali disponíveis são atualizadas sempre que uma nova versão estiver disponível, além de outras vantagens.
Instalar de um arquivo ZIP. Essa é uma opção que fica também no mesmo menu sketch. Use essa opção quando a lib não está presente no gerenciador de bibliotecas.
Baixe o arquivo zip para uma o pasta qualquer e selecione essa opção que a IDE se encarrega de colocar o pacote nas pastas corretas, O arquivo zip você encontra no site do desenvolvedor, normalmente um github.
Manualmente. Significa baixar o pacote e copiá-lo para a pasta libraries.

Obs: Depois de instalar, você pode colocar a diretiva include respectiva no seu código. Para fazer isso, você pode selecionar a opção include library do menu e selecionar a biblioteca recém instalada.

Gerenciador de bibliotecas

Como escolher a biblioteca certa

Os seguintes passos devem ser tomados para selecionar um biblioteca para seu projeto:

Comece procurando a biblioteca no gerenciador de bibliotecas. Digite uma palavra-chave na pesquisa que uma relação de bibliotecas será exibida.
Para cada lib exibida, procure o site do desenvolvedor (Opção more info) e verifique qual foi a última data de atualização da biblioteca. Cuidado com as libs que estão a mais de 4 anos sem atualizações.
Verifique também quantos mantenedores (desenvolvedores) trabalham com essa lib. Cuidado com as libs com menos de 2 contribuidores.
Passeie pelo site do desenvolvedor e verifique se a lib possui boa documentação. Observe o arquivo keywords e os arquivos de exemplo para verificar se possui os comandos que precisa e assim por diante.
Procure observar se a lib dá suporte para a arquitetura da sua placa (Arduino , esp*.*, Attiny, etc).
Verifique se a lib consome muita memória. A maneira mais fácil de saber é instalar a biblioteca e compilar um arquivo de exemplo. A compilação informará a quantidade de bytes livres para você comparar com as demais.

Pronto! Entre as libs que passaram nos testes acima, escolha a mais simpática.

Obs:

Se não encontrar nenhuma lib no gerenciador, pesquise na Internet e siga os passos a partir de (2).
Esse roteiro é subjetivo e não implica em 100% de sucesso na escolha.

Testando e Utilizando

As bibliotecas Arduino, em sua maioria, seguem o paradigma OOP (Programação Orientada a Objetos), ou seja, uma classe que disponibiliza vários métodos que são as suas funcionalidades.
Para identificar as classes e seus métodos, temos que recorrer à documentação, aos exemplos e ao arquivo keywords. Depois que você instala uma biblioteca, os códigos de exemplos ficam disponíveis no menu examples.
A forma de utilização varia de caso para caso mas, basicamente, consiste dos seguintes passos:

Declaração e instanciação
A declaração consiste em criar uma variável com o tipo de dados definido pela classe.
A instanciação consiste na criação de um objeto específico dessa classe.
Quando instanciamos objetos de uma classe, as vezes precisamos informar os parâmetros do construtor que, na maioria dos casos, consistem de itens lógicos de hardware, tais como pinos digitais, analógicos, endereços, etc.
Frequentemente, a criação do objeto é feita no início do sketch, antes do SETUP. Isso não é uma regra mas, fazendo assim, o objeto adquire o escopo GLOBAL e fica disponível para todas as funções do sketch.
A declaração e a instanciação podem ser feitas concomitantemente, num único comando.
Execução
Consiste em executar os métodos disponiblizados pela classe. De novo, aqui, precisamos conhecer a assinatura do método, ou seja, seus parâmetros de entrada e valores de retorno.

Isso tudo é muito vago. Vamos agora ver um exemplo prático para entendermos melhor os conceitos apresentados neste guia.

Exemplo Prático

Vamos supor que queremos testar um encoder rotativo com o Arduino que é um tipo de sensor de posição. Ele possui muitas utilidades, tais como determinação de ângulos ou mesmo para controlar menus em conjunto com um LCD.
O modelo que possuo é o Keyes KY-040 tem rotação contínua e um botão (o próprio o eixo) que pode ser usado, por exemplo, para selecionar uma opção de um “menu”.
Esse tipo de encoder usa Três pinos digitais do Arduino: Dois para detectar a rotação do eixo e outro para detectar o pressionamento do botão.
Segue abaixo a imagem do encoder. Para ver o esquema de ligação, consulte este link:

https://blogmasterwalkershop.com.br/arduino/como-usar-com-arduino-modulo-encoder-rotativo-ky-040/.

Quero encontrar uma biblioteca para controlar esse encoder que tenha as seguintes funcionalidades, pelo menos:
– Controle da rotação com tratamento debounce
– Controle do push button com tratamento debounce

Vamos fazer uma pesquisa no gerenciador de bibliotecas pelo termo “rotary encoder”.

No resultado da pesquisa, surge muito lixo (libs que não são para encoders) pois a pesquisa é feita para cada palavra do termo pesquisado.
Para cada biblioteca significativa que aparece na relação, vamos consultar o site do desenvolvedor, selecionando o link More info.

Depois de analisar as libs de acordo com os passos do tópico anterior, escolhi a biblioteca Simple Rotary disponível em:

https://github.com/mprograms/SimpleRotary

Motivos da escolha:

Possui todos os requisitos desejados;
Ocupa pouca memória;
É atualizada frequentemente;
Fácil de usar;
Documentação razoável.

O que pesa contra essa biblioteca é que ela é mantida por apenas um desenvolvedor e é recente, ou seja, PODE ser pouco estável.

O próximo passo é instalar e testar. No próprio gerenciador de bibliotecas, selecione o botão instalar.
Agora, para testar, podemos usar um dos exemplos prontos que vem com o pacote. Acesse o menu examples e escolha o exemplo ROTATE.

Vamos agora examinar o código para entender a utilização da biblioteca.

/*
===============================================================================================================
SimpleRotary.h Library CW / CCW Example Sketch
Learn more at [https://github.com/mprograms/SimpleRotary]

This example shows how to get the rotational direction.

===============================================================================================================
Release under the GNU General Public License v3
[https://www.gnu.org/licenses/gpl-3.0.en.html]
===============================================================================================================
*/
#include <SimpleRotary.h>

// Pin A, Pin B, Button Pin
SimpleRotary rotary(6,5,7);

void setup() {
  Serial.begin(9600);
}

void loop() {
  
  byte i;

  // 0 = not turning, 1 = CW, 2 = CCW
  i = rotary.rotate();

  if ( i == 1 ) {
    Serial.println("CW");
  }

  if ( i == 2 ) {
    Serial.println("CCW");
  }
}

Na linha 13, temos a diretiva include. Isso vai fazer com que a IDE inclua a library na compilação. Por isso, ela precisa estar instalada apropriadamente, como vimos anteriormente.

Na linha 16, Temos a declaração e instanciação da variável para o objeto encoder, onde:

SimpleRotary é o tipo de Dado (Classe);
rotary é o nome da variável que vai armazenar nosso objeto. Voce pode dar o nome que quiser para essa variável;
Os valores dentro dos parênteses são os parâmetros para criação do objeto, que nesse caso são os pinos digitais (5,6 e 7) conforme definido na documentação. Você também pode escolher outros pinos digitais para fazer a ligação.

Depois que o objeto foi criado, podemos chamar suas funções (métodos). No caso, vamos chamar a função “rotate” (linha 27). Essa função não precisa de parâmetros e retorna qual é o sentido da rotação:

0 = sem rotação, 1 = Sentido horário, 2 = Sentido anti-horário

Aqui vemos uma deficiência dessa biblioteca. Deveriam existir constantes definidas para representar esses valores. Isso deixaria o código mais inteligível.

Bem, isso é tudo. Esse é um exemplo simples, mas que dá uma boa ideia de como é o funcionamento das bibliotecas do Arduino e a importância da documentação das mesmas.

Referências

Conclusão

Todos sabemos das deficiências da IDE do Arduino, porém o gerenciador de bibliotecas é uma ferramenta muito útil para o desenvolvedor e espero ter contribuído para uma utilização efetiva dessa ferramenta.

O grande problema referente às bibliotecas é a documentação amadora disponibilizada pelos seus desenvolvedores que, na sua maioria, não possui um referência completa das classes, o que nos força, às vezes, buscar ajuda no próprio código-fonte da mesma.
Mas existem exceções. Veja aqui um exemplo de biblioteca bem documentada: DS3231_Simple.

Até a próxima…