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

04 · Учёт периодов и тарифный расчёт

Для тарифного учёта энергии (Втч за 1 мин / 15 мин / 1 час / сутки / месяц / год) rbAmp предоставляет атомарный периодный снимок: одна команда I2C фиксирует усреднённую по времени мощность за период, а мастер умножает её на собственный интервал dt по часам, чтобы получить Втч.

Это производственный способ получать данные об энергии. Альтернатива — интегрировать P_real из RT на стороне мастера каждое окно измерения (~100 мс, v1.2 и новее) — даёт почти тот же результат на BASIC (немного меньшая точность из-за дискретизации) и держит мастер постоянно занятым.

Периоды BASIC и STD. BASIC хранит один снимок периода на канал: по команде мастера модуль фиксирует среднюю и пиковую мощность и длину периода (рядом с живым окном 100 мс, которое периодом не является), а энергию интегрирует хост. STANDARD (STD) хранит энергию в модуле: накопительные счётчики (импорт/экспорт, активные и реактивные), которые переживают отключение питания, а также записи с меткой времени каждые 15 минут и каждый час (часы задаёт мастер). Модули STD, у которых бит 8 в CAPABILITIES установлен, имеют также 8 независимых банков снимков; без него интервальная энергия берётся из разностей счётчиков. Остальная часть главы описывает снимок периода BASIC; STD описан в техническом справочнике STD.

Зачем нужен периодный снимок

Зачем снимок периода нужен поверх окна измерения.

Единая временная база, которой владеет мастер

В многомодульной системе временная база должна быть на мастере. Поэтому микросхема не интегрирует Втч внутренне. Вместо этого:

  • Микросхема предоставляет не зависящую от времени статистику — среднюю P за период.
  • Мастер умножает его на собственный dt по настенным часам.
  • Все модули работают с одной временной опорой → в общем суммарном итоге энергии по системе дрейф не накапливается.

Формула

Text
E_Wh = avg_P_W × master_dt_seconds / 3600

Where:

  • avg_P_W — значение PERIOD_AVG_P_W, прочитанное после CMD_LATCH_PERIOD.
  • master_dt_seconds — секунды между двумя последовательными снимками, измеренные мастером.

Атомарный период — концепция

Как одна команда снимка фиксирует периодный снимок и открывает следующий период.

Что делает команда

Запись 0x27 в REG_COMMAND = 0x01 запускает атомарную последовательность внутри прошивки (выполняется под __disable_irq()):

Text
1. snapshot ← live      (copy the live accumulator into the I2C-visible snapshot)
2. live     ← 0         (reset the accumulator; start the next period)
3. period_start_ms = now

Эти три шага неделимы — прерывание не может вклиниться между ними. Это гарантирует:

  • Атомарность: каждый отсчёт P по окну принадлежит ровно одному снимку — либо предыдущему, либо следующему; ни дублирования, ни потерь.
  • Без разрыва: новый период начинается в тот же момент, когда закончился предыдущий — мёртвого интервала нет.

Где хранится снимок

После снимка регистры периодного снимка (0xBE..0xCD, а также 0xDC..0xDF для ch0 avg_p, а также 0xE0..0xE3 для MAX_P, а также 0xEC..0xEF для диагностического PERIOD_LATCH_MS) возвращают только что закрытый период. Обратите внимание, что этот диапазон не непрерывен: 0xD0..0xDB содержит блок Q (текущие RT-значения, а не периодный снимок), а 0xE4..0xEB зарезервирован/заводской. Точную раскладку см. в главе 11, §4.11–4.13. Текущий накопитель уже считает следующий период; регистры снимка обновляются только при следующем снимке.

Одна запись — закрывает и открывает

Это определяющее свойство снимка rbAmp. Одна команда снимка одновременно:

  • Закрывает только что завершившийся период (его данные → снимок)
  • Открывает следующий период (live ← 0)

Мастеру нужна одна запись на измерение, а не две (как в наивной реализации «старт → стоп → чтение»).

В клиентских библиотеках

— та же задача без доступа к регистрам:

Библиотека Вызов Что делает
Arduino RbAmp::latchPeriod() / RbAmp::isPeriodValid() отправить команду снимка; проверить флаг достоверности
ESP-IDF rbamp_latch_period() / rbamp_is_period_valid() отправить команду снимка; проверить флаг достоверности
Python dev.latch_period() / dev.is_period_valid() отправить команду снимка; проверить флаг достоверности
ESPHome update_interval: каждое обновление закрывает период; команду снимка и установление обрабатывает компонент
Text
master                          chip
------                          ----
                                accumulator running since boot...

write CMD_LATCH (0x27)   ────►  snapshot ← live (since-boot — DISCARD)
                                live ← 0, period_start = T0
t0 = master.clock()      ◄──── first snapshot — primer (discard)

  [wait 60 seconds]

write CMD_LATCH          ────►  snapshot ← live (over [T0..T1] — KEEP)
                                live ← 0, period_start = T1
t1 = master.clock()
read avg_p_W @ 0xDC      ────►  float32 LE
E1_Wh = avg_p × (t1 − t0) / 3600

  [wait 60 seconds]

write CMD_LATCH          ────►  snapshot ← live (over [T1..T2] — KEEP)
                                live ← 0, period_start = T2
t2 = master.clock()
read avg_p_W
E2_Wh = avg_p × (t2 − t1) / 3600

...and so on. t1 is both the end of period 1 and the start of period 2.

Первый снимок — пробный (отбросьте)

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

В клиентских библиотеках

— та же задача без доступа к регистрам:

Библиотека Вызов Что делает
Arduino RbAmp::readPeriodSnapshot(out, settle_ms, skip_latch) / RbAmp::begin() снимок, установление, проверка достоверности и чтение одним вызовом; begin() отбрасывает первый снимок
ESP-IDF rbamp_read_period_snapshot() / rbamp_begin() снимок, установление, проверка достоверности и чтение одним вызовом; begin отбрасывает первый снимок
Python dev.read_period_snapshot(settle_ms=50, skip_latch=False) / dev.begin() снимок, установление, проверка достоверности и чтение одним вызовом; begin() отбрасывает первый снимок
ESPHome update_interval: / latch_interval: частота обновления цикла снимков; по желанию отдельная частота снимков

Регистры снимка периода

Адрес Имя Тип Когда читать Описание
0x07 PERIOD_VALID u8 сначала прочитайте bit0 = 1, если снимок свежий и действительный, 0, если устаревший (гонка или преждевременный снимок)
0xDC..0xDF PERIOD_AVG_P_W[0] float32 LE основной PRODUCTION — среднее P_real канала I0 за период (Вт)
0xC2..0xC5 PERIOD_AVG_P_W[1] float32 LE UI2/UI3 Среднее P_real канала I1
0xC6..0xC9 PERIOD_AVG_P_W[2] float32 LE UI3 Средняя P_real канала I2
Энергия по каналам (UI2/UI3)

: тот же снимок фиксирует и усреднения по каналам — в том же проходе прочитайте 0xC2 (ch1) / 0xC6 (ch2) и умножьте на тот же dt: e1_wh = avg_p1 * dt_s / 3600. | 0xE0..0xE3 | PERIOD_MAX_P_W | float32 LE | необязательно | Пиковая P_real за период (для тарифов по мощности) | | 0xEC..0xEF | PERIOD_LATCH_MS | u32 LE | только диагностика | Взгляд микросхемы на dt между снимками — может занижать под нагрузкой; для длины окна на стороне модуля используйте PERIOD_COMMIT_COUNT × длину коммита | | 0xBE..0xC1 | PERIOD_COMMIT_COUNT | u32 LE | измерение окна | Число коммитов RT в закрытом периоде. Один коммит = 0.1 s с v1.2; 0.2 s на более старых образах — количество × 0.1 s (или × 0.2 s) — собственная мера модуля для длины окна. Как понять, какой вариант применим, см. раздел о дрейфе часов

Накопители экспорта

Адрес Имя Тип Описание
— — В карте BASIC нет накопителей экспорта (обратного направления); на STD энергия хранится иначе — см. документацию STD
Примечание

На модулях BASIC регистров экспорта нет; чтение из неотображённого адреса возвращает 0x00 (прошивка никогда не отвечает NACK на чтение — см. главу 11 §5.2). Мастеру, которому нужен учёт экспорта на BASIC, следует переходить на учёт по RT (см. arduino-examples.md → Пример 5).

В клиентских библиотеках — та же задача без работы с регистрами:

Библиотека Вызов Что делает
Arduino RbAmp::readPeriodAvgPower(ch) / RbAmp::readPeriodMaxPower() средняя и пиковая мощность закрытого периода
ESP-IDF rbamp_read_period_avg_power() / rbamp_read_period_max_power() средняя и пиковая мощность закрытого периода
Python dev.read_period_avg_power(ch=0) / dev.read_period_max_power() средняя и пиковая мощность закрытого периода
ESPHome update_interval: компонент читает средние значения периода при каждом обновлении

Алгоритм на стороне мастера

Базовый цикл (один модуль, период 60 секунд)

C++
#include 

#define RB_ADDR 0x50

void setup() {
  Serial.begin(115200);
  Wire.begin();
  delay(300);

  // 1. Primer snapshot (discard result)
  rb_write_u8(RB_ADDR, 0x01, 0x27);
}

void loop() {
  static uint32_t t_prev = millis();
  delay(60000);                                    // wait 60 seconds

  // 2. Final snapshot — closes [t_prev, now]
  rb_write_u8(RB_ADDR, 0x01, 0x27);
  uint32_t t_now = millis();
  delay(50);                                       // firmware finishes in ~5 ms; allow margin

  // 3. Check PERIOD_VALID
  uint8_t valid = rb_read_u8(RB_ADDR, 0x07);
  if ((valid & 0x01) == 0) {
    // Race or premature snapshot — retry
    delay(250);
    rb_write_u8(RB_ADDR, 0x01, 0x27);
    t_now = millis();
    delay(50);
    valid = rb_read_u8(RB_ADDR, 0x07);
    if ((valid & 0x01) == 0) {
      Serial.println("WARN: two stale snapshots in a row");
      t_prev = millis();
      return;
    }
  }

  // 4. Read the snapshot
  float avg_p = rb_read_float_le(RB_ADDR, 0xDC);
  float max_p = rb_read_float_le(RB_ADDR, 0xE0);

  // 5. Compute energy on master clock
  float dt_s = (t_now - t_prev) / 1000.0f;
  float e_wh = avg_p * dt_s / 3600.0f;

  Serial.printf("[+%5.1fs] E=%.3f Wh  avg_P=%.1f W  max_P=%.1f W\n",
                dt_s, e_wh, avg_p, max_p);

  t_prev = t_now;
}

Что важно в этом коде

  1. Первый снимок — пробный: его результат отбрасывается.
  2. PERIOD_VALID читается ДО использования снимка — иначе устаревшие данные могут просочиться при гонке.
  3. dt измеряется на мастере, а не вычисляется из PERIOD_LATCH_MS — регистр микросхемы нужен только для диагностики дрейфа.
  4. t_prev переходит к t_now успешного снимка, а не к исходному началу периода — так цепочка остаётся непрерывной без пропусков.
В клиентских библиотеках

— та же задача без доступа к регистрам:

Библиотека Вызов Что делает
Arduino RbAmp::energyWh(ch) / RbAmpEnergy::reset(ch) накопленный итог Вт·ч хранится на хосте; обнулить накопитель
ESP-IDF rbamp_energy_wh() / rbamp_energy_reset() накопленный итог Вт·ч хранится на хосте; обнулить накопитель
Python dev.energy.wh(ch) / dev.energy.reset(ch) накопленный итог Вт·ч хранится на хосте; обнулить накопитель
ESPHome energy датчик энергии, интегрируемый компонентом

Двунаправленный учёт

Примечание

На модуле BASIC регистры PERIOD_AVG_P_NEG_W не выделены (чтение возвращает 0x00), а PERIOD_AVG_P_W всегда ≥ 0 (отрицательные выборки отбрасываются накопителем).

Как учитывается энергия на модулях BASIC и STANDARD (STD).

Что означает двунаправленный учёт

Микросхема ведёт два отдельных накопителя за период:

  • Потребление: интеграл max(P, 0) × dt — только положительная мощность.
  • Выдача: интеграл max(−P, 0) × dt — только отрицательная мощность, по модулю.

Сумма обоих даёт полную энергию, прошедшую через счётчик по модулю; разность — чистое потребление (то, что показал бы механический дисковый счётчик).

Применение

  • Дома с солнечными панелями: потребление и выдача в сеть тарифицируются по разным тарифам (тариф на выдачу)
  • Системы с аккумуляторами: учёт циклов заряда/разряда
  • Ветрогенераторы, рекуперативные нагрузки, зарядные станции V2G для электромобилей

Где находится двунаправленный учёт

Двунаправленные (потребление + экспорт) продукты относятся к линейке rbAmp STD, которая использует другую, 16-битную карту регистров с знаковыми счётчиками энергии на устройстве — см. справочную документацию STD. В 8-битной карте BASIC, описанной в этой главе, регистров экспорта нет.

C++
// BASIC-map period accounting, 60-second period (consumption only)
void loop() {
  static uint32_t t_prev = millis();
  delay(60000);

  rb_write_u8(RB_ADDR, 0x01, 0x27);
  uint32_t t_now = millis();
  delay(50);

  if ((rb_read_u8(RB_ADDR, 0x07) & 0x01) == 0) {
    t_prev = millis();
    return;
  }

  float avg_p_consume = rb_read_float_le(RB_ADDR, 0xDC);                  // ≥ 0

  float dt_s = (t_now - t_prev) / 1000.0f;
  float e_consume_wh = avg_p_consume * dt_s / 3600.0f;

  Serial.printf("[%.1fs] consume=%.3f Wh\n", dt_s, e_consume_wh);

  t_prev = t_now;
}

Что недоступно на BASIC

Если у вас модуль уровня BASIC и нужен двунаправленный учёт, есть два варианта:

  1. Интеграция на стороне мастера — читайте RT P_real (0xA6) каждое окно измерения (~100 мс с v1.2; до этого 200 мс) и интегрируйте положительные и отрицательные выборки раздельно на стороне мастера. См. Пример 5 в arduino-examples.md. Точность немного ниже (из-за дискретизации), но работает на любой прошивке.
В клиентских библиотеках

— та же задача без доступа к регистрам:

Библиотека Вызов Что делает
Arduino RbAmp::stdReadEnergy(out) / RbAmp::readPower(ch) STD: счётчики импорта/экспорта на устройстве; BASIC: знаковая мощность, разделяется на хосте
ESP-IDF rbamp_std_read_energy() / rbamp_read_power() (со знаком) STD: счётчики импорта/экспорта на устройстве; BASIC: знаковая мощность, разделяется на хосте
Python dev.read_std_energy() / dev.read_power(ch) STD: счётчики импорта/экспорта на устройстве; BASIC: знаковая мощность, разделяется на хосте
ESPHome bidirectional: / energy_exported включите учёт энергии выдачи; датчики выдачи (BASIC публикует 0)

Варианты только с током — учёт периодов возвращает ноль

На I1/I2/I3 (и более высоких I*-only вариантах) без датчика напряжения:

  • PERIOD_AVG_P_W[*] всегда 0.0f — без U интегрировать нечего.
  • PERIOD_VALID по-прежнему показывает 1 (снимок действителен, просто нулевой).
  • PERIOD_MAX_P_W также равна 0.

Для вариантов только с током встроенный учёт периода не выдаёт показаний энергии. Мастер должен либо:

  • Использовать собственный датчик напряжения и интегрировать I_rms × U_master × cos(φ)_master (сложнее; требует синхронизации фаз), либо
  • Используйте модуль только с током лишь для контроля наличия тока и сочетайте его с модулем UI* или внешним счётчиком для энергии.

Опрос по событиям и периодический опрос

Периодически (по расписанию, как cron)

Мастер читает каждые N секунд по таймеру:

C++
// Once per hour
setInterval(60 * 60 * 1000, [](){
  rb_write_u8(0x50, 0x01, 0x27);
  // ... read snapshot, accumulate Wh
});

Подходит для классического тарифного учёта (1 мин, 15 мин, 1 час).

По событиям

Мастер выдаёт снимок при наступлении внешнего события:

  • Импульс со счётчика электронного счётчика энергосбыта (контрольная сверка)
  • Смена тарифа (пик / внепиковое время)
  • Пользовательский запрос («сколько я уже израсходовал?»)
C++
void on_tariff_change() {
  rb_write_u8(0x50, 0x01, 0x27);    // close the period under the old tariff
  delay(50);
  if (rb_read_u8(0x50, 0x07) & 0x01) {
    float avg_p = rb_read_float_le(0x50, 0xDC);
    save_period_to_tariff_a_bucket(avg_p, current_dt_s);
  }
  // the next period accumulates into bucket B
}

Перезапуск периода

Чтобы отбросить живой накопитель и начать заново, выполните лишний снимок и проигнорируйте его результат:

C++
void restart_period() {
  rb_write_u8(0x50, 0x01, 0x27);    // close current + start new
  // do not read the snapshot — discard
}

После этого возобновите обычный цикл снимков с нуля.

Обнаружение перезапуска модуля

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

Адрес Имя Тип Описание
0x46..0x49 UPTIME_S u32 LE Собственный счётчик времени работы модуля (номинально секунды с загрузки). Только детектор перезапуска — на прошивке до 1.4.21 идёт медленнее настенных часов (измерено 0.58–0.80×); никогда не используйте как часы или для расчётов времени
0x4A RESET_CAUSE u8 Флаги причины сброса: bit0 внешний пин, bit1 включение питания / просадка, bit2 программный, bit3/bit4 сторожевые таймеры. Только для журнала

Проверяйте при каждом снимке — модуль перезапустился внутри периода, если выполняется хотя бы одно из условий:

  • UPTIME_S уменьшился с вашего предыдущего снимка, или
  • UPTIME_S меньше времени, прошедшего с вашего предыдущего снимка (по часам мастера).

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

При обнаружении перезапуска отбросьте снимок этого периода (считайте снимок новым пробным), повторно зафиксируйте модель CT, если используете не заводскую модель на прошивке до 1.4.20 (бит 12 в CAPABILITY сброшен) (initialization.md → Что сохраняется при перезапуске), и заново инициализируйте любую конфигурацию только в RAM — см. главу 11 (бит события RESET_OCCURRED). RESET_CAUSE не меняет обработку; запишите его в журнал и двигайтесь дальше.

В клиентских библиотеках

— та же задача без доступа к регистрам:

Библиотека Вызов Что делает
Arduino RbAmpPeriodSnapshot::module_restarted флаг перезапуска в результате периода (путь счётчиков STD)
ESP-IDF rbamp_read_uptime_s() / module_restarted прочитайте время работы модуля; флаг перезапуска в результате периода
Python — не предоставляется — отдельного вызова для обнаружения перезапуска на BASIC нет
ESPHome — не предоставляется — опции обнаружения перезапуска в YAML нет

Несколько модулей — одновременный снимок

Если мастеру нужны синхронные снимки со всех модулей (для мгновенного баланса энергии дома), есть два подхода.

Подход 1 — последовательный снимок (простой)

Мастер снимает показания с модулей по очереди:

C++
const uint8_t modules[] = {0x50, 0x51, 0x52};
uint32_t t_prev[] = {0, 0, 0};

void setup() {
  Wire.begin();
  // Primer
  for (int i = 0; i < 3; i++) {
    rb_write_u8(modules[i], 0x01, 0x27);
    t_prev[i] = millis();
  }
}

void loop() {
  delay(60000);
  for (int i = 0; i < 3; i++) {
    rb_write_u8(modules[i], 0x01, 0x27);
    uint32_t t_now = millis();
    delay(50);
    if (rb_read_u8(modules[i], 0x07) & 0x01) {
      float avg_p = rb_read_float_le(modules[i], 0xDC);
      float dt_s = (t_now - t_prev[i]) / 1000.0f;
      float e_wh = avg_p * dt_s / 3600.0f;
      Serial.printf("[0x%02X] E=%.3f Wh\n", modules[i], e_wh);
      t_prev[i] = t_now;
    }
  }
}

Недостаток: моменты снимков отличаются на несколько миллисекунд. Для периода 60 секунд это даёт погрешность < 0.1 % — незначительно.

Подход 2 — широковещательный снимок через общий вызов (точно, по выбору)

Адрес I²C общего вызова 0x00 — это пакет, который одновременно принимают все ведомые. rbAmp принимает канонический 5-байтовый кадр по адресу общего вызова, который запускает CMD_LATCH_PERIOD на каждом модуле с включённым приёмом GC. GC включается для каждого модуля отдельно через FLEET_CONFIG.bit0 (по умолчанию ВЫКЛ.) — порядок включения и формат кадра см. в initialization.md.

Широковещательный снимок, одновременно достигающий всех модулей через адрес общего вызова.

C++
// Canonical 5-byte GC frame: A5 27 group tick_lo tick_hi.
// Returns true on ACK, false on bus-level NACK (no module has GC enabled).
bool broadcast_latch(uint16_t tick16, uint8_t group = 0) {
  Wire.beginTransmission(0x00);                // general call
  Wire.write(0xA5);                            // frame magic
  Wire.write(0x27);                            // CMD_LATCH_PERIOD opcode
  Wire.write(group);                           // group_id (0 = all-call)
  Wire.write((uint8_t)(tick16 & 0xFF));        // tick_lo
  Wire.write((uint8_t)((tick16 >> 8) & 0xFF)); // tick_hi
  return Wire.endTransmission() == 0;
}

Мастер ведёт 16-битный счётчик tick, который увеличивается при каждой широковещательной передаче. Каждый модуль зеркалирует последний принятый такт в GC_TICK (0x59), так что мастер может обнаружить пропущенную широковещательную передачу на конкретном модуле.

После широковещательного снимка мастер читает снимок каждого модуля по его отдельному адресу. Всегда проверяйте возвращаемое значение — при NACK кадр GC не дошёл (ни у одного модуля не включён GC), и мастер должен перейти к последовательному снимку по модулям:

C++
const uint8_t modules[] = {0x50, 0x51, 0x52};
uint32_t t_prev;
uint16_t gc_tick = 0;

void setup() {
  Wire.begin();
  if (!broadcast_latch(gc_tick++)) {
    // Fall back: per-module sequential snapshot.
    for (uint8_t m : modules) rb_write_u8(m, 0x01, 0x27);
  }
  t_prev = millis();
}

void loop() {
  delay(60000);
  if (!broadcast_latch(gc_tick++)) {
    for (uint8_t m : modules) rb_write_u8(m, 0x01, 0x27);
  }
  uint32_t t_now = millis();
  delay(50);

  float dt_s = (t_now - t_prev) / 1000.0f;
  for (int i = 0; i < 3; i++) {
    if (rb_read_u8(modules[i], 0x07) & 0x01) {
      float avg_p = rb_read_float_le(modules[i], 0xDC);
      float e_wh = avg_p * dt_s / 3600.0f;
      Serial.printf("[0x%02X] E=%.3f Wh  P_avg=%.1f W\n",
                    modules[i], e_wh, avg_p);
    }
  }
  t_prev = t_now;
}

Преимущество: точная синхронизация — снимки делаются в один и тот же момент на всех модулях с включённым GC, с точностью до нескольких микросекунд.

Сценарий: важно для мгновенной балансировки (например, house_consume − solar_export в один момент времени).

Широковещательный снимок включается отдельно

для каждого модуля через FLEET_CONFIG.bit0 (по умолчанию ВЫКЛ. на новом модуле). Когда выключено, ведомый отвечает NACK на кадр общего вызова, и мастер автоматически переходит на поочерёдный снимок каждого модуля. См. initialization.md — General Call (широковещательно по адресу 0x00) — порядок включения и формат кадра.

Один накопитель, два триггера. Адресный снимок (0x27 по собственному адресу модуля) и широковещательный снимок сбрасывают один и тот же накопитель периода — на модуль он один. Для регулярного цикла выбирайте один способ на модуль; дополнительный снимок другим способом обрывает текущий период раньше времени. Резервные схемы выше безопасны, потому что срабатывают только тогда, когда широковещательная команда до модуля не дошла.

В клиентских библиотеках — та же задача без работы с регистрами:

Библиотека Вызов Что делает
Arduino RbAmpFleet::gcLatch(group, tick, settle_ms) / RbAmp::readPeriodSnapshot(out, settle_ms, skip_latch=true) широковещательный кадр снимка на весь парк; после внешнего снимка прочитайте каждый модуль
ESP-IDF rbamp_fleet_gclatch() / rbamp_read_period_snapshot(..., skip_latch=true) широковещательный кадр снимка на весь парк; после внешнего снимка прочитайте каждый модуль
Python fleet.gc_latch(group, tick, settle_ms) / dev.read_period_snapshot(skip_latch=True) широковещательный кадр снимка на весь парк; после внешнего снимка прочитайте каждый модуль
ESPHome fleet_gc_enable: / group_id: Параметры YAML для включения общего вызова и идентификатора группы

Выбор длины периода

Применение Рекомендуемый dt
Живая панель UI 1 с (или читайте P_real RT напрямую)
График тренда, разрешение 1 мин 60 s
Учёт пиковой мощности за 15-минутные интервалы 900 s
Почасовой учёт 3600 s
Суточные итоги Накапливайте часовые снимки на мастере; не допускайте, чтобы один период превышал 1 час
Примечание

Периоды дольше 1 часа допустимы, переполнения не происходит — накопитель продолжает усреднять, пока снимок не поступил. Что деградирует на очень длинном окне — это точность среднего: в худшем случае ≈ 0.2 % за 1 час, 1.3 % за 6 часов, 5 % за 24 часа. По этой причине держите отдельные периоды ≤ 1 часа, а более длинные суммы накапливайте на мастере.

PERIOD_MAX_P_W — пиковое потребление

Регистр 0xE0 показывает максимальную мощность, замеченную в любом окне RT внутри периода. Применение:

  • Тарифы с пиковым потреблением: поставщики выставляют счёт за наибольшую 15-минутную нагрузку месяца в составе платы за мощность.
  • Обнаружение пускового тока: пуски двигателей дают всплеск в 5–10 раз выше номинала — max_P >> avg_P отмечает событие.
  • Проверка здравого смысла: если max_P намного превышает avg_P, нагрузка пульсирующая — для многих бытовых сценариев это нормально, но стоит проверить, если нагрузка ожидается ровной.

Атомарность гарантирована

CMD_LATCH_PERIOD выполняется с запрещёнными прерываниями во время копирования снимка (несколько микросекунд). Мастер никогда не прочитает наполовину обновлённый снимок — даже если он читает байты сразу после записи, прошивка завершает обновление блока до окончания следующей транзакции I2C (проходит не менее 10+ мкс между записью и чтением).

Та же атомарность связывает сброс накопителя с копией снимка — каждая выборка P попадает ровно в один снимок (либо в предыдущий период, либо в следующий), никогда ни в оба, ни ни в один.

Чего мастер делать НЕ должен

  • ❌ Не вычисляйте U_rms × I_rms × dt — это полная энергия (VAh), а не Вт·ч. Полная мощность включает реактивную составляющую и завышает нагрузку индуктивного характера. Используйте PERIOD_AVG_P_W.
  • ❌ Не выводите направление из I_rms — RMS всегда ≥ 0. Направление задаёт знак P_real.
  • ❌ Не используйте PERIOD_LATCH_MS для Втч — этот регистр диагностический и может дрейфовать вместе с часами микросхемы. Авторитетен master_dt.
  • ❌ Не делайте снимки чаще цикла фиксации RT. Микросхеме нужно накопить не менее одного периода сети (~20 мс при 50 Гц) плюс время установления — минимум 50 мс между выдачами CMD_LATCH_PERIOD. Более частые снимки дают пустой снимок (PERIOD_VALID = 0). Для установившегося опроса безопасным практическим минимумом считается 200 мс; см. главу 11 §6.0 / §6.4.

Диагностика дрейфа часов

PERIOD_LATCH_MS — регистр только для диагностики: внутренняя временная база модуля занижает показания, когда модуль занят. Перекрёстная проверка должна использовать широкий допуск:

C++
uint32_t chip_dt = rb_read_u32(0x50, 0xEC);
uint32_t master_dt = t_now - t_prev;
float ratio = (float)chip_dt / (float)master_dt;
if (ratio < 0.70f || ratio > 1.05f) {
  Serial.printf("WARN: chip drift outside ±30%% envelope, ratio=%.3f\n", ratio);
}

Приёмка: занижение до 30 % под нагрузкой — норма (соотношение до ~0.70). Это штатно — см. troubleshooting.md §13. Не используйте жёсткий порог 3 %–5 %: он массово отбракует исправные модули.

Этот дрейф не влияет на точность Вт·ч (Вт·ч использует часы мастера); PERIOD_LATCH_MS предназначен только для вывода серьёзных аномалий на стороне микросхемы.

Когда нужна собственная мера модуля для длины закрытого окна, используйте PERIOD_COMMIT_COUNT (регистр 0xBE), умноженный на длину коммита: он считает целые коммиты RT и не занижает под нагрузкой так, как может PERIOD_LATCH_MS. Один коммит — 0.1 s с v1.2; образы старше v1.2 используют 0.2 s. Таблица версий для различения не нужна: отношение PERIOD_LATCH_MS / PERIOD_COMMIT_COUNT получается близким к 100 или к 200.

Далее

  • troubleshooting.md — что делать, если значения выглядят неверно
  • arduino-examples.md — пример 5 (двунаправленный обмен со стороны мастера на прошивке BASIC)