Czujnik ruchu PIR zauważa cię przy wejściu do pokoju, ale gubi, gdy tylko usiądziesz z książką, i światło gaśnie w najmniej odpowiednim momencie. Radar 24 GHz, taki jak moduł Hi-Link LD2410, wykrywa także człowieka, który się nie rusza, a tego właśnie potrzeba w gabinecie, łazience czy salonie. ESPHome obsługuje ten moduł bezpośrednio, więc do zbudowania czujnika obecności dla Home Assistanta wystarczy ESP32 i cztery przewody.

Podłączenie i konfiguracja zajmą pół godziny. Strojenie trwa dłużej i to od niego zależy, czy czujnik będzie pomagał, czy irytował.

Który LD2410 kupić

Komponent ld2410 w ESPHome obsługuje trzy odmiany o podobnych protokołach komunikacji: LD2410, LD2410B i LD2410C. W kartach katalogowych Hi-Linka wersje B i C mają te same podstawowe parametry: radar FMCW pracujący w paśmie 24-24,25 GHz, zasięg wykrywania regulowany od 0,75 do 6 m, kąt wykrywania ±60°, zasilanie 5 V z zasilacza o wydajności powyżej 200 mA oraz poziomy logiczne 3,3 V na porcie szeregowym i wyjściu OUT.

Przy samodzielnym montażu najbardziej liczy się złącze:

  • LD2410C ma wymiary 16 x 22 mm i wyprowadzenia w rastrze 2,54 mm, typowym dla płytek stykowych i przewodów połączeniowych. Najłatwiej go podłączyć.
  • LD2410B to pasek 7 x 35 mm z otworami w rastrze 1,27 mm, a według karty katalogowej moduł sprzedawany jest bez szpilek. Przyda się cienki przewód i trochę cierpliwości przy lutowaniu.

Wersje B i C mają też Bluetooth do konfiguracji przez aplikację HLKRadarTool na telefon. Domyślnie jest włączony, ale o tym niżej.

Podłączenie do ESP32

Moduł ma pięć wyprowadzeń: VCC, GND, TX, RX i OUT. Same dokumenty Hi-Linka podają ich kolejność różnie (karta katalogowa LD2410C wymienia TX, RX, OUT, GND, VCC, a dokument z protokołem komunikacji LD2410C stawia OUT na początku), więc kieruj się opisami nadrukowanymi na płytce, a nie schematem z internetu.

LD2410 ESP32
VCC 5V (często opisane jako VIN)
GND GND
TX GPIO16 (odbiór po stronie ESP)
RX GPIO17 (nadawanie po stronie ESP)
OUT opcjonalnie, dowolny wolny GPIO

Na co uważać:

  • Zasilaj moduł z 5 V, nie z 3,3 V. Karty katalogowe wymagają 5 V i ponad 200 mA. W większości płytek prototypowych z ESP32 zasilanych przez USB napięcie najprościej wziąć z wyprowadzenia 5V/VIN.
  • Konwerter poziomów nie jest potrzebny. Wejścia i wyjścia modułu pracują przy 3,3 V, tak samo jak ESP32.
  • TX łączysz z RX. Wyjście TX modułu idzie do wyprowadzenia, na którym ESP odbiera dane, i odwrotnie. Dokumentacja UART w ESPHome przypomina, że nazwy zależą od punktu widzenia, więc jeśli dane nie przychodzą, najpierw zamień te dwa przewody.
  • GPIO16 i GPIO17 to tylko przykład. Na ESP32 program ESPHome korzysta ze sprzętowych układów UART (oryginalne ESP32 ma trzy) i nada się dowolna para wyprowadzeń GPIO, które obsługują potrzebne tryby wejścia i wyjścia.
  • Tu lepiej sprawdzi się ESP32 niż ESP8266. LD2410 domyślnie komunikuje się z prędkością 256000 bodów, a ESPHome zdecydowanie zaleca do niego sprzętowy UART. Na ESP8266 program przechodzi na programową obsługę portu szeregowego, która przy wyższych prędkościach potrafi gubić dane, a jedyny pełny sprzętowy UART (UART0 na GPIO1/GPIO3 albo GPIO15/GPIO13) domyślnie zajmuje dziennik (logger).

Na wyjściu OUT pojawia się stan wysoki, gdy moduł kogoś wykryje. Nie musisz go podłączać, bo port szeregowy przekazuje tę samą informację i dużo więcej, ale jeśli przyda ci się drugi sygnał, odczytasz go zwykłym czujnikiem binarnym gpio.

Konfiguracja ESPHome

Poniższy plik to działający punkt wyjścia dla ESP32. Udostępnia obecność, odległości i ustawienia potrzebne do strojenia. Nazwy encji zostawiam po angielsku, bo na nich opiera się gotowa karta do strojenia z dokumentacji ESPHome, o której piszę dalej.

esphome:
  name: office-presence

esp32:
  board: esp32dev

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

logger:

api:
  encryption:
    key: !secret encryption_key

ota:
  platform: esphome

uart:
  id: ld2410_uart
  tx_pin: GPIO17
  rx_pin: GPIO16
  baud_rate: 256000
  parity: NONE
  stop_bits: 1

ld2410:
  uart_id: ld2410_uart

binary_sensor:
  - platform: ld2410
    has_target:
      name: Presence
    has_moving_target:
      name: Moving target
    has_still_target:
      name: Still target

sensor:
  - platform: ld2410
    moving_distance:
      name: Moving distance
    still_distance:
      name: Still distance
    detection_distance:
      name: Detection distance

number:
  - platform: ld2410
    timeout:
      name: Timeout
    max_move_distance_gate:
      name: Max move distance gate
    max_still_distance_gate:
      name: Max still distance gate

switch:
  - platform: ld2410
    engineering_mode:
      name: Engineering mode
    bluetooth:
      name: Bluetooth

button:
  - platform: ld2410
    restart:
      name: Restart
    factory_reset:
      name: Factory reset
    query_params:
      name: Query params

Co robią mniej oczywiste fragmenty:

  • parity: NONE i stop_bits: 1 to i tak wartości domyślne dla UART. Strona ESPHome o LD2410 wymaga dokładnie takich ustawień, a jeśli wpiszesz je jawnie, nikt ich przypadkiem nie zmieni.
  • has_target to encja do automatyzacji. Jest włączona, gdy moduł widzi cel ruchomy albo nieruchomy. Osobne encje dla ruchu i bezruchu przydają się głównie do diagnozowania problemów.
  • Każdy czujnik binarny ld2410 ma domyślnie filtr settle: 1000ms, a każdy zwykły czujnik filtr throttle_with_priority: 1000ms. Dzięki nim Home Assistant nie dostaje lawiny aktualizacji. Jeśli dopiszesz własne filtry (filters:), zastąpią one domyślny, więc żeby go zachować, dopisz go ręcznie.
  • Encje typu number, switch i button zmieniają ustawienia zapisane w samym module, prosto z Home Assistanta i bez ponownego wgrywania oprogramowania na ESP32.
  • Jest jeszcze lista wyboru baud_rate. Bez powodu jej nie ruszaj: po zmianie prędkości wszystkie czujniki przestają działać, dopóki nie poprawisz sekcji uart: i nie wgrasz konfiguracji ponownie.

Za pierwszym razem wgraj oprogramowanie przez USB, jak przy każdym nowym urządzeniu z ESPHome. Potem urządzenie pojawi się w Home Assistancie w menu Ustawienia > Urządzenia oraz usługi (Settings > Devices & services).

Jak działają strefy odległości

Radar dzieli swój zasięg na dziewięć stref odległości, od g0 do g8. W dokumentacji i nazwach encji nazywają się one bramkami („gate”). Domyślnie każda strefa ma 0,75 m głębokości. W liście wyboru distance_resolution w ESPHome możesz zmienić ją na 0,2 m, jeśli potrzebujesz drobniejszego podziału.

Każda strefa ma dwa progi w skali od 0 do 100: jeden dla ruchu, drugi dla nieruchomego celu. Gdy energia sygnału zmierzona w strefie przekroczy jej próg, moduł zgłasza wykrycie. ESPHome podaje takie wartości fabryczne:

Strefa Próg ruchu Próg bezruchu
0 50 0
1 50 0
2 40 40
3 30 40
4 20 30
5 15 30
6 15 20
7 15 20
8 15 20

Na co dzień liczą się jeszcze trzy ustawienia:

  • Max move distance gate i Max still distance gate (od 2 do 8, domyślnie 8) to ostatnia strefa, w której moduł w ogóle wykrywa ruch albo bezruch. Przy strefach po 0,75 m wartość 3 oznacza, że czujnik pomija wszystko dalej niż około 2,25 m. To najszybszy sposób na mały pokój przy korytarzu.
  • Timeout to liczba sekund, przez którą obecność pozostaje włączona po zniknięciu celu. Domyślna wartość to 5 s, czyli mało jak na sterowanie światłem. Zwiększ tę wartość, jeśli światło gaśnie przy każdej chwili bezruchu.

Strojenie w trybie inżynierskim

W trybie inżynierskim („Engineering mode”) moduł podaje energię ruchu i bezruchu osobno dla każdej strefy. Od razu widać, w której strefie radar „widzi” wentylator, kaloryfer albo korytarz sąsiada. Najpierw dopisz encje dla poszczególnych stref do istniejących wpisów - platform: ld2410 w sekcjach sensor: i number::

sensor:
  - platform: ld2410
    # ...wpisy z poprzedniego przykładu, a do tego:
    g0:
      move_energy:
        name: G0 move energy
      still_energy:
        name: G0 still energy
    g1:
      move_energy:
        name: G1 move energy
      still_energy:
        name: G1 still energy
    # i tak dalej dla g2-g8

number:
  - platform: ld2410
    # ...wpisy z poprzedniego przykładu, a do tego:
    g0:
      move_threshold:
        name: G0 move threshold
      still_threshold:
        name: G0 still threshold
    g1:
      move_threshold:
        name: G1 move threshold
      still_threshold:
        name: G1 still threshold
    # i tak dalej dla g2-g8

W bloku gX w sekcji number: oba klucze, move_threshold i still_threshold, są obowiązkowe. Procedura z dokumentacji ESPHome jest krótka: włącz tryb inżynierski, obserwuj czujniki energii, poprawiaj progi i powtarzaj, aż wynik będzie zadowalający, a na koniec wyłącz tryb inżynierski. Na stronie ESPHome o LD2410 jest też gotowa karta panelu ze wszystkimi tymi encjami. Wystarczy zamienić w niej DEVICE na nazwę swojego urządzenia.

W praktyce najwygodniej podzielić to na dwa etapy:

  1. Pusty pokój. Zostaw włączone to, co czujnik ma ignorować (wentylator, firankę poruszaną przez przeciąg z okna), wyjdź i przez kilka minut obserwuj każdą strefę. Każdy próg ustaw trochę powyżej najwyższej wartości, jaką zobaczyłeś.
  2. Ty, bez ruchu. Usiądź tam, gdzie zwykle siedzisz, i sprawdź, czy energia bezruchu w tej strefie nie spada poniżej progu. Spokojnie oddychający człowiek daje słaby sygnał, a przy zbyt wysokim progu bezruchu czujnik „zgubi” cię po upływie czasu podtrzymania.

Energia nie przekracza 100, a wykrycie wymaga wartości wyższej od progu, więc próg 100 w praktyce wyłącza strefę. Po strojeniu nie zostawiaj włączonego trybu inżynierskiego. ESPHome zaznacza, że zużywa on więcej zasobów, a Akamatis, firma sprzedająca czujniki na LD2410, ostrzega, że moduł wysyła wtedy dużo danych przez UART i encje mogą pokazywać stan „unknown”.

Gdzie zamontować: radar widzi więcej, niż myślisz

Fale radaru przechodzą przez płyty gipsowo-kartonowe, sufity i podłogi. Akamatis wymienia typowe źródła niespodziewanych wykryć: ludzi za ścianą albo w sąsiednim mieszkaniu, ruch piętro wyżej lub niżej, wodę płynącą w toalecie, wentylację i wentylatory sufitowe, zasłony i wiszące przedmioty. Tak po prostu działa radar, moduł nie jest uszkodzony.

  • Skieruj moduł na obszar, który cię interesuje, i ogranicz maksymalne strefy do głębokości pokoju.
  • Nie kieruj go wprost na wentylator ani zasłony. Jeśli nie da się tego uniknąć, znajdź ich strefę w trybie inżynierskim i podnieś w niej progi.
  • Jeśli czujnik nadal sam się włącza, pomóc może dodatkowy filtr. W długim wątku o LD2410 na forum Home Assistanta jeden z użytkowników z wentylatorem sufitowym opisał dobre wyniki po skalibrowaniu modułu, lekkim pochyleniu go w dół i dodaniu do czujnika obecności filtrów delayed_on: 5s i delayed_off: 10s.

Wyłącz Bluetooth, jeśli go nie używasz

Według dokumentacji Hi-Linka dla LD2410B Bluetooth jest w module domyślnie włączony, a aplikacja HLKRadarTool działa w zasięgu Bluetooth, do około 4 m. Przełącznik bluetooth w ESPHome też jest domyślnie włączony, a domyślne hasło Bluetooth, HiLink, podaje dokumentacja ESPHome. Jeśli wszystko konfigurujesz przez ESPHome, wyłącz przełącznik Bluetooth. Według dokumentu z protokołem LD2410B zmiana zadziała dopiero po ponownym uruchomieniu modułu i do tego służy przycisk Restart. Jeśli nadal korzystasz z aplikacji, ustaw własne sześcioznakowe hasło akcją bluetooth_password.set.

Czujnik w automatyzacjach

Podstawowa automatyzacja potrzebuje jednej encji: światło włącza się, gdy Presence przechodzi w stan włączony, i gaśnie, gdy się wyłącza. Czas podtrzymania ustawiasz liczbą Timeout, która jest zapisana w module i możesz ją zmienić z Home Assistanta w dowolnej chwili. Jeśli wolisz wygładzać stan po stronie ESPHome, dodaj filtr do has_target. Własne filtry zastępują domyślny settle, więc dopisz go z powrotem:

binary_sensor:
  - platform: ld2410
    has_target:
      name: Presence
      filters:
        - settle: 1000ms
        - delayed_off: 30s

Czujniki odległości traktuj jako przybliżenie. Przy strefach po 0,75 m ich odczyty zmieniają się dużymi skokami, więc automatyzacje lepiej opierać na obecności.

Gdy coś nie działa

  • Wszystkie encje mają stan „unknown”. Sprawdź TX i RX (zamień je), prędkość w sekcji uart: i zasilanie 5 V.
  • Czujniki przestały działać po zmianie ustawień. Jeśli zmieniłeś prędkość transmisji modułu, ustaw tę samą wartość baud_rate w sekcji uart: i wgraj konfigurację ponownie. Przycisk Factory reset przywraca w module ustawienia fabryczne.
  • Obecność nigdy się nie wyłącza. Coś w pokoju przekracza próg bezruchu w którejś strefie. Znajdź to w trybie inżynierskim i podnieś próg tej strefy albo zmniejsz Max still distance gate.
  • Obecność znika, gdy siedzisz bez ruchu. Próg bezruchu w strefie, w której siedzisz, jest za wysoki albo Timeout za krótki.
  • Przypadkowe błędy na ESP8266. To programowy UART, który nie nadąża przy 256000 bodów. Przenieś moduł na ESP32.