Controlando um display OLED com a biblioteca SSD1306 4

Aqui no blog já ensinamos a utilizar um display OLED com diversas placas de desenvolvimento: Raspberry Pi, Raspberry Pi Pico, ESP8266 e Arduino. Uma das bibliotecas mais utilizadas para controlar um display OLED é a biblioteca SSD1306 da Adafruit. E é sobre esta biblioteca que vamos falar neste post.

Foto Display OLED 0.96 polegadas I2C Azul
Display OLED 0.96 polegadas I2C Azul

A biblioteca Adafruit SSD1306 foi desenvolvida para controlar displays OLED monocromáticos baseados em drives SSD1306, com comunicação I2C ou SPI. Quando instalada junto com a biblioteca Adafruit GFX, fornece gráficos primitivos, como linhas, formas e textos.

O que é um display OLED?

OLED significa Organic Light-Emiting Diode, ou Diodo Emissor de Luz Orgânico. Esse tipo de display é composto por uma camada de material orgânico que é colocado entre dois eletrodos sendo que um deles geralmente é transparente. Esse material orgânico, ao ser estimulado por um campo eletromagnético, emite luz, dispensando assim o uso da luz de fundo (backlight). Por não haver a necessidade de utilização de backlight, esse display se torna extremamente econômico em termos de consumo de energia.

Existem diversos tipos de comunicação com este display, sendo a maneira mais comum a comunicação I²C. Pelo fato da comunicação I²C ser facilmente feita com Arduino, Raspberry Pi, etc, este tipo de display é muito usado e bem aceito entre os makers e hobbistas.

Instalação da biblioteca SSD1306 na Arduino IDE

Para utilização da biblioteca SSD1306 e GFX é necessário realizar a instalação, que pode ser feita através do Gerenciador de Bibliotecas da Arduino IDE.
Para isso, vá em Ferramentas > Gerenciar Bibliotecas… e procure por Adafruit SSD1306. Clique em Instalar.

Captura de tela Arduino IDE mostrando a opção Ferramentas - Gerenciar Bibliotecas...
Ferramentas -> Gerenciar Bibliotecas…
Captura te tela mostrando como instalar biblioteca SSD1306
Instalando a biblioteca SSD1306

Na sequência procure por Adafruit GFX e também clique em Instalar:

Captura te tela mostrando a janela Gerenciar Bibliotecas e como instalar o Adafruit GFX
Instalando a biblioteca Adafruit GFX

Configurações iniciais para utilização da biblioteca SSD1306

Para a construção do programa, o primeiro passo é fazer a inclusão das bibliotecas para o controle do display OLED. Além das bibliotecas Adafruit GFX e Adafruit SSD1306 é necessário fazer a inclusão das bibliotecas SPI e Wire para que o código funcione da maneira correta. Não é necessário fazer a instalação das bibliotecas Wire e SPI, pois elas já são nativas na Arduino IDE.

#include <SPI.h>
#include <Wire.h>
#include <Adafruit_GFX.h>
#include <Adafruit_SSD1306.h>

Na sequência é preciso instanciar o objeto display, para que o controle possa ser feito biblioteca Adafruit SSD1306. Os parâmetros de entrada são: largura do display (em pixels), altura do display (em pixels), tipo de comunicação utilizada (Wire ou SPI) e pino de reset.

#define LARGURA_OLED 128
#define ALTURA_OLED 64

#define RESET_OLED -1

Adafruit_SSD1306 display(LARGURA_OLED, ALTURA_OLED, &Wire, RESET_OLED);

OBS: Como o OLED que estamos utilizando não possui um pino RESET, enviamos -1 ao construtor para que nenhum dos pinos do Arduino seja utilizado como um reset para o display.
Dentro da estrutura void setup() precisamos inicializar o objeto OLED usando a função begin() que possui 2 parâmetros.O primeiro parâmetro, SSD1306_SWITCHCAPVCC, liga os circuitos internos. O segundo parâmetro define o endereço I2C do display OLED utilizado. Este endereço é fixo e não pode ser alterado.

É recomendável limpar o buffer de memória do módulo display OLED antes de qualquer comando de exibição. Na estrutura void setup() ainda, utilize a função clearDisplay() para fazer a limpeza no buffer e apagar tudo na tela. Isso é muito útil no caso de você desligar e ligar o Arduino novamente.

void setup() {
display.begin(SSD1306_SWITCHCAPVCC, 0x3C);
display.clearDisplay();
}

OBS: Geralmente os módulos I2C OLED possuem como padrão o endereço 0x3C.

Principais funções da biblioteca Adafruit SSD1306

A biblioteca Adafruit para o display OLED possui várias funções para escrever textos e imprimir formas geométricas. Conheça abaixo as principais.

Textos e números

Antes de escrever o texto, você precisa definir o tamanho do texto, a cor e onde o texto será exibido no OLED. Defina o tamanho da fonte usando a função setTextSize():

display.setTextSize(1);

Defina a cor da fonte com setTextColor().O parâmetro WHITE define fonte branca e fundo preto:

display.setTextColor(WHITE);

Defina a posição onde o texto começa usando setCursor(x,y). O parâmetro x (em pixels) é a posição na largura do display que o texto inicia. O parâmetro y (em pixels) define a posição na altura que o texto inicial.

display.setCursor(0,10);

Finalmente, você pode enviar o texto para o display usando print(), como segue:

display.print("Ola makers!");

Então, você precisa usar a função display() para realmente exibir o texto na tela.

display.display();

O resultado será esse:

Display OLED utilizando a biblioteca SSD1306 e mostrando o texto "Olá Makers"
Display OLED – “Olá Makers!”

Para imprimir números, você também pode usar a função print():

Foto do display OLED mostrando o texto "0123456789" utilizando a biblioteca SSD1306
Display OLED – “0123456789”
display.setTextSize(1);
display.setTextColor(WHITE);
display.setCursor(0,10);
display.print(“0123456789”);
display.display();

Caracteres ASCII

As função printl() envia dados para o display como texto ASCII legível, enquanto a função write() envia dados binários para o display. Portanto, podemos usar esta função para exibir símbolos ASCII.

Display OLED utilizando a biblioteca SSD1306 mostrando o texto em ASCII
Display OLED – Símbolos ASCII

Abaixo você pode conferir a tabela de símbolos ASCII relacionados à códigos binários de 0 a 255:

Imagem com tabela de símbolos ASCII relacionados à códigos binários de 0 a 255
Símbolos ASCII relacionados à códigos binários de 0 a 255

Movimento do texto sobre a tela

Para rolar o texto na tela temos algumas opções de funções:

  • startscrollright() – rola o texto para a direita
  • startscrollleft() – rola o texto para a esquerda
  • startscrolldiagright() – rola o texto na diagonal, para a direita
  • startscrolldiagleft () – rola o texto na diagonal, para a esquerda
display.setTextSize(1);
display.setTextColor(WHITE);
display.setCursor(0,0);
display.print("Ola makers!");
display.display();
display.startscrollright(0x00, 0x07);
delay(3000);
display.startscrollleft(0x00, 0x07);
delay(3000);
GIF mostrando texto "Olá makers!" se movimentando para os lados
Texto “Olá makers!” movimento horizontal
display.setTextSize(1);
display.setTextColor(WHITE);
display.setCursor(0,0);
display.print("Ola makers!");
display.display();
display.startscrolldiagright(0x00, 0x07);
delay(5000);
display.startscrolldiagleft(0x00, 0x07);
delay(5000);
GIF mostrando Texto "Olá makers!" movimento diagonal
Texto “Olá makers!” movimento diagonal

Pixel

Para desenhar um pixel na tela, você pode usar a função drawPixel(x, y, cor), onde os parâmetros são as coordenadas xey onde o pixel aparece e a cor. Por exemplo:

display.drawPixel(64, 32, WHITE);
display.display();
Imagem mostrando display OLED com pixel no centro da tela
Display OLED – Pixel no centro da tela

Linha

Use a função drawLine(x1, y1, x2, y2, cor) para criar uma linha. As coordenadas (x1, y1) indicam o início da linha e as coordenadas (x2, y2) indicam onde a linha termina. Por exemplo:

display.drawLine(0, 0, 127, 63, WHITE);
display.display();
Imagem mostrando display OLED com linha na diagonal
Display OLED – Linha na diagonal

Retângulo e Retângulo com Bordas Arredondadas

A função drawRect(x, y, largura, altura, cor) fornece uma maneira fácil de desenhar um retângulo. As coordenadas (x, y) indicam o canto superior esquerdo do retângulo. Então, você precisa especificar a largura, altura e cor.Você pode usar um retângulo preenchido com a função fillRect(x, y, largura, altura, cor).

display.drawRect(10, 10, 50, 44, WHITE);
display.fillRect(68, 10, 50, 44, WHITE);
display.display();
Imagem mostrando 2 retângulos no display OLED
Display OLED – Retângulos

Também é possível exibir retângulos com cantos arredondados com drawRoundRect(x, y, largura, altura, raio, cor) e fillRoundRect(x, y, largura, altura, raio, cor).

display.drawRoundRect(10, 10, 50, 44, 5, WHITE);
display.fillRoundRect(68, 10, 50, 44, 5, WHITE);
display.display();
Imagem mostrando 2 retângulos com bordas arredondadas no display OLED
Display OLED – Retângulos com bordas arredondadas

Círculo

Para desenhar um círculo use drawCircle(x, y, raio, cor). As coordenadas (x,y) indicam o centro do círculo. Da mesma forma, para construir um círculo preenchido, use fiilCircle(x, y, raio, cor).

display.drawCircle(32, 32, 25, WHITE);
display.fillCircle(96, 32, 25, WHITE);
display.display();
Imagem mostrando 2 círculos no display OLED
Display OLED – Círculos

Triângulo

Para desenhar um triângulo use drawTriangle(x1, y1, x2, y2, x3, y3, cor). Cada coordenada xy representa uma das pontas do triângulo. Da mesma forma, para construir um círculo preenchido, use fillTriangle(x1, y1, x2, y2, x3, y3, cor).

display.drawTriangle(5, 10, 55, 10, 30, 54, WHITE);
display.fillTriangle(70, 55, 120, 55, 95, 10, WHITE);
display.display();
Imagem mostrando 2 triângulos no display OLED utilizando a biblioteca SSD1306
Display OLED – Triângulos

Inversão de cores

A biblioteca fornece uma função para inverter as cores de formas e textos: invertDisplay(). Passar true como argumento irá inverter as cores da tela e false faz voltar às cores originais.

display.drawRoundRect(10, 10, 108, 44, 3, WHITE);
display.setTextSize(1);
display.setTextColor(WHITE);
display.setCursor(32, 30);
display.print("Ola makers!");
display.display();
display.invertDisplay(true);
delay(2000);
display.invertDisplay(false);
delay(2000);
Frase "Olá Makers!"com inversão de cores em display OLED utilizando a biblioteca SSD1306
“Olá Makers!” – Inversão de cores

Imagens

Além de imprimir textos e formas, a biblioteca SSD1306 permite imprimir na tela imagens monocromáticas. O post “como criar imagens em um display OLED” mostra o passo-a-passo para fazer isso.

Gostou de aprender a utilizar um display OLED com a biblioteca SSD1306? Deixe um comentário abaixo dizendo o que achou. Para mais conteúdos como esse acesse nosso blog e para não perder nenhuma novidade nos siga no Instagram.

Faça seu comentário

Acesse sua conta e participe

4 Comentários

  1. Resolvido em parte.

    Tive em incluir na IDE a biblioteca BusIO da própria Adafruit.

    Agora tenho um outro problema. Mas não tem nada a ver com as instruções do post.

    1. Olá Charles!

      Algumas bibliotecas tem dependência de outras, em geral quando é feita a instalação pelo gerenciador de bibliotecas ele avisa/instala as dependências.

      Qual é o outro problema?

      Abraços!
      Vinícius – Equipe FilipeFlop

  2. Desculpe a repostarem. Mas que é na anterior ficouo faltando uma parte importante.

    Fui o mais fiel possivel nas instruções até a parte do “Ola makers!”
    Então quando vou compilar, aparece as seguintes linhas de aviso.

    In file included from C:\Users\ComprasPeças\Documents\Arduino\libraries\Adafruit_GFX_Library\Adafruit_GrayOLED.cpp:20:0:

    C:\Users\Compras Peças\Documents\Arduino\libraries\Adafruit_GFX_Library\Adafruit_GrayOLED.h:30:32: fatal error: Adafruit_I2CDevice.h: No such file or directory

    #include Adafruit_I2CDevice.h

    ^

    compilation terminated.

    E ao final essas linhas…

    exit status 1
    Erro compilando para a placa Arduino/Genuino Uno

    Já reinstalei as bibliotecas e a ide varias vezes. Mas parece que falta algo.

  3. Olá.
    Fui o mais fiel possivel nas instruções até a parte do “Ola makers!”
    Então quando vou compilar, aparece as seguintes linhas de aviso.

    In file included from C:\Users\ComprasPeças\Documents\Arduino\libraries\Adafruit_GFX_Library\Adafruit_GrayOLED.cpp:20:0:

    C:\Users\Compras Peças\Documents\Arduino\libraries\Adafruit_GFX_Library\Adafruit_GrayOLED.h:30:32: fatal error: Adafruit_I2CDevice.h: No such file or directory

    #include

    ^

    compilation terminated.

    E ao final essas linhas…

    exit status 1
    Erro compilando para a placa Arduino/Genuino Uno

    Já reinstalei as bibliotecas e a ide varias vezes. Mas parece que falta algo.