HLK-LD2450: Głęboka integracja z ESPHome i Home Assistant

Głęboka integracja HLK-LD2450: sterowanie radarem milimetrowym za pomocą ESPHome i Home Assistant

Radar milimetrowy HLK-LD2450, pomimo swojej przystępności cenowej, jest potężnym czujnikiem obecności, zdolnym do wykrywania nie tylko ruchu, ale także precyzyjnych współrzędnych, prędkości i kąta do trzech celów jednocześnie. Jednak jego potencjał często pozostaje niewykorzystany z powodu ograniczeń standardowych rozwiązań. Ten artykuł opisuje podejście do pełnej integracji LD2450 w ekosystemie inteligentnego domu opartym na ESPHome i Home Assistant, zapewniając głęboką kontrolę nad wszystkimi parametrami sprzętowymi radaru za pośrednictwem jego protokołu binarnego, z pominięciem wszelkich pośrednich warstw.

Możliwości i ograniczenia HLK-LD2450 w standardowych scenariuszach

Czujnik LD2450 działa na częstotliwości 24 GHz, zapewniając zasięg wykrywania od 0.5 do 8 metrów i szeroki kąt widzenia ±60° w poziomie. Komunikacja z nim odbywa się poprzez UART z prędkością 256000 bodów, wykorzystując protokół binarny, co odróżnia go od urządzeń sterowanych komendami AT. Jedną z kluczowych cech sprzętowych są trzy konfigurowalne strefy, które można zdefiniować jako prostokąty w milimetrach. Radar jest w stanie samodzielnie filtrować cele, dostarczając dane tylko o tych, które znajdują się wewnątrz tych stref.

Główny problem, z którym borykają się użytkownicy podczas pracy z LD2450 „po wyjęciu z pudełka”, polega na ograniczonym dostępie do jego zaawansowanych funkcji. Większość gotowych rozwiązań koncentruje się wyłącznie na odczycie strumienia danych, ignorując możliwości dynamicznej konfiguracji. Sprzętowe strefy pozostają albo nienaruszone, albo są konfigurowane jednorazowo za pomocą specjalistycznego narzędzia HLK-LD2450_TOOL, często dostępnego tylko dla systemu Windows. Krytyczne parametry, takie jak czułość, próg energii, tryb pracy (Normal, High Sensitivity, Low Power, High Precision) i czas utrzymywania celu, są przechowywane w rejestrach urządzenia, ale zazwyczaj są niedostępne do zmiany z poziomu systemów automatyki domowej. To znacznie obniża elastyczność zastosowania czujnika w złożonych scenariuszach, gdzie wymagana jest adaptacyjna reakcja na zmieniające się warunki.

Cele głębokiej integracji:

Aby w pełni wykorzystać potencjał LD2450, sformułowano następujące kluczowe zadania, których nie da się rozwiązać standardowymi metodami:

Dynamiczne zarządzanie strefami: Możliwość zmiany współrzędnych i rozmiarów stref sprzętowych bezpośrednio z Home Assistant. Pozwala to dostosować obszar wykrywania do różnych scenariuszy, na przykład do trybu nocnego lub w przypadku zmiany układu mebli.
Precyzyjna regulacja czułości: Regulacja czułości radaru, progu energii, czasu utrzymywania celu i filtra prędkości w celu minimalizacji fałszywych alarmów i optymalizacji pracy czujnika w konkretnych warunkach.
Przełączanie trybów pracy: Zmiana trybów Normal, High Sensitivity, Low Power, High Precision w celu dostosowania do wymagań dotyczących zużycia energii lub precyzji.
Zarządzanie częstotliwością odświeżania: Konfiguracja częstotliwości odbierania danych w celu zachowania równowagi między szybkością reakcji a obciążeniem systemu.
Zapisywanie konfiguracji: Możliwość zapisu zmienionych ustawień do wewnętrznej pamięci radaru w celu ich zachowania po odłączeniu zasilania.
Monitorowanie wielu celów: Odbieranie danych o trzech celach jednocześnie z ich współrzędnymi w czasie rzeczywistym, co jest kluczowe dla złożonych scenariuszy obecności.

Zalety natywnego komponentu ESPHome i przejścia na ESP-IDF

W celu realizacji wymienionych możliwości opracowano natywny komponent ld2450 dla ESPHome. Takie podejście pozwala na bezpośrednią interakcję z UART czujnika, wysyłanie komend binarnych i przetwarzanie odpowiedzi bez żadnych pośrednich protokołów czy abstrakcji. Bezpośredni dostęp do rejestrów zapewnia pełną kontrolę nad urządzeniem, przekształcając je z „czarnej skrzynki” w w pełni zarządzalny sensor.

Kluczowym aspektem stabilnej pracy przy wysokich prędkościach UART (256000 bodów) była migracja z frameworka Arduino na ESP-IDF. Framework Arduino, choć wygodny do szybkiego prototypowania, często wykazuje niestabilność podczas pracy z UART przy takich prędkościach, co prowadzi do utraty danych lub błędów komunikacji. Przejście na ESP-IDF przyniosło następujące korzyści:

Zwiększona stabilność UART: ESP-IDF zapewnia bardziej niezawodną i przewidywalną pracę z peryferiami, co jest kluczowe dla szybkiej transmisji danych z radaru.
Optymalizacja zasobów: Firmware zbudowany na ESP-IDF zajmuje mniej miejsca w pamięci flash (około 17%) i zużywa mniej pamięci RAM. To uwalnia zasoby ESP32 do wykonywania innych zadań, zwiększając ogólną wydajność systemu.
Perspektywiczność: ESPHome aktywnie przechodzi na ESP-IDF jako domyślny dla swoich komponentów, co czyni ten wybór strategicznie słusznym i zapewnia kompatybilność z przyszłymi aktualizacjami platformy.

Szczegółowa analiza protokołu binarnego i zarządzanie rejestrami

Interakcja z HLK-LD2450 odbywa się poprzez wysyłanie specyficznych komend binarnych. Każda komenda ma ściśle określoną strukturę:

Header: FD FC FB FA
Length: 2 bajty (little-endian)
Command: 2 bajty
Data: N bajtów
Footer: 04 03 02 01

Przykłady komend do konfiguracji kluczowych parametrów:

Ustawienie czułości (komenda 0x64): Ten parametr pozwala regulować reakcję radaru na wykrywanie obiektów w ośmiu różnych zakresach odległości. Elastyczna regulacja czułości minimalizuje fałszywe alarmy i optymalizuje pracę czujnika w zależności od otoczenia.

```c

uint8_t cmd_sensitivity[] = {

0xFD, 0xFC, 0xFB, 0xFA,

0x0A, 0x00,

0x64, 0x00,

sens, sens, sens, sens, sens, sens, sens, sens, // 8 wartości czułości

0x04, 0x03, 0x02, 0x01

};

```

Konfiguracja progu energii (komenda 0x60): Próg energii służy do filtrowania słabych odbić, które mogą być spowodowane niewielkimi zakłóceniami lub bardzo małymi obiektami. Zwiększenie tego progu zmniejsza prawdopodobieństwo fałszywych alarmów.

```c

uint8_t cmd_energy[] = {

0xFD, 0xFC, 0xFB, 0xFA,

0x04, 0x00,

0x60, 0x00,

(uint8_t)(energy & 0xFF),

(uint8_t)((energy >> 8) & 0xFF),

0x04, 0x03, 0x02, 0x01

};

```

Analogicznie, za pośrednictwem protokołu binarnego, konfigurowane są inne krytyczne parametry:

Czas utrzymywania celu (komenda 0x61): Określa, jak długo radar będzie informował o obecności celu po jego zniknięciu ze strefy wykrywania.
Filtr prędkości (komenda 0x62): Pozwala ignorować obiekty poruszające się z prędkością poniżej zadanego progu, co jest przydatne do odrzucania powolnych, nieistotnych ruchów.
Tryb pracy (komenda 0x65): Przełączanie między trybami Normal, High Sensitivity, Low Power, High Precision w celu optymalizacji pod kątem konkretnych zadań.
Częstotliwość odświeżania (komenda 0x66): Ustawienie częstotliwości, z jaką radar przesyła dane o celach.

Wszystkie te ustawienia są zintegrowane z Home Assistant i mogą być zmieniane za pośrednictwem interfejsu użytkownika. Po wprowadzeniu zmian wystarczy nacisnąć przycisk „Zapisz konfigurację w radarze”, aby nowe parametry zostały zapisane w pamięci EEPROM czujnika i działały nawet po ponownym uruchomieniu.

Rozszerzona konfiguracja stref sprzętowych i śledzenie wielu celów (Multi-Target Tracking)

LD2450 oferuje możliwość zdefiniowania do trzech sprzętowych stref wykrywania. Każda strefa to prostokąt, zdefiniowany przez współrzędne (X1, Y1, X2, Y2) w milimetrach względem czujnika, a także przez limit czasu obecności. Radar przetwarza dane na poziomie sprzętowym, odrzucając cele znajdujące się poza zdefiniowanymi strefami, co zmniejsza obciążenie mikrokontrolera i zwiększa precyzję wykrywania.

Przykład kaskadowej konfiguracji stref według głębokości:

Strefa 1 (bliska): Obejmuje obszar 2 m × 0.75 m na głębokości 250–1000 mm. Idealna do wykrywania obiektów w bezpośrednim sąsiedztwie.
Strefa 2 (średnia): Rozszerza zasięg do 4 m × 2 m na głębokości 1000–3000 mm. Wykorzystywana do szerszej kontroli przestrzeni.
Strefa 3 (daleka): Zajmuje 6 m × 3 m na głębokości 3000–6000 mm. Umożliwia monitorowanie odległych obszarów.

Współrzędne i limity czasowe stref są w pełni dostępne do konfiguracji poprzez Home Assistant jako encje typu number. Przewidziano przyciski do zastosowania stref domyślnych oraz do ich zapisania z późniejszym ponownym uruchomieniem radaru.

Domyślnie LD2450 może dostarczać dane tylko o jednym celu. Aby śledzić wiele obiektów, należy aktywować tryb Multi-Target za pomocą specjalnej komendy. Po włączeniu tego trybu radar zaczyna przesyłać informacje o trzech oddzielnych celach. Ważne jest, aby pamiętać, że w trybie Multi-Target częstotliwość odświeżania danych jest ograniczona do 10 Hz, a minimalny interwał odpytywania czujników wynosi 100 ms. Konfiguracja ESPHome zawiera sprawdzenia, które zapobiegają naruszaniu tych limitów w aktywnym trybie Multi-Target.

Dla każdego wykrytego celu dostępne są następujące dane:

X, Y: Współrzędne celu w milimetrach.
Speed: Prędkość ruchu celu.
Angle: Kąt do celu.
Resolution: Rozdzielczość wykrywania.

Wszystkie te parametry są przesyłane do Home Assistant jako oddzielne sensory, co pozwala na szczegółową analizę położenia i ruchu obiektów w przestrzeni.

Wizualizacja i praktyczne zastosowanie w Home Assistant

Integracja z Home Assistant nie ogranicza się tylko do ustawień. Do wizualizacji danych wykorzystywana jest karta Plotly (dostępna przez HACS), która pozwala przedstawić wykryte cele w postaci punktów, a skonfigurowane strefy – w postaci półprzezroczystych prostokątów. Obszar pokrycia radaru jest wyświetlany linią przerywaną, zapewniając pełny obraz aktualnego stanu czujnika. Wizualizacja odświeża się co kilka sekund, co jest konfigurowalne przez użytkownika.

Lista konfigurowalnych parametrów z Home Assistant:

Czułość radaru: Zakres 0–9.
Próg energii: Zakres 100–10000.
Czas utrzymywania celu: Zakres 0–60 sekund.
Filtr prędkości: Zakres 0–100 cm/s.
Tryb pracy: Normal, High Sensitivity, Low Power, High Precision.
Częstotliwość odświeżania: 1–20 Hz (w trybie Multi-Target do 10 Hz).
Współrzędne i limity czasowe trzech stref.
Włączanie/wyłączanie trybu Multi-Target i Bluetooth (w razie potrzeby).

Dodatkowo zaimplementowano przyciski do wygodnego zarządzania: „Zastosuj strefy domyślne”, „Zapisz konfigurację w radarze”, „Uruchom ponownie radar” i „Przywróć ustawienia fabryczne”. Zapewnia to pełną kontrolę nad czujnikiem poprzez intuicyjny interfejs Home Assistant.

Narzędzia pomocnicze i integracja fizyczna

Przed ostateczną instalacją i podłączeniem do ESP32, HLK-LD2450 można wstępnie skonfigurować lub przetestować za pomocą adaptera USB-UART. Oficjalne narzędzie HLK-LD2450_TOOL jest dostępne dla systemu Windows. Dla użytkowników Linux/WSL opracowano skrypt connect_radar.sh (wykorzystujący usbipd) oraz skrypt Python radar.py, który pozwala monitorować strumień danych i analizować protokół binarny. Warto zauważyć, że protokół danych wykorzystuje znaczniki AA FF, a współrzędne są przesyłane jako 16-bitowe wartości ze znakiem.

Dla fizycznej integracji czujnika w projekcie przewidziano gotowe rozwiązania. W repozytorium projektu dostępne są pliki STL do druku 3D obudów i pokryw, co znacznie upraszcza tworzenie estetycznego i funkcjonalnego urządzenia. Szczegółowe zalecenia dotyczące druku i montażu znajdują się w pliku README w folderze case_stl.

Co ważne

Pełna kontrola nad HLK-LD2450: Natywny komponent ESPHome pozwala zarządzać wszystkimi rejestrami radaru za pośrednictwem protokołu binarnego, ujawniając jego pełny potencjał.
Stabilność z ESP-IDF: Przejście na ESP-IDF jest kluczowe dla niezawodnej pracy UART przy wysokich prędkościach (256000 bodów), oferując lepszą stabilność i optymalizację zasobów w porównaniu z frameworkiem Arduino.
Dynamiczne strefy sprzętowe: Możliwość konfiguracji i zmiany do trzech sprzętowych stref wykrywania bezpośrednio z Home Assistant znacznie zwiększa elastyczność zastosowania czujnika w różnych scenariuszach.
Śledzenie wielu celów (Multi-Target Tracking): Radar jest w stanie śledzić do trzech celów jednocześnie, dostarczając ich dokładne współrzędne, prędkość i kąt, co otwiera nowe możliwości dla złożonych systemów obecności.
Bezproblemowa integracja z Home Assistant: Wszystkie parametry i dane czujnika są dostępne i konfigurowalne za pośrednictwem interfejsu użytkownika Home Assistant, w tym wizualizacja stref i celów za pomocą Plotly.

— Editorial Team