Arduino "fatal error: LiquidCrystal_I2C.h: No such file or directory" Hatası Nasıl Çözülür?

Arduino fatal error: LiquidCrystal_I2C.h: No such file or directory hatası, derleyicinin (kodu karta göndermeden önce kontrol eden program) #include <LiquidCrystal_I2C.h> satırında istenen header’ı (başlık dosyası; kütüphanenin sınıf ve fonksiyon tanımlarını içeren dosya) bulamadığını gösterir. En olası nedenler kütüphanenin kurulmaması, dosya adının birebir uyuşmaması, kütüphanenin yanlış veya iç içe klasörde bulunması ya da aynı ada yakın fakat farklı bir kütüphanenin seçilmesidir.

Buradaki #include (başlık dosyasını kaynak koda dahil eden yönerge) çözülemediği için derleme (kodun karta gönderilmeden önce işlenmesi) tamamlanmaz. Kod derlenip yüklenebildiği hâlde LCD boş kalıyorsa sorun; I2C adresi, ekran boyutu, kullanılan kütüphanenin API’si veya SDA/SCL, güç ve toprak bağlantılarıyla ilgili olabilir. Bu nedenle iki durumu aynı hata sanmamak gerekir.

Yazar: Berk Keskin

LiquidCrystal_I2C.h bulunamadı hatası ne anlama gelir?

Bu mesaj, LCD’nin fiziksel olarak yanıt vermediğini değil, derleyicinin istenen dosya için uygun bir kütüphane eşleşmesi bulamadığını anlatır. Arduino’nun derleme hata rehberinde bu hata türü için önce kütüphane adının doğru yazılması ve ilgili .h dosyasının uygun biçimde içe aktarılması önerilir.

• Kurulum eksikliği: LiquidCrystal_I2C kütüphanesi bilgisayarda kurulu değilse derleyici başlık dosyasını bulamaz.
• İsim uyuşmazlığı: Kodda LiquidCrystal_I2C.h yazarken dosyanın farklı adla kaydedilmesi veya başka bir başlık dosyasının kullanılması aynı sonucu doğurabilir.
• Klasör yerleşimi: ZIP arşivinden çıkarılan kütüphane yanlış ya da iç içe bir klasöre taşınmış olabilir. Dosyanın bilgisayarda görünmesi, Arduino IDE’nin onu kütüphane arama yolunda bulduğu anlamına gelmez. Arduino kütüphaneleri kök klasörde veya src altında farklı yapılara sahip olabilir.
• Çakışan seçim: Aynı başlık adıyla eşleşen birden fazla kütüphane varsa derleme çıktısında Multiple libraries were found, Used ve Not used satırlarını görebilirsin. Seçilen aday beklediğin başlık dosyasını veya API’yi sağlamıyorsa ek hatalar oluşabilir.

Bu aşamada I2C adresini değiştirmek ya da kabloları yeniden bağlamak, başlık dosyası bulunamadığı sürece sorunu çözmez. Öncelik, kodda kullanılan include adı ile kurulan kütüphanenin gerçekten aynı dosyayı sağladığını doğrulamaktır.

Library Manager ile kütüphaneyi kurup örnekle doğrulama

Arduino IDE 2’de kütüphaneyi önce Library Manager üzerinden aramak, ardından aynı kütüphanenin kendi örneğini açmak en düzenli kontroldür. Sol kenar çubuğundaki Library Manager simgesine tıklayabilir veya menüden Tools > Manage Libraries… yolunu izleyebilirsin.

1. Adayı ara: Arama alanına LiquidCrystal I2C yaz. Birden fazla sonuç varsa yalnızca isme bakma; açıklamayı, yazarı ve More info bağlantısının yönlendirdiği kaynak deposunu incele.
2. Header ve örnek uyumunu kontrol et: Arduino Library Registry’de kayıtlı johnrickman/LiquidCrystal_I2C deposunda LiquidCrystal_I2C.h dosyası ve examples klasörü bulunur. Aynı depodaki HelloWorld örneği de #include <LiquidCrystal_I2C.h> satırını kullanır. Bu, dosya adı ile örnek kodun uyumunu doğrulamak için bir referanstır; tüm LCD modülleri için evrensel kütüphane önerisi değildir.
3. Kur: Uyumlu adayı seçtikten sonra Install düğmesine tıkla ve kurulumun tamamlanmasını bekle. Bu adımda farklı bir kütüphanenin ZIP dosyasını aynı klasöre karıştırma.
4. Örneği aç ve derlemeyi dene: File > Examples > [kütüphane adı] yolundan aynı kütüphanenin LCD örneğini, örneğin HelloWorld dosyasını aç. Include satırını tekrar kontrol ettikten sonra Verify düğmesine bas. Böylece kartı çalıştırmadan önce yalnızca derleme aşamasını test edersin. Bazı kütüphaneler örnek içermeyebilir; bu durumda header ve örnek uyumunu bu yöntemle doğrulayamazsın.

Örnekte görülen I2C adresini, satır-sütun değerlerini veya init() ve begin() çağrılarını başka bir kütüphaneye doğrudan taşıma. Bu değerler ve API ayrıntıları seçilen kütüphaneye göre değişebilir.

1-2-3 teşhis akışı: kurulum, include adı ve klasör yapısı

LiquidCrystal_I2C.h hatasını çözerken üç olasılığı sırayla ele al: kütüphane kurulmamış olabilir, #include satırı gerçek dosya adıyla eşleşmeyebilir veya kütüphane IDE’nin taradığı konumda bulunmayabilir.

1. Kütüphanenin gerçekten kurulu olduğunu kontrol et. Arduino IDE’de Tools > Manage Libraries… yoluyla Library Manager’ı açıp LiquidCrystal_I2C aramasında seçtiğin kaydın kurulu olduğunu doğrula. Elle kurulum yaptıysan ZIP’ten çıkan ana klasör, etkin Sketchbook klasörünün içindeki libraries klasörüne doğrudan taşınmalı ve ardından IDE yeniden başlatılmalıdır. Örneğin libraries/LiquidCrystal_I2C-master/LiquidCrystal_I2C/ yapısında gerçek kütüphane kökü bir seviye içeride kalmış olabilir. Library Manager’dan gelen kopyayla elle eklenen kopya aynı anda varsa, birini geçici bir klasöre taşıyarak yalnızca tek aday bırak ve yeniden derle.
2. include adını gerçek header dosyasıyla karşılaştır. Kodda satır tam olarak #include <LiquidCrystal_I2C.h> olmalıdır. Dosya adını harf, büyük-küçük karakter, alt çizgi ve uzantı düzeyinde karşılaştır: LiquidCrystal_I2C.h ile LiquidCrystal_I2c.h veya LiquidCrystal_I2C.hpp aynı dosya değildir. Kütüphane klasörünün adıyla header dosyasının adının mutlaka aynı olduğunu varsayma; Arduino kütüphaneleri kaynak dosyalarını kökte ya da src klasörü altında taşıyabilir. -master veya -main eki tek başına hata değildir; asıl sorun gerçek kütüphane kökünün yanlış iç içe yerleştirilmesidir.
3. Klasör konumunu ve çakışan kopyaları incele. Kullanıcı kütüphaneleri için etkin Sketchbook içindeki libraries konumunu kontrol et. Kütüphane başka bir üst klasörün içinde kalmışsa, örneğin libraries/LiquidCrystal_I2C/LiquidCrystal_I2C/ biçimindeyse, kök klasörü bir üst seviyeye çıkar. Aynı header’ı içeren birden fazla aday varsa ayrıntılı derleme çıktısını aç: Windows/Linux’ta File > Preferences, macOS’ta Arduino IDE > Settings bölümünden derleme için ayrıntılı çıktıyı etkinleştir. Yeniden derlemede konsolda gösterilen kullanılan kütüphane klasörü beklediğin konum değilse kopyaları tek tek izole edip tekrar dene.

Tutarlı kısa kodla başlık dosyasını ve derlemeyi doğrulama

Bu doğrulama için tek referans olarak markub3327/LiquidCrystal_I2C deposundaki kütüphaneyi esas alıyoruz. Bu kütüphanenin header dosyasında üç parametreli constructor ile init(), backlight() ve setCursor() çağrıları tanımlıdır; kendi örneği de aynı başlangıç yaklaşımını kullanır.

#include <LiquidCrystal_I2C.h>

LiquidCrystal_I2C lcd(0x27, 20, 4);

void setup() {
  lcd.init();
  lcd.backlight();
  lcd.setCursor(0, 0);
  lcd.print("Header OK");
}

void loop() {
}

0x27 adresi ile 20, 4 sütun-satır değerleri bu testte seçilmiş örnek değerlerdir; her I2C LCD için evrensel kabul edilmemelidir. Kendi donanımının adresini, boyutunu ve kullandığın kütüphanenin örnek API’sini doğrulamadan bu değerleri değiştirme ya da başka bir kütüphanenin constructor’ını karıştırma.

Derleme başarılıysa fatal error: LiquidCrystal_I2C.h: No such file or directory tanısı ortadan kalkmalıdır. Bunun yerine constructor bulunamadı veya sınıfta init() metodu yok gibi yeni bir hata çıkarsa header dosyası bulunmuş, ancak kod ile seçilen kütüphanenin API’si eşleşmemiş olabilir. Kodun derlenmesi yalnızca dosya ve API çözümlemesini doğrular; LCD’nin fiziksel olarak görüntü vermesi ayrıca adres, bağlantı ve donanım koşullarına bağlıdır.

Yazar: Berk Keskin

Derleme hatası ile boş LCD ekranını birbirinden ayırma

fatal error: LiquidCrystal_I2C.h: No such file or directory, derleyicinin istenen başlık dosyasını bulamadığını gösterir; bu derleme turunda karta yükleme aşamasına geçilemez. Başlık dosyası bulunduğu hâlde kurucu veya metot hatası görüyorsan, kod başka bir LiquidCrystal_I2C uygulamasının API'sini varsayıyor olabilir. Kod doğrulanıp karta yüklendiği hâlde LCD boşsa, teşhis derleme katmanından çalışma zamanı ve donanım katmanına geçmelidir.

Boş ekranı “kütüphane hâlâ bozuk” diye yorumlama. Şu kontrolleri ayrı ayrı yap:

• Besleme ve toprak: Modül belgesindeki gereksinime göre VCC ve GND bağlantılarını, ayrıca kart ile LCD'nin ortak toprağını denetle.
• Kontrast: Modülde kontrast ayarı varsa, karakterlerin görünürlüğünü kontrol etmek için ayarı dikkatlice değiştir.
• SDA ve SCL: Başka bir kartın pin numarasını kopyalamak yerine, kullandığın kartın resmî pinout veya veri sayfasındaki I2C uçlarını kullan.
• I2C adresi: I2C taramasında bulunan adresin, kodda kullanılan değerle ve modülün belgeleriyle uyuştuğunu doğrula.
• LCD boyutu: Kurucudaki sütun ve satır değerlerini tahmin etmek yerine, elindeki ekranın gerçek boyutuna göre belirle.
• Başlatma API'si: init(), begin(...) veya başka bir başlangıç çağrısından hangisinin gerektiğini, yalnızca kurulu kütüphanenin örneğinden kontrol et.

Sık Sorulan Sorular

Kütüphane kurulu görünmesine rağmen LiquidCrystal_I2C.h neden bulunamıyor?

Kütüphanenin listede kurulu görünmesi, derleyicinin aradığı başlık dosyasını doğru yerde bulduğu anlamına gelmez. Etkin Sketchbook konumu farklı olabilir, elle kurulumdan sonra IDE yeniden başlatılmamış olabilir veya kurulan paket tam olarak bu dosyayı içermiyor olabilir. Arduino IDE'de yönetici ve ZIP ile kurulan kütüphaneler genellikle Sketchbook içindeki libraries klasöründe tutulur.

Include satırındaki dosya adı ile kütüphane klasörünün adı aynı olmak zorunda mı?

Hayır. #include satırı, kullanılacak başlık dosyasının adını belirtir; kütüphane klasörünün adı bununla birebir aynı olmak zorunda değildir. Önemli olan, başlık dosyasının Arduino'nun tanıdığı kütüphane yapısında ve erişilebilir bir konumda bulunmasıdır.

Elle kurulan kütüphane klasörünün iç içe olması nasıl fark edilir?

libraries klasöründeki dizini açtığında ilk seviyede yalnızca bir başka kütüphane klasörü görüyorsan, kurulum büyük olasılıkla iç içedir. İç klasörde src, başlık dosyası veya kütüphane kaynakları bulunuyorsa, asıl kütüphane kökü odur; onu doğrudan libraries klasörüne taşımalısın.

Başlık dosyası hatası düzeldikten sonra LCD neden boş görünebilir?

Derlemenin başarılı olması yalnızca kaynak kodun ve kütüphane bağımlılığının çözüldüğünü gösterir. I2C iletişiminin çalıştığını, adresin doğru olduğunu, bağlantıların sağlam olduğunu veya ekranın doğru başlatıldığını tek başına kanıtlamaz.

I2C adresi, LCD boyutu ve başlatma API'si neden her modülde aynı olmayabilir?

I2C adresi ve ekran boyutu fiziksel LCD modülüne bağlıdır; başlatma yöntemi ise kullandığın kütüphanenin uygulamasına bağlıdır. Bu nedenle başka bir projedeki adresi, satır-sütun değerini veya API çağrısını doğrudan kopyalamak yerine kendi modülünün belgelerini ve kurulu kütüphanenin örneğini esas almalısın.

Belirtiyi doğru katmana ayırdığında, aynı anda hem klasörleri hem kabloları değiştirmek yerine sorunu daha kısa ve kontrollü bir yoldan çözebilirsin.