📡 Radar + Light

Совет

TL;DR. Радар HLK-LD2402 (через UART) + фоторезистор на ADC. В HA — binary_sensor присутствия, sensor дистанции, sensor освещённости 0–100% и 9 кнопок калибровки. Работает на ESP32 / C3 / C6 (рекомендуется C6).

🧩 Матрица поддержки плат

3 платы Wi-Fi 2 Zigbee каркаса

Плата	Wi-Fi (ESPHome)	Zigbee (ESP-IDF)
ESP32 (classic)	✅	❌
ESP32-C3 SuperMini	✅	❌
ESP32-C6 SuperMini (рек.)	✅	🐝 C6 Router
ESP32-H2	❌ нет Wi-Fi	🐝 H2 End Device
ESP8266	🚧 (RAM критичен)	❌

🔌 Подключение пинов

ESP32-C6 (рек.)

Сигнал LD2402	GPIO
TX (данные → ESP)	GPIO6
RX (команды ← ESP)	GPIO7
5V	5V
GND	GND
LDR (делитель 10kΩ)	GPIO4 (ADC)

Осторожно

GPIO4 на C6 — strapping pin. Используйте резистор ≥ 10 kΩ к 3.3 V в делителе LDR, иначе плата может не загружаться.

ESP32-C3

Сигнал LD2402	GPIO
TX	GPIO20
RX	GPIO21
5V	5V
GND	GND
LDR (делитель 10kΩ)	GPIO4 (ADC)

ESP32 (classic)

Сигнал LD2402	GPIO
TX	GPIO17
RX	GPIO16
5V	5V
GND	GND
LDR (делитель 10kΩ)	GPIO34 (input-only ADC1)

Заметка

UART: линия TX модуля всегда идёт на RX ESP (и наоборот). Скорость UART — 115200 (компонент hlk_ld2402).

📁 Структура шаблона

• Директорияfirmwares/ci-overrides/mihazzzold.espHome_radarLight/

  • espHome_radarLight.yaml.j2 единая точка входа
  • Директория_includes/

    • runtime.yaml.j2 Wi-Fi, API, OTA, UART, hlk_ld2402
    • logic.yaml.j2 RAD:* / LUX:* сущности, калибровка
    • maintenance.yaml.j2 OTA, SETUP, серийник, HELP
    • logic_radar_buttons.yaml.j2 9 кнопок (calibrate, save, …)
    • logic_radar_text_sensors.yaml.j2 firmware version, режим
  • README.md
  • HOME_ASSISTANT.md
  • hardware.yaml

📦 Сборка

1. Установите ESPHome (pip install esphome или через GUI).

2. Скопируйте секреты:

   cp firmwares/secrets.yaml.example firmwares/secrets.yaml
   # отредактируйте wifi_ssid / wifi_password / api_encryption_key

3. Синхронизируйте внешние репо + примените канон:

   python scripts/sync_firmwares.py
   python scripts/apply_ci_overrides.py

4. Прошейте устройство (выбор платы — см. Tabs ниже):

   ESP32-C6 (рек.)

   py -3.13 scripts/flasher.py --local `
     -f firmwares-external/mihazzzold.espHome_radarLight/espHome_radarLight.yaml.j2 `
     --board-profile esp32c6-supermini -a run --port COM5 -y

   ESP32-C3

   py -3.13 scripts/flasher.py --local `
     -f firmwares-external/mihazzzold.espHome_radarLight/espHome_radarLight.yaml.j2 `
     --board-profile esp32c3-supermini -a run --port COM5 -y

   ESP32 (classic)

   py -3.13 scripts/flasher.py --local `
     -f firmwares-external/mihazzzold.espHome_radarLight/espHome_radarLight.yaml.j2 `
     --board-profile esp32-supermini -a run --port COM5 -y

5. Добавьте устройство в Home Assistant через ESPHome integration. Появятся сущности с префиксами RAD: / LUX: / OTA: + HELP: инструкция с шагами калибровки.

🏠 Сущности в Home Assistant

После добавления устройства в HA появятся следующие группы сущностей.

Основные сенсоры

Сущность	Тип	Описание
Присутствие	binary_sensor	Обнаружен человек / нет
Дистанция	sensor, cm	Расстояние до ближайшего объекта
Освещённость	sensor, %	Уровень света от LDR (0–100%)
Микродвижение	binary_sensor	Минимальное движение (дыхание, рука)
Помехи питания	binary_sensor	⚠️ Шум БП мешает радару — см. ниже

Диагностика (скрыты по умолчанию)

Сущность	Описание
Энергия ворот 0–4	Энергия отражённого сигнала по зонам дальности. Gate 0 = ближайшая зона (~0–0.7м), Gate 4 = дальняя (~2.8–3.5м). Видны только в инженерном режиме.
Прогресс калибровки	0–100% во время выполнения команды «Калибровка»
Версия прошивки радара	Версия встроенного ПО модуля LD2402
Режим работы	Normal / Engineering / Calibrating

Кнопки управления

Кнопка	Что делает
Калибровка	Запускает ручную калибровку фона (комната должна быть пустой). Следить за «Прогресс калибровки» — займёт 30–60 сек.
Авто-калибровка	Автоматический вариант: датчик сам решает когда запустить калибровку. Менее надёжна — лучше использовать ручную.
Сохранить настройки	Записывает текущие параметры во флэш модуля. Обязательно нажимать после любых изменений — иначе настройки сбросятся при отключении питания.
Инженерный режим	Включает вывод «Энергия ворот 0–4» в реальном времени. Нужен для диагностики и настройки чувствительности.
Обычный режим	Возвращает из инженерного в рабочий режим.
Автоусиление	Автоматически подбирает усиление приёмника под условия помещения.
Проверка помех	Сканирует помехи от блока питания и сохраняет профиль. Запускать при включённом «Помехи питания».
SN модуля	Запрашивает серийный номер встроенного ПО LD2402 (выводится в лог).
Factory reset радара	Сбрасывает LD2402 к заводским порогам. Использовать если калибровка зашла в тупик.

---

🎯 Настройка и калибровка

Осторожно

Перед первой калибровкой убедитесь что «Помехи питания» = Выключено. Если включено — сначала исправьте питание (см. Устранение проблем).

Первоначальная настройка

1. Проверьте питание. Откройте карточку устройства в HA. Если «Помехи питания» = Включено — сначала нажмите «Проверка помех» и «Сохранить настройки». Если не помогло — см. раздел о помехах ниже.

2. Включите инженерный режим. Нажмите «Инженерный режим» — появятся сенсоры «Энергия ворот 0–4».

3. Определите рабочие зоны. Встаньте на разные позиции в комнате и смотрите какие ворота загораются:

   • Gate 0: ~0–0.7 м (прямо под датчиком на потолке)
   • Gate 1: ~0.7–1.4 м
   • Gate 2: ~1.4–2.1 м
   • Gate 3: ~2.1–2.8 м
   • Gate 4: ~2.8–3.5 м

   При потолке 2.08 м вы будете в Gate 0–1 (расстояние по прямой от потолка).

4. Выполните калибровку фона. Выйдите из комнаты (или замрите за дверью) минимум на 30 секунд. Нажмите «Калибровка», дождитесь «Прогресс калибровки» = 100%.

5. Сохраните. Нажмите «Сохранить настройки» — обязательно!

6. Вернитесь в обычный режим. Нажмите «Обычный режим».

7. Проверьте работу. Зайдите в комнату — «Присутствие» должно стать Дома. Выйдите — через несколько секунд переключится обратно.

Когда калибровка не помогает

Если датчик плохо видит краи комнаты — повторите калибровку, но перед этим нажмите «Автоусиление». Датчик подберёт усиление под вашу комнату, после этого калибровка будет точнее.

---

🔧 Устранение проблем

❌ «Помехи питания: Включено»

Самая частая причина слабого обнаружения. LD2402 обнаруживает шум от блока питания и снижает чувствительность в защитный режим.

Решение по шагам:

1. Нажмите «Проверка помех» → «Сохранить настройки» — датчик запишет профиль шума и начнёт его компенсировать.
2. Если не помогло — попробуйте другой БП (желательно 5V с хорошей фильтрацией).
3. Добавьте конденсатор 100–470 мкФ параллельно питанию модуля LD2402.
4. Разнесите кабель питания и UART-кабели.

❌ Датчик видит только прямо под собой, углы не покрывает

Проблема монтажа: LD2402 на потолке имеет узкий конус обнаружения по горизонтали в маленькой комнате.

Варианты:

• Лучший: перенесите датчик на стену, угол вниз ~30–45°, высота ~1.5 м. Тогда радар «смотрит» поперёк комнаты и видит всё.
• На потолке: нажмите «Автоусиление» → повторите калибровку. Иногда помогает.
• Убедитесь что в комнате нет крупных металлических предметов прямо перед датчиком.

❌ Ложные срабатывания (видит людей когда их нет)

• Запустите «Калибровка» с пустой комнатой — датчик запомнит фон (вентилятор, стиральная машина за стеной и т.д.).
• Проверьте наличие движущихся объектов в зоне: вентиляция, шторы, крупные насекомые.
• Попробуйте «Factory reset радара» и начните калибровку заново.

❌ «Дистанция: 0.0 cm» и «Присутствие: Нет» даже когда стоите под датчиком

1. Проверьте UART-подключение: TX модуля → RX ESP, RX модуля → TX ESP.
2. Убедитесь что питание LD2402 — 5V (не 3.3V).
3. Нажмите «Инженерный режим» — если «Энергия ворот» всё равно «Неизвестно», UART не работает.
4. Попробуйте «Factory reset радара» → «Калибровка».

❌ После перезагрузки настройки сбросились

Вы забыли нажать «Сохранить настройки» после калибровки. LD2402 хранит параметры во внутренней флэш — без явного сохранения они теряются при отключении питания.

🐝 Zigbee-вариант

Параллельная Zigbee-реализация на ESP-IDF — для устройств в Zigbee mesh:

🐝 esp32c6-radar (Router) Каркас Z3 на C6 с питанием от сети. Кластеры Occupancy + Illuminance — TODO.

🐝 esp32h2-radar (End Device) Каркас Z3 на H2 для батарейного варианта. Кластеры — TODO.

📚 Дальше

Каталог прошивок

Профили плат

OTA quickstart