05 · Быстрый старт — от нуля до Home Assistant
Около 5 минут работы руками плюс время компиляции и прошивки (первая компиляция также загружает инструментарий ESP32, до ~15 минут при медленном соединении), и вы переходите от голого ESP32 и модуля rbAmp к живым датчикам в Home Assistant.
Что понадобится
Аппаратное обеспечение
- Плата ESP32 — подойдёт любая плата с двумя свободными пинами I²C. В примерах используются
GPIO21(SDA) иGPIO22(SCL) — стандартные значения для DevKitC. Если ваша плата отличается, измените номера пинов в YAML. - Модуль rbAmp — любой артикул UI или I. Для первого запуска проще всего UI1: одно напряжение + один канал тока, меньше всего проводов.
- Питание 5 В для rbAmp — модуль работает от 4.5..5.5 В. Питание по USB от ESP32 работает, если плата выводит шину 5 В.
- Токовые клещи (CT) — разъёмные токовые клещи SCT-013, подключённые к разъёму CT модуля. Номинал считайте с наклейки (например,
SCT-013-030= 30 А); он нужен дляct_model:ниже. - Подключение (низковольтная сторона): VCC → +5 В, GND → GND, SDA → GPIO21, SCL → GPIO22. Внешние подтягивающие резисторы для одного модуля не нужны (встроенные 4.7 кОм уже есть на плате). Полную схему см. в 04_hardware.md.
- Подключение (сторона сети): сеть L и N подключаются к клеммам L/N модуля (для измерения напряжения), а клипса CT охватывает только проводник L, стрелка направлена к нагрузке. См. 04_hardware.md и 03_sensor_selection.md.
клеммы L/N находятся под сетевым напряжением. Обесточьте и заблокируйте цепь перед подключением, поручите сетевой монтаж и любые работы внутри щитка квалифицированному специалисту, зажимайте клипсой ТОЛЬКО один проводник (L) и никогда не оставляйте клипсу CT на проводнике при отключённом разъёме CT.
- Кабель USB от ESP32 к компьютеру для прошивки.
Программное обеспечение
| Требование | Примечание |
|---|---|
| ESPHome ≥ 2025.3.0 | Компонент использует современный синтаксис ota: (список платформ) и хеширование object-id ESPHome 2025.x. Проверено до ESPHome 2026.5 и новее. |
| Python 3.11..3.13 для CLI | Внутренний слой PlatformIO ESPHome (penv) не принимает Python 3.14. Если вы используете надстройку HA, этот пункт не относится. |
| Home Assistant | Любая свежая версия. Автообнаружение работает по mDNS (Avahi / Bonjour). |
Два пути сборки:
- Надстройка HA ESPHome Add-on (рекомендуется большинству пользователей) — положите YAML в каталог конфигурации надстройки и нажмите Compile. Локальное окружение Python не требуется.
- Локальное окружение CLI (venv) — для разработки и CI. Установите командой
pip install esphomeв venv Python 3.11–3.13.
Настройка venv (только путь CLI)
# Windows PowerShell — adjust the Python path to your 3.11 / 3.13
& "C:\Python311\python.exe" -m venv .venv-esphome
.\.venv-esphome\Scripts\Activate.ps1
pip install esphome
esphome version # should print 2025.3.0 or newer
В Linux / macOS:
python3.11 -m venv .venv-esphome
source .venv-esphome/bin/activate
pip install esphome
esphome version
Шаг 1 — Найдите компонент
Для блока external_components есть два варианта — выберите по своей среде.
Форма A — github (по умолчанию, работает в надстройке HA)
external_components:
- source: github://rb-amp/rbamp-esphome@v1.9.0 # pin a release tag
components: [rbamp]
refresh: 1d # 1 day for production. If you track @main during
# development, change this to `0s`, otherwise ESPHome will
# cache the copy and ignore new commits.
Эта форма — единственная, которая работает в аддоне ESPHome для HA (у аддона нет доступа к shell соседних каталогов). Она также удобна для CLI: ничего не нужно клонировать локально.
Форма B — локальный путь (для разработки)
Если вы клонировали rb-amp/rbamp-esphome и работаете напрямую с исходниками компонента, укажите ESPHome локальный путь:
external_components:
- source:
type: local
path: /absolute/path/to/rbamp-esphome/components
components: [rbamp]
В example/ui1.yaml блок уже настроен на относительный путь (../components), что работает при запуске esphome compile из каталога example/:
cd rbamp-esphome/example
esphome compile ui1.yaml
⚠ Локальный путь не работает в надстройке HA Add-on — надстройка хранит YAML в /config/esphome/ без доступа к остальной файловой системе. Пользователи надстройки выбирают форму A.
Шаг 2 — Создайте YAML
Скопируйте example/ui1.yaml как отправную точку (он использует локальный путь, форма B; список ниже использует форму A, поэтому работает и в аддоне). Откройте в любом редакторе и заполните учётные данные WiFi и имя устройства. Полный файл с построчными комментариями показан ниже.
Правило: power, energy, power_factor, reactive_power и apparent_power требуют, чтобы voltage И current были объявлены в том же блоке sensor: (добавьте internal: true к датчику, который не должен быть сущностью Home Assistant); иначе esphome config останавливается с сообщением «power requires current to also be declared». То же относится к пронумерованным датчикам каналов (power_1 требует current_1 и voltage).
esphome:
name: rbamp-ui1 # node name — sets the mDNS hostname (rbamp-ui1.local)
esp32:
board: esp32dev # your board (e.g. nodemcu-32s, lolin_d32)
framework:
type: arduino # arduino or esp-idf — both work with the component
logger:
level: DEBUG # DEBUG shows I²C reads; after the first run you can use INFO
wifi:
ssid: !secret wifi_ssid # see secrets.yaml below
password: !secret wifi_password
ap:
ssid: "rbAmp UI1 Fallback" # fallback AP if the connection fails
password: !secret ap_password
captive_portal: # config page on the fallback AP
api: # Home Assistant native API on port 6053
# encryption:
# key: "BASE64_KEY" # optional — see 08_has_integrations.md
ota:
- platform: esphome # over-the-air updates
i2c:
sda: GPIO21
scl: GPIO22
frequency: 50kHz # IMPORTANT: 100 kHz causes intermittent NACKs from the module;
# 50 kHz reduces them ~5-10x (see 10 · troubleshooting → NACK-discipline)
scan: true # logs every I²C address found at boot
external_components:
- source: github://rb-amp/rbamp-esphome@v1.9.0 # works in the HA Add-on and the CLI
components: [rbamp]
# Working from a local clone instead? Use Form B above.
rbamp:
id: meter1
address: 0x50 # factory default address
update_interval: 60s # how often to close the period and publish sensors
# minimum 1 s (v1.3); below this → cv.Invalid
ct_model: SCT_013_030 # CT clamp model — change it to match yours
# (SCT_013_005 / _010 / _020 / _030 / _050 / _060 / _100)
sensor:
- platform: rbamp
rbamp_id: meter1
voltage:
name: "Mains Voltage" # entity ID in HA: sensor.rbamp_ui1_mains_voltage
current:
name: "Mains Current"
power:
name: "Mains Power"
energy:
name: "Mains Energy" # state_class: total_increasing — ready for the Energy dashboard
frequency:
name: "Mains Frequency"
power_factor:
name: "Mains Power Factor"
Ключ ct_model: загружает заводские коэффициенты для выбранной модели клещей. Если у вас нет SCT-013-030, замените на модель, которая у вас есть. Подробнее о выборе — см. 03_sensor_selection.md.
secrets.yaml
Создайте secrets.yaml в том же каталоге, что и YAML (по умолчанию он в .gitignore в example/.gitignore, чтобы учётные данные не утекли в коммит):
wifi_ssid: "YourNetworkName"
wifi_password: "YourPassword"
ap_password: "rbamprbamp"
Шаг 3 — Компиляция
# from the example/ directory with the venv active
esphome compile ui1.yaml
Что происходит:
- ESPHome распаковывает
external_componentsи загружает пакет Pythonrbampиз../components. - PlatformIO загружает платформу ESP32 при первом запуске (~1–2 ГБ, кэшируется). Это самый медленный шаг — до 15 минут при медленном соединении.
- Компонент C++ собирается и линкуется. Успешное завершение выглядит так:
SUCCESS Took 58.71 seconds
Wrote .esphome/build/rbamp-ui1/.pioenvs/rbamp-ui1/firmware.factory.bin
Если сборка падает с Error: Failed to install Python dependencies, хост, скорее всего, работает на Python 3.14. Используйте надстройку HA или venv с 3.11 / 3.13 (см. «What you'll need»). Это несовместимость резолвера uv PlatformIO с некоторыми моделями процессоров, а не ошибка компонента.
Шаг 4 — Первая прошивка
esphome upload прошивает бинарник по USB. Сначала найдите правильный порт:
- Windows: Диспетчер устройств → Порты (COM и LPT). Обычно
COM3–COM9. - Linux / macOS:
ls /dev/tty*— обычно/dev/ttyUSB0или/dev/ttyACM0.
esphome upload --device COM6 ui1.yaml # Windows
esphome upload --device /dev/ttyUSB0 ui1.yaml # Linux
Для пути с аддоном HA:
- Откройте Home Assistant → Настройки → Аддоны → ESPHome.
- Откройте веб-интерфейс надстройки ESPHome Add-on.
- Найдите устройство (или нажмите «New Device») → Install → Plug in to this computer (Find your device / New Device / Install / Plug in to this computer).
Инструмент прошивки (внутри — esptool.py) перезагружает ESP32 автоматически после записи. Полное время прошивки обычно 30–60 секунд.
Шаг 5 — Что ожидать в журнале загрузки
4.7 Зеркала проверки модели ТТ (0x51..0x53) (api-reference) · 8.10 Обратное чтение зеркала проверки модели ТТ (проверка после привязки) (api-reference)
Запустите esphome logs, чтобы следить за загрузкой в реальном времени:
esphome logs ui1.yaml --device COM6
Нормальная первая загрузка даёт примерно такие строки (значения и тайминги приблизительны):
[D][i2c]: Found i2c device at address 0x50
[C][rbamp]: Setting up rbAmp at 0x50 ...
[C][rbamp]: Firmware version: 0x04
[C][rbamp]: Variant: UI1
[C][rbamp]: UID: 0x1A2B3C4D5E6F708192A3
[C][rbamp]: sensor_class: matches → skipped (nothing to write)
[C][rbamp]: ct_model[0]: matches → skipped (nothing to write)
[C][rbamp]: rbAmp:
[C][rbamp]: Address: 0x50
[C][rbamp]: Firmware version: 1.3
[C][rbamp]: Topology: SINGLE, channels: 1, voltage: yes
[C][rbamp]: Bidirectional: NO
[C][rbamp]: Wh persistence: NVS every 300s
[C][component]: Setup rbamp took 67ms
Строка i2c: scan: true появляется перед строками компонента и подтверждает, что модуль физически виден на шине. Если Found i2c device at address 0x50 отсутствует, см. раздел «Что делать, если» ниже.
В пределах одного update_interval (по умолчанию 60 с) публикации датчиков появляются — подождите ~60 с или задайте update_interval: 5s на время тестирования:
[D][sensor]: 'Mains Voltage': Sending state 226.70 V
[D][sensor]: 'Mains Current': Sending state 0.755 A
[D][sensor]: 'Mains Power': Sending state 92.80 W
[D][sensor]: 'Mains Power Factor': Sending state 0.542
[D][sensor]: 'Mains Frequency': Sending state 50.0 Hz
[D][sensor]: 'Mains Energy': Sending state 0.026 Wh
Опорные значения на стенде с артикулом UI1 и индуктивной нагрузкой: U ≈ 225 В, I ≈ 0.78 А, P ≈ 110 Вт, PF ≈ 0.62. Точные значения зависят от подключённой нагрузки.
Шаг 6 — Обнаружение в Home Assistant
mDNS (автоматически)
HA сам находит узлы ESPHome с настроенным блоком api: в той же локальной сети. Через 30–60 секунд после первой загрузки ESP32:
- HA показывает уведомление: Обнаружены новые устройства.
- Настройки → Устройства и службы → ESPHome (Settings → Devices & Services → ESPHome) или нажмите на уведомление.
- Выберите новый узел (например,
rbamp-ui1). - Введите локальный IP устройства (виден в журнале как
[I][wifi]: IP: 192.168.0.xxx), если HA не нашёл его сам. - Add.
Все сущности датчиков регистрируются сразу. ID сущности следует шаблону sensor. (пробелы заменяются подчёркиваниями, всё строчными). Для YAML выше: sensor.rbamp_ui1_mains_voltage, sensor.rbamp_ui1_mains_energy и т. д.
Добавление вручную (если mDNS заблокирован)
Настройки → Устройства и службы → Добавить интеграцию → ESPHome → IP-адрес и порт API (6053). Если ключ задан в api: encryption: key:, введите его при запросе.
Панель энергии
Датчик energy уже настроен для Energy HA:
device_class: energystate_class: total_increasingunit_of_measurement: Wh
Настройки → Панели управления → Energy → Добавить потребление → выберите «Mains Energy» (Settings → Dashboards → Energy → Add Consumption). HA сразу начинает учитывать накопленное потребление.
Шаг 7 — Масштабирование до парка (каноническое развёртывание из нескольких модулей)
Один UI1 на сети даёт итоги по всему дому. Чтобы получить разбивку по ответвлениям (бойлер, кондиционер, EV), добавьте модули I2/I3 на ту же шину I²C. Это канонический 80%-вариант развёртывания (см. 01_overview.md).
Минимальное расширение YAML
i2c:
sda: GPIO21
scl: GPIO22
frequency: 50kHz
scan: true
# external_components: ... as in Step 1
rbamp:
- id: mains_meter
address: 0x50
sensor_class: SCT_013
ct_model: SCT_013_030
fleet_gc_enable: true # NEW v1.3 — capability-gated GC snapshot
group_id: 1 # cluster id
- id: boiler_meter # I2 sub-meter, address 0x51 after provisioning
address: 0x51
sensor_class: SCT_013
ct_models: [SCT_013_020, SCT_013_010] # 20A boiler + 10A washing machine
fleet_gc_enable: true
group_id: 1 # same group → synchronized snapshots
- id: panel_meter # I3 sub-meter, address 0x52
address: 0x52
sensor_class: SCT_013
ct_models: [SCT_013_005, SCT_013_030, SCT_013_020] # mixed CT sizes
fleet_gc_enable: true
group_id: 1
sensor:
- platform: rbamp
rbamp_id: mains_meter
voltage: { name: "Mains Voltage" }
current: { name: "Mains Current" }
power: { name: "Mains Power" }
energy: { name: "Mains Energy" }
- platform: rbamp
rbamp_id: boiler_meter
current: { name: "Boiler Current" } # SCT_013_020 channel 0
current_1: { name: "Washer Current" } # SCT_013_010 channel 1
- platform: rbamp
rbamp_id: panel_meter
current: { name: "Lighting Current" } # SCT_013_005 channel 0
current_1: { name: "Appliances Current" } # SCT_013_030 channel 1
current_2: { name: "Sub-panel Current" } # SCT_013_020 channel 2
Что сделать перед первой загрузкой
-
Провизионирование адреса — все модули поставляются с завода с адресом 0x50. См. 04_hardware.md, Двухфазная фиксация адреса — пошаговая процедура (один девственный модуль на шине одновременно).
-
Подтяжки — следуйте таблице подтяжек в 04_hardware.md, раздел «Шина из нескольких модулей». Для 3 модулей: разрежьте перемычки подтяжки на всех и добавьте одну внешнюю пару 2.7–3.3 кОм (SDA и SCL к 3.3 В) на ESP32.
-
Внешнее питание 5 V — 3 модуля × ~15 mA = ~45 mA + ESP32 ~200 mA. VBUS USB обычно хватает для запуска; для промышленной установки используйте отдельный импульсный блок питания 5 V.
Что ожидать в логе после загрузки
[D][i2c]: Found i2c device at address 0x50
[D][i2c]: Found i2c device at address 0x51
[D][i2c]: Found i2c device at address 0x52
[C][rbamp]: rbAmp 0x50: variant=UI1, fleet_gc=on, group=1
[C][rbamp]: rbAmp 0x51: variant=I2, fleet_gc=on, group=1
[C][rbamp]: rbAmp 0x52: variant=I3, fleet_gc=on, group=1
[I][rbamp]: GC latch enabled fleet-wide: 3 modules in group 1
Проверка синхронизации
6.3 Широковещательный снимок GC — синхронизация парка по выбору (api-reference) · 8.4 Широковещательный снимок GC + резервный свидетель (api-reference)
С UI1@0x50 + I2@0x51 + I3@0x52 и fleet_gc_enable: true:
[D][rbamp]: GC frame emit: group=1, tick=42, all 3 modules ACK'd
[D][rbamp]: check_sync(tick=42) → 3/3 in_sync ; fleet in sync
См. 09_api_reference.md, раздел Fleet для программной отправки и проверки синхронизации через нативные службы API.
Что делать, если
| Симптом | Вероятная причина | Что делать |
|---|---|---|
Отсутствует Found i2c device at address 0x50 |
Модуль не запитан или подключён неверно, неверные пины GPIO | Проверьте VCC (должно быть 4.5–5.0 V), GND, SDA / SCL; убедитесь, что перемычки подтяжки на модуле целы |
Probe failed at 0x50 в логах |
Модуль виден при сканировании, но не отвечает на чтение регистров | Проверьте frequency: 50kHz в YAML; убедитесь, что модуль не находится в середине записи во флеш (~700 мс) |
| Датчики показывают 0 или NaN | Модуль ещё загружается; первые ~250 мс после включения регистры читают 0 | Дождитесь первого цикла update_interval; компонент пропускает чтение, пока регистр состояния не готов |
| HA не находит устройство | mDNS заблокирован роутером / VLAN; блок api: отсутствует |
Добавьте api:; попробуйте добавить вручную по IP |
Предупреждение update() took 406ms |
Компонент откатился с пакетного чтения v1.3 к чтению по регистрам (4 транзакции × 9 float на 50 кГц) | Не проблема; проверьте, что версия прошивки 0x04 и подтяжки шины соответствуют таблице в 04_hardware.md (подтянуты к чистым 3.3 V) — исправный цикл v1.3 укладывается в 30 мс |
| Переход в режим точки доступа | Неверный SSID / пароль; точка доступа вне зоны | Проверьте secrets.yaml; подойдите ближе к точке доступа; 2.4 ГГц или 5 ГГц |
Для проблем, которых нет в этом списке, см. 10_troubleshooting.md.
Что дальше
- Настройка из трёх каналов: 06_examples.md — YAML для UI3 с тремя независимыми токовыми каналами и всеми производными величинами.
- Несколько модулей на одной шине: 06_examples.md — раздел о нескольких модулях.
- Подробный разбор панели энергии HA: 08_has_integrations.md.
- Интеграции DIY (Grafana, MQTT, автоматизации): 07_diy_integrations.md.
- Полный справочник конфигурации: 09_api_reference.md.
- Диагностика проблем при первом запуске rbAmp: 10_troubleshooting.md.
Исходники и вопросы: rb-amp/rbamp-esphome · эта страница в репозитории: docs/05_quickstart.md (v1.9.1)