Komponen · 9 mnt baca

ST7789 ESP32: Layar IPS Berwarna dengan TFT_eSPI, Sprite, dan Jam

Panduan ST7789 ESP32: TFT_eSPI dan User_Setup.h, pin SPI berlabel SCL/SDA, indikator dan jam dengan sprite tanpa kedipan, Adafruit pada Uno, Pico, serta solusi layar hitam.

Pasangan ST7789 ESP32 adalah cara termurah untuk memberi proyek kecil antarmuka berwarna dengan kualitas layar ponsel. ST7789 merupakan chip driver TFT buatan Sitronix yang digunakan pada sebagian besar layar IPS 1,3 inci 240x240, 1,54 inci 240x240, 1,69 inci 240x280, dan 2,0 inci 240x320 di pasaran. Berkat panel IPS, warnanya terlihat cerah dari semua sudut; dengan 65 ribu warna, resolusi tinggi, dan koneksi SPI yang cepat, kamu bisa menggambar indikator, grafik, dan animasi yang tidak bisa ditampilkan OLED atau LCD karakter.

Dalam panduan ini kamu akan mempelajari langkah demi langkah cara menghubungkan ST7789 ke ESP32 dengan library TFT_eSPI, cara mengatur User_Setup.h yang merupakan bagian paling membingungkan dari library ini, alasan modul menggunakan SPI dan bukan I2C meskipun berlabel SCL dan SDA, cara membuat animasi tanpa kedipan menggunakan sprite, serta cara membuat indikator sensor analog dan antarmuka jam berbasis NTP. Kita juga akan membahas library Adafruit_ST7789 untuk Arduino Uno, driver MicroPython tanpa library untuk Raspberry Pi Pico, dan semua penyebab masalah layar hitam.

Modul layar TFT berwarna ST7789
Modul IPS TFT ST7789: 240x240 piksel, 65 ribu warna, dan koneksi SPI; dengan ESP32, modul ini menggambar grafis yang mulus.

Apa itu ST7789 dan layar apa saja yang menggunakannya?

ST7789 adalah chip driver yang mengendalikan setiap piksel layar dan mengubah perintah dari mikrokontroler menjadi gambar. Di dalamnya terdapat memori frame 240x320 piksel; layar yang lebih kecil hanya menggunakan sebagian memori ini. Warna biasanya dikirim dalam format RGB565, yaitu 16 bit per piksel (5 bit merah, 6 bit hijau, 5 bit biru). Komunikasi berlangsung melalui SPI 4 kabel dan chip mampu menangani kecepatan clock sekitar 60 MHz; dalam praktiknya, 40 MHz merupakan nilai yang aman dengan ESP32. Pada kecepatan tersebut, satu frame penuh 240x240 berukuran 921.600 bit dan dikirim dalam sekitar 23 ms, sehingga kamu bisa melampaui 40 frame per detik.

LayarResolusiPenggunaan umum
1,14 inci135x240Board ESP32 dengan layar bawaan seperti TTGO T-Display
1,3 inci dan 1,54 inci240x240Jam tangan pintar, indikator kecil, antarmuka persegi
1,69 inci240x280Layar jam tangan dengan sudut membulat
1,9 inci170x320Bilah status yang panjang dan sempit
2,0 inci240x320Menu, grafik, dan layar game kecil
FiturNilai
Chip driverST7789 (Sitronix)
PanelIPS, sudut pandang lebar
Warna65 ribu (RGB565), chip mendukung hingga 262 ribu
AntarmukaSPI 4 kabel (SCK, MOSI, DC, CS) ditambah RESET
Catu daya3,3 V pada sebagian besar modul
Level logika3,3 V
ArusSekitar 20–40 mA termasuk lampu latar

Pin: tertulis SCL dan SDA, tetapi layar ini menggunakan SPI

Modul ST7789 1,3 inci yang murah berlabel GND, VCC, SCL, SDA, RES, DC, BLK; beberapa juga memiliki CS. Label SCL dan SDA paling sering membingungkan pemula: layar ini tidak menggunakan I2C, melainkan SPI. SCL sebenarnya adalah jalur clock SPI (SCK) dan SDA adalah jalur data (MOSI). Jika kamu menghubungkannya ke pin I2C ESP32, yaitu GPIO 21 dan 22, layar tidak akan pernah berfungsi. Cara kerja SPI dijelaskan dalam panduan Apa Itu SPI?.

Pin modulFungsiESP32 (TFT_eSPI)Arduino Uno (Adafruit)Raspberry Pi Pico
GNDGroundGNDGNDGND
VCCCatu daya3V33.3V3V3 (OUT)
SCLClock SPI (SCK)GPIO 18D13GP18
SDAData SPI (MOSI)GPIO 23D11GP19
RESResetGPIO 4D8GP21
DCPemilihan data atau perintahGPIO 2D9GP20
CSPemilihan chip (jika ada)GPIO 5D10GP17
BLKLampu latarGPIO 323.3VGP22
ST7789 merupakan chip 3,3 V. ESP32 dan Pico bisa dihubungkan langsung, tetapi pin Arduino Uno mengeluarkan 5 V, yang bisa merusak layar secara bertahap atau seketika. Jika kamu menggunakannya dengan Uno, pasang level shifter seperti 74HC4050 pada jalur SCL, SDA, RES, DC, dan CS. Selain itu, modul tanpa pin CS membutuhkan mode SPI 3; TFT_eSPI mengaturnya secara otomatis untuk ST7789, tetapi dengan library Adafruit, kamu harus meneruskan SPI_MODE3 ke init().

Menginstal TFT_eSPI dan mengatur User_Setup.h

Board pengembangan ESP32
ESP32: dengan SPI yang cepat dan RAM yang besar, inilah board terbaik untuk ST7789.

TFT_eSPI, yang ditulis oleh Bodmer, adalah salah satu library TFT tercepat untuk ESP32. Cari TFT_eSPI di Library Manager dan instal. Berbeda dari library lain, jenis layar dan pin tidak diatur dalam sketch-mu, melainkan di file User_Setup.h dalam folder library. File tersebut berada di Documents > Arduino > libraries > TFT_eSPI dan secara default dikonfigurasi untuk layar ILI9341. Buka dengan editor teks dan ganti isinya dengan yang berikut:

C++ (Arduino IDE)
1// User_Setup.h: ST7789 240x240 + ESP32 (dosyanın tamamını bununla değiştir / replace the whole file with this)
2#define ST7789_DRIVER                // sürücü yonga / driver chip
3#define TFT_WIDTH  240
4#define TFT_HEIGHT 240               // 240x320 ekranda 320 / 320 for a 240x320 panel
5
6#define TFT_MOSI 23                  // modüldeki SDA / SDA on the module
7#define TFT_SCLK 18                  // modüldeki SCL / SCL on the module
8#define TFT_CS    5                  // CS pini yoksa -1 / -1 if the module has no CS pin
9#define TFT_DC    2                  // veri-komut / data-command
10#define TFT_RST   4                  // reset (RES)
11#define TFT_BL   32                  // arka ışık (BLK) / backlight (BLK)
12#define TFT_BACKLIGHT_ON HIGH
13
14// #define TFT_RGB_ORDER TFT_BGR     // kırmızı ve mavi yer değiştirmişse aç / enable if red and blue are swapped
15// #define TFT_INVERSION_OFF         // renkler negatif görünüyorsa aç / enable if colours look inverted
16
17#define LOAD_GLCD                    // 8 px yazı tipi / 8 px font
18#define LOAD_FONT2                   // 16 px
19#define LOAD_FONT4                   // 26 px
20#define LOAD_FONT7                   // 48 px 7 segment rakam / 48 px 7-segment digits
21#define LOAD_GFXFF                   // Adafruit GFX yazı tipleri / Adafruit GFX fonts
22#define SMOOTH_FONT
23
24#define SPI_FREQUENCY 40000000       // 40 MHz; sorun olursa 27000000 / 40 MHz; drop to 27000000 if unstable
  1. Instal library TFT_eSPI dan ganti isi User_Setup.h dengan baris-baris di atas.
  2. Jika layarmu berukuran 240x320, atur TFT_HEIGHT ke 320; pada modul tanpa pin CS, atur TFT_CS ke -1.
  3. Hubungkan layar sesuai tabel: SCL ke GPIO 18, SDA ke GPIO 23, RES ke GPIO 4, DC ke GPIO 2, CS ke GPIO 5, BLK ke GPIO 32.
  4. Tutup dan buka kembali Arduino IDE; pengaturan library dibaca ketika kompilasi.
  5. Upload sketch pengujian pertama di bawah; kamu seharusnya melihat teks dan bentuk berwarna di layar.
Ketika kamu memperbarui library, User_Setup.h juga direset, dan suatu hari layarmu bisa tiba-tiba gelap. Simpan salinan file pengaturanmu di folder proyek, atau tambahkan file buatanmu sendiri ke folder User_Setups dan pilih di User_Setup_Select.h. Dengan begitu, kamu hanya perlu mengubah satu baris setelah pembaruan.

Pengujian pertama: teks, bentuk, dan warna

C++ (Arduino IDE)
1#include <TFT_eSPI.h>                // ayarlar User_Setup.h içinde / settings live in User_Setup.h
2
3TFT_eSPI tft = TFT_eSPI();
4
5void setup() {
6  tft.init();
7  tft.setRotation(0);                // 0-3: ekranı 90'ar derece döndürür / rotates in 90° steps
8  tft.fillScreen(TFT_BLACK);
9
10  tft.setTextDatum(MC_DATUM);        // metni ortadan hizala / centre-align text
11  tft.setTextColor(TFT_WHITE, TFT_BLACK);
12  tft.drawString("BlueGrays", 120, 30, 4);        // metin, x, y, yazı tipi / text, x, y, font
13  tft.drawString("ST7789 240x240", 120, 60, 2);
14
15  tft.fillRect(20, 90, 60, 60, TFT_RED);           // dolu kare / filled square
16  tft.fillCircle(120, 120, 30, TFT_GREEN);         // dolu daire / filled circle
17  tft.fillTriangle(170, 150, 200, 90, 230, 150, TFT_BLUE);
18  tft.drawRoundRect(10, 170, 220, 50, 10, TFT_YELLOW);
19
20  uint16_t orange = tft.color565(255, 140, 0);     // kendi rengin (RGB565) / your own colour (RGB565)
21  tft.setTextColor(orange, TFT_BLACK);
22  tft.drawString("R  G  B", 120, 195, 4);
23}
24
25void loop() {
26}

Pada TFT_eSPI, koordinat dimulai dari sudut kiri atas (0, 0), dan sudut kanan bawah layar 240x240 berada di (239, 239). Angka terakhir pada drawString(text, x, y, font) memilih font: 1 adalah font kecil 8 piksel, 2 berukuran 16 piksel, 4 berukuran 26 piksel, dan 7 merupakan font angka 7-segmen berukuran 48 piksel. setTextDatum(MC_DATUM) menempatkan titik tengah teks pada titik yang diberikan, sehingga sangat praktis untuk indikator dan jam. Warna ditentukan dengan nama siap pakai seperti TFT_RED dan TFT_GREEN, atau dengan warna pilihanmu sendiri menggunakan color565(r, g, b).

FungsiApa kegunaannya?
fillScreen(colour)Mengisi seluruh layar
drawPixel(x, y, colour)Satu piksel
drawLine / drawWideLineGaris tipis atau tebal
drawRect / fillRect / fillRoundRectPersegi panjang, berisi dan bersudut membulat
drawCircle / fillCircleLingkaran
fillTriangleSegitiga berisi
drawString / drawNumber / drawFloatTeks, bilangan bulat, dan bilangan desimal
setRotation(0-3)Memutar layar dalam langkah 90°

Animasi tanpa kedipan dengan sprite

Ketika kamu menggambar langsung ke layar, memperbarui sesuatu berarti menghapus versi lama terlebih dahulu, lalu menggambar versi baru. Di antara kedua langkah tersebut, layar kosong sebentar dan mata melihatnya sebagai kedipan. Sprite mengatasi masalah ini: kamu menggambar terlebih dahulu pada kanvas tak terlihat di RAM ESP32, lalu ketika frame sudah benar-benar siap, kamu mengirimkannya ke layar sekaligus dengan pushSprite(). Gambar yang baru setengah jadi tidak pernah muncul di layar.

Satu-satunya biaya penggunaan sprite adalah memori. Sprite berwarna 16-bit menggunakan 2 byte per piksel: sprite layar penuh 240x240 membutuhkan 115.200 byte, sedangkan 240x320 membutuhkan 153.600 byte. Meskipun ESP32 memiliki total RAM 520 KB, blok terbesar yang bisa dialokasikan sekaligus sering kali hanya sekitar 110 KB, sehingga sprite 16-bit layar penuh mungkin tidak muat pada board tanpa PSRAM. Solusinya adalah menurunkan kedalaman warna menjadi 8-bit dengan setColorDepth(8) (57,6 KB untuk 240x240), atau menggambar hanya area yang berubah, misalnya angka jam, sebagai sprite kecil. createSprite() mengembalikan nullptr jika tidak menemukan memori; memeriksa hasil ini mencegah kegagalan yang tidak terdeteksi.

Ukuran sprite16-bit8-bit
240x240 (layar penuh)115,2 KB57,6 KB
240x320 (layar penuh)153,6 KB76,8 KB
220x120 (area jam)52,8 KB26,4 KB
100x50 (satu nilai)10 KB5 KB

Proyek: indikator sensor analog

Sketch di bawah mengubah pembacaan potensiometer pada GPIO 34 menjadi nilai dari 0 hingga 100 dan menampilkannya dengan jarum pada busur 270 derajat, seperti indikator pada dasbor mobil. Tanda skala di atas 80 berwarna merah. Sebagai pengganti potensiometer, kamu bisa memasukkan pembacaan suhu, kelembapan, gas, atau kelembapan tanah ke fungsi yang sama. Karena sprite dikosongkan dan digambar ulang dari awal pada setiap frame, jarum bergerak mulus dan tidak pernah berkedip.

C++ (Arduino IDE)
1#include <TFT_eSPI.h>
2
3TFT_eSPI tft = TFT_eSPI();
4TFT_eSprite spr = TFT_eSprite(&tft);  // bellekteki çizim alanı / off-screen drawing area
5
6const int POT_PIN = 34;               // potansiyometre ya da sensör / potentiometer or sensor
7const int CX = 120, CY = 130, R = 100;
8float smooth = 0;
9
10void pointAt(float v, int radius, int &x, int &y) {   // 0-100 değeri yay üzerindeki noktaya çevir / value to a point on the arc
11  float a = radians(225 - v * 2.7);   // 270 derecelik yay / 270-degree arc
12  x = CX + cos(a) * radius;
13  y = CY - sin(a) * radius;
14}
15
16void drawGauge(int value) {
17  spr.fillSprite(TFT_BLACK);          // her kare temiz başlar / every frame starts clean
18  for (int v = 0; v <= 100; v += 5) { // ölçek çizgileri / scale ticks
19    int x0, y0, x1, y1;
20    pointAt(v, R, x0, y0);
21    pointAt(v, (v % 10 == 0) ? R - 14 : R - 7, x1, y1);
22    spr.drawLine(x0, y0, x1, y1, v >= 80 ? TFT_RED : TFT_LIGHTGREY);
23  }
24  int nx, ny;
25  pointAt(value, R - 20, nx, ny);
26  spr.drawWideLine(CX, CY, nx, ny, 4, TFT_ORANGE);  // ibre / needle
27  spr.fillCircle(CX, CY, 8, TFT_DARKGREY);
28
29  spr.setTextDatum(MC_DATUM);
30  spr.setTextColor(TFT_WHITE);
31  spr.drawNumber(value, CX, CY + 55, 7);            // 7 segment rakam / 7-segment digits
32  spr.drawString("%", CX + 62, CY + 62, 4);
33  spr.pushSprite(0, 0);               // tek seferde ekrana bas / push to the screen in one go
34}
35
36void setup() {
37  tft.init();
38  tft.fillScreen(TFT_BLACK);
39  spr.setColorDepth(8);               // 8 bit: 57,6 KB, 16 bit olsa 115 KB / 8-bit: 57.6 KB instead of 115 KB
40  if (spr.createSprite(240, 240) == nullptr) {      // bellek yetmezse / if memory runs out
41    tft.drawString("Sprite RAM yok", 10, 10, 2);
42    while (true) delay(100);
43  }
44}
45
46void loop() {
47  float raw = analogRead(POT_PIN) * 100.0 / 4095.0; // 0-100 aralığı / 0-100 range
48  smooth += (raw - smooth) * 0.2;                   // titremeyi yumuşat / smooth out jitter
49  drawGauge((int)smooth);
50  delay(20);                                        // yaklaşık 40 kare/sn / about 40 frames per second
51}

Fungsi pointAt() dalam kode mengubah nilai dari 0 hingga 100 menjadi titik pada busur: 0 sesuai dengan 225 derajat (kiri bawah) dan 100 dengan −45 derajat (kanan bawah). Karena sumbu y bertambah ke arah bawah layar, ada tanda minus di depan sinus. Variabel smooth menyaring fluktuasi kecil dari ADC; turunkan faktor 0.2 agar gerakan jarum lebih berat, atau naikkan agar responsnya lebih cepat. Untuk informasi lebih lanjut tentang ADC ESP32, lihat panduan Apa Itu ADC?.

Proyek: antarmuka jam berbasis NTP

Salah satu penggunaan ST7789 yang paling populer adalah jam meja. Sketch di bawah menghubungkan ESP32 ke Wi-Fi, mengambil waktu dari server NTP internet dalam zona waktu Turki, dan menampilkannya dengan angka 7-segmen berukuran besar. Kali ini, alih-alih sprite layar penuh, kita menggunakan sprite 220x120 yang hanya mencakup area jam; nama hari ditulis langsung ke layar karena hanya berubah sekali sehari. Ubah TZ_INFO sesuai zona waktumu; detail NTP dan pengaturan zona waktu ada di panduan jam NTP ESP32.

C++ (Arduino IDE)
1#include <WiFi.h>
2#include <time.h>
3#include <TFT_eSPI.h>
4
5const char* WIFI_SSID = "AgAdi";
6const char* WIFI_PASS = "Sifre123";
7const char* TZ_INFO   = "<+03>-3";               // Türkiye UTC+3 / Turkey UTC+3
8const char* DAYS[] = {"Pazar", "Pazartesi", "Sali", "Carsamba", "Persembe", "Cuma", "Cumartesi"};
9
10TFT_eSPI tft = TFT_eSPI();
11TFT_eSprite clockSpr = TFT_eSprite(&tft);        // yalnız saat bölgesi / clock area only
12int lastSecond = -1;
13
14void setup() {
15  tft.init();
16  tft.fillScreen(TFT_NAVY);
17  tft.setTextDatum(MC_DATUM);
18  tft.setTextColor(TFT_WHITE, TFT_NAVY);
19  tft.drawString("Wi-Fi...", 120, 120, 4);
20
21  WiFi.begin(WIFI_SSID, WIFI_PASS);
22  while (WiFi.status() != WL_CONNECTED) delay(300);
23  configTzTime(TZ_INFO, "pool.ntp.org", "time.cloudflare.com");
24
25  tft.fillScreen(TFT_NAVY);
26  clockSpr.createSprite(220, 120);               // 16 bit: 52,8 KB / 16-bit: 52.8 KB
27  clockSpr.setTextDatum(MC_DATUM);
28}
29
30void loop() {
31  struct tm t;
32  if (!getLocalTime(&t, 100) || t.tm_sec == lastSecond) return;   // saniye değişince çiz / draw on each new second
33  lastSecond = t.tm_sec;
34
35  char hm[6], sec[3], date[11];
36  strftime(hm, sizeof(hm), "%H:%M", &t);
37  strftime(sec, sizeof(sec), "%S", &t);
38  strftime(date, sizeof(date), "%d.%m.%Y", &t);
39
40  clockSpr.fillSprite(TFT_NAVY);
41  clockSpr.fillRoundRect(0, 0, 220, 120, 14, TFT_BLACK);
42  clockSpr.setTextColor(TFT_CYAN);
43  clockSpr.drawString(hm, 95, 45, 7);            // büyük saat:dakika / big hours:minutes
44  clockSpr.setTextColor(TFT_ORANGE);
45  clockSpr.drawString(sec, 195, 55, 4);          // saniye / seconds
46  clockSpr.setTextColor(TFT_WHITE);
47  clockSpr.drawString(date, 110, 100, 4);
48  clockSpr.pushSprite(10, 40);                   // titremeden güncelle / update without flicker
49
50  tft.setTextColor(TFT_YELLOW, TFT_NAVY);
51  tft.fillRect(0, 175, 240, 30, TFT_NAVY);
52  tft.drawString(DAYS[t.tm_wday], 120, 190, 4);  // gün adı / day name
53}

Jam hanya digambar ulang ketika detik berubah, sehingga selama loop() berputar, prosesor memiliki waktu untuk tugas lain. Font bawaan TFT_eSPI tidak memiliki karakter beraksen, jadi nama hari dalam bahasa Turki pada kode ditulis tanpa huruf khusus; kamu bisa menerjemahkannya ke bahasamu sendiri jika mau. Jika ingin huruf beraksen, kamu bisa membuat dan memuat font sendiri dengan fitur smooth font TFT_eSPI. Untuk menambahkan baris cuaca ke jam ini, cukup gabungkan dengan kode Open-Meteo dari panduan API cuaca ESP32.

ST7789 dengan Arduino Uno: Adafruit_ST7789

TFT_eSPI tidak bekerja pada Arduino Uno; di sini kamu menggunakan Adafruit ST7735 and ST7789 Library bersama Adafruit GFX. RAM Uno sebesar 2 KB bahkan tidak cukup untuk satu sprite, sehingga semuanya digambar langsung ke layar dan terasa jauh lebih lambat daripada ESP32. Namun, cara ini masih memadai untuk menu, angka, dan grafis sederhana. Pin SPI perangkat keras bersifat tetap: SDA (MOSI) terhubung ke D11 dan SCL (SCK) ke D13; kamu bisa memilih pin digital mana pun untuk CS, DC, dan RST.

C++ (Arduino IDE)
1#include <Adafruit_GFX.h>
2#include <Adafruit_ST7789.h>
3#include <SPI.h>
4
5#define TFT_CS   10                  // CS pini yoksa -1 / -1 if there is no CS pin
6#define TFT_DC    9
7#define TFT_RST   8
8// SDA (MOSI) -> D11, SCL (SCK) -> D13: donanım SPI / hardware SPI
9
10Adafruit_ST7789 tft = Adafruit_ST7789(TFT_CS, TFT_DC, TFT_RST);
11
12void setup() {
13  tft.init(240, 240);                // CS'siz modülde: tft.init(240, 240, SPI_MODE3) / without CS
14  tft.setRotation(0);
15  tft.fillScreen(ST77XX_BLACK);
16  tft.setTextColor(ST77XX_WHITE);
17  tft.setTextSize(3);
18  tft.setCursor(20, 20);
19  tft.print(F("BlueGrays"));
20  tft.setTextSize(2);
21  tft.setCursor(20, 70);
22  tft.print(F("A0 degeri:"));
23}
24
25void loop() {
26  int value = analogRead(A0);
27  tft.setTextColor(ST77XX_YELLOW, ST77XX_BLACK);   // arka plan rengi eski rakamı siler / background colour erases old digits
28  tft.setTextSize(5);
29  tft.setCursor(20, 110);
30  if (value < 1000) tft.print(' ');                 // basamak sayısı değişince boşluk / pad when digits shrink
31  if (value < 100)  tft.print(' ');
32  if (value < 10)   tft.print(' ');
33  tft.print(value);
34  delay(200);
35}

Sketch ini menunjukkan cara menghindari kedipan yang cocok untuk Uno: ketika setTextColor(textColour, backgroundColour) dipanggil dengan dua warna, setiap karakter digambar bersama latar belakangnya sendiri dan menimpa angka lama. Layar tidak perlu dikosongkan, dan angka berubah tanpa berkedip. Spasi ditambahkan di depan agar sisa angka lama tidak tertinggal ketika jumlah digit berkurang. Jika kamu ingin tampilan serupa pada panel sentuh 2,4 inci, panduan ILI9341 menggunakan logika yang sama.

ST7789 dengan Raspberry Pi Pico (MicroPython)

MicroPython tidak memiliki driver ST7789 bawaan, tetapi perintah chip ini cukup sederhana untuk membuat driver kecil sendiri. RAM Pico sebesar 264 KB cukup untuk frame buffer 115 KB yang mencakup seluruh layar 240x240. Kode di bawah menginisialisasi layar, menggambar teks dan bentuk ke buffer dengan modul framebuf MicroPython, lalu mengirim buffer melalui SPI sekaligus; sebuah persegi yang bergerak menunjukkan cara membuat animasi. Pengkabelan menggunakan bus SPI0: SCL ke GP18 dan SDA ke GP19.

MicroPython
1from machine import Pin, SPI
2import framebuf
3import time
4
5W, H = 240, 240
6spi = SPI(0, baudrate=40_000_000, polarity=1, phase=1, sck=Pin(18), mosi=Pin(19))  # SPI mod 3 / SPI mode 3
7cs = Pin(17, Pin.OUT, value=1)           # CS'siz modülde boşta kalır / unused on modules without CS
8dc = Pin(20, Pin.OUT)
9rst = Pin(21, Pin.OUT, value=1)
10bl = Pin(22, Pin.OUT, value=1)           # arka ışık açık / backlight on
11
12def cmd(c, data=None):                   # komut + isteğe bağlı veri / command + optional data
13    cs(0)
14    dc(0)
15    spi.write(bytes([c]))
16    if data:
17        dc(1)
18        spi.write(data)
19    cs(1)
20
21def init():
22    rst(0); time.sleep_ms(50); rst(1); time.sleep_ms(150)
23    cmd(0x01); time.sleep_ms(150)        # SWRESET: yazılım reseti / software reset
24    cmd(0x11); time.sleep_ms(120)        # SLPOUT: uykudan çık / exit sleep
25    cmd(0x3A, b'\x55')                   # COLMOD: 16 bit RGB565
26    cmd(0x36, b'\x00')                   # MADCTL: yön, RGB sırası / orientation, RGB order
27    cmd(0x21)                            # INVON: IPS paneller için / for IPS panels
28    cmd(0x13)                            # NORON: normal mod / normal mode
29    cmd(0x29); time.sleep_ms(50)         # DISPON: ekranı aç / display on
30
31def show(buf):
32    cmd(0x2A, bytes([0, 0, 0, W - 1]))   # CASET: sütun 0-239 / columns 0-239
33    cmd(0x2B, bytes([0, 0, 0, H - 1]))   # RASET: satır 0-239 / rows 0-239
34    cmd(0x2C, buf)                       # RAMWR: tamponu gönder / send the buffer
35
36def rgb(r, g, b):                        # RGB565, bayt sırası ekrana göre çevrilmiş / byte-swapped for the panel
37    c = ((r & 0xF8) << 8) | ((g & 0xFC) << 3) | (b >> 3)
38    return ((c & 0xFF) << 8) | (c >> 8)
39
40init()
41buf = bytearray(W * H * 2)               # 115.200 bayt / 115,200 bytes
42fb = framebuf.FrameBuffer(buf, W, H, framebuf.RGB565)
43
44x, dx = 0, 4
45while True:
46    fb.fill(rgb(0, 0, 40))
47    fb.text("BlueGrays", 84, 20, rgb(255, 255, 255))
48    fb.text("Pico + ST7789", 68, 40, rgb(0, 200, 255))
49    fb.rect(20, 200, 200, 20, rgb(255, 255, 0))
50    fb.fill_rect(20 + x, 100, 40, 40, rgb(255, 60, 0))   # kayan kare / moving square
51    show(buf)                            # tüm kareyi tek seferde gönder / send the whole frame at once
52    x += dx
53    if x <= 0 or x >= 160:
54        dx = -dx

Fungsi rgb() dalam kode mengatasi detail penting: framebuf menyimpan warna di memori dengan byte rendah terlebih dahulu, sedangkan ST7789 mengharapkan byte tinggi terlebih dahulu. Jika kamu tidak menukar byte-nya, merah terlihat biru dan biru terlihat kehijauan. Perintah 0x36 (MADCTL) mengatur orientasi layar dan urutan RGB atau BGR; jika kamu memutar gambar 180 derajat pada panel 240x240, gambar bergeser ke bagian bawah memori, sehingga kamu perlu menambahkan offset 80 piksel ke alamat baris. Jika lebih suka Arduino IDE, instal core arduino-pico pada Pico dan gunakan TFT_eSPI dengan pengaturan RP2040. Jika baru mengenal MicroPython, mulailah dari panduan dasar-dasar MicroPython.

Layar hitam dan masalah lain: tabel diagnosis

GejalaKemungkinan penyebabSolusi
Layar sepenuhnya hitam, lampu latar tidak menyalaBLK tidak terhubung atau LOWHubungkan BLK ke 3,3 V atau pin TFT_BL, dengan TFT_BACKLIGHT_ON diatur ke HIGH
Lampu latar menyala tetapi tidak ada gambarUser_Setup.h masih diatur ke ILI9341 atau direset oleh pembaruanPeriksa kembali baris ST7789_DRIVER dan pin
Lampu latar menyala, tidak ada gambar (modul tanpa CS)Mode SPI salahAtur TFT_CS ke -1; dengan Adafruit gunakan init(240, 240, SPI_MODE3)
Tidak ada respons sama sekaliSCL dan SDA terhubung ke pin I2C (21, 22)Hubungkan SCL ke GPIO 18 dan SDA ke GPIO 23
Kadang berfungsi, kadang berhentiPin reset mengambang, kabel panjang, atau SPI terlalu cepatHubungkan RES, pendekkan kabel, turunkan SPI_FREQUENCY ke 27 MHz
Warna terlihat seperti negatifPengaturan inversi warna tidak cocok dengan panelCoba TFT_INVERSION_OFF atau TFT_INVERSION_ON
Merah dan biru tertukarPanel menggunakan urutan BGRAktifkan baris TFT_RGB_ORDER TFT_BGR
Pita berderau pada sebagian layarTinggi salah (320 pada panel 240x240) atau offset rotasiAtur TFT_HEIGHT dengan benar, uji dengan setRotation
ESP32 mengalami crash pada tft.init()Ketidakcocokan dengan core ESP32 3.x telah dilaporkanCoba core 2.0.x dari Boards Manager atau beralih ke library LovyanGFX
Layar menjadi panas atau mati pada UnoLevel logika 5 VGunakan level shifter
Ketika mengatasi layar hitam, ubah satu hal setiap kali mencoba. Pertama, pastikan lampu latar menyala ketika hanya VCC, GND, dan BLK yang terhubung; lalu jalankan sketch pengujian pertama di atas. Jika lampu latar menyala dan layar tetap hitam, masalahnya hampir selalu terletak pada definisi driver, ukuran, atau pin di User_Setup.h.

Ide proyek ST7789

  • Jam meja pintar: Tampilkan waktu NTP, suhu ruangan dari BME280, dan cuaca hari ini dari internet pada satu layar.
  • Dasbor sensor: Sajikan pembacaan suhu, kelembapan, dan gas pada indikator berwarna; ubah latar belakang menjadi merah ketika ambang MQ-2 terlampaui.
  • Konsol game mini: Mainkan Snake, Pong, atau game luar angkasa dengan joystick; sprite membuat game tetap mulus.
  • Antarmuka pemutar musik: Tampilkan judul lagu, volume, dan bilah progres untuk DFPlayer Mini.
  • Grafik seperti osiloskop: Gambar nilai analogRead sebagai grafik berjalan dan amati bentuk sinyalnya.
  • Layar pembaca kartu: Tampilkan nama dan status akses kartu yang dibaca oleh RFID RC522 pada kartu berwarna.

Ketika dipadukan dengan ESP32, ST7789 mengubah layar seharga beberapa dolar menjadi antarmuka yang terlihat profesional. Setelah mengatur User_Setup.h dengan benar dan memahami konsep sprite, kamu bisa menggambar jam, indikator, menu, game, dan antarmuka lainnya tanpa kedipan. Untuk membandingkan layar yang cocok bagi proyekmu, lihat panduan jenis-jenis layar Arduino. Di aplikasi BlueGrays, kamu akan menemukan proyek cuaca, jam, pencampur warna, dan sensor parkir ESP32 dengan layar OLED dan LCD, dilengkapi skema rangkaian serta kode langkah demi langkah, dan kamu bisa mengubah proyek yang sama menjadi versi berwarna dengan ST7789.

Pertanyaan umum

Apakah ST7789 menggunakan I2C atau SPI?

ST7789 menggunakan SPI. Label SCL dan SDA pada modul menyesatkan: SCL merupakan jalur clock SPI (SCK), sedangkan SDA merupakan jalur data (MOSI). Pada ESP32, hubungkan keduanya ke GPIO 18 dan GPIO 23, bukan ke pin I2C 21 dan 22.

Mengapa layar ST7789-ku tetap hitam?

Penyebab paling umum adalah lampu latar (BLK) yang tidak terhubung, User_Setup.h masih memilih driver ILI9341, SCL dan SDA terhubung ke pin I2C, serta mode SPI yang salah pada modul tanpa CS. Pertama, pastikan lampu latar menyala, lalu periksa baris ST7789_DRIVER, TFT_WIDTH, TFT_HEIGHT, dan pin di User_Setup.h.

Apakah ST7789 bekerja dengan 5 V?

Chip ST7789 bekerja pada 3,3 V dan pin-nya tidak tahan 5 V. ESP32 dan Pico bisa dihubungkan langsung; dengan Arduino Uno, beri daya modul dari 3,3 V dan pasang level shifter pada jalur sinyal. Beberapa modul memiliki regulator, tetapi jalur datanya tetap 3,3 V.

Di mana file User_Setup.h TFT_eSPI?

User_Setup.h berada di dalam folder TFT_eSPI pada folder library Arduino-mu, biasanya Documents > Arduino > libraries > TFT_eSPI. Driver layar, resolusi, pin, dan kecepatan SPI ditentukan dalam file ini. File direset ketika library diperbarui, jadi simpan salinan pengaturanmu.

Apa itu sprite dan mengapa sprite mencegah kedipan?

Sprite adalah area gambar tak terlihat yang disimpan di RAM ESP32. Kamu menggambar semuanya di sana terlebih dahulu lalu mengirimkannya ke layar sekaligus dengan pushSprite() setelah siap, sehingga gambar peralihan yang sedang dihapus tidak pernah terlihat. Konsekuensinya adalah penggunaan memori: pada warna 16-bit, setiap piksel membutuhkan 2 byte.

Bisakah ST7789 digunakan dengan Arduino Uno?

Ya, dengan library Adafruit ST7789 dan Adafruit GFX, tetapi penggambarannya lambat karena RAM Uno sebesar 2 KB tidak cukup untuk sprite. Pin-nya bertegangan 5 V, jadi kamu perlu memasang level shifter di antaranya. Jika kamu menginginkan antarmuka berwarna yang mulus, ESP32 adalah pilihan yang jauh lebih baik.

Lihat semua proyek
HTTPClient + API Cuaca ESP32 (dengan Layar OLED SSD1306)
ES-32Mahir
Premium

HTTPClient + API Cuaca ESP32 (dengan Layar OLED SSD1306)

Di proyek ini, kita memakai ESP32 untuk melakukan panggilan REST API ke API cuaca (wttr.in) lewat internet dengan HTTPClient.h. Berbeda dengan versi LCD I2C sebelumnya, di sini kita memakai layar OLED SSD1306 (128×64), yang memungkinkan font besar, ikon vektor, dan tampilan visual yang kaya di satu layar. Tujuh ikon vektor untuk kondisi cuaca (cerah, berawan sebagian, berawan, hujan, salju, badai, berkabut) digambar ketika program berjalan (tanpa file bitmap).

4.3(10)
22
Layar LCD I2C ESP32 (16x2)
ES-17Menengah
Premium

Layar LCD I2C ESP32 (16x2)

Di proyek ini, kita menampilkan teks dengan menyambungkan layar LCD karakter 16x2 ke ESP32 lewat protokol I2C. Berkat I2C, kita bisa mengendalikan layar hanya dengan dua pin data (SDA dan SCL), sehingga tidak perlu memboroskan 6+ pin seperti pada sambungan paralel klasik. Kode mencetak pesan tetap di baris pertama dan penghitung yang naik setiap detik di baris kedua. Selain itu, kita menjalankan pemindai I2C di awal untuk mencetak alamat layar ke Serial Monitor (biasanya 0x27).

4.9(23)
40
Layar 7 Segmen 4 Digit TM1637 ESP32
ES-23Menengah
Premium

Layar 7 Segmen 4 Digit TM1637 ESP32

Kita mengendalikan modul layar 7 segmen 4 digit dengan driver TM1637 memakai ESP32. Hanya dengan 2 pin GPIO (CLK dan DIO), kita menjalankan penghitung dari 0 sampai 9999, mengatur tingkat kecerahan, dan menampilkan karakter titik dua (:) dalam format jam. Berkat library TM1637Display, mengendalikan angka, nilai hex, segmen, dan string sangat mudah.

4.7(20)
32
Deep Sleep ESP32: Hemat Baterai (OLED + Penghitung RTC RAM)
ES-33Mahir
Premium

Deep Sleep ESP32: Hemat Baterai (OLED + Penghitung RTC RAM)

Mode Deep Sleep ESP32 menurunkan konsumsi arus hingga ~10 µA dengan mematikan CPU dan sebagian besar periferal, sehingga sangat penting untuk perangkat IoT bertenaga baterai. Di proyek ini, kita memakai tiga sumber bangun yang berbeda: timer (15 detik), pin eksternal (EXT0, tombol GPIO 33), dan sentuhan (T0/GPIO 4). Variabel yang ditandai RTC_DATA_ATTR dipertahankan selama deep sleep; penghitung boot, penghitung bangun karena timer, dan penghitung bangun karena tombol terus dilacak.

4.3(10)
16
Penghitung Rakaat Salat ESP32 (HC-SR04 + OLED SSD1306 + 2 Tombol)
ES-34Mahir
Premium

Penghitung Rakaat Salat ESP32 (HC-SR04 + OLED SSD1306 + 2 Tombol)

Kadang lupa sudah berapa rakaat ketika salat? Proyek ini membuat penghitung rakaat yang diletakkan di samping sajadah dan menghitung sujudmu ketika kamu mendekatkan tangan. Sensor ultrasonik HC-SR04 mendeteksi tangan yang mendekat, OLED SSD1306 menampilkan jumlah rakaat, dan dua tombol memilih 2, 3, atau 4 rakaat serta mereset hitungan. State machine dengan jeda debounce 2,5 detik dan algoritma "tangan menjauh" mencegah sujud yang sama terhitung dua kali.

4.8(11)
14
Lampu Pencampur Warna ESP32 (3 Potensiometer + LED RGB + OLED)
ES-36Mahir
Premium

Lampu Pencampur Warna ESP32 (3 Potensiometer + LED RGB + OLED)

Lampu pencampur warna pintar: campur warna apa pun dengan memutar tiga potensiometer di ESP32! Ketika potensiometer merah, hijau, dan biru diputar, LED RGB katoda bersama berubah warna secara real-time. OLED SSD1306 menampilkan nilai setiap warna dalam rentang 0–255, bar pengisi, dan kode warna web HEX (seperti #FF8040). Studio warna mini yang mengajarkan teori warna RGB, pembacaan ADC, pengaturan kecerahan dengan PWM, dan desain layar I2C sekaligus.

4.7(6)
10
Sensor Parkir ESP32 (HC-SR04 + Bar 5 LED + Buzzer + OLED)
ES-38Mahir
Premium

Sensor Parkir ESP32 (HC-SR04 + Bar 5 LED + Buzzer + OLED)

Versi ESP32 dari sensor parkir mobil! Kita memakai sensor ultrasonik HC-SR04 untuk mengukur jarak ke benda di depannya. Semakin dekat jaraknya, bar 5 LED semakin penuh (hijau → kuning → merah) dan jeda bunyi bip buzzer semakin pendek. Ketika benda sudah sangat dekat (di bawah 10 cm), alarm berbunyi terus dan semua LED menyala. Layar OLED SSD1306 menampilkan jarak terkini dalam cm dengan font besar, pesan status (STOP / CAUTION / CLOSE / STOP! / DANGER), dan simulasi bar jarak.

14
Game Bola Pemukul - SSD1306
AR-86Menengah
Premium

Game Bola Pemukul - SSD1306

Satu bola, dua pemukul, dan kamu: kamu bermain tenis meja, salah satu video game paling awal, di layar OLED kecil.

4.5(47)
65