ESPHome 2026.11 obsłuży czujnik odległości VL53L1X: do 4 m i kilka czujników na jednej magistrali I2C

Sterownik do czujnika czasu przelotu VL53L0X firmy ST jest w ESPHome od lat. Teraz własny sterownik dostaje też jego większy brat, VL53L1X. Platformę czujnika vl53l1x scalono 21 października 2026, w dniu premiery ESPHome 2026.10.0, więc trafi do wydania 2026.11. Tego samego dnia scalono też stronę dokumentacji.

VL53L1X mierzy odległość, licząc czas, w jakim wraca do niego impuls światła podczerwonego, a nowy sterownik odczytuje ją do 4 m. Kod odtwarza sekwencję rejestrów z uproszczonego sterownika ST (Ultra Lite Driver, ULD), przeniesioną do ESPHome, a nie dołączaną jako zewnętrzna biblioteka.

Konfiguracja

Podstawowy wpis wygląda tak:

sensor:
  - platform: vl53l1x
    name: Distance
    distance_mode: long      # short, medium or long
    timing_budget: 50ms      # one of the ULD budgets for the mode
    roi_width: 8
    roi_height: 8

Do wyboru są trzy tryby zasięgu (distance_mode). Sterownik ULD od ST zna tylko short i long. Tryb medium korzysta ze standardowych ustawień pomiaru z pełnego API VL53L1 od ST, a dopuszczalne czasy pomiaru (timing_budget) wylicza z tabeli trybu dalekiego. W każdym trybie można ustawić tylko te czasy, które dla niego istnieją.

Da się też ustawić obszar pomiaru (ROI, klucze roi_width i roi_height), przesunięcie wyniku i próg siły sygnału. ESPHome sprawdza je wszystkie przy walidacji konfiguracji, więc niemożliwe połączenie ustawień zostanie odrzucone, zanim cokolwiek wgrasz do urządzenia. Publikowane są tylko pomiary, które czujnik oznaczył jako prawidłowe.

Kilka czujników na jednej magistrali

Każdy VL53L1X startuje pod adresem I2C 0x29, więc dwa takie czujniki na jednej magistrali wchodzą sobie w drogę, dopóki któryś nie dostanie innego adresu. Sterownik rozwiązuje to tak samo jak vl53l0x. Każdy czujnik ma przypisany pin enable_pin, podłączony do jego wejścia XSHUT. Przy starcie wszystkie są trzymane w stanie resetu, a potem sterownik po kolei wybudza każdy z nich, sprawdza go i nadaje mu własny adres.

Przy sprawdzaniu konfiguracji czujniki są grupowane według magistrali I2C. Jeśli na jednej magistrali jest więcej niż jeden, każdy musi mieć enable_pin, żaden nie może zostać pod adresem 0x29, a adresy muszą być różne. Czujnik, który zawiedzie, zanim dostanie nowy adres, zostaje w stanie resetu, żeby nie zderzył się z następnym.

Szczegóły

Pomiary obsługuje pętla, która pozostaje wyłączona, dopóki nie ma czego odczytać. Sterownik odczekuje ustawiony czas pomiaru, a potem sprawdza bit gotowości danych i poddaje się po dwukrotności tego czasu plus 100 ms. Tabele rejestrów są zapisane w pamięci flash (PROGMEM), a do komponentu dołączono licencję BSD-3 od ST, która obejmuje wartości z ULD.