ESPHome'da desteklenmeyen sensör için custom external component yazıp derleme
ESPHome'un yerleşik sensör listesinde bulunmayan bir I2C sensörü custom (external) component olarak nasıl yazacağınızı, YAML tarafından nasıl çağıracağınızı ve firmware'i nasıl derleyeceğinizi adım adım anlatır. Örnek olarak genel bir I2C sicaklik sensörü üzerinden cpp kodu, register okuma döngüsü ve derleme hatalarının giderilmesi ele alınır.
Gerekenler
8 kalem- ESP32 geliştirme kartı (ESP32 DevKit veya benzeri)
- USB veri kablosu
- Home Assistant veya komut satırından ESPHome kurulumu (2024.12 ve üzeri önerilir)
- Custom component için metin editörü (VS Code önerilir)
- Sensörün veri sayfası (register haritası ve adresi için)
- I2C sensör kartı (ör. breakout üzerinde)
- Jumper kablolar (SDA/SCL, VCC, GND)
- Ölçüm için multimetre (bağlantı doğrulamak için, isteğe bağlı)
Giriş ve kapsam
ESPHome'un resmi bileşen listesi oldukça geniş ama bazen elinizdeki sensör listede yoktur ya da üreticinin niş bir protokolü vardır. Bu durumda iki yol var: eski usul custom anahtarı (artık kullanımdan kaldırılıyor ve yeni derlemelerde uyarı veriyor) ve önerilen modern yol olan external_components. Bu rehberde, sanal bir I2C sıcaklık sensörü üzerinden local (yerel dosya tabanlı) bir external component yazıp firmware'e dahil etmeyi anlatacağım. Aynı yöntem UART tabanlı sensörlerde de neredeyse birebir uygulanır.
Ön şart olarak temel C++ bilgisi ve ESPHome YAML yapısına aşinalık gerekli. Devre tarafı basit: sensörü ESP32'nin I2C hattına bağlıyoruz, tipik olarak GPIO21 (SDA) ve GPIO22 (SCL). Besleme 3.3 V olmalı; 5 V'luk sensörler için seviye dönüştürücü şart.
External component mantığı ve dosya yapısı
ESPHome derlerken external_components bloğundaki yolu tarar ve oradaki .h / .cpp dosyalarını otomatik derlemeye katar. Yerel proje dizininizde şu yapıyı kurun:
config/
my_sensor.yaml
components/
my_sensor/
__init__.py
sensor.py
my_sensor.h
my_sensor.cpp
__init__.py ve sensor.py dosyaları Python şemasıdır; ESPHome'a "bu component hangi YAML anahtarlarını kabul eder, hangi C++ sınıfına bağlanır" bilgisini verir. my_sensor.h ve .cpp ise asıl işi yapan kod.
Adımlar
-
Sensörün veri sayfasını açın. Gereken üç şey: I2C adresi (7 bit, ör. 0x48), ölçüm register'ı (ör. 0x00) ve ham verinin fiziksel değere çevrim formülü. Bu üçü olmadan component yazılamaz; uydurmayın, üreticinin veri sayfasına bakın.
-
sensor.pydosyasını yazın:
import esphome.codegen as cg
import esphome.config_validation as cv
from esphome.components import i2c, sensor
from esphome.const import CONF_ID, UNIT_CELSIUS, ICON_THERMOMETER, STATE_CLASS_MEASUREMENT, DEVICE_CLASS_TEMPERATURE
DEPENDENCIES = ["i2c"]
my_sensor_ns = cg.esphome_ns.namespace("my_sensor")
MySensor = my_sensor_ns.class_("MySensor", cg.PollingComponent, i2c.I2CDevice)
CONFIG_SCHEMA = sensor.sensor_schema(
MySensor,
unit_of_measurement=UNIT_CELSIUS,
icon=ICON_THERMOMETER,
accuracy_decimals=2,
device_class=DEVICE_CLASS_TEMPERATURE,
state_class=STATE_CLASS_MEASUREMENT,
).extend(cv.polling_component_schema("60s")).extend(i2c.i2c_device_schema(0x48))
async def to_code(config):
var = await sensor.new_sensor(config)
await cg.register_component(var, config)
await i2c.register_i2c_device(var, config)
__init__.py boş kalabilir ama dosya mevcut olmalı.
my_sensor.hdosyasında sınıfı tanımlayın:
#pragma once
#include "esphome/core/component.h"
#include "esphome/components/sensor/sensor.h"
#include "esphome/components/i2c/i2c.h"
namespace esphome {
namespace my_sensor {
class MySensor : public PollingComponent, public i2c::I2CDevice, public sensor::Sensor {
public:
void setup() override;
void update() override;
};
} // namespace my_sensor
} // namespace esphome
my_sensor.cppiçinde register okumasını yapın. Örnek: 16 bit imzalı değer, çözünürlük 0.0625 °C/LSB (yaygın bir format):
#include "my_sensor.h"
#include "esphome/core/log.h"
namespace esphome {
namespace my_sensor {
static const char *const TAG = "my_sensor";
void MySensor::setup() {
ESP_LOGCONFIG(TAG, "Setting up MySensor...");
}
void MySensor::update() {
uint8_t data[2];
if (!this->write_byte(0x00)) {
ESP_LOGW(TAG, "Register pointer write failed");
return;
}
if (!this->read_bytes_raw(data, 2)) {
ESP_LOGW(TAG, "Read failed");
return;
}
int16_t raw = (int16_t)((data[0] << 8) | data[1]);
float temperature = raw * 0.0625f;
ESP_LOGD(TAG, "Raw: %d -> %.2f C", raw, temperature);
this->publish_state(temperature);
}
} // namespace my_sensor
} // namespace esphome
- YAML dosyasında component'i çağırın:
external_components:
- source:
type: local
path: components
i2c:
sda: 21
scl: 22
scan: true
sensor:
- platform: my_sensor
name: "Kart Sıcaklığı"
update_interval: 60s
- Derleyin:
esphome compile my_sensor.yaml. İlk derleme 3-8 dakika sürer. Hata yoksaesphome run my_sensor.yamlile OTA veya USB üzerinden yükleyin.
Doğrulama
Loglarda scan: true sayesinde I2C adresi 0x48'de bir cihaz görünmeli. Görünmüyorsa bağlantı yanlıştır. Sensör cevap veriyorsa [my_sensor] Raw: ... -> ... C satırı gelir. Sensörü parmakla ısıtıp değerin yükseldiğini kontrol edin; beklenen ile ölçülen arasında sabit fark varsa çevrim katsayısını veri sayfasıyla tekrar karşılaştırın.
Sorun giderme
En sık hata, Python şemasındaki isim uyuşmazlığıdır: sensor.py içindeki sınıf adı ile header'daki C++ sınıf adı birebir aynı olmalı, namespace dahil. İkinci sık hata I2C read fonksiyonlarının karıştırılması: bazı sensörler register adresi yazıp ardından repeated-start ile okuma ister, write_byte + read_bytes_raw çifti çoğu basit sensörde yeter. Üçüncü sık hata: derleme kuyruğunda "undefined reference" görürseniz .cpp dosyası taranmamış demektir, components klasör yolunun YAML dosyasına göre doğru olduğunu doğrulayın. Ayrıca sensör 5 V ile çalışıyorsa SDA/SCL hatlarında seviye dönüştürücü olmadan ESP32 pinlerine zarar verebilirsiniz; bu kontrolü multimetreyle yapın.
Aynı kategoriden rehberler
Rehberler topluluk üyelerince yazılır ve editörlerce incelenir; yine de bilgilendirme amaçlıdır. Elektrik, batarya, gaz ve tesisat işlerinde yetkili bir uzmana danış. Hatalı veya tehlikeli bir yönlendirme görürsen “Raporla” ile bildir.

