Интеграция с хостом
Как запустить модуль 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 (псевдокод)
# 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
Схема учёта энергии
# 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).
Никогда не интегрируйте мощность во времени на хосте — счётчики модуля компенсируют разрывы и сохраняются, ваш интеграл не является ни тем, ни другим. Подробности: Измерения и энергия.
Чтение часовых записей
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).
Правила интеграции, которые стоит повторить
- Ограничивайте каналы по
N_VOLTAGE/N_CURRENT, функции — поCAPABILITIES, раскладку карты — поVERSION. - Идентифицируйте модули по UID, а не по адресу на шине.
- Заново задайте состояние ОЗУ (маска событий, пороги, часы) после любого обнаруженного перезапуска модуля.
- Терпите NACK / растяжение тактов во время команд, затрагивающих флеш; соблюдайте время установки.
- Энергия: приращения счётчиков с обработкой смены поколения и перезапусков — никогда не P·dt на стороне хоста.
- Обновления прошивки: передавайте подготовленный файл релиза как есть; сначала проверьте
BOARD_ID.