Thư viện Adafruit SSD1306: vẽ pixel, text, hình trên OLED

Adafruit_SSD1306 + Adafruit_GFX là cặp đôi cổ điển cho OLED 0.96" I2C — gọn, dễ dùng, tài liệu nhiều. Bài này hướng dẫn API đầy đủ và so sánh khi nào nên chuyển sang U8g2.

1. Cài đặt

Library Manager cài 2 thư viện:

• Adafruit SSD1306 — driver cho SSD1306.
• Adafruit GFX Library — API vẽ chung (dependency).

Khi cài SSD1306, IDE tự đề xuất cài GFX kèm.

2. Khởi tạo

#include 
#include 
#include 

#define WIDTH  128
#define HEIGHT 64
#define OLED_RESET -1   // không dùng chân reset
#define OLED_ADDR  0x3C // hoặc 0x3D

Adafruit_SSD1306 display(WIDTH, HEIGHT, &Wire, OLED_RESET);

void setup() {
  if (!display.begin(SSD1306_SWITCHCAPVCC, OLED_ADDR)) {
    Serial.println("OLED fail");
    while (1);
  }
  display.clearDisplay();
  display.setTextColor(SSD1306_WHITE);
  display.setTextSize(2);
  display.setCursor(0, 0);
  display.println("Hello!");
  display.display();
}

Quan trọng: display.display() để gửi buffer lên màn hình — không có nó, không thấy gì.

3. RAM yêu cầu

SSD1306 128×64 cần 1024 byte buffer. Trên Uno (2KB RAM), thư viện này chiếm ~50% RAM — code chính chỉ còn 1KB. Đó là lý do nhiều người chuyển sang U8g2 page mode hoặc dùng OLED 128×32 (chỉ 512 byte).

4. Text

display.setTextSize(1);        // 1 = 6×8 pixel/ký tự
display.setTextSize(2);        // 12×16
display.setTextColor(SSD1306_WHITE);
display.setTextColor(SSD1306_WHITE, SSD1306_BLACK);  // text + background
display.setCursor(x, y);
display.print("static");
display.printf("T=%.1f", 25.4);   // ESP32 có printf
display.println();
display.write('A');

5. Drawing primitives — từ GFX

display.drawPixel(x, y, SSD1306_WHITE);
display.drawLine(x0, y0, x1, y1, SSD1306_WHITE);
display.drawRect(x, y, w, h, SSD1306_WHITE);     // khung
display.fillRect(x, y, w, h, SSD1306_WHITE);     // tô đặc
display.drawCircle(x, y, r, SSD1306_WHITE);
display.fillCircle(x, y, r, SSD1306_WHITE);
display.drawTriangle(x0, y0, x1, y1, x2, y2, SSD1306_WHITE);
display.fillTriangle(x0, y0, x1, y1, x2, y2, SSD1306_WHITE);
display.drawRoundRect(x, y, w, h, r, SSD1306_WHITE);
display.drawBitmap(x, y, bitmap, w, h, SSD1306_WHITE);

6. Clear và update

display.clearDisplay();          // xoá buffer
display.display();               // gửi buffer lên màn hình
display.dim(true);               // giảm sáng

7. Xoay màn hình

display.setRotation(0);   // mặc định
display.setRotation(1);   // xoay 90°
display.setRotation(2);   // 180°
display.setRotation(3);   // 270°

8. Invert color

display.invertDisplay(true);  // đen-trắng đảo
display.invertDisplay(false);

9. Bitmap — logo, icon

Convert ảnh PNG monochrome → byte array bằng image2cpp. Paste array, gọi:

const uint8_t logo[] PROGMEM = { /* ... */ };
display.clearDisplay();
display.drawBitmap(0, 0, logo, 128, 64, SSD1306_WHITE);
display.display();

10. Custom font

GFX hỗ trợ Adafruit GFX font (file .h). Cài thêm Adafruit_GFX_Library → có sẵn nhiều font trong Fonts/:

#include 
display.setFont(&FreeSans9pt7b);
display.print("Custom");
display.setFont();   // về font mặc định

Convert font TTF → GFX format bằng fontconvert trong repo Adafruit_GFX. Có lib fontconvert online nhanh hơn.

11. Scrolling — animation"chữ chạy"

display.startscrollright(0x00, 0x07);  // scroll page 0..7 sang phải
display.startscrollleft(0x00, 0x07);
display.startscrolldiagright(0x00, 0x07);
display.stopscroll();

Native scroll của chip — không tốn CPU.

12. Adafruit vs U8g2

13. Lỗi thường gặp

• begin() fail — sai địa chỉ (0x3C vs 0x3D), không có pull-up I2C, dây dài.
• Màn hình không bật — quên display.display().
• Text bị cắt — y position là baseline (đáy chữ). Set y = 8 cho textSize 1 line đầu.
• Crash trên Uno — hết RAM. Đổi sang U8x8 hoặc OLED 128×32.

Liên quan

So sánh chi tiết với U8g2: thư viện OLED mạnh hơn Adafruit. Áp dụng vào dự án Đo nhiệt độ & độ ẩm DHT22 + OLED.