rbAmp
RU
Магазин
Документация
Обновлено · Редактировать на GitHub

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.
DANGER

клеммы 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).

Два пути сборки:

  1. Надстройка HA ESPHome Add-on (рекомендуется большинству пользователей) — положите YAML в каталог конфигурации надстройки и нажмите Compile. Локальное окружение Python не требуется.
  2. Локальное окружение CLI (venv) — для разработки и CI. Установите командой pip install esphome в venv Python 3.11–3.13.

Настройка venv (только путь CLI)

Shell
# 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:

Shell
python3.11 -m venv .venv-esphome
source .venv-esphome/bin/activate
pip install esphome
esphome version

Шаг 1 — Найдите компонент

Для блока external_components есть два варианта — выберите по своей среде.

Форма A — github (по умолчанию, работает в надстройке HA)

YAML
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 локальный путь:

YAML
external_components:
  - source:
      type: local
      path: /absolute/path/to/rbamp-esphome/components
    components: [rbamp]

В example/ui1.yaml блок уже настроен на относительный путь (../components), что работает при запуске esphome compile из каталога example/:

Shell
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).

YAML
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, чтобы учётные данные не утекли в коммит):

YAML
wifi_ssid: "YourNetworkName"
wifi_password: "YourPassword"
ap_password: "rbamprbamp"

Шаг 3 — Компиляция

Shell
# from the example/ directory with the venv active
esphome compile ui1.yaml

Что происходит:

  1. ESPHome распаковывает external_components и загружает пакет Python rbamp из ../components.
  2. PlatformIO загружает платформу ESP32 при первом запуске (~1–2 ГБ, кэшируется). Это самый медленный шаг — до 15 минут при медленном соединении.
  3. Компонент C++ собирается и линкуется. Успешное завершение выглядит так:
Text
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.
Shell
esphome upload --device COM6 ui1.yaml             # Windows
esphome upload --device /dev/ttyUSB0 ui1.yaml     # Linux

Для пути с аддоном HA:

  1. Откройте Home Assistant → Настройки → Аддоны → ESPHome.
  2. Откройте веб-интерфейс надстройки ESPHome Add-on.
  3. Найдите устройство (или нажмите «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 — Что ожидать в журнале загрузки

Запустите esphome logs, чтобы следить за загрузкой в реальном времени:

Shell
esphome logs ui1.yaml --device COM6

Нормальная первая загрузка даёт примерно такие строки (значения и тайминги приблизительны):

Text
[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 на время тестирования:

Text
[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:

  1. HA показывает уведомление: Обнаружены новые устройства.
  2. Настройки → Устройства и службы → ESPHome (Settings → Devices & Services → ESPHome) или нажмите на уведомление.
  3. Выберите новый узел (например, rbamp-ui1).
  4. Введите локальный IP устройства (виден в журнале как [I][wifi]: IP: 192.168.0.xxx), если HA не нашёл его сам.
  5. 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: energy
  • state_class: total_increasing
  • unit_of_measurement: Wh

Настройки → Панели управления → Energy → Добавить потребление → выберите «Mains Energy» (Settings → Dashboards → Energy → Add Consumption). HA сразу начинает учитывать накопленное потребление.

Шаг 7 — Масштабирование до парка (каноническое развёртывание из нескольких модулей)

Один UI1 на сети даёт итоги по всему дому. Чтобы получить разбивку по ответвлениям (бойлер, кондиционер, EV), добавьте модули I2/I3 на ту же шину I²C. Это канонический 80%-вариант развёртывания (см. 01_overview.md).

Минимальное расширение YAML

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

Что сделать перед первой загрузкой

  1. Провизионирование адреса — все модули поставляются с завода с адресом 0x50. См. 04_hardware.md, Двухфазная фиксация адреса — пошаговая процедура (один девственный модуль на шине одновременно).

  2. Подтяжки — следуйте таблице подтяжек в 04_hardware.md, раздел «Шина из нескольких модулей». Для 3 модулей: разрежьте перемычки подтяжки на всех и добавьте одну внешнюю пару 2.7–3.3 кОм (SDA и SCL к 3.3 В) на ESP32.

  3. Внешнее питание 5 V — 3 модуля × ~15 mA = ~45 mA + ESP32 ~200 mA. VBUS USB обычно хватает для запуска; для промышленной установки используйте отдельный импульсный блок питания 5 V.

Что ожидать в логе после загрузки

Text
[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

Проверка синхронизации

С UI1@0x50 + I2@0x51 + I3@0x52 и fleet_gc_enable: true:

Text
[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)