Raspberry Pi Zero 2 W ile SPI TFT Ekran Kurulum Rehberi

Merhaba! Bu rehberde, mini boyutuyla projelerimizin gözbebeği olan Raspberry Pi Zero 2 W ile SPI TFT (ILI9341) ekranı nasıl bağlayacağımızı, ekrana nasıl yazı yazdıracağımızı ve bu uygulamanın Raspberry Pi her açıldığında otomatik olarak nasıl başlayacağını adım adım öğreneceğiz.

Hiç gözünüz korkmasın; daha önce hiç Linux, terminal veya elektronik bağlantı yapmadıysanız bile bu dokümanı takip ederek başarıyla tamamlayabilirsiniz!

Günün sonunda ekranımızda tam olarak şöyle şık bir çıktı göreceğiz:

Nasuhcan TFT TEST
Raspberry Pi Zero 2 W
SPI ekran calisiyor
TFT OK

1. Kullanılan Donanımlar ve Ön Hazırlık

Projeye başlamadan önce masamızda şu malzemelerin olduğundan emin olalım:

• 1 adet Raspberry Pi Zero 2 W (Pinleri lehimlenmiş olmalıdır)
• 1 adet SPI TFT Ekran (Bu rehber, popüler ILI9341 sürücülü 240x320 ekranlar için hazırlanmıştır)
• 1 adet microSD kart (En az 8 GB)
• 1 adet 5V Güç Adaptörü (Raspberry Pi uyumlu)
• Dişi-Dişi Jumper Kablolar (Bağlantılar için)
• Kurulumu yapacağımız bir Bilgisayar

⚠️ Önemli Not: Bu rehberde varsayılan Raspberry kullanıcı adını pi, cihaz adını (hostname) ise ekran olarak kabul edeceğiz. Eğer kurulum sırasında farklı bir kullanıcı adı seçerseniz, komutlardaki /home/pi/ kısımlarını kendi kullanıcı adınıza göre (örn: /home/ahmet/) değiştirmeyi unutmayın!

2. İşletim Sistemi Kurulumu

2.1 Raspberry Pi Imager ile OS Yazma

Bilgisayarımıza Raspberry Pi Imager uygulamasını indirip açıyoruz.

• Device (Cihaz): Raspberry Pi Zero 2 W
• Operating System (İşletim Sistemi): Raspberry Pi OS Lite (32-bit) (Ekran kartı arayüzüne ihtiyacımız olmadığı için hafif olan Lite versiyonu seçiyoruz)
• Storage (Depolama): Bilgisayara taktığınız microSD kartınız.

2.2 Gizli Ayarları Yapılandırma (Çok Önemli!)

“Next” butonuna bastığınızda karşınıza “OS Customisation” (Ayarları Düzenle) seçeneği gelecek. Burayı mutlaka doldurmalıyız ki Raspberry’ye ekran veya klavye bağlamadan bilgisayarımızdan erişebilelim:

• Hostname: ekran
• Username: pi
• Password: Güçlü bir şifre belirleyin.
• Enable SSH: Kutucuğu işaretleyin ve “Use password authentication” seçeneğini seçin.
• Configure Wireless LAN: Ev/ofis Wi-Fi adınızı (SSID) ve şifresini yazın.
• Wireless LAN Country: TR
• Timezone: Europe/Istanbul

Ayarları kaydedip “WRITE” diyerek işletim sistemini karta yazdırın.

3. Raspberry Pi’ye SSH ile Uzaktan Bağlanma

• SD kartı bilgisayardan çıkarıp Raspberry Pi’ye takın ve güç adaptörünü bağlayın.
• İlk açılışta cihazın Wi-Fi’ye bağlanması ve kendini yapılandırması için 2–3 dakika bekleyin.
• Bilgisayarınızda Windows PowerShell (veya Mac kullanıyorsanız Terminal) uygulamasını açın ve şu komutu yazıp Enter’a basın:

ssh pi@ekran.local

• Eğer ilk kez bağlanıyorsanız Are you sure you want to continue connecting (yes/no)? sorusu gelecektir. yes yazıp Enter'a basın.
• Ardından Imager’da belirlediğiniz şifreyi girin (Yazarken şifre ekranda görünmez, bu normaldir, direkt yazıp Enter’layın).

💡 Bağlantı Hatası mı Alıyorsunuz? ekran.local çalışmazsa, modeminizin arayüzüne girerek Raspberry Pi'nin aldığı IP adresini (Örn: 192.168.1.45) bulun ve terminale ssh pi@192.168.1.45 yazarak bağlanmayı deneyin.

4. TFT Ekran Kablo Bağlantısı

🛑 DİKKAT: Kablo bağlantılarını yaparken Raspberry Pi’nin güç kablosu kesinlikle takılı olmamalıdır! Kısa devre cihazınıza zarar verebilir.

Raspberry Pi Zero’nun üzerindeki pinlerin bir fiziksel numarası (1'den 40'a kadar) bir de GPIO adı vardır. Aşağıdaki tabloyu dikkatlice takip ederek jumper kabloları tek tek bağlayın:

🎯 Yeni Başlayanlar İçin Altın İpuçları:

• Ekranınızda hem CS hem de T_CS pini görebilirsiniz. T_CS dokunmatik (Touch) içindir, bizim işimiz sadece görüntüyle olduğu için düz CS pinini bağlamalısınız. Başında T olanların hepsi dokunmatik içindir. İngilizce dokunmatik anlamıa gelen Touch kelimesinin baş harfinden gelmektedir.
• Dokunmatik için ayrıca pinlerin nasıl olacağını aşağıda anlattım.
• Yanlış pin bağlantısı yaparsanız ekranın sadece beyaz ışığı yanar ama görüntü gelmez. Bağlantıları iki kez kontrol edin.

Ayrıca internette aramayın diye Pi Zeronun Pin Outlarını aşağı koyuyorum.

Zero Pins

5. Raspberry Pi İçinde SPI Protokolünü Açma

Ekranın haberleşebilmesi için Raspberry’nin uyuyan SPI özelliğini uyandırmamız gerekiyor. Terminale şu komutu yazın:

sudo raspi-config

Karşınıza mavi bir arayüz çıkacak. Yön tuşlarını kullanarak şu adımları takip edin:

• Interface Options üzerine gelip Enter’a basın.
• SPI seçeneğini bulun ve Enter’layın.
• “Would you like the SPI interface to be enabled?” sorusuna Yes deyin.
• Gelen onay ekranında Enter yapıp ana menüden Finish diyerek çıkın.

Değişikliklerin aktif olması için cihazı yeniden başlatalım:

sudo reboot

1 dakika bekledikten sonra tekrar ssh pi@ekran.local ile bağlanın ve SPI'ın açılıp açılmadığını şu komutla test edin:

ls /dev/spidev*

Ekranda /dev/spidev0.0 /dev/spidev0.1 çıktılarını görüyorsanız, tebrikler! İlk büyük aşamayı geçtiniz.

6. Gerekli Yazılım Paketlerinin Kurulması

Python kodumuzun ekranla konuşabilmesi ve ekrana çizim yapabilmesi için sistem paketlerini güncelleyip gerekli kütüphaneleri yüklüyoruz. Terminale sırasıyla şu komutları yazın:

sudo apt update
sudo apt install -y python3-spidev python3-rpi.gpio python3-pil

• python3-spidev: SPI haberleşmesi için,
• python3-rpi.gpio: Raspberry pinlerini kontrol etmek için,
• python3-pil: Ekrana yazı, resim ve şekil çizmemizi sağlayan efsanevi Pillow kütüphanesi.

7. Python Test Kodunu Oluşturma

Şimdi kodlarımızı düzenli tutmak için bir klasör oluşturup içine giriyoruz:

mkdir -p /home/pi/tft-test
cd /home/pi/tft-test

Ardından nano adındaki terminal metin editörünü kullanarak boş bir Python dosyası açıyoruz:

nano tft_yazi_test.py

Aşağıdaki kod bloğunun tamamını kopyalayın ve terminal ekranına sağ tıklayarak (veya CMD+V ile) yapıştırın:

import time
import spidev
import RPi.GPIO as GPIO
from PIL import Image, ImageDraw

# Pin Tanımlamaları (GPIO Numaraları)
DC = 24
RST = 25
WIDTH = 240
HEIGHT = 320
GPIO.setmode(GPIO.BCM)
GPIO.setwarnings(False)
GPIO.setup(DC, GPIO.OUT)
GPIO.setup(RST, GPIO.OUT)
# SPI Kurulumu
spi = spidev.SpiDev()
spi.open(0, 0)
spi.max_speed_hz = 8000000
spi.mode = 0
def spi_write(data):
    for i in range(0, len(data), 4096):
        spi.xfer2(list(data[i:i + 4096]))
def command(cmd, data=None):
    GPIO.output(DC, GPIO.LOW)
    spi.xfer2([cmd])
    if data is not None:
        GPIO.output(DC, GPIO.HIGH)
        spi_write(bytearray(data))
def reset_display():
    GPIO.output(RST, GPIO.HIGH)
    time.sleep(0.1)
    GPIO.output(RST, GPIO.LOW)
    time.sleep(0.1)
    GPIO.output(RST, GPIO.HIGH)
    time.sleep(0.2)
def init_ili9341():
    reset_display()
    command(0xEF, [0x03, 0x80, 0x02])
    command(0xCF, [0x00, 0xC1, 0x30])
    command(0xED, [0x64, 0x03, 0x12, 0x81])
    command(0xE8, [0x85, 0x00, 0x78])
    command(0xCB, [0x39, 0x2C, 0x00, 0x34, 0x02])
    command(0xF7, [0x20])
    command(0xEA, [0x00, 0x00])
    command(0xC0, [0x23])
    command(0xC1, [0x10])
    command(0xC5, [0x3E, 0x28])
    command(0xC7, [0x86])
    command(0x36, [0x48])
    command(0x3A, [0x55])
    command(0xB1, [0x00, 0x18])
    command(0xB6, [0x08, 0x82, 0x27])
    command(0xF2, [0x00])
    command(0x26, [0x01])
    command(0x11)
    time.sleep(0.12)
    command(0x29)
    time.sleep(0.05)
def set_window(x0, y0, x1, y1):
    command(0x2A, [x0 >> 8, x0 & 0xFF, x1 >> 8, x1 & 0xFF])
    command(0x2B, [y0 >> 8, y0 & 0xFF, y1 >> 8, y1 & 0xFF])
    command(0x2C)
def image_to_rgb565(image):
    image = image.convert("RGB").resize((WIDTH, HEIGHT))
    pixels = image.load()
    buf = bytearray(WIDTH * HEIGHT * 2)
    index = 0
    for y in range(HEIGHT):
        for x in range(WIDTH):
            r, g, b = pixels[x, y]
            buf[index] = (r & 0xF8) | (g >> 5)
            buf[index + 1] = ((g & 0x1C) << 3) | (b >> 3)
            index += 2
    return buf
def display_image(image):
    set_window(0, 0, WIDTH - 1, HEIGHT - 1)
    GPIO.output(DC, GPIO.HIGH)
    spi_write(image_to_rgb565(image))
def draw_screen():
    # Siyah bir arka plan oluşturuyoruz
    img = Image.new("RGB", (WIDTH, HEIGHT), "black")
    draw = ImageDraw.Draw(img)
    # Üst mavi bant ve başlık
    draw.rectangle((0, 0, 240, 50), fill="blue")
    draw.text((15, 15), "NASUHCAN TFT TEST", fill="white")
    # Bilgi Metinleri
    draw.text((20, 80), "Raspberry Pi Zero 2 W", fill="white")
    draw.text((20, 115), "SPI ekran calisiyor", fill="green")
    draw.text((20, 150), "Driver: ILI9341", fill="yellow")
    draw.text((20, 185), "240 x 320 TFT", fill="cyan")
    # Durum Kutusu
    draw.rectangle((20, 235, 220, 295), outline="white")
    draw.text((35, 250), "Durum:", fill="white")
    draw.text((35, 275), "TFT OK", fill="green")
    return img
try:
    print("TFT baslatiliyor...")
    init_ili9341()
    print("Yazi ekrana gonderiliyor...")
    display_image(draw_screen())
    print("Tamam. TFT ekranda yazi gorunmeli.")
    print("Cikmak icin: CTRL + C")
    while True:
        time.sleep(1)
except KeyboardInterrupt:
    print("Cikis yapiliyor...")
finally:
    spi.close()
    GPIO.cleanup()

Dosyayı Kaydedip Çıkmak İçin:

• Klavye üzerinden **CTRL + O** tuşlarına basın.
• Aşağıda dosya adını onaylamak için **Enter**'a basın.
• Editörden çıkmak için **CTRL + X** tuşlarına basın.

8. İlk Testi Çalıştırma!

Heyecanlı dakikalar başladı. Yazdığımız kodu test etmek için şu komutu veriyoruz:

sudo python3 tft_yazi_test.py

Eğer terminalde şu yazıları gördüyseniz ve ekranınıza mavi-siyah test arayüzü geldiyse tebrikler, donanımınız ve kodunuz hatasız çalışıyor!

TFT baslatiliyor...
Yazi ekrana gonderiliyor...
Tamam. TFT ekranda yazi gorunmeli.
Cikmak icin CTRL + C

Testi sonlandırmak ve terminale geri dönmek için klavyeden **CTRL + C** yapabilirsiniz.

9. Cihaz Açıldığında Otomatik Başlatma (Systemd Servisi)

Projemizin bir bilgisayara bağlı kalmadan, Raspberry’ye güç verdiğimiz anda kendi kendine çalışmasını istiyoruz. Bunun için Linux’un servis mekanizmasını (systemd) kullanacağız.

Yeni bir servis dosyası açalım:

sudo nano /etc/systemd/system/tft.service

İçerisine şu konfigürasyonu yapıştırın:

[Unit]
Description=TFT Display Test
After=multi-user.target

[Service]
Type=simple
User=root
WorkingDirectory=/home/pi/tft-test
ExecStartPre=/bin/sleep 10
ExecStart=/usr/bin/python3 -u /home/pi/tft-test/tft_yazi_test.py
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

*CTRL + O -> Enter -> CTRL + X ile kaydedip çıkın.*

Şimdi bu yeni servisi sisteme tanıtalım ve aktif edelim:

sudo systemctl daemon-reload
sudo systemctl enable tft.service
sudo systemctl restart tft.service

Servisin başarıyla arka planda çalışıp çalışmadığını kontrol edelim:

sudo systemctl status tft.service

Ekranda yeşil renkle **Active: active (running) yazısını görmelisiniz. Bu ekrandan çıkmak için klavyeden `q`** tuşuna basmanız yeterlidir.

Nihai Test (Reboot)

Şimdi Raspberry’yi tamamen yeniden başlatalım:

sudo reboot

Raspberry’nin elektriğini kesmeyin, sadece bekleyin. Yaklaşık 15–20 saniye sonra, hiçbir terminal komutu yazmanıza gerek kalmadan ekranın kendiliğinden canlandığını göreceksiniz!

Dokunmatik Testi

Not:USE_IRQ=False yapınca kod dokunma var mı yok mu bakmadan sürekli koordinat okuyor. XPT2046 dokunmatik boşta iken de rastgele/son değerler verebilir. Bu yüzden olmayan basmayı algılıyor. T_IRQ pinini kullanmak, bu durumun önüne geçer. Dokunma yokken IRQ=1, dokununca IRQ=0 bekliyoruz.

import time
import spidev
import RPi.GPIO as GPIO

# XPT2046 / HR2046 touch controller test
# T_CS  -> CE1 -> /dev/spidev0.1
# T_IRQ -> GPIO17, opsiyonel

TOUCH_IRQ = 17

spi = spidev.SpiDev()
spi.open(0, 1)  # SPI0 CE1, yani /dev/spidev0.1
spi.max_speed_hz = 1000000
spi.mode = 0

GPIO.setmode(GPIO.BCM)
GPIO.setwarnings(False)

# IRQ bağlı değilse de sorun çıkmasın diye yine input yapıyoruz
GPIO.setup(TOUCH_IRQ, GPIO.IN, pull_up_down=GPIO.PUD_UP)

def read_adc(command):
    """
    XPT2046 12-bit ADC okuma.
    Çıktı yaklaşık 0 - 4095 arasında olur.
    """
    response = spi.xfer2([command, 0x00, 0x00])
    value = ((response[1] << 8) | response[2]) >> 3
    return value

def read_touch_raw():
    # Birkaç okuma alıp ortalama yapıyoruz
    xs = []
    ys = []

    for _ in range(5):
        x = read_adc(0xD0)
        y = read_adc(0x90)
        xs.append(x)
        ys.append(y)
        time.sleep(0.005)

    x_avg = sum(xs) // len(xs)
    y_avg = sum(ys) // len(ys)

    return x_avg, y_avg

try:
    print("Dokunmatik test basladi.")
    print("Ekrana dokununca X/Y degerleri degismeli.")
    print("Cikmak icin CTRL + C")
    print("")

    while True:
        x, y = read_touch_raw()

        # IRQ bağlıysa dokununca genelde 0 olur
        irq = GPIO.input(TOUCH_IRQ)

        print(f"X: {x:4d}   Y: {y:4d}   IRQ: {irq}")
        time.sleep(0.2)

except KeyboardInterrupt:
    print("Cikis yapiliyor...")

finally:
    spi.close()
    GPIO.cleanup()

10. Sık Karşılaşılan Hatalar ve Çözümleri

Eğer bir şeyler ters gittiyse panik yok. Yeni başlayanların en çok karşılaştığı durumlar ve çözümleri:

🔴 Ekran ışığı yanıyor ama görüntü tamamen beyaz/boş

• Çözüm: Büyük ihtimalle SPI hatlarında bir temassızlık veya yanlış pin eşleşmesi var. Özellikle CS, SDI (MOSI) ve SCK pinlerini şemaya bakarak tekrar kontrol edin. T_CS pini yerine CS pinini kullandığınızdan emin olun.

🔴 Ekran bir anlığına kararıyor (reset atıyor) ama yazı gelmiyor

• Çözüm: Bu iyiye işaret! RESET pininiz doğru çalışıyor demektir. Ancak Raspberry ekrana veri gönderemiyor. SPI veri hattını (SDI ve SCK) kontrol edin.

🔴 status=200/CHDIR Hatası Alıyorum

• Çözüm: Yazdığınız servis dosyası, Python kodunun bulunduğu klasörü bulamıyor demektir. Kodunuzun tam yolunu öğrenmek için terminale sudo find /home -name "tft_yazi_test.py" yazın. Çıkan yolu servis dosyanızdaki WorkingDirectory ve ExecStart kısımlarıyla güncelleyin.

🔴 ls /dev/spidev* komutu boş dönüyor

• Çözüm: SPI arayüzü sistemde aktif edilmemiş. sudo raspi-config adımını tekrarlayıp adımları doğru yaptığınızdan emin olun ve ardından cihazı mutlaka sudo reboot ile yeniden başlatın.

Umarım bu rehber ilk ekran projenizde size yardımcı olmuştur. Sorularınızı veya takıldığınız yerleri yorumlarda benimle paylaşabilirsiniz. Herkese keyifli kodlamalar!

Herkese İyi Mediumlar ve inşaa ederken eğlenmenizi dilerim. ƪ(˘⌣˘)ʃ