rbAmp
RU
Магазин
Документация
Обновлено

Интеграция с хостом

Как запустить модуль STD из собственного кода — с нашими библиотеками или только с мастером I²C/Modbus.

С библиотеками rbAmp

Одна клиентская библиотека на платформу покрывает всю линейку; число каналов и функции определяются во время работы:

  • Arduino (rbamp-arduino) — поддержка STD: обнаружение, реальное время, конфигурация, события и DRDY, OTA, история, энергия с микроразрешением, пусковой ток, фазовый угол и последовательность. На модуле с банками снимков и счётчиками энергии используйте v1.6.2 или новее (более ранние версии берут период из банка 0, а не из счётчиков; источник энергии и минимальная версия).
  • ESP-IDF (rbamp-esp-idf) — компонент с поддержкой STD, включая энергию с микроразрешением и пусковой ток. На модуле с банками снимков и счётчиками энергии используйте v1.7.3 или новее (более ранние версии берут период из банка 0, а не из счётчиков; минимальная версия).
  • ESPHome / Home Assistant (rbamp-esphome) — внешний компонент: счётчики энергии на устройстве, пусковой ток и диагностика фаз. Используйте v1.9.0 или новее; банки снимков (period_banks:) — с v1.9.1.
  • Python (rbamp-python) — поддержка STD: один класс клиента, линейка модуля определяется при подключении. Используйте v1.6.0 или новее; вызовы банков снимков — с v1.6.1. Проверено на стандартном Linux Python (smbus2).

Библиотеки покрывают эти сценарии (проверка обнаружения, опрос busy/err, OTA подготовленного образа, учёт дельт энергии), поэтому там, где платформа позволяет, предпочитайте их.

Микроразрешающая энергия и функции пускового тока кратко — каждый вызов корректно деградирует на модулях, которые не публикуют функцию (без трафика шины или значения из грубых счётчиков):

Функция Arduino ESP-IDF ESPHome (YAML) Python
Микроразрешающая энергия (поля µWh / µvarh всегда пригодны; флаг fine показывает, являются ли они собственными счётчиками модуля) stdReadEnergy() → поля RbAmpStdEnergy *_uwh / *_uvarh, stdEnergyDelta() поля rbamp_std_energy_t *_uwh / *_uvarh, rbamp_std_energy_delta() energy_total · energy_exported_total · energy_net · reactive_energy / reactive_energy_exported read_std_energy() → RbAmpStdEnergy поля *_uwh / *_uvarh, RbAmp.std_energy_delta()
Пусковой ток для энергии stdSetEnergyStartCurrent() / stdReadEnergyStartCurrent() rbamp_std_set_start_current() / rbamp_std_get_start_current() start_current_ua: set_start_current() / get_start_current()
Фазовый угол напряжения stdReadVoltage(v) → angle_deg / angle_valid rbamp_std_voltage_t.angle_deg / angle_valid voltage_angle_b / voltage_angle_c read_std_voltage(phase) → angle_deg / angle_valid
Порядок фаз stdReadPhaseSequence() rbamp_std_read_phase_seq() phase_sequence read_phase_sequence()

Если ваше приложение сохраняет снимок энергии библиотеки (NVS, EEPROM, файл), храните нужные поля в собственном фиксированном формате, а не структуру как сырой блок — структуры снимков получают новые поля между версиями библиотеки.

Без наших библиотек

Всё, что делают библиотеки, — обычный ввод-вывод регистров. Протокол задокументирован и стабилен; изменения карты версионируются (VERSION) и привязаны к возможностям (CAPABILITIES). Канонические пошаговые сценарии (инициализация, команда, конфигурация, смена адреса, энергия, история, OTA, разблокировка) — в Последовательностях — ниже самые короткие рабочие шаблоны.

Минимальный запуск I²C (псевдокод)

Text
# discovery (once)
id   = read(0x0000, 2)            # expect 'S','T'
ver  = read(0x0003, 1)            # map version, expect >= 0x36
caps = read_u16(0x0004)
nv   = read(0x0007, 1); ni = read(0x0008, 1)
uid  = read(0x00F4, 12)           # device identity for your database
fwv  = read_u32(0x0114)           # firmware version: high word . low word (1.126)

# clock (after every module reset: STATUS bit4 == 0)
write_u32(0x08C0, unix_epoch)     # TIME_SET
write(0x0060, 0x06)               # SET_TIME; then poll CMD_STATE 0x006A bit0 -> 0, check ERROR == 0

# realtime poll (every 0.2..1 s, or on the DRDY edge)
u_mv  = read_i32(0x0200 + v*0x20)             # per voltage channel
i_ua  = read_i32(0x1000 + c*0x40)             # per current channel
p_mw  = read_i32(0x1000 + c*0x40 + 0x04)      # signed
pf    = read_i16(0x1000 + c*0x40 + 0x10)      # /1024
freq  = read_u16(0x0010)                      # /100 Hz
tot_p = read_i32(0x0300 + 0x04)               # grand active power

Схема учёта энергии

Text
# at each interval boundary (your clock):
blk = read(0x0800, 0x44)          # ONE transaction <= 128 B: Wh + mWh counters + LT_GEN — coherent
e_imp = i64(blk, 0x28); e_exp = i64(blk, 0x30)   # grand import/export, mWh
gen   = u32(blk, 0x40)            # LT_GEN (0x0840)
up    = read_u32(0x08A0)          # UPTIME

interval_import = e_imp - last_imp          # delta of cumulative counters
if gen != last_gen: re-anchor, no delta     # counter was reset/adopted (event-logged)
if up < last_up:    delta = max(0, delta)   # restart: ~last second of energy may be missing; re-feed time

Читайте блок энергии одной транзакцией ≤ 128 байт — поля i64, читаемые отдельными транзакциями, могут разойтись внутри публикации (транспорт I²C).

Никогда не интегрируйте мощность во времени на хосте — счётчики модуля компенсируют разрывы и сохраняются, ваш интеграл не является ни тем, ни другим. Подробности: Измерения и энергия.

Чтение часовых записей

Text
write(0x0C00, 1)                  # HIST_PERIOD = hourly
write_u16(0x0C04, n)              # n records back from newest
write(0x0060, 0x08)               # HIST_READ
poll CMD_STATE (0x006A) bit0 -> 0
err = read(0x0002, 1)             # 0xFC = no such record
flags = read(0x0C02, 1)           # bit0 = record valid
rec   = read(0x0C20, 80)          # one transaction; see record layout

Записи содержат абсолютную энергию Wh за весь срок службы на конец периода плюс энергию фаз за период (структура).

Опрос здоровья

См. контрольный список диагностики — шесть чтений покрывают живость, состояние хранилища, перезапуски и поколения счётчиков.

Интеграция с Modbus без библиотек

  • Профиль float32: точки, которые публикует модуль — V/I/P по фазам, общая P, частота, импорт/экспорт kWh — по адресам входа float32 (список). Прочие адреса профиля читаются как 0.

  • Родной профиль: FC04 читает с 0x6000 (обнаружение), 0x6100/0x6200 (каналы), 0x6B00+ (энергия), 0x6C00 (итоги); конфигурация и команды — через FC16 с 0x8000+, с UNLOCK для команд, меняющих состояние. Полная карта: карта регистров; правила: транспорт Modbus.

  • мастера, читающие только FC03, получают родные данные через зеркало 0xA000+ (input + 0x4000).

Правила интеграции, которые стоит повторить

  1. Ограничивайте каналы по N_VOLTAGE/N_CURRENT, функции — по CAPABILITIES, раскладку карты — по VERSION.
  2. Идентифицируйте модули по UID, а не по адресу на шине.
  3. Заново задайте состояние ОЗУ (маска событий, пороги, часы) после любого обнаруженного перезапуска модуля.
  4. Терпите NACK / растяжение тактов во время команд, затрагивающих флеш; соблюдайте время установки.
  5. Энергия: приращения счётчиков с обработкой смены поколения и перезапусков — никогда не P·dt на стороне хоста.
  6. Обновления прошивки: передавайте подготовленный файл релиза как есть; сначала проверьте BOARD_ID.