ST7789とESP32:TFT_eSPIでカラーIPSディスプレイ、スプライト、時計を使う
ST7789とESP32のガイドです。TFT_eSPIとUser_Setup.h、SCL/SDA表記のSPIピン、スプライトによるちらつかないメーターと時計、UnoでのAdafruit、Pico、黒い画面の対処を解説します。
ST7789とESP32の組み合わせは、小さなプロジェクトにスマートフォンの画面のような高品質のカラーインターフェースを付ける最も安価な方法です。ST7789はSitronix製のTFTドライバチップで、市販の1.3インチ240x240、1.54インチ240x240、1.69インチ240x280、2.0インチ240x320のIPSディスプレイの多くに搭載されています。IPSパネルのおかげで、どの角度から見ても色が鮮やかです。65K色、高解像度、高速なSPI通信により、OLEDやキャラクターLCDでは描けないメーター、グラフ、アニメーションを描画できます。
このガイドでは、TFT_eSPIライブラリでST7789をESP32に接続する方法、ライブラリで最も分かりにくいUser_Setup.hの設定方法、SCLやSDAと書かれていてもI2CではなくSPIである理由、スプライトを使ってちらつかずにアニメーションを表示する方法、アナログ式のセンサーメーターとNTPで動く時計画面の作り方を順を追って説明します。Arduino Uno向けのAdafruit_ST7789ライブラリ、Raspberry Pi Pico向けの外部ライブラリ不要のMicroPythonドライバ、画面が黒いままになる問題の原因もすべて取り上げます。

ST7789とは?どのディスプレイに使われている?
ST7789はディスプレイの各ピクセルを制御し、マイコンからのコマンドを画像に変えるドライバチップです。内部に240x320ピクセルのフレームメモリがあり、小さいディスプレイではその一部だけを使います。色は通常、RGB565形式、つまり1ピクセル16ビット(赤5ビット、緑6ビット、青5ビット)で送ります。通信は4線式SPIで行い、チップは約60 MHzのクロック速度まで対応します。実際にESP32で使う場合は40 MHzが安全な値です。この速度では240x240の1フレーム全体が921,600ビットで、約23 msで送信できるため、毎秒40フレームを超える表示が可能です。
| ディスプレイ | 解像度 | 代表的な用途 |
|---|---|---|
| 1.14インチ | 135x240 | TTGO T-Displayなど、画面を内蔵したESP32ボード |
| 1.3インチと1.54インチ | 240x240 | スマートウォッチ、小型メーター、正方形のインターフェース |
| 1.69インチ | 240x280 | 角が丸い時計の画面 |
| 1.9インチ | 170x320 | 細長いステータスバー |
| 2.0インチ | 240x320 | メニュー、グラフ、小型ゲーム画面 |
| 項目 | 値 |
|---|---|
| ドライバチップ | ST7789 (Sitronix) |
| パネル | IPS、広い視野角 |
| 色数 | 65K色(RGB565)、チップは最大262K色に対応 |
| インターフェース | 4線式SPI(SCK、MOSI、DC、CS)とRESET |
| 電源 | ほとんどのモジュールは3.3 V |
| ロジックレベル | 3.3 V |
| 電流 | バックライト込みで約20〜40 mA |
ピン:SCLとSDAという表記でも、このディスプレイはSPI
安価な1.3インチのST7789モジュールにはGND, VCC, SCL, SDA, RES, DC, BLKと表記され、一部にはCSもあります。SCLとSDAの表記は、初心者が最も混乱する点です。このディスプレイはI2CではなくSPIを使います。SCLは実際にはSPIのクロック線(SCK)、SDAはデータ線(MOSI)です。ESP32のI2CピンであるGPIO 21と22につないでも、ディスプレイは動きません。SPIの仕組みはSPIとは?のガイドで説明しています。
| モジュールのピン | 機能 | ESP32(TFT_eSPI) | Arduino Uno(Adafruit) | Raspberry Pi Pico |
|---|---|---|---|---|
| GND | グラウンド | GND | GND | GND |
| VCC | 電源 | 3V3 | 3.3V | 3V3 (OUT) |
| SCL | SPIクロック(SCK) | GPIO 18 | D13 | GP18 |
| SDA | SPIデータ(MOSI) | GPIO 23 | D11 | GP19 |
| RES | リセット | GPIO 4 | D8 | GP21 |
| DC | データかコマンドかを選択 | GPIO 2 | D9 | GP20 |
| CS | チップセレクト(搭載されている場合) | GPIO 5 | D10 | GP17 |
| BLK | バックライト | GPIO 32 | 3.3V | GP22 |
TFT_eSPIのインストールとUser_Setup.hの設定

Bodmerが開発したTFT_eSPIは、ESP32用のTFTライブラリの中でも特に高速です。ライブラリマネージャでTFT_eSPIを検索してインストールしてください。ほかのライブラリと異なり、ディスプレイの種類とピンはスケッチではなく、ライブラリフォルダー内のUser_Setup.hで設定します。ファイルはドキュメント > Arduino > libraries > TFT_eSPIにあり、初期状態ではILI9341ディスプレイ用に設定されています。テキストエディターで開き、内容を次のように置き換えてください。
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- TFT_eSPIライブラリをインストールし、User_Setup.hの内容を上の各行に置き換えてください。
- 240x320ディスプレイの場合はTFT_HEIGHTを320に設定します。CSピンのないモジュールではTFT_CSを-1に設定してください。
- 表に従って、SCLをGPIO 18、SDAをGPIO 23、RESをGPIO 4、DCをGPIO 2、CSをGPIO 5、BLKをGPIO 32に配線してください。
- 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}TFT_eSPIの座標は左上の(0、0)から始まり、240x240ディスプレイの右下は(239、239)です。drawString(text, x, y, font)の最後の数値でフォントを選びます。1は小さな8ピクセルのフォント、2は16ピクセル、4は26ピクセル、7は48ピクセルの7セグメント数字フォントです。setTextDatum(MC_DATUM)は指定位置に文字列の中心を合わせるので、メーターや時計にとても便利です。色はTFT_REDやTFT_GREENなどの定義済みの名前で指定するか、color565(r, g, b)で独自の色を作ります。
| 関数 | 機能 |
|---|---|
| fillScreen(colour) | 画面全体を塗りつぶす |
| drawPixel(x, y, colour) | 1ピクセルを描く |
| drawLine / drawWideLine | 細い線や太い線を描く |
| drawRect / fillRect / fillRoundRect | 長方形、塗りつぶした長方形、角丸の長方形を描く |
| drawCircle / fillCircle | 円を描く |
| fillTriangle | 塗りつぶした三角形を描く |
| drawString / drawNumber / drawFloat | 文字列、整数、小数を描く |
| setRotation(0-3) | 画面を90°刻みで回転する |
スプライトでちらつきのないアニメーション
画面へ直接描画すると、表示の更新には古い表示を消してから新しい表示を描く必要があります。この2つの処理の間に画面が一瞬空白になり、目にはちらつきとして見えます。スプライトはこの問題を解決します。まずESP32のRAMにある見えないキャンバスに描画し、フレームが完全に仕上がったらpushSprite()で一度に画面へ転送します。描きかけの画像がディスプレイに出ることはありません。
スプライトの唯一の代償はメモリです。16ビットカラーのスプライトは1ピクセルに2バイトを使います。全画面の240x240スプライトは115,200バイト、240x320なら153,600バイトです。ESP32には合計520 KBのRAMがありますが、連続した領域として確保できる最大ブロックは110 KB程度の場合が多く、PSRAMのないボードでは全画面の16ビットスプライトを確保できないことがあります。対処方法は、setColorDepth(8)で8ビットカラーに下げる(240x240で57.6 KB)か、時計の数字など変化する部分だけを小さなスプライトとして描くことです。createSprite()はメモリを確保できないとnullptrを返すため、戻り値を確認すれば、気づかないまま処理が失敗するのを防げます。
| スプライトのサイズ | 16ビット | 8ビット |
|---|---|---|
| 240x240(全画面) | 115.2 KB | 57.6 KB |
| 240x320(全画面) | 153.6 KB | 76.8 KB |
| 220x120(時計部分) | 52.8 KB | 26.4 KB |
| 100x50(1つの値) | 10 KB | 5 KB |
プロジェクト:アナログ式のセンサーメーター
以下のスケッチは、GPIO 34につないだポテンショメーターの読み取り値を0〜100に変換し、自動車のメーターのような270度の円弧上に針で表示します。80を超える目盛りは赤です。ポテンショメーターの代わりに、温度、湿度、ガス、土壌水分の測定値を同じ関数に渡すこともできます。スプライトはフレームごとに消去して最初から描き直すので、針が滑らかに動き、ちらつきません。
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}コード内のpointAt()関数は、0〜100の値を円弧上の点に変換します。0は225度(左下)、100は−45度(右下)に対応します。画面ではy軸の値が下向きに増えるため、正弦の前にマイナス符号を付けています。smooth変数はADCの小さな変動を取り除きます。係数0.2を下げると針の動きがゆっくりになり、上げると反応が速くなります。ESP32のADCについてはADCとアナログ-デジタル変換のガイドを参照してください。
プロジェクト:NTPで動く時計画面
ST7789の人気の用途の1つが卓上時計です。以下のスケッチはESP32をWi-Fiに接続し、インターネット上のNTPサーバーからトルコ時間で時刻を取得して、大きな7セグメント数字で表示します。今回は全画面のスプライトではなく、時計部分だけを覆う220x120のスプライトを使います。曜日名は1日に1回しか変わらないので、画面に直接書き込みます。使用するタイムゾーンに合わせてTZ_INFOを変更してください。NTPとタイムゾーンの設定の詳細はESP32のNTP時計のガイドにあります。
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}時計は秒が変わったときだけ描き直すため、loop()が繰り返される間、プロセッサーはほかの処理を実行できます。TFT_eSPIの内蔵フォントにはアクセント付き文字がないため、コード内のトルコ語の曜日名は特殊な文字を使わずに書かれています。必要に応じて使用する言語に翻訳してください。アクセント付き文字を表示したい場合は、TFT_eSPIのsmooth font機能で独自のフォントを作成して読み込めます。この時計に天気の行を追加するには、ESP32の天気APIのガイドにあるOpen-Meteoのコードを組み合わせるだけです。
Arduino UnoでST7789を使う:Adafruit_ST7789
TFT_eSPIはArduino Unoでは動作しません。ここではAdafruit ST7735 and ST7789 LibraryとAdafruit GFXを組み合わせて使います。Unoの2 KBのRAMではスプライトを1つも確保できないため、すべてを画面に直接描画し、ESP32より明らかに遅くなります。それでもメニュー、数字、簡単なグラフィックには十分です。ハードウェアSPIのピンは固定で、SDA(MOSI)はD11、SCL(SCK)はD13に接続します。CS、DC、RSTには任意のデジタルピンを選べます。
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}このスケッチはUnoに適したちらつき対策を示しています。setTextColor(textColour, backgroundColour)を2色指定して呼び出すと、各文字が背景と一緒に描画され、古い数字を上書きします。画面を消去する必要がなく、数字がちらつかずに変化します。桁数が減ったときに古い数字が残らないよう、先頭に空白を追加しています。2.4インチのタッチパネルで同様の表示を行いたい場合は、ILI9341 TFTディスプレイのガイドでも同じ考え方を使っています。
Raspberry Pi PicoでST7789を使う(MicroPython)
MicroPythonにはST7789の内蔵ドライバがありませんが、チップのコマンドは小さなドライバを自作できるほど簡単です。Picoの264 KBのRAMは、240x240ディスプレイ全体を覆う115 KBのフレームバッファを確保するのに十分です。以下のコードはディスプレイを初期化し、MicroPythonのframebufモジュールでバッファに文字と図形を描き、SPIでバッファを一度に送信します。動く正方形でアニメーションの方法を示します。配線にはSPI0バスを使い、SCLをGP18、SDAをGP19に接続します。
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コード内のrgb()関数は、重要な細部に対処しています。framebufはメモリに色を下位バイトから格納しますが、ST7789は上位バイトからのデータを要求します。バイトを入れ替えないと、赤は青に、青は緑がかった色に見えます。0x36 (MADCTL)コマンドは画面の向きとRGBまたはBGRの順序を設定します。240x240パネルで画像を180度回転すると、画像がメモリの下部へ移るため、行アドレスに80ピクセルのオフセットを加える必要があります。Arduino IDEを使いたい場合は、Picoにarduino-picoコアをインストールし、TFT_eSPIのRP2040用設定を使ってください。MicroPythonが初めてなら、MicroPythonの基本のガイドから始めてください。
黒い画面とその他の問題:トラブルシューティング表
| 症状 | 考えられる原因 | 対処方法 |
|---|---|---|
| 画面が完全に黒く、バックライトも点かない | BLKが未接続、またはLOW | BLKを3.3 VまたはTFT_BLピンに接続し、TFT_BACKLIGHT_ONをHIGHに設定する |
| バックライトは点くが画像が出ない | User_Setup.hがILI9341の設定のまま、または更新で初期化された | ST7789_DRIVERの行とピンを再確認する |
| バックライトは点くが画像が出ない(CSのないモジュール) | SPIモードが間違っている | TFT_CSを-1に設定する。Adafruitではinit(240, 240, SPI_MODE3)を使う |
| まったく反応しない | SCLとSDAをI2Cのピン(21、22)に接続している | SCLをGPIO 18、SDAをGPIO 23に接続する |
| 動いたり動かなかったりする | リセットピンが浮いている、配線が長い、SPIが速すぎる | RESを接続し、配線を短くし、SPI_FREQUENCYを27 MHzに下げる |
| 色がネガのように見える | 色の反転設定がパネルに合っていない | TFT_INVERSION_OFFまたはTFT_INVERSION_ONを試す |
| 赤と青が入れ替わっている | パネルがBGR順を使っている | TFT_RGB_ORDER TFT_BGRの行を有効にする |
| 画面の一部にノイズの帯が出る | 高さの設定が間違っている(240x240パネルで320)、または回転時のオフセットが原因 | TFT_HEIGHTを正しく設定し、setRotationでテストする |
| tft.init()でESP32がクラッシュする | ESP32コア3.xとの非互換性が報告されている | ボードマネージャで2.0.xのコアを試すか、LovyanGFXライブラリへ切り替える |
| Unoでディスプレイが熱くなる、または故障する | 5 Vのロジックレベル | レベル変換回路を使う |
ST7789のプロジェクトアイデア
- スマート卓上時計:NTP時刻、BME280で測った室温、インターネットから取得した今日の天気を1つの画面に表示します。
- センサーダッシュボード:温度、湿度、ガスの測定値をカラフルなメーターに表示し、MQ-2のしきい値を超えたら背景を赤にします。
- ミニゲーム機:ジョイスティックでスネーク、Pong、宇宙ゲームを遊べます。スプライトでゲームが滑らかに動きます。
- 音楽プレーヤー画面:DFPlayer Miniの曲名、音量、進行状況バーを表示します。
- オシロスコープ風グラフ:analogReadの値をスクロールするグラフに描き、信号の形を観察します。
- カードリーダーの画面:RFID RC522で読み取ったカードの名前とアクセス状態を、カラフルなカード形式で表示します。
ST7789はESP32と組み合わせることで、数ドルのディスプレイを本格的な見た目のインターフェースに変えます。User_Setup.hを正しく設定し、スプライトの考え方を理解すれば、時計、メーター、メニュー、ゲームなど、さまざまな画面をちらつきなく描けます。プロジェクトに合うディスプレイを比較するには、Arduinoのディスプレイの種類のガイドを参照してください。BlueGraysアプリには、OLEDやLCDを使うESP32の天気、時計、カラーミキサー、駐車センサーのプロジェクトが、手順に沿った回路図とコード付きで用意されています。同じプロジェクトをST7789でカラー版にすることもできます。
よくある質問
ST7789はI2Cですか、SPIですか?
ST7789はSPIを使います。モジュールのSCLとSDAという表記は紛らわしいものですが、SCLはSPIのクロック線(SCK)、SDAはデータ線(MOSI)です。ESP32ではI2Cのピン21と22ではなく、GPIO 18とGPIO 23に接続してください。
ST7789の画面が黒いままなのはなぜですか?
よくある原因は、バックライト(BLK)の未接続、User_Setup.hでILI9341ドライバが選択されたままになっていること、SCLとSDAをI2Cピンに接続していること、CSのないモジュールでSPIモードを間違えていることです。まずバックライトが点灯しているか確認し、次にUser_Setup.hのST7789_DRIVER、TFT_WIDTH、TFT_HEIGHT、ピンの設定行を確認してください。
ST7789は5 Vで動作しますか?
ST7789チップは3.3 Vで動作し、ピンに5 V耐性はありません。ESP32とPicoは直接接続できます。Arduino Unoではモジュールに3.3 Vで給電し、信号線にレベル変換回路を入れてください。レギュレーターを搭載するモジュールもありますが、データ線は依然として3.3 Vです。
TFT_eSPIのUser_Setup.hファイルはどこにありますか?
User_Setup.hはArduinoのライブラリフォルダー内のTFT_eSPIフォルダーにあり、通常はドキュメント > Arduino > libraries > TFT_eSPIです。このファイルでディスプレイのドライバ、解像度、ピン、SPI速度を定義します。ライブラリの更新時に初期化されるため、設定のコピーを保存してください。
スプライトとは何ですか?なぜちらつきを防げるのですか?
スプライトはESP32のRAMに置かれる、目に見えない描画領域です。最初にそこで描画をすべて済ませ、完成してからpushSprite()で一度に画面へ送るため、途中の消去された画像が表示されません。代償はメモリで、16ビットカラーでは1ピクセルに2バイト必要です。
ST7789はArduino Unoで使えますか?
はい。Adafruit ST7789とAdafruit GFXのライブラリで使えます。ただし、Unoの2 KBのRAMではスプライトを確保できないため、描画は遅くなります。ピンは5 Vなので、間にレベル変換回路を入れる必要があります。滑らかなカラーインターフェースを作るなら、ESP32のほうがはるかに適しています。
この記事を読んだ後に作れるプロジェクト
全プロジェクトを見る
ESP32 HTTPClient+天気API(SSD1306 OLED付き)
このプロジェクトでは、ESP32でHTTPClient.hを使い、インターネット経由で天気API(wttr.in)をREST APIとして呼び出します。前のI2C LCD版とは異なり、SSD1306 OLED(128×64)ディスプレイを使うため、大きな文字やベクターアイコンで、1つの画面に豊かな表現ができます。天気を表す7種類のベクターアイコン(晴れ、晴れ時々曇り、曇り、雨、雪、嵐、霧)を実行時に描画するので、ビットマップファイルは不要です。気温は中央に3倍の大きさの文字で表示します。

ESP32 I2C LCDディスプレイ(16x2)
このプロジェクトでは、16x2文字のLCDをI2CでESP32に接続して文字を表示します。I2Cならデータ用の2本のピン(SDAとSCL)だけで制御でき、従来のパラレル接続のように6本以上のピンを使わずに済みます。コードでは1行目に固定メッセージ、2行目に毎秒増えるカウンターを表示します。また、起動時にI2Cスキャナーを実行し、ディスプレイのアドレス(通常は0x27または0x3F)をシリアルモニタに表示します。

ESP32 TM1637 4桁7セグメントディスプレイ
TM1637ドライバーを搭載した4桁7セグメントディスプレイモジュールをESP32で制御します。2本のGPIOピン(CLKとDIO)だけで0~9999のカウンターを動かし、明るさを調整し、中央のコロン(:)を時計のように表示します。TM1637Displayライブラリを使えば、数値、16進数、セグメント、文字列を簡単に扱えます。

ESP32のディープスリープで節電(OLED + RTC RAMカウンター)
ESP32のディープスリープモードは、CPUとほとんどの周辺機器を停止し、消費電流を約10 µAまで抑えます。電池で動くIoT機器に欠かせない機能です。このプロジェクトでは、タイマー(15秒)、外部ピン(EXT0、ボタンはGPIO 33)、タッチ(T0/GPIO 4)の3種類の復帰方法を使います。RTC_DATA_ATTRを付けた変数はディープスリープ中も保持され、起動回数、タイマーによる復帰回数、ボタンによる復帰回数を継続して記録できます。復帰するたびにSSD1306 OLEDディスプレイに復帰理由と回数を表示します。

ESP32の礼拝ラカア数カウンター(HC-SR04 + SSD1306 OLED + ボタン2個)
礼拝中に何ラカア行ったか忘れてしまうことはありませんか?このプロジェクトでは、礼拝マットの横に置き、手を近づけると平伏の回数を数えるラカア数カウンターを作ります。HC-SR04超音波距離センサーで手の接近を検知し、SSD1306 OLEDディスプレイにラカア数を表示します。2個のボタンで2・3・4ラカアの選択とリセットができます。状態遷移による制御に2.5秒のデバウンス処理と手が離れたことを確認するアルゴリズムを組み合わせ、誤検知を防ぎます。同じ平伏を2回数えることはありません。

ESP32の調色ライト(可変抵抗3個 + RGB LED + OLED)
ESP32と3個の可変抵抗で、好みの色を作れるスマート調色ライトです。赤・緑・青の可変抵抗を回すと、カソードコモンのRGB LEDの色がリアルタイムに変わります。SSD1306 OLEDディスプレイには、各色の0~255の値、色の強さを示すバー、#FF8040などのWeb用HEXカラーコードをリアルタイムで表示します。小さなプロ仕様のカラースタジオとして、RGBの色の仕組み、ADCによるアナログ値の読み取り、PWMによる明るさの制御、I2Cディスプレイの表示設計を1つのプロジェクトで学べます。

ESP32駐車センサー(HC-SR04 + 5連LEDバー + ブザー + OLED)
車の駐車センサーをESP32で作ります!HC-SR04超音波センサーで前方の物体までの距離を測ります。距離が縮まるほど5連LEDバーが緑 → 黄 → 赤の順に点灯し、ブザーの鳴る間隔が短くなります。10 cm未満まで近づくとアラームが鳴り続け、すべてのLEDが点灯します。SSD1306 OLEDには現在の距離をcm単位の大きな文字で表示し、状態メッセージ(落ち着いて / 注意 / 接近 / 停止! / 危険)とLEDバーのシミュレーションも表示します。HC-SR04のpulseIn、複数のデジタル出力、ブザーを学べる定番のプロジェクトです。

パドルボールゲーム(SSD1306)
ボール1個とパドル2本で遊ぶ、ビデオゲームの原点の1つである卓球ゲームを、小さなOLEDディスプレイで楽しめます。2つのボタンで右のパドルを上下に動かします。左のパドルはコンピューターがボールを追いながら操作し、ボールを打つたびにブザーが短く鳴ります。先に9点を取ると勝ちです。その後、新しいゲームが自動で始まります。
ほかの記事
BlueGraysアプリ
この回路をスマホでステップごとに作る
回路図、コード、部品リストを1つの画面で確認できます。Arduino、ESP32、Picoのプロジェクトを500件以上用意しています。

