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

Справочник по проводному протоколу rbAmp (v1.3)

rbAmp — компактный модуль для измерения параметров сетевого переменного тока по интерфейсу I²C. Модуль ведёт себя как стандартное I²C-устройство с фиксированной картой регистров (страница 0, 0x00..0xFF). Этот документ описывает проводной протокол на уровне регистров, команд и последовательностей.

Аудитория

: сторонние и продвинутые интеграторы, пишущие собственные драйверы I²C для модуля rbAmp без клиентских библиотек (Arduino / ESP-IDF / Python / ESPHome).

Область: канонический проводной протокол модуля rbAmp версии v1.3 — карта регистров, последовательности протокола, гарантии поведения. Это полный справочник на уровне проводного контракта.

Версия: «v1.3» — это версия проводного протокола (регистр VERSION 0x03 возвращает 0x04), а не версия этого документа. Это протокол всех текущих прошивок модулей BASIC (1.4.x); модули STANDARD (STD) используют другую карту регистров — см. техническую справку STD.

НЕ входит в область: интеграция с конкретной библиотекой / ОС / фреймворком — читайте документацию этой библиотеки.


1 · Введение

1.1 Линейка SKU

Варианты модулей (SCT-UI1 … SCT-I3, с их каналами напряжения и тока) перечислены в overview.md → Варианты модулей.

I-варианты (I1/I2/I3) не имеют аппаратуры напряжения — регистры U_RMS, U_PEAK и P возвращают 0.0. Частота (AC_FREQ) доступна на всех вариантах (по переходу через ноль).

Калибровка заводская. Потребительский мастер НЕ настраивает уровень шума (NF), усиление, фазовую компенсацию или любые другие заводские параметры — всё это заводская калибровка, прошитая в модуль (см. §4.0 зарезервированные диапазоны). На модулях BASIC серии SCT (с датчиками SCT-013) потребитель записывает только SENSOR_CLASS + CT_MODEL (см. §6.2) — остальное модуль применяет сам из таблицы предустановок. Модули BASIC серии CT и STANDARD (STD) поставляются в паре со своими датчиками, настроенными и откалиброванными на заводе: ничего не записывается.

1.2 Версионирование

Поле Значение
protocol_version 1.3
schema_version 2
Регистр VERSION (0x03) 0x04 для v1.3
Контракт страницы 0 заморожено к выпуску v1.3

2 · Основы протокола шины

2.0 Мощность и питание

Параметр Значение
VCC номинальное +5 V
Диапазон VCC 4.5..5.5 V
Типичное потребление тока ~15 мА
Пиковое потребление тока (снимок + запись во флеш) ~25 mA
Бросок тока при включении ≤ 50 мА @ 5 мс
Последовательность VCC может подаваться одновременно с I²C; подтяжки (3.3 V) допустимы до подачи VCC
Изоляция модуль полностью низковольтный: клещи связываются магнитно, а отвод напряжения в модуле гальванически изолирован
Примечание

На низковольтной стороне обязательны четыре провода: VCC, GND, SDA, SCL. DRDY (открытый сток) необязателен. См. §2.3 о подтяжках и нескольких модулях.

2.1 Параметры I²C

  • Адрес по умолчанию: 0x50 (7-битный).
  • Допустимый диапазон адресов: 0x08..0x77 (стандартные зарезервированные границы I²C).
  • Логические уровни: 3.3 V (5 V-толерантны на подтяжках к 3.3 V).
  • Встроенные подтяжки: 4.7 кОм на SDA/SCL к 3.3 В (модуль).
  • Растяжение тактов: модуль НЕ использует растяжение SCL как штатное управление потоком. Между транзакциями мастер должен соблюдать паузу между транзакциями ≥ 100 мкс (tBUF). Транзакции без паузы (повторный START без tBUF) допустимы, но не рекомендуются — некоторые стеки хоста (ESP-IDF i2c_master) дают повышенную долю NACK. См. отдельно §5 о приёмке и ЭМС.

2.2 Скорость шины

Скорость Применимость Примечание
50 kHz рекомендуется на хостах ESP32 и ESP8266 Драйвер I²C ESP-IDF показывает ~20 % NACK при 100 kHz — ограничение драйвера хоста, а не модуля; 50 kHz + 3 повтора дают < 0.8 % ошибок.
100 kHz рекомендуется на других хостах также работоспособна на ESP32/ESP8266 с повтором 3× на уровне приложения.
400 кГц не рекомендуется скорость выбирает пользователь.

2.3 Многомодульная шина

На одной шине могут работать несколько модулей rbAmp:

  • До ~16 модулей (ограничено суммарной ёмкостью шины ≤ 400 пФ при 100 кГц).
  • Подтяжки: при 2–3 модулях на шине длиной до 15 см оставьте встроенные подтяжки; при четырёх и более или на более длинной шине 4.7 кОм подтяжки, включённые параллельно, перегружают выход. Отключите встроенные подтяжки на каждом модуле, кроме одного (или используйте буфер I²C PCA9515/9615).
  • Длина: до 0.15 m простым проводом → 100 kHz; 0.15–1 m витая пара (SDA+GND и SCL+GND в отдельных парах) → 100 kHz; > 1 m — буфер I²C; > 3 m — дифференциальная шина (PCA9615 / LTC4332).

2.4 Бюджет опроса шины

При 50 kHz одна транзакция чтения регистра занимает ≈ 200–400 µs. Полный блок RT для одного канала (U + I + P + PF, 4 float = 16 байт пакетом) занимает ≈ 5–8 мс на канал.

Конфигурация Шина за цикл Макс. частота опроса
1× UI1, блок RT ~5 мс 100+ Гц (но модуль обновляется с 10 Гц)
5× UI1, блок RT ~25 мс 10 Гц
16× I3, RT + период ~400 мс не успевает — читает примерно каждое 4-е окно 100 мс

Ориентир: при 50 kHz комфортные пределы — 8–10× I3 или 15–16× UI1 при опросе через окно (5 Гц); чтобы опрашивать каждое окно (10 Гц), число модулей вдвое меньше.


3 · Модель вариантов

3.1 HW_VARIANT (рег. 0x55, u8, только чтение)

Авторитетный байт SKU:

Значение SKU N_I HW напряжения
0x01 UI1 1 да
0x02 UI2 2 да
0x03 UI3 3 да
0x04 I1 1 нет
0x05 I2 2 нет
0x06 I3 3 нет
0x07 UI5 5 да
0x08 UI7 7 да

Любое другое значение → устройство не распознано как rbAmp.

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

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

Библиотека Вызов Что делает
Arduino RbAmp::readVariant() прочитать аппаратный вариант (SKU)
ESP-IDF rbamp_read_variant() прочитать аппаратный вариант (SKU)
Python dev.read_variant() прочитать аппаратный вариант (SKU)
ESPHome get_variant_str() прочитать аппаратный вариант (SKU)

3.2 CAPABILITY (регистры 0x57/0x58, u16 LE, только чтение)

Битовая карта функций. Это канонический способ определять поддерживаемые функции — без сравнения числовых версий.

бит Флаг Значение
0 EXT_ADDRESSING расширенная 16-битная адресация (префикс 0xFF)
1 GC_LATCH Снимок общего вызова поддерживается
2 GC_GROUP_FILTER фильтр GROUP_ID активен
3 DIGEST блок дайджеста (0x70..0x85) открыт
4 EVENTS EVENT_FLAGS поддерживается
5 UID_ARBITRATION арбитраж адресов по UID (публичных команд нет)
6 SEAL зарезервировано — не реализовано
7 TWO_PHASE_ADDR двухфазная фиксация смены адреса
8 ZC_PHASE_OFFSET = аппаратура напряжения у модуля есть канал U
9 SAVE_USER_CONFIG CMD_SAVE_USER_CONFIG доступна
10 CLEAR_ERROR CMD_CLEAR_ERROR доступна
11 IAP внутрисхемное программирование (только уровни F4)
12 SCT_RATING_SELF прошивка 1.4.20+: переключение модели CT сохраняет калибровку блока и переживает перезапуск; библиотеки пропускают собственную коррекцию номинала

3.2.1 Определение функций

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

3.2.2 Раскладка байтов CAPABILITY u16 LE

CAPABILITY — 2 байта по адресам 0x57 (младший байт) и 0x58 (старший байт), little-endian:

Text
register layout (byte-addressed):

  0x57   0x58
  ┌──────┬──────┐
  │ LO   │ HI   │
  └──────┴──────┘
   bits   bits
   0-7    8-15

  full u16 = (read_u8(0x58) << 8) | read_u8(0x57)

Распределение битов:

  • байт 0x57 (LO) содержит биты 0..7: EXT_ADDRESSING, GC_LATCH, GC_GROUP_FILTER, DIGEST, EVENTS, UID_ARBITRATION, SEAL, TWO_PHASE_ADDR.
  • байт 0x58 (HI) содержит биты 8..15: ZC_PHASE_OFFSET (= HW напряжения), SAVE_USER_CONFIG, CLEAR_ERROR, IAP, SCT_RATING_SELF (бит 12, fw 1.4.20+), биты 13–15 зарезервированы.

3.2.3 Канонический рецепт has_voltage

Python
cap_hi = read_u8(0x58)             # high byte holds bits 8..15
has_voltage = bool(cap_hi & 0x01)  # bit 8 of the u16 = bit 0 of byte 0x58
В клиентских библиотеках

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

Библиотека Вызов Что делает
Arduino RbAmp::readCapability(out) / RbAmp::hasVoltageHw() прочитать 16-битную карту функций; проверить наличие канала напряжения
ESP-IDF rbamp_read_capability() / rbamp_has_voltage() прочитать 16-битную карту функций; проверить наличие канала напряжения
Python dev.read_capability() / dev.has_voltage() прочитать 16-битную карту функций; проверить наличие канала напряжения
ESPHome get_capability_hex() прочитать битовую карту функций

3.3 Таблица профилей вариантов — инвариант

SKU HW_VARIANT (0x55) N_I аппаратура напряжения CAPABILITY бит 8 (аппаратура напряжения)
UI1 1 1 да бит 8 установлен
UI2 2 2 да бит 8 установлен
UI3 3 3 да бит 8 установлен
I1 4 1 нет бит 8 сброшен
I2 5 2 нет бит 8 сброшен
I3 6 3 нет бит 8 сброшен
UI5 7 5 да бит 8 установлен
UI7 8 7 да бит 8 установлен

Согласованность HW_VARIANT ⟷ CAPABILITY: HW_VARIANT 1..3 и 7..8 (UI) → бит 8 установлен; HW_VARIANT 4..6 (I) → бит 8 сброшен. Несоответствие означает аппаратную или прошивочную аномалию (неисправное устройство или неверная прошивка).

3.4 SENSOR_CLASS ≠ признак варианта

⚠ SENSOR_CLASS (0x25) НЕ является признаком варианта. Это регистр пользовательской конфигурации (выбор класса датчика CT: Unset/Sct013/WiredCT/BuiltinCT), он не отражает аппаратный вариант. Для определения варианта используйте только HW_VARIANT (0x55) + CAPABILITY (0x57/0x58).

3.5 PRODUCT_ID (0x54, u8, только чтение)

Признак семейства продуктов:

Значение Семейство
0x01 датчик rbAmp (этот документ)
0x02 rbDimmer (отдельная карта регистров; в этом документе не описывается)

Мастер ДОЛЖЕН прочитать PRODUCT_ID до интерпретации любого регистра, специфичного для семейства.

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

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

Библиотека Вызов Что делает
Arduino RbAmp::readProductId() прочитать байт идентификатора семейства
ESP-IDF rbamp_read_product_id() прочитать байт идентификатора семейства
Python dev.read_product_id() прочитать байт идентификатора семейства
ESPHome — не предоставляется

3.6 Канонический алгоритм обнаружения

Python
if not i2c_addr_acks(addr):
    return NO_DEVICE
product = read_u8(addr, 0x54)
if product != 0x01:
    return NOT_RBAMP_SENSOR
hw = read_u8(addr, 0x55)
if 1 <= hw <= 8:
    cap_hi = read_u8(addr, 0x58)
    has_voltage = bool(cap_hi & 0x01)
    return {sku: SKU[hw], N_I: N_I_TABLE[hw], has_voltage: has_voltage}
return UNKNOWN_DEVICE
В клиентских библиотеках

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

Библиотека Вызов Что делает
Arduino RbAmp::begin() / RbAmp::readVariant() опросите модуль, определите его линию; прочитайте вариант
ESP-IDF rbamp_begin() / rbamp_read_variant() опросите модуль, определите его линию; прочитайте вариант
Python dev.begin() / dev.read_variant() опросите модуль, определите его линию; прочитайте вариант
ESPHome rbamp: address: / get_variant_str() адрес модуля задан в YAML; вариант в виде текста

4 · Карта регистров (производственная v1.3)

Применённый фильтр: build: production(регистры калибровки для сборки cal исключены). Регистры заводской калибровки (NF, GAIN, PHASE) —не документировано— они относятся к заводскому стенду, а не к пользовательской части.

Обзор карты регистров rbAmp и её блоков адресов.

4.0 Зарезервированные диапазоны (внутренние)

Следующие диапазоны зарезервированы для внутреннего/заводского использования и в этом документе не описаны. Чтение возвращает либо данные, не относящиеся к логике потребителя, либо 0x00 для несуществующих адресов (см. §5.2). Записи в эти адреса либо молча отбрасываются, либо отклоняются с ERR_PARAM:

  • 0x04 — внутренний индикатор режима (управляется на заводе, не настраивается потребителем).
  • 0x06, 0x26 — внутренние калибровочные параметры (заводской стенд).
  • 0x08..0x0F — отладочный вид LUT (заводская диагностика).
  • 0x1B..0x1F — зарезервированы в странице 0 (0x18..0x1A — производственная диагностика, см. §4.2).
  • 0x36..0x3B, 0x40..0x45 — зарезервировано на странице 0 (0x32 + 0x3C..0x3F — окно доступа к каналам, см. §4.14).
  • 0x4F, 0x50 — зарезервированы (предварительный резерв блока идентификации).
  • 0xE4..0xEB, 0xF0..0xFF — заводская калибровка (NF, GAIN); записи разрешены только на заводе.
Примечание

Примечание о 0xD0..0xE3: в производственной сборке этот диапазон занят блоком V03 Q (см. §4.12). В отдельной калибровочной прошивке (потребителю не поставляется) тот же диапазон перекрыт калибровочным блоком (build:cal). Потребительский мастер видит только производственное наложение — блок Q.

Сторонние интеграторы (3rd-party) должны игнорировать эти диапазоны.

4.1 Блок управления (0x00..0x07)

Адрес Имя Размер Тип Доступ Сохранение Примечания
0x00 STATUS 1 u8 r ram bit0=READY, bit1=ERROR (зеркало REG_ERROR != 0), bit2=EVENTS_PENDING (зеркало EVENT_FLAGS != 0)
0x01 COMMAND 1 u8 w ram Запишите код CMD_* (см. §5.2)
0x02 ERROR 1 u8 r ram результат последней записи; 0x00 = OK; классы ошибок 0xFA..0xFF. Сбрасывается командой CMD_CLEAR_ERROR. См. §5.3
0x03 VERSION 1 u8 r rom Версия протокола. 0x04 = v1.3
0x05 CT_MODEL 1 u8 rw user_config Код SKU датчика SCT-013 (чистая промежуточная запись v1.3 — см. §6.2)
0x07 V03_PERIOD_VALID 1 u8 r ram Выставляется CMD_LATCH_PERIOD: 1 = свежий, 0 = пустой/устаревший. НЕ сбрасывается при чтении. См. §6.3.3 (свидетель) + §7.5 (сохранение периода при неудачном снимке)
В клиентских библиотеках

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

Библиотека Вызов Что делает
Arduino RbAmp::waitReady(timeout_ms) / RbAmp::readLastError() дождаться бита готовности; прочитать код ошибки устройства
ESP-IDF rbamp_wait_ready() / rbamp_read_last_error() дождаться бита готовности; прочитать код ошибки устройства
Python dev.wait_ready(timeout_ms=1000) / dev.read_last_error() дождитесь флага готовности (вызывает ошибку по таймауту); прочитайте код ошибки устройства
ESPHome update() проверка готовности / get_last_error_str() показания публикуются, когда модуль сообщает о готовности; код ошибки в виде текста

4.2 Диагностика — средние сырых входов и окно захвата (0x10..0x1C)

Адрес Имя Размер Тип Доступ Сохранение Примечания
0x10 ADC_MEAN_U 2 u16 LE r ram Среднее сырого входа, канал U (~2048, по центру)
0x12 ADC_MEAN_I0 2 u16 LE r ram Среднее сырого входа, I0
0x14 ADC_MEAN_I1 2 u16 LE r ram Среднее сырого входа, I1 (UI2/I2/I3/UI3)
0x16 ADC_MEAN_I2 2 u16 LE r ram Среднее сырого входа, I2 (UI3/I3)
0x18 CAPTURE_STATUS 1 u8 r ram Захват сырых выборок: bit0=готово
0x19 CAPTURE_PAGE 1 u8 rw ram Страница 0..15 → 16 сырых отсчётов I0 в CAPTURE_WINDOW
0x1A CAPTURE_WINDOW 32 байт r ram 16×u16 LE сырых кодов I0 до LUT. Пакетное чтение 32 байт.

4.3 Система (0x20..0x25)

Адрес Имя Размер Тип Доступ Сохранение Примечания
0x20 AC_FREQ 1 u8 r ram По переходу через ноль. 50 или 60 Гц, целое. Переход через ноль активен на всех вариантах (включая I*)
0x21 AC_PERIOD 2 u16 LE r ram Полупериод сети, µs
0x23 CALIBRATION 1 u8 r ram Байт статуса устаревшей калибровки
0x24 TOPOLOGY 1 u8 r rom Число токовых каналов (= V03_N_I): 1, 2 или 3; 5 = UI5, 7 = UI7
0x25 SENSOR_CLASS 1 u8 rw user_config 0 = UNSET, 1 = SCT_013, 2 = WIRED_CT (серия клещей CT, модели 1..13: 1..5 — устаревшие; заводски спаренные на SKU CT- — на прошивке 1.4.22 и новее модуль отклоняет запись класса и модели в штатном режиме с ERR_PARAM (0xFE); клиентские библиотеки отклоняют их на всех прошивках), 3 = BUILTIN_CT (заводская калибровка каждого экземпляра, код модели не используется). Смена класса сбрасывает CT_MODEL = 0. Не является признаком варианта (см. §3.4)
В клиентских библиотеках

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

Библиотека Вызов Что делает
Arduino RbAmp::setSensorClass(cls) / RbAmp::readSensorClass(out) задать класс датчика; прочитать его обратно
ESP-IDF rbamp_set_sensor_class() / rbamp_read_sensor_class() задать класс датчика; прочитать его обратно
Python dev.set_sensor_class(cls) / dev.read_sensor_class() задать класс датчика; прочитать его обратно
ESPHome sensor_class: Параметр YAML, фиксирующий класс датчика

4.4 Конфигурация парка (0x27..0x2F)

Адрес Имя Размер Тип Доступ Сохранение Примечания
0x27 FLEET_CONFIG 1 u8 rw user_config bit0 = GC_ENABLE (приём снимка общего вызова; действует после сброса). Биты 1–7 зарезервированы
0x28 GROUP_ID 1 u8 rw user_config Фильтр группы снимков GC. 0 = отвечать на общий вызов. Байт группы в кадре GC должен совпадать или быть 0x00
0x29 DIGEST_CONFIG 1 u8 rw ram Битовая маска состава окна дайджеста (см. §4.9); запись неподдерживаемого бита → ERR_PARAM. По умолчанию 0x00 (дайджест отключён) после сброса; перезаписывайте при каждой инициализации
0x2A EVENT_FLAGS 1 u8 w1c ram Липкие биты событий (см. §5.3 модель ошибок). По умолчанию 0x00 после сброса (но бит5 RESET_OCCURRED выставляется при загрузке)
0x2B EVENT_MASK 1 u8 rw ram Какие биты EVENT_FLAGS переводят DRDY в постоянный LOW
0x2C THRESH_I_HI 2 u16 LE rw ram Порог тока → EVENT_FLAGS.THRESH_I. Единицы: 0.01 A. 0xFFFF = отключено
0x2E THRESH_P_HI 2 u16 LE rw ram Порог мощности → EVENT_FLAGS.THRESH_P. Единицы: Вт. 0xFFFF = отключено
В клиентских библиотеках

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

Библиотека Вызов Что делает
Arduino RbAmp::enableGc(enable) / RbAmp::setEventThresholds(i_amps, p_watts) включить общий вызов на модуле; задать пороги тока и мощности
ESP-IDF rbamp_enable_gc() / rbamp_set_event_thresholds() включить общий вызов на модуле; задать пороги тока и мощности
Python dev.enable_gc(enable=True) / dev.read_event_flags() включите General Call на модуле; читайте флаги событий (сеттера порога для устройства нет)
ESPHome fleet_gc_enable: / group_id: Параметры YAML для включения общего вызова и идентификатора группы

4.5 Адрес (0x30..0x31)

Адрес Имя Размер Тип Доступ Сохранение Примечания
0x30 I2C_ADDRESS 1 u8 rw user_config Двухфазная фиксация: запишите кандидата 0x08..0x77 → промежуточный регистр RAM; взведите ADDR_COMMIT_MAGIC; затем CMD_COMMIT_ADDR; применяется после сброса. При загрузке активный адрес читается обратно (v1.3 Fix 4)
0x31 ADDR_COMMIT_MAGIC 1 u8 w ram Запишите 0xA5, чтобы взвести CMD_COMMIT_ADDR. Сбрасывается (очищается) при попытке фиксации. Чтения возвращают 0x00

Последовательность — см. §6.1.

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

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

Библиотека Вызов Что делает
Arduino RbAmp::prepareAddressChange(new_addr) / RbAmp::readActiveAddress(out) записать и взвести новый адрес; прочитать активный адрес
ESP-IDF rbamp_prepare_address_change() / rbamp_read_active_address() записать и взвести новый адрес; прочитать активный адрес
Python dev.prepare_address_change(new_addr) / dev.commit_address_change() поставьте в очередь и взведите новый адрес, затем зафиксируйте его
ESPHome new_address: однократная смена адреса при загрузке; затем удалите этот параметр

4.6 Здоровье / диагностика (0x46..0x4F)

Адрес Имя Размер Тип Доступ Сохранение Примечания
0x46 UPTIME_S 4 u32 LE r ram Собственный счётчик времени работы модуля (номинально секунды с загрузки) — только детектор перезапуска: в прошивках до 1.4.21 он идёт медленнее реального времени (измерено 0.58–0.80×), поэтому никогда не используйте его как часы. Обнаружение перезапуска для мастера: значение уменьшилось или меньше времени, прошедшего с предыдущего снимка мастера
0x4A RESET_CAUSE 1 u8 r ram Флаги причины сброса (bit0=PIN, bit1=POR/BOR, bit2=SW, bit3=IWDG, bit4=WWDG, bit5=LPWR). Только для журнала — обработка перезапуска одинакова независимо от причины
0x4B I2C_ERR_COUNT 2 u16 LE r ram Ошибки шины (BERR+OVR) с момента загрузки, с насыщением
0x4D I2C_REINIT_COUNT 1 u8 r ram счётчик восстановлений I²C-периферии после BUSY, с насыщением
0x4E ZC_OFFSET 2 u16 LE r ram мкс от фронта STOP последнего GC-снимка до следующего перехода напряжения через ноль — используется для фазовой компенсации U/I при расчёте мощности. На вариантах только с током прошивка фиксирует значение 0xFFFF (нет входа напряжения → нет перехода через ноль по U). Это не источник перехода через ноль сети — AC_FREQ (0x20) берётся с отдельного пина перехода через ноль сети и доступен на всех вариантах.
В клиентских библиотеках

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

Библиотека Вызов Что делает
Arduino — Регистры состояния BASIC не выведены (только линейка STD)
ESP-IDF rbamp_read_uptime_s() прочитать время работы модуля в секундах
Python — Регистры состояния BASIC не выведены (только линейка STD)
ESPHome — нет сущности времени работы или состояния

4.7 Зеркала проверки модели CT (0x51..0x53)

Регистры только для чтения — зеркала применённой предустановки модели CT по каналам. Протокол записи не меняется (см. §6.2) — это только обратное чтение для проверки.

Адрес Имя Размер Тип Доступ Сохранение Примечания
0x51 CT_MODEL_CH0 1 u8 r user_config Применённая предустановка модели CT на ch0 (зеркало проверки)
0x52 CT_MODEL_CH1 1 u8 r user_config Применённая предустановка модели CT на ch1
0x53 CT_MODEL_CH2 1 u8 r user_config Применённый пресет модели CT на ch2
В клиентских библиотеках

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

Библиотека Вызов Что делает
Arduino RbAmp::readCTModelCh(channel, out) прочитайте модель CT, фактически применённую на канале
ESP-IDF rbamp_read_ct_model_ch() прочитайте модель CT, фактически применённую на канале
Python dev.read_ct_model_ch(ch) прочитайте модель CT, фактически применённую на канале
ESPHome журнал загрузки ct_model[0]: matches строки лога, подтверждающие, что класс датчика и модель применены

4.8 Идентификация (0x54..0x6F)

Адрес Имя Размер Тип Доступ Сохранение Примечания
0x54 PRODUCT_ID 1 u8 r rom Семейство: 0x01 = датчик rbAmp. Мастер читает это до любого регистра, специфичного для семейства
0x55 HW_VARIANT 1 u8 r rom См. §3.1
0x56 FW_TIER 1 u8 r rom биты 0-1: 0=BASIC, 1=STANDARD (2 = не реализовано); бит 2=двунаправленный; бит 3=калибровка по LUT
0x57 CAPABILITY 2 u16 LE r rom См. §3.2
0x59 GC_TICK 2 u16 LE r ram Тик мастера по последнему принятому кадру GC; 0xFFFF = ни одного не получено
0x5C UID 12 байт r rom 96-битный UID микросхемы. Читается одной пакетной операцией.
0x68 LABEL 8 байт rw user_config Пользовательская метка места (ASCII, дополнена нулями). Пусто = не задано. Записывайте побайтно (см. §5.1)
В клиентских библиотеках

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

Библиотека Вызов Что делает
Arduino RbAmp::readProductId() / RbAmp::readUid(uid) прочитать ID семейства; прочитать 96-битный UID
ESP-IDF rbamp_read_product_id() / rbamp_read_uid() прочитать ID семейства; прочитать 96-битный UID
Python dev.read_product_id() / dev.read_uid() прочитать ID семейства; прочитать 96-битный UID
ESPHome get_uid_hex() / get_variant_str() UID в шестнадцатеричном виде; исполнение — текстом

4.9 Окно дайджеста (0x70..0x85)

DIGEST — компактное окно опроса, отдаётся одной пакетной операцией чтения. Его состав выбирается через DIGEST_CONFIG (0x29); запись, устанавливающая неподдерживаемый бит, отклоняется с ERR_PARAM:

DIGEST_CONFIG бит Содержание Формат
бит 0 I_RMS[N] u16 на канал, 0.01 A
бит 1 U_RMS u16, 0.1 V (только для варианта с напряжением)
бит 2 P_REAL[N] i16 на канал, 1 W (только has_power)
бит 3 PF[N] u8 на канал, 0..100 (только has_power)
Адрес Имя Размер Тип Доступ Сохранение Примечания
0x70 DIGEST 22 байт r ram Структура: [STATUS_MIRROR u8][SEQ u8] + поля, разрешённые маской. Максимальная полезная нагрузка (полная маска UI3) — 19 B + заголовок 2 B = 21 B используется; 1 B хвоста не используется (читается как 0x00). SEQ увеличивается на каждый коммит RT, с переходом 255→0. Атомарно через заморозку чтения (см. §5.4).

Раскладка динамическая, по DIGEST_CONFIG — каждый включённый бит добавляет свои поля в фиксированном порядке: I_RMS[N] → U_RMS → P[N] → PF[N]. Отключённые биты не оставляют заполнения — поля сдвигаются вперёд. Мастер должен разбирать данные с той же маской, которую записал в DIGEST_CONFIG. Пакетное чтение 22 байт безопасно (хвост равен 0x00, пока общая полезная нагрузка меньше 22 байт). Однобайтовый хвост всегда 0x00 (зарезервирован).

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

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

Библиотека Вызов Что делает
Arduino — окно дайджеста не выведено
ESP-IDF rbamp_set_digest_fields() / rbamp_read_digest() выберите поля дайджеста; прочитайте их одной транзакцией (BASIC)
Python — окно дайджеста не выведено
ESPHome — окно дайджеста не выведено

4.10 Блок реального времени V03 (0x86..0xBD)

Все float32 LE (IEEE 754 одинарной точности, стандартный порядок байтов little-endian). Побайтовая раскладка заморожена на v1.2. Все регистры — доступ r, хранение ram, группа v03_rt. Атомарно через заморозку чтения (см. §5.4): пакетное чтение 56 байт (0x86..0xBD) гарантированно непрерывно (без разорванного снимка).

Адрес Имя Размер Тип Доступ Сохранение Единицы Примечания
0x86 V03_U_RMS 4 float32 LE r ram V 0.0 на I-вариантах
0x8A V03_U_PEAK 4 float32 LE r ram V
0x8E V03_I0_RMS 4 float32 LE r ram A
0x92 V03_I1_RMS 4 float32 LE r ram A 0.0, если вариант не имеет ch1
0x96 V03_I2_RMS 4 float32 LE r ram A 0.0, если вариант не имеет ch2
⛔ СТОП — плоские посканальные RMS заканчиваются на канале 2. Следующая строка (0x9A) — это V03_I0_PEAK, а НЕ V03_I3_RMS. НЕ экстраполируйте шаблон шага 4 дальше канала 2 — вы получите правдоподобные, но молча неверные числа (пик, а не RMS; канал 0, а не 3). Каналы 3+ (UI5/UI7) доступны только через окно доступа к каналам — см. §4.14.
0x9A V03_I0_PEAK 4 float32 LE r ram A
0x9E V03_I1_PEAK 4 float32 LE r ram A
0xA2 V03_I2_PEAK 4 float32 LE r ram A
0xA6 V03_P0_REAL 4 float32 LE r ram W 0.0 на I-вариантах (расчёта мощности нет)
0xAA V03_P1_REAL 4 float32 LE r ram W
0xAE V03_P2_REAL 4 float32 LE r ram W
0xB2 V03_PF0 4 float32 LE r ram – диапазон −1..+1
0xB6 V03_PF1 4 float32 LE r ram –
0xBA V03_PF2 4 float32 LE r ram –
В клиентских библиотеках

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

Библиотека Вызов Что делает
Arduino RbAmp::readAll(snapshot) / RbAmp::channels() читайте весь блок реального времени; количество токовых каналов
ESP-IDF rbamp_read_all() / rbamp_channels() читайте весь блок реального времени; количество токовых каналов
Python dev.read_all() / dev.channels читайте весь блок реального времени; количество токовых каналов
ESPHome voltage / power Датчики YAML для значений реального времени

4.11 Блок периода V03 (0xBE..0xCF)

Снимок периода, взятый по CMD_LATCH_PERIOD. Неровная раскладка (историческое наследие v1.2, заморожено в v1.3): avg_p для ch1/ch2 находится здесь, а avg_p для ch0 — в §4.12 по адресу 0xDC (исходный примитив энергии не переносился, чтобы не ломать API существующих интеграторов). Логически эти три значения относятся к одной группе.

Адрес Имя Размер Тип Доступ Сохранение Единицы Примечания
0xBE V03_PERIOD_COMMIT_CNT 4 u32 LE r ram – Коммиты RT в закрытом периоде. Один коммит = 0.1 s с v1.2 (0.2 s раньше) — количество × длина коммита — собственная мера модуля для длины окна (см. §7.4)
0xC2 V03_PERIOD_AVG_P_CH1 4 float32 LE r ram W Снимок средней P ch1 (UI2, UI3)
0xC6 V03_PERIOD_AVG_P_CH2 4 float32 LE r ram W Снимок средней P ch2 (UI3)
0xCA V03_PERIOD_MS 4 u32 LE r ram мс Длительность текущего периода
0xCE V03_STATUS 1 u8 r ram – бит 0 = действителен (результат фиксации RT). НЕ сбрасывается при чтении. Мастер опрашивает STATUS (0x00) в ожидании готовности. Псевдоним DATA_VALID иногда используется для этого регистра в учебных главах — тот же адрес, та же семантика.
В клиентских библиотеках

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

Библиотека Вызов Что делает
Arduino RbAmp::readPeriodAvgPower(ch) / RbAmp::readPeriodSnapshot() прочитайте среднюю мощность периода; снимите и прочитайте полный периодный снимок
ESP-IDF rbamp_read_period_avg_power() / rbamp_read_period_snapshot() прочитайте среднюю мощность периода; снимите и прочитайте полный периодный снимок
Python dev.read_period_avg_power(ch) / dev.read_period_snapshot() прочитайте среднюю мощность периода; снимите и прочитайте полный периодный снимок
ESPHome update_interval: / latch_interval: Параметры YAML для периода и частоты снимков

4.12 V03 Q + период ch0 (0xD0..0xE3, производственная сборка)

Адрес Имя Размер Тип Доступ Сохранение Единицы Примечания
0xD0 V03_Q0_REAC 4 float32 LE r ram ВАр Реактивная мощность ch0 = √(S² − P²), S = U_rms × I_rms — без знака (≥ 0), включает мощность искажений; 0 на I-only вариантах; шумная вблизи PF ≈ 1. Точность не задана
0xD4 V03_Q1_REAC 4 float32 LE r ram ВАр
0xD8 V03_Q2_REAC 4 float32 LE r ram ВАр
0xDC V03_PERIOD_AVG_P 4 float32 LE r ram W PRODUCTION примитив энергии: снимок средней P ch0, ≥ 0 (однонаправленные клещи BASIC). Логически сгруппирован с V03_PERIOD_AVG_P_CH1/CH2 (§4.11); старая раскладка сохранена для совместимости
0xE0 V03_PERIOD_MAX_P 4 float32 LE r ram W Максимум снимка P ch0 за этот период
В клиентских библиотеках

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

Библиотека Вызов Что делает
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) / dev.read_period_max_power() прочитать среднюю и максимальную мощность периода
ESPHome reactive_power / update_interval: датчик реактивной мощности; каждое обновление закрывает период и читает средние значения

4.13 Диагностический dt на стороне микросхемы (0xEC)

Адрес Имя Размер Тип Доступ Сохранение Единицы Примечания
0xEC V03_PERIOD_LATCH_MS 4 u32 LE r ram мс Dt на стороне микросхемы между двумя последними снимками. Диагностический таймер модуля — под нагрузкой может занижать; для энергии используйте часы мастера. См. §7.4
В клиентских библиотеках

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

Библиотека Вызов Что делает
Arduino RbAmp::readPeriodLatchMs() прочитать длину периода на стороне модуля (только для диагностики)
ESP-IDF rbamp_read_period_latch_ms() прочитать длину периода на стороне модуля (только для диагностики)
Python dev.read_period_latch_ms() прочитать длину периода на стороне модуля (только для диагностики)
ESPHome — не предоставляется

4.14 Окно доступа к каналам (0x32 + 0x3C..0x3F)

Относится к UI5 (5 каналов) и UI7 (7 каналов). На UI1/UI2/UI3 и I1/I2/I3 доступен тоже — единый путь, если вы предпочитаете его плоским регистрам §4.10.

Каналы 3..6 не имеют плоских посканальных регистров (в 8-битном адресном пространстве было место для 8 байт, а плоская раскладка потребовала бы ~88). Вместо этого открыто окно выбора и чтения:

Адрес Имя Размер Тип Доступ Сохранение Примечания
0x32 REG_CHANNEL_SELECT 1 u8 rw ram Это адрес регистра, а НЕ код операции CMD_SAVE_USER_CONFIG — они численно совпадают. Всегда указывайте 0x32 вместе с тем пространством (регистры или команды), которое имеете в виду. Кодируется как (field << 4) \| channel. Диапазон номера канала channel — 0..15 (зарезервировано до 16 каналов); физический максимум для SKU — channels() (7 у UI7). Селектор, у которого индекс канала >= channels(), принимается без ERR_PARAM; окно данных тогда читается как 0, а записи в него игнорируются. field — по таблице ниже. Запись селектора переносит запрошенное значение в REG_CHANNEL_DATA.
0x3C..0x3F REG_CHANNEL_DATA 4 float32 LE r ram Буфер данных для выбора. float32 LE для всех публичных полей.

Коды полей (старший полубайт в 0x32):

Код Поле Тип Доступ Значение
0 CHFIELD_I_RMS float32 LE r Действующий ток выбранного канала в реальном времени (единицы — A)
1 CHFIELD_I_PEAK float32 LE r Живой пиковый ток (единицы A)
2 CHFIELD_P_REAL float32 LE r Мгновенная активная мощность (единицы Вт)
3 CHFIELD_PF float32 LE r Коэффициент мощности в реальном времени (−1..+1)
4..12 (reserved) – – Не документировано для пользовательского кода; не полагайтесь на значения или коды.
13 CHFIELD_PERIOD_AVG_P float32 LE r Снимок средней активной мощности за период (Вт). Для каналов 3+ это ЕДИНСТВЕННОЕ поле периода/энергии — плоские V03_PERIOD_AVG_P* (§4.11/§4.12) покрывают только ch0..ch2.
14 (reserved) – – Зарезервировано для будущих прошивок; не полагайтесь на это.
15 CHFIELD_CT_MODEL u8 в 0x3C (байты 0x3D..0x3F читаются как нули-заполнители) rw Прошивка ≥ 1.4.18. Код модели клещей CT для выбранного канала (0..N-1). Чтение возвращает применённую на канале модель. Запись только в RAM и применяется сразу: масштабирование канала переключается на предустановку выбранной модели в той же транзакции; отдельной команды фиксации и CMD_SET_CT_MODEL_CH* не требуется. Записи выполняются побайтно согласно правилу проводного протокола (§5.1). Неизвестная пара (SENSOR_CLASS, code) возвращает ERR_PARAM (0xFE), и канал сохраняет прежнюю модель — частичного состояния не возникает. Каналы старших SKU (ch3+) БОЛЬШЕ НЕ наследуют глобальную модель — каждый канал нужно настраивать явно через поле 15. Сохранение: CMD_SAVE_USER_CONFIG (опкод 0x32 в REG_COMMAND, без гейта) сохраняет модели всех каналов во flash-страницу пользовательской конфигурации одной командой. Запись без последующего CMD_SAVE_USER_CONFIG откатывается при перезагрузке. Набор допустимых пар (class, code) определяется таблицей моделей вашей версии прошивки; модуль однозначно подтверждает код — запишите, прочитайте обратно и проверьте REG_ERROR. На модулях с прошивкой v1.4.0 запись этого поля возвращает ERR_PARAM; вместо неё используйте команды по каналам и промежуточную запись плоского REG_CT_MODEL.

Четыре ловушки — прочитайте это до написания кода

  1. ⛔ Плоский RMS по каналам заканчивается на канале 2. Строки V03_I0_RMS (0x8E) → V03_I1_RMS (0x92) → V03_I2_RMS (0x96) идут с шагом 4, и 0x9A продолжает шаг — но 0x9A — это V03_I0_PEAK, а не V03_I3_RMS. Экстраполяция шаблона молча вернёт пик канала 0 вместо RMS канала 3. Прошивка ошибку не обнаружит; значение выглядит правдоподобно. Каналы 3+ доступны только через окно доступа к каналам.
  2. Выбирайте перед каждым чтением. REG_CHANNEL_DATA — это снимок, взятый в момент записи селектора, а не живое представление. Опрос 0x3C..0x3F в цикле без повторной записи 0x32 возвращает замороженное значение навсегда. Каждое новое показание требует новой записи в 0x32.
  3. 0x32 адрес регистра ≠ 0x32 код операции. CMD_SAVE_USER_CONFIG использует опкод 0x32, записываемый в REG_COMMAND (0x01) — это другое адресное пространство, чем REG_CHANNEL_SELECT (находящийся по адресу регистра 0x32). Никогда не указывайте 0x32 без пояснения, о каком пространстве речь.
  4. Для каналов 3+ период/энергия поступают только из поля 13 (CHFIELD_PERIOD_AVG_P). Регистры V03_PERIOD_AVG_P* (0xC2/0xC6/0xDC) покрывают только ch0/ch1/ch2. Плоского V03_PERIOD_AVG_P_CH3 не существует — вместо него читайте поле 13 через окно.

Пример на уровне кадров — чтение действующего тока канала 3

Text
# select field=0 (I_RMS), channel=3  →  (0 << 4) | 3  =  0x03
write_u8(REG_CHANNEL_SELECT=0x32, 0x03)

# read 4 bytes at REG_CHANNEL_DATA — float32 LE
bytes = read(0x3C, 4)
i3_rms = unpack_float32_le(bytes)   # amperes

Для пикового тока канала 4: селектор = (1 << 4) | 4 = 0x14, затем читайте 0x3C..0x3F. Для средней мощности периода канала 5: селектор = (13 << 4) | 5 = 0xD5, затем читайте 0x3C..0x3F.

Пример на уровне кадров — чтение действующего тока по ВСЕМ каналам модуля UI7

Объединяет оба пути в одном цикле: плоский блок RT для ch 0..2, окно доступа к каналам для ch 3..6.

Text
# --- Discover physical channel count -----------------------------
N = read_u8(TOPOLOGY=0x24)      # 5 on UI5, 7 on UI7

# --- ch 0..2 via flat block (single 12-byte burst) ---------------
bytes = read(V03_I0_RMS=0x8E, 12)
i0 = unpack_float32_le(bytes[0:4])
i1 = unpack_float32_le(bytes[4:8])
i2 = unpack_float32_le(bytes[8:12])

# --- ch 3..N-1 via channel access window (re-select per read) ----
i_rms = [i0, i1, i2]
for ch in range(3, N):
    write_u8(REG_CHANNEL_SELECT=0x32, (0 << 4) | ch)   # field 0 = I_RMS
    i_rms.append(unpack_float32_le(read(REG_CHANNEL_DATA=0x3C, 4)))

# i_rms is now length-N: RMS current for every physical channel of the module.

Тот же шаблон распространяется на I_PEAK (поле 1), P_REAL (поле 2), PF (поле 3) и на снимок PERIOD_AVG_P (поле 13) — плоский блок для ch0..ch2, окно для ch3+. Поле 13 — ЕДИНСТВЕННЫЙ источник периода/энергии для ch3+ — у плоского блока нет V03_PERIOD_AVG_P_CH3..6.

Для настройки модели CT для отдельного канала (0..N-1) используйте поле окна 15 (CHFIELD_CT_MODEL): запишите (15 << 4) | ch в 0x32, затем запишите код модели одним байтом в 0x3C. Сохраните модели всех каналов одной командой CMD_SAVE_USER_CONFIG (код операции 0x32 в REG_COMMAND (0x01) — без ограничений).

Рекомендация для новых интеграций

Окно охватывает каналы 0..6 — его можно использовать как единый унифицированный путь для всех каналов вместо ветвления между плоскими регистрами (ch0..ch2) и окном (ch3..ch6). Для парков, где смешаны младшие (UI1/UI2/UI3) и старшие (UI5/UI7) SKU, это устраняет раздвоение кода. Задержка — одна лишняя короткая запись на показание (по сравнению с одним пакетным чтением плоского блока).

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

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

Библиотека Вызов Что делает
Arduino RbAmp::readCurrent(ch) / RbAmp::channels() прочитать любой канал по индексу; число каналов
ESP-IDF rbamp_read_channel() / rbamp_read_all_channels() прочитать один канал по индексу, включая каналы 3 и выше; прочитать все каналы
Python dev.current[ch] / dev.channels индекс по допустимым каналам; число каналов
ESPHome current_N: слоты датчиков по каналам для до семи токовых каналов

5 · Проводной протокол

5.1 Асимметрия READ / WRITE

Пакетное чтение автоинкрементируется, а многобайтные записи идут побайтно.

Канонически заложенное поведение:

Направление Авто-инкремент Шаблон
READ (пакетное чтение N байт) ✅ ДА read(addr, N) возвращает N подряд идущих байтов, начиная с addr.
ЗАПИСЬ (многобайтные регистры) ❌ НЕТ Многобайтовый регистр записывается побайтово — отдельная однобайтовая транзакция на каждый адрес. Пакетная запись теряет байты 1..N-1 и принимает только первый.

Затрагиваемые записываемые многобайтовые регистры (запись побайтово)

  • LABEL (0x68-0x6F, 8 байт)
  • THRESH_I_HI (0x2C, 2 байта u16 LE)
  • THRESH_P_HI (0x2E, 2 байта u16 LE)

Порядок байтов при многобайтной ЗАПИСИ: байт по меньшему адресу — младший (LE). Например, чтобы записать THRESH_I_HI = 0x1234 (4660 в десятичной записи):

Text
# CORRECT: low byte first (LE)
write(addr=0x2C, value=0x34)   # LO byte
write(addr=0x2D, value=0x12)   # HI byte

Пример НЕПРАВИЛЬНО / ПРАВИЛЬНО (псевдокод)

Text
# WRONG — only 'M' (first byte) is accepted, the rest are dropped
write(addr=0x50, reg=0x68, data=b"MyMeter1")   # 8-byte burst

# CORRECT — byte-at-a-time loop
label = b"MyMeter1"
for i, byte in enumerate(label):
    write(addr=0x50, reg=0x68 + i, data=byte)

Исключение — широковещательный кадр GC

Кадр широковещательного снимка GC (адрес общего вызова 0x00 + полезная нагрузка 5 байт) — это отдельный путь проводного протокола, а не запись в регистр. Асимметрия чтения/записи из §5.1 к GC не применяется. См. §6.3.

5.2 Поведение незанятых регистров

Любое чтение неотображённого адреса возвращает 0x00. Прошивка никогда не отвечает NACK на чтение регистров. Так задумано (исправление зависания шины).

Следствие для обнаружения: обнаружение отсутствующего устройства должно идти через подтверждение адреса I²C (ACK), а не через проверку регистров.

5.3 Модель ошибок

Канон v1.3:

  • REG_ERROR (0x02) — результат последней записи, НЕ липкий. При каждой записи в регистр прошивка устанавливает reg_error = ERR_OK; любая последующая не связанная запись сбрасывает предыдущую ошибку.
  • EVENT_FLAGS (0x2A) bit 3 — долговременный сигнал (липкий W1C), выставляется при любой отклонённой записи или команде.

Коды ошибок

Код Имя Серьёзность
0x00 OK –
0xF9 CLONE зарезервировано — не выставляется
0xFA LUT_BAD ошибка
0xFB FLASH_PARAMS_BAD ошибка (см. §6.5 первая прошивка)
0xFC NOT_READY ошибка
0xFD SENSOR_OVERFLOW ошибка
0xFE PARAM ошибка (отклонённая запись — неверный аргумент / неизвестный опкод / значение перечисления вне диапазона; выставляет EVENT.bit3. Самые ранние образы, 1.2–1.4.3, молча игнорировали неизвестные опкоды)
0xFF UNHANDLED ошибка

Структура EVENT_FLAGS (0x2A) (липкий, W1C)

бит Имя Примечания
0 PERIOD_READY снимок периода доступен
1 THRESH_I I_rms превысил THRESH_I_HI
2 THRESH_P Сумма P превысила THRESH_P_HI
3 ERROR REG_ERROR != 0 (долговременный сигнал ошибки)
4 CONFIG_CHANGED класс/модель/адрес/метка изменены
5 RESET_OCCURRED модуль перезагружен (выставляется при загрузке до W1C). Мастер должен заново инициализировать конфигурацию в RAM.

Канонические шаблоны ошибок

Шаблон 1 — разовый захват после операции (результат именно этой операции):

Text
write target_reg(...)
err = read_u8(0x02)   # IMMEDIATELY after the operation, before the next write

Шаблон 2 — долговременный мониторинг (канонический для постоянно работающего мастера):

Text
event_flags = read_u8(0x2A)
if event_flags & (1 << 3):    # ERROR bit
    last_err = read_u8(0x02)
    # handle
    write_u8(0x2A, 1 << 3)    # W1C clear bit 3
    # or CMD_CLEAR_ERROR

⚠ оговорка по асинхронному биту 3

Отказ записи взводит EVENT_FLAGS.bit3 асинхронно, в пределах одного окна измерения (~100 мс с v1.2; 200 мс на образах до v1.2) после операции, а не сразу. Не опрашивайте бит 3 сразу после записи — либо подождите ≥ 200 мс (покрывает все образы), либо используйте Шаблон 1 (немедленный захват REG_ERROR) для результата конкретной операции, а опрос бита 3 оставьте для долгосрочного мониторинга.

Защитный сторожевой маркер от клонирования

DEV_ERR_CLONE (0xF9) зарезервирован — никогда не выставляется. Код сохранён для прямой совместимости.

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

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

Библиотека Вызов Что делает
Arduino RbAmp::readLastError() / RbAmp::hasError(out) прочитать код ошибки последней записи; прочитать устойчивый флаг ошибки
ESP-IDF rbamp_read_last_error() / rbamp_has_error() прочитать код ошибки последней записи; прочитать устойчивый флаг ошибки
Python dev.read_last_error() / dev.has_error() прочитать код ошибки последней записи; прочитать устойчивый флаг ошибки
ESPHome get_last_error_str() / get_event_flags() код ошибки в текстовом виде; флаги событий

5.4 Атомарность / семантика заморозки чтения

5.4.1 Заморозка чтения есть (атомарно — НЕ разорванно)

Эти блоки защищены прошивкой через заморозку чтения. Пакетное чтение атомарно относительно коммита RT:

  • Блок V03 RMS / P / PF (0x86..0xBD) — полный блок с плавающей точкой.
  • Блок дайджеста (0x70..0x85).

Пакетное чтение этих диапазонов безопасно — между двумя последовательными фиксациями нет разорванного снимка.

Эти регистры обновляются асинхронно, без заморозки внутри чтения. Однобайтовые чтения допустимы, но значение может измениться между транзакциями:

  • GC_TICK (0x59) — счётчик тиков GC.
  • I2C_ADDRESS (0x30) — зеркало промежуточного регистра в RAM.
  • CT_MODEL_CH0/1/2 (0x51..0x53) — зеркала для проверки.

Шаблон для надёжного чтения:

Text
val1 = read_u8(addr)
val2 = read_u8(addr)
if val1 == val2:
    return val1   # stable
else:
    retry          # value changed between reads

5.4.3 Семантика NF-клещей

I_RMS = 0x00000000 означает «сигнал ниже порога шума» (прошивка вычисляет rms_corr² = max(0, raw² − nf²)), НЕ «нет данных» / «ошибка». Это допустимое измерение для сценариев без нагрузки или с очень малой нагрузкой.

Код мастера не должен воспринимать I_RMS = 0.0 как ошибку или отсутствие данных.

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

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

Библиотека Вызов Что делает
Arduino RbAmp::readAll(snapshot) прочитать весь блок реального времени одним вызовом
ESP-IDF rbamp_read_all() прочитать весь блок реального времени одним вызовом
Python dev.read_all() прочитать весь блок реального времени одним вызовом
ESPHome пакетное чтение мгновенного блока компонент читает блок мгновенных значений одним пакетом за обновление

6 · Последовательности протокола

6.0 Хронология холодного запуска

После POR (сброса по включению питания) или аппаратного сброса модуль проходит следующие фазы:

Время с момента POR Состояние
0 мс POR — все регистры в состоянии сброса, SCL/SDA в высокоимпедансном состоянии
~10 мс Отвечает на шине (модуль подтверждает свой адрес, ACK)
~50 мс Первая фиксация RT (блок RT с 0x86+ содержит действительные данные; STATUS.bit0 = 1)
~60–80 мс Первый действительный V03_STATUS.bit0 (конвейер RT прошёл один полный период сети)
~100 мс Первый CMD_LATCH_PERIOD может вернуть V03_PERIOD_VALID = 1 (снимку нужно накопить не менее 1 периода сети; примерно 200 мс на прошивках до v1.2)
~250 мс Все измерения стабильны (типично)
Примечание

Полная хронология холодного запуска до первого действительного измерения ≈ 250 мс (типично). После мягкого CMD_RESET хронология такая же (выполняется полный конечный автомат сброса).

Последовательность инициализации мастера:

Text
1. wait ~50 ms after VCC stable
2. probe slave address (read PRODUCT_ID = 0x54); retry up to 300 ms on NACK
3. read identity (HW_VARIANT 0x55, CAPABILITY 0x57/0x58); validate
4. check REG_ERROR (0x02):
   - 0x00 — normal boot
   - 0xFB — fresh flash, provisioning required (§6.5)
   - other — see §6.7 error-state recovery
5. configure (SENSOR_CLASS, CT_MODEL, FLEET_CONFIG, etc.)
6. poll STATUS (0x00) until bit0 = 1 (READY) — usually immediate after step 5
В клиентских библиотеках

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

Библиотека Вызов Что делает
Arduino RbAmp::begin() / RbAmp::waitReady(timeout_ms) опросите модуль, затем дождитесь флага готовности
ESP-IDF rbamp_begin() / rbamp_wait_ready() опросите модуль, затем дождитесь флага готовности
Python dev.begin() / dev.wait_ready(timeout_ms=1000) опросите модуль, затем дождитесь флага готовности
ESPHome rbamp: address: адрес модуля задан в YAML; компонент опрашивает модуль при настройке

6.1 Смена адреса — двухфазная фиксация (допустимо в производстве)

Проводной протокол (канон v1.3):

Text
1. write candidate_addr (1 byte) → REG_I2C_ADDRESS (0x30)   # RAM staging, not persisted
2. write 0xA5 → REG_ADDR_COMMIT_MAGIC (0x31)                # arm commit
3. issue CMD_COMMIT_ADDR (opcode 0x30 in REG_COMMAND)        # persists into flash
4. wait ~700 ms (flash write completion; see §6.6 settle)
5. issue CMD_RESET (opcode 0x01)                             # module resets
6. wait ~300 ms boot-to-responsive
7. verify: bus-probe the new address (ACK = success)
Примечание

: CMD_COMMIT_ADDR НЕ перезапускает модуль автоматически — на шаге 5 обязателен явный CMD_RESET. Если мастер пропускает явный сброс, новый адрес остаётся сохранённым во flash, но старый адрес активен до следующего внешнего сброса (отключение питания, аппаратный сброс, IWDG).

Guarantees:

  • Смена адреса работает в производственном режиме (не закрыта фабричным режимом).
  • REG_I2C_ADDRESS (0x30) при загрузке возвращает активный адрес (канон v1.3). До перезагрузки после постановки в очередь возвращает кандидата.
  • Адрес исключён из пространства CMD_SAVE_GAINS / CMD_SAVE_USER_CONFIG — он сохраняется только через CMD_COMMIT_ADDR.

Тайминг окна загрузки для проверки:

  • Минимум 300 мс от загрузки до готовности к ответу.
  • Окно повтора на новом адресе: ~1 с всего (если NACK сохраняется после 1–2 повторов, может понадобиться дополнительная задержка загрузки).
  • Как только новый адрес ответит ACK, по желанию проверьте чтением 0x30 (отражающий теперь новый активный адрес).

Режимы отказа:

  • ADDR_COMMIT_MAGIC не взведён → CMD_COMMIT_ADDR → REG_ERROR = ERR_PARAM (0xFE).
  • Кандидат вне диапазона (< 0x08 или > 0x77) → ERR_PARAM.
  • Таймаут 5 с без фиксации → магическое значение сбрасывается; шаг prepare нужно повторить.
В клиентских библиотеках

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

Библиотека Вызов Что делает
Arduino RbAmp::prepareAddressChange(new_addr) / RbAmp::commitAddressChange() поставьте в очередь и взведите новый адрес, затем зафиксируйте его
ESP-IDF rbamp_prepare_address_change() / rbamp_commit_address_change() поставьте в очередь и взведите новый адрес, затем зафиксируйте его
Python dev.prepare_address_change(new_addr) / dev.commit_address_change() поставьте в очередь и взведите новый адрес, затем зафиксируйте его
ESPHome new_address: однократная смена адреса при загрузке; затем удалите этот параметр

6.2 Привязка модели клещей CT — только промежуточная запись + команда на каждый канал

Примечание

На образах до прошивки 1.4.20 (бит 12 CAPABILITY сброшен) применённое масштабирование модели после перезапуска модуля возвращается к заводскому значению по умолчанию — заново задавайте и фиксируйте CT_MODEL по каждому каналу после каждого обнаруженного перезапуска, иначе энергия будет неверной.

Канон v1.3 — чистая постановка в очередь: запись REG_CT_MODEL (0x05) больше не применяет пресет к ch0 автоматически. Привязка выполняется только через CMD_SET_CT_MODEL_CHn.

Канонический протокол по каналам (порядок не важен в v1.3):

Text
1. write REG_SENSOR_CLASS (0x25) = sct013    # if not already set
2. write REG_CT_MODEL (0x05) = model_code     # stages, applies nothing
3. issue CMD_SET_CT_MODEL_CHn (opcode 0x28/0x29/0x2A for ch0/1/2)
   # VALIDATES (class, model) + binds to channel n
4. wait 5 ms settle
5. (optional) issue CMD_SAVE_USER_CONFIG (opcode 0x32) for persistence

Независимость от порядка: в v1.3 каналы можно настраивать в любом порядке — ch0 первым, последним, как удобно. Обходной путь «привязать ch0 последним» из v1.2 больше не нужен.

Проверка чтением: после привязки прочитайте CT_MODEL_CH0/1/2 (0x51..0x53) — там отражается применённое состояние по каждому каналу.

Режимы отказа (проверка (класс, модель) выполняется на шаге привязки CMD_SET_CT_MODEL_CHn, а не при чистой записи постановки в очередь по адресу 0x05):

  • SENSOR_CLASS = 0 (UNSET) при выдаче CMD_SET_CT_MODEL_CHn → REG_ERROR = ERR_PARAM.
  • CT_MODEL вне 1..7 (SCT-013-005/-010/-030/-050/-100/-020/-060) при CMD_SET → ERR_PARAM.
В клиентских библиотеках

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

Библиотека Вызов Что делает
Arduino RbAmp::setSensorClass(cls) / RbAmp::setCTModel(channel, code) задать класс датчика и модель CT по каналам
ESP-IDF rbamp_set_sensor_class() / rbamp_set_ct_model_ch() задать класс датчика и модель CT по каналам
Python dev.set_sensor_class(cls) / dev.set_ct_model_ch(channel, code) задать класс датчика и модель CT по каналам
ESPHome sensor_class: / ct_model: Параметры YAML для класса датчика и модели клещей CT

6.3 Широковещательный снимок GC — синхронизация парка по выбору

Включается для каждого модуля через REG_FLEET_CONFIG.bit0 (GC_ENABLE). По умолчанию ВЫКЛ. Изменение вступает в силу после сброса (мягкого CMD_RESET или аппаратного).

6.3.1 Последовательность включения (однократно на модуль)

Text
1. write REG_FLEET_CONFIG (0x27) = 0x01    # bit0 = GC_ENABLE
2. issue CMD_SAVE_USER_CONFIG (opcode 0x32, ungated)
3. issue CMD_RESET (opcode 0x01)
4. wait ~300 ms boot
5. verify: read REG_FLEET_CONFIG → bit 0 should be 1

6.3.2 Формат кадра GC

Text
I²C general-call address 0x00 | A5 27      (5-byte payload)
  • A5 — магическое значение кадра.
  • 27 — код операции CMD_LATCH_PERIOD.
  • — 0x00 = вызов всех; иначе должен совпадать с REG_GROUP_ID (0x28) устройства.
  • — 16-битный счётчик тактов на стороне мастера (для сквозной нумерации окон по парку и обнаружения пропусков по модулям через GC_TICK (0x59)).

Только снимок: кадры GC не несут деструктивных опкодов (SAVE_*, COMMIT_ADDR, FACTORY_RESET и т. п.) — по конструкции.

6.3.3 Обнаружение режимов отказа — 2 уровня

Уровень 1 — NACK адреса общего вызова (мгновенно, на уровне шины):

  • Если GC отключён на всём парке → мастер получает жёсткую ошибку (NACK по адресу 0x00 или драйверный эквивалент).
  • Это жёсткая ошибка, НЕ тихий сброс — мастер может её обнаружить и отреагировать.
  • Сбой: NACK на GC = «GC не включён ни на одном устройстве парка».

Уровень 2 — свидетель на уровне модуля (после установления):

  • Если NACK не возникает (слушает хотя бы один модуль), мастер читает REG_V03_PERIOD_VALID (0x07) с каждого ожидаемого ведомого.
  • 1 = снимок на этом модуле прошёл успешно.
  • 0 = GC отключён на этом модуле или текущий период пуст.

Переход на снимок по каждому устройству, если свидетель сообщает 0:

Text
foreach module where witness == 0:
    write_cmd(module, CMD_LATCH_PERIOD)
sleep(50 ms)
foreach module: read period snapshot with skip_latch=true
В клиентских библиотеках

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

Библиотека Вызов Что делает
Arduino RbAmpFleet::gcLatch(group, tick, settle_ms) / RbAmpFleet::checkSync() отправьте кадр широковещательного снимка General Call; проверьте каждый модуль
ESP-IDF rbamp_fleet_gclatch() / rbamp_fleet_check_sync() отправьте кадр широковещательного снимка General Call; проверьте каждый модуль
Python fleet.gc_latch(group, tick, settle_ms) / fleet.check_sync(expected_tick) отправьте кадр широковещательного снимка General Call; проверьте каждый модуль
ESPHome fleet_gc_enable: / журнал проверки синхронности опциональный General Call снимок; строка журнала, подтверждающая синхронность модулей

6.4 Синхронизация периодов — две стратегии

Подход 1 — последовательный снимок + общее установление (любая прошивка)

Text
for module in modules:
    write_cmd(module, CMD_LATCH_PERIOD)
sleep(50 ms)
for module in modules:
    read_period_snapshot(module)   # skip_latch=true

Расхождение между модулями: ~1 мс на модуль при 50 кГц. При 16 модулях относительно 60-секундного периода это 0.027 %. Незначительно для тарифного учёта.

Время установления после CMD_LATCH_PERIOD:

  • Минимум 50 мс перед чтением V03_PERIOD_VALID (0x07) или периодного снимка — это покрывает задержку снимка в худшем случае (1 период сети 50 Гц = 20 мс + фиксация RT + установление периферии I²C).
  • При желании мастер может опрашивать STATUS.bit0 (READY) вместо фиксированной паузы: READY=1 означает, что блок RT в согласованном состоянии, поэтому периодный снимок можно безопасно прочитать пакетом.
  • На совсем новом модуле (< ~100 мс после загрузки с v1.2; < 200 мс раньше) снимок может вернуть V03_PERIOD_VALID = 0, потому что накоплено меньше 1 периода сети — см. хронологию холодного запуска §6.0.

Стратегия 2 — широковещательный снимок General-Call (требует enable)

Сдвиг = 0 (атомарно на уровне шины). См. §6.3.

Когда что использовать:

  • < 8 модулей: стратегия 1 (проще, без необходимости в enable).
  • ≥ 8 модулей или жёсткая синхронизация: Подход 2.
  • Один способ на модуль: адресная команда CMD_LATCH_PERIOD и широковещательный снимок GC сбрасывают один и тот же накопитель — их смешение на одном модуле обрывает текущий период. Резервная схема по модулям (§6.3.3) безопасна, потому что срабатывает только на модуле, до которого широковещательный вызов не дошёл.
В клиентских библиотеках

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

Библиотека Вызов Что делает
Arduino RbAmp::readPeriodSnapshot(..., skip_latch=true) / RbAmpFleet::gcLatch() последовательное чтение после одного общего снимка; кадр снимка общего вызова
ESP-IDF rbamp_read_period_snapshot(..., skip_latch=true) / rbamp_fleet_gclatch() последовательное чтение после одного общего снимка; кадр снимка общего вызова
Python последовательный снимок, skip_latch=True / fleet.gc_latch() последовательное чтение после одного общего снимка; кадр снимка общего вызова
ESPHome latch_interval: / fleet_gc_enable: отдельный график снимков; опциональный снимок General Call

6.5 Provisioning — первая прошивка + SAVE

Поведение модуля после первой прошивки:

  • При первом включении после прошивки: REG_ERROR = 0xFB (FLASH_PARAMS_BAD) + установлен EVENT_FLAGS.bit3.
  • Страница параметров не инициализирована → загружаются заводские значения по умолчанию.

Это НОРМА для нового модуля и не критично. Не прерывайте provisioning из-за 0xFB при первой загрузке.

Recovery:

Text
1. configure SENSOR_CLASS + CT_MODEL (per §6.2)
2. (optional) configure FLEET_CONFIG + GROUP_ID + LABEL
3. issue CMD_SAVE_USER_CONFIG (opcode 0x32, ungated)
4. wait ~700 ms (flash write)
5. verify: REG_ERROR = 0x00, EVENT_FLAGS.bit3 cleared
В клиентских библиотеках

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

Библиотека Вызов Что делает
Arduino RbAmpFleet::provision() / RbAmp::saveUserConfig() переназначить чистый модуль на его адрес; сохранить пользовательскую конфигурацию
ESP-IDF rbamp_provision() / rbamp_save_user_config() переназначить чистый модуль на его адрес; сохранить пользовательскую конфигурацию
Python настройка парка / dev.save_user_config() проведите provisioning одного нового модуля, затем добавьте его в парк; сохраните пользовательскую конфигурацию
ESPHome Порядок настройки / new_address: пошаговый YAML для нового модуля; однократная смена адреса

6.7 Восстановление после ошибки — дерево решений

Если при загрузке или во время работы STATUS.bit1 (ERROR) = 1 или установлен долговременный сигнал EVENT_FLAGS.bit3 (ERROR), мастер читает REG_ERROR (0x02) и решает по коду:

Text
read REG_ERROR (0x02):

  0x00  → no error (false signal — clear stale EVENT bit3 via W1C)
         action: write 1<<3 → EVENT_FLAGS (W1C clear)

  0xF9  → CLONE (reserved)
         action: not raised. If ever observed, treat as
                 vendor-reserved and contact the supplier.

  0xFA  → LUT_BAD (calibration LUT corrupted)
         action: device unusable for measurement. Factory recovery required.

  0xFB  → FLASH_PARAMS_BAD (params page uninitialized — virgin module)
         action: NORMAL for a freshly flashed module. Provision per §6.5
                 (configure SENSOR_CLASS/CT_MODEL/...; issue CMD_SAVE_USER_CONFIG).
                 Cleared after a successful SAVE.

  0xFC  → NOT_READY (transient; module still booting)
         action: wait 50 ms, retry. If persistent > 300 ms — power cycle.

  0xFD  → SENSOR_OVERFLOW (transient; signal saturated)
         action: physical overload detected. The chosen CT clamp has
                 insufficient range for the measured current, or a real overload.
                 Issue CMD_CLEAR_ERROR (0x31) after the cause is removed.

  0xFE  → PARAM (last operation rejected — invalid argument / unknown opcode;
                 EVENT bit3 set. Very early images, 1.2–1.4.3, ignored unknown
                 opcodes silently)
         action: master-side bug — review the last write. Issue CMD_CLEAR_ERROR
                 after fixing the master logic.

  0xFF  → UNHANDLED (firmware-side anomaly)
         action: open an issue with the vendor; CMD_CLEAR_ERROR attempts to clear.
                 If persistent after CMD_RESET — the device is suspect.

Общий порядок восстановления при временных ошибках (0xFC/0xFD/0xFE):

Text
1. capture context (what was the last write? master state?)
2. issue CMD_CLEAR_ERROR (opcode 0x31)
3. wait 5 ms
4. re-read STATUS / REG_ERROR — verify cleared

При постоянных ошибках — выполните CMD_RESET и пройдите хронологию холодного запуска (§6.0). Если ошибка сохраняется после сброса и это не 0xFB (первая прошивка) — обратитесь в техподдержку поставщика.

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

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

Библиотека Вызов Что делает
Arduino RbAmp::readLastError() / RbAmp::clearError() прочитайте код ошибки; сбросьте его
ESP-IDF rbamp_read_last_error() / rbamp_clear_error() прочитайте код ошибки; сбросьте его
Python dev.read_last_error() / dev.clear_error() прочитайте код ошибки; сбросьте его
ESPHome write_clear_error() / write_reset() сбросить ошибку; мягкий сброс модуля

6.6 Справочник команд

Основные коды операций (запись в REG_COMMAND (0x01))

Код операции Имя Установление С гейтом Примечания
0x01 RESET ~300 мс – Мягкий сброс (HAL_NVIC_SystemReset)
0x27 LATCH_PERIOD 50 мс – Переписать счётчики RT в снимок периода
0x28 SET_CT_MODEL_CH0 5 мс – Привяжите промежуточное REG_CT_MODEL к ch0
0x29 SET_CT_MODEL_CH1 5 мс – Привяжите промежуточное REG_CT_MODEL к ch1
0x2A SET_CT_MODEL_CH2 5 мс – Привяжите промежуточное REG_CT_MODEL к ch2
0x30 COMMIT_ADDR 700 мс – Сохраните I2C_ADDRESS (см. §6.1)
0x31 CLEAR_ERROR 0 – Сбросьте REG_ERROR (только временные классы; CLONE (0xF9) зарезервирован, не выставляется)
0x32 SAVE_USER_CONFIG 700 мс – Сохранить группу user_config (допустимо в производственном режиме)
Примечание

Коды операций вне публичного диапазона (для использования на заводе) в этом справочнике не описаны. Пользовательский мастер в штатном режиме их не отправляет; неподдерживаемый код операции → REG_ERROR = ERR_PARAM (0xFE).


7 · Семантика

7.0 Ресурс flash и поведение при сбросе

Примечание

Напоминание: до прошивки 1.4.20 сброс также возвращает применённое масштабирование модели CT к заводскому значению по умолчанию (бит 12 CAPABILITY сброшен) — см. §6.2.

Ресурс флеша: ~10 000 циклов на страницу (типично, по спецификации производителя). Каждый CMD_SAVE_USER_CONFIG или CMD_COMMIT_ADDR — один цикл стирания и записи страницы параметров.

Безопасность

⚠ Не зацикливайте SAVE/COMMIT в рабочем цикле. При 1 SAVE в секунду модуль выходит из строя примерно за 3 часа. Настройка выполняется однократно при монтаже; обновления настроек во время работы не требуются (потребительский мастер редко их меняет).

Сохранность данных: обычно 10+ лет при типичной рабочей температуре.

Сравнение поведения при сбросе:

Тип сброса Сохраняется Сброшено
CMD_RESET (0x01) флеш (конфигурация, адрес, метка, усиления, NF) RAM (UPTIME, ZC_OFFSET, EVENT_FLAGS — кроме бита RESET_OCCURRED 5, выставляемого при загрузке; THRESH_*; DIGEST_CONFIG)
Пин питания / аппаратного сброса флеш то же, что CMD_RESET, плюс любая внешняя RAM, которая хранится на стороне хоста
CMD_FACTORY_RESET (0xAA) (только в заводском режиме) ничего всё — весь блок параметров, включая заводскую калибровку каналов
Безопасность

⚠ CMD_FACTORY_RESET — это не пользовательский «возврат настроек по умолчанию». Он перезаписывает весь блок параметров, включая заводскую калибровку каналов, и модуль принимает его только в заводском режиме — это производственная операция, а не шаг обслуживания. У модуля BASIC нет пользовательской команды сброса. Чтобы вернуть модуль в известное состояние, используйте CMD_RESET (0x01) (мягкий сброс: flash не затрагивается) и заново задайте пользовательские параметры командой CMD_SAVE_USER_CONFIG (0x32).

RESET_OCCURRED — шаблон бита (канон):

  • После сброса при загрузке: EVENT_FLAGS.bit5 = 1.
  • Мастер видит бит 5 → понимает, что модуль перезагрузился → должен заново инициализировать поля только в RAM (DIGEST_CONFIG, THRESH_*, EVENT_MASK).
  • Мастер сбрасывает бит 5 через W1C: write 1<<5 → EVENT_FLAGS.

7.1 Модель сохранения

Команда Продакшн Сохраняется
CMD_SAVE_USER_CONFIG (0x32) ✅ OK i2c_address (через двухфазную фиксацию), ct_model, sensor_class, fleet_config, group_id, label
CMD_COMMIT_ADDR (0x30) ✅ OK (с магическим кодом) i2c_address
CMD_RESET (0x01) ✅ OK — (мягкий сброс)
CMD_LATCH_PERIOD (0x27) ✅ OK — (снимает снимок периода)
CMD_CLEAR_ERROR (0x31) ✅ OK — (сбрасывает REG_ERROR)
CMD_SAVE_GAINS (0x26) ❌ ЗАБЛОКИРОВАНО в производственном режиме (отклонено: REG_ERROR = 0xFE; перезагрузка откатывает) заводская калибровка
CMD_FACTORY_RESET (0xAA) ❌ ЗАБЛОКИРОВАНО в production —

7.2 Чтение-обратно ≠ сохранение

⚠ Защита производственного режима принимает запись в RAM (последующее чтение возвращает записанное значение), но сохранение во flash может быть отклонено. После перезагрузки значение возвращается к состоянию до записи.

Единственный корректный способ подтвердить сохранение — CMD_RESET + ожидание загрузки + повторное чтение:

Text
1. write target_reg(...)
2. issue CMD_RESET (0x01)
3. wait ~300 ms boot
4. re-read target_reg
5. assert read == written     # only now is persistence confirmed

Адрес — исключение (канон v1.3): REG_I2C_ADDRESS (0x30) при загрузке возвращает активный адрес. После постановки в очередь он возвращает кандидата; после перезагрузки показывает фактически сохранённое значение.

7.3 Оговорка об единой опоре напряжения

Модуль использует один канал U для расчёта P на всех каналах I. Если токовые клещи охватывают провод другой фазы (многофазный распределительный щиток), показания P для этого канала будут неверными (произвольный фазовый сдвиг U/I). I_RMS остаётся правильным.

Многофазные измерения (L1/L2/L3 одновременно) — отдельное исполнение со своей спецификацией.

7.4 Интеграция энергии мастером — канон часов

⚠ V03_PERIOD_LATCH_MS (0xEC) — диагностический таймер модуля; под нагрузкой может занижать — для энергии используйте часы мастера.

Канонический учёт энергии мастером:

Text
# CORRECT — master wall-clock
t_now = master_clock()
dt_s = (t_now - t_prev_latch) / time_unit
energy_wh[ch] += avg_p[ch] * dt_s / 3600
t_prev_latch = t_now

# WRONG — the module diagnostic timer may read short under load
dt_chip_s = read_u32(0xEC) / 1000.0
energy_wh[ch] += avg_p[ch] * dt_chip_s / 3600    # systematically under-reported

Измерение закрытого окна со стороны модуля — это V03_PERIOD_COMMIT_CNT (0xBE), умноженный на длину фиксации; он считает целые фиксации RT и не зависит от задержки таймера, из-за которой V03_PERIOD_LATCH_MS занижает показания. Одна фиксация = 0.1 с начиная с v1.2; более ранние прошивки используют 0.2 с. Чтобы определить, какая из них, без таблицы версий: отношение V03_PERIOD_LATCH_MS / V03_PERIOD_COMMIT_CNT будет близко к 100 или близко к 200. Используйте это для перекрёстных проверок; для тарифного учёта решающими остаются часы мастера.

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

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

Библиотека Вызов Что делает
Arduino RbAmp::energyWh(ch) текущий накопленный итог Втч по каналу
ESP-IDF rbamp_energy_wh() текущий накопленный итог Втч по каналу
Python dev.energy.wh(ch) текущий накопленный итог Втч по каналу
ESPHome energy Счётчик Втч по каналу

7.5 Сохранение периода при неудачном снимке

Прошивка СОХРАНЯЕТ накопитель периода при пустом снимке. Когда g_period_count == 0 (снимок без читаемого периода):

  • REG_V03_PERIOD_VALID = 0 (сигнал устарел).
  • period_start_ms сохраняется → следующий успешный снимок охватывает весь интервал, заданный мастером.

Следствие: мастер не теряет данные при устаревшем снимке. Шаблон интеграции мастера:

Text
issue snapshot
if PERIOD_VALID == 1:
    integrate(avg_p, master_dt)
    reset_master_clock
# else: skip integration (FW will automatically recover on the next success)
В клиентских библиотеках

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

Библиотека Вызов Что делает
Arduino RbAmp::readPeriodSnapshot() / RbAmp::isPeriodValid() снимите периодный снимок и интегрируйте только тогда, когда он действителен; проверьте бит готовности
ESP-IDF rbamp_read_period_snapshot() / rbamp_is_period_valid() снимите периодный снимок и интегрируйте только тогда, когда он действителен; проверьте бит готовности
Python dev.read_period_snapshot() / RbAmpStaleError снимите периодный снимок; вызывает ошибку, если снимок не готов, следующий охватит полный интервал
ESPHome Периодный снимок недействителен записывается в журнал, когда флаг достоверности равен 0; первый снимок после загрузки отбрасывается

7.6 Допуск дрейфа тактирования

Канон: внутренняя временная база модуля может показывать меньше под нагрузкой — до 30 %; это нормально, свойство временной базы модуля, заложенное по конструкции. Измерено аппаратно при производственной нагрузке.

Приёмка: микросхема в порядке при дрейфе ≤ 30 %.

⚠ Прежний порог 3 % НЕВЕРЕН. Этот порог массово отбраковал бы исправные микросхемы.

7.7 Устойчивость к ЭМП / переходным процессам коммутации

Чтения во время активного переключения реле (ЭМИ 5 А) не проходят примерно в ~67 % случаев (измерено на аппаратуре). В установившемся режиме чтения надёжны. Шина восстанавливается сама, зависания не происходит, модули не теряются.

Шаблон мастера — повтор на уровне приложения (обязателен при переключении индуктивных нагрузок):

Text
for attempt in range(5):
    result = read_register(...)
    if result is OK:
        return result
    sleep(20 ms)
raise IOError("read failed after retries")

Одного сброса шины на стороне мастера недостаточно, если EMI-помеха совпадает с окном повторов драйвера.


7.8 Сводка известных ограничений

Сводный список известных характеристик, которые мастер должен учитывать:

Тема Поведение См.
Дрейф таймера микросхемы Может занижать под нагрузкой до 30 % (приёмочный допуск) §7.4, §7.6
ЭМП при переключении реле ~67 % доля ошибок чтения во время коммутации; шина восстанавливается сама §7.7
задержка EVENT.bit3 до одного окна (~100 мс; 200 мс до v1.2) от отказа записи до взведения бита 3 §5.3
V03_PERIOD_LATCH_MS (0xEC) Диагностический таймер модуля; под нагрузкой может занижать — мастер использует собственные часы §4.13, §7.4
Семантика REG_ERROR (0x02) Результат последней записи (не липкий); бит 3 в EVENT = устойчивый сигнал §5.3
I_RMS = 0.0 Ниже порога шума (допустимое измерение), а НЕ «нет данных» §5.4.3
U_RMS/U_PEAK/P на I-вариантах Читается как 0.0 (действительно только если бит 8 CAPABILITY = 1) §4.10, §7.3
Многобайтная ЗАПИСЬ Без авто-инкремента; нужен цикл побайтово §5.1
Проверка смены адреса Через сканирование шины на новом адресе; 0x30 также достоверен после перезагрузки §6.1
Загрузка с чистого flash REG_ERROR = 0xFB — норма; SAVE сбрасывает её §6.5
GC по умолчанию ВЫКЛ. (включается для каждого модуля отдельно); NACK на GC = «не включено» §6.3
Ресурс flash ~10 000 циклов на страницу; не зацикливайте SAVE §7.0

8 · Примеры трассировки проводов

8.1 Определение — чтение PRODUCT_ID + HW_VARIANT + CAPABILITY

Text
# I²C operations on default slave addr 0x50
S 0xA0 W 0x54 Sr 0xA1 R [PRODUCT_ID]  P     # read 0x54
S 0xA0 W 0x55 Sr 0xA1 R [HW_VARIANT]  P     # read 0x55
S 0xA0 W 0x57 Sr 0xA1 R [CAP_lo][CAP_hi] P  # burst-read 0x57..0x58 (auto-increment)

Где S=старт, Sr=повторный старт, P=стоп, W=бит записи, R=бит чтения, 0xA0=адрес ведомого 0x50 << 1.

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

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

Библиотека Вызов Что делает
Arduino RbAmp::readVariant() / RbAmp::readCapability(out) прочитать аппаратный вариант; прочитать битовую карту функций
ESP-IDF rbamp_read_variant() / rbamp_read_capability() прочитать аппаратный вариант; прочитать битовую карту функций
Python dev.read_variant() / dev.read_capability() прочитать аппаратный вариант; прочитать битовую карту функций
ESPHome get_variant_str() / get_capability_hex() вариант в виде текста; битовая карта функций в hex

8.2 Пакетное чтение блока RT (вариант UI, все каналы)

Text
# Read all of V03 RMS + P + PF (0x86..0xBD) — 56 bytes, atomic via read-freeze
S 0xA0 W 0x86 Sr 0xA1 R [56 bytes] P
В клиентских библиотеках

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

Библиотека Вызов Что делает
Arduino RbAmp::readAll(snapshot) прочитать весь блок реального времени одним вызовом
ESP-IDF rbamp_read_all() прочитать весь блок реального времени одним вызовом
Python dev.read_all() прочитать весь блок реального времени одним вызовом
ESPHome пакетное чтение мгновенного блока компонент читает блок мгновенных значений одним пакетом за обновление

8.3 Многобайтная ЗАПИСЬ — LABEL побайтно

Text
# WRONG: burst-write — only 'M' is accepted
S 0xA0 W 0x68 'M' 'y' 'M' 'e' 't' 'e' 'r' '1' P

# CORRECT: byte-at-a-time loop
S 0xA0 W 0x68 'M' P
S 0xA0 W 0x69 'y' P
S 0xA0 W 0x6A 'M' P
S 0xA0 W 0x6B 'e' P
S 0xA0 W 0x6C 't' P
S 0xA0 W 0x6D 'e' P
S 0xA0 W 0x6E 'r' P
S 0xA0 W 0x6F '1' P
В клиентских библиотеках

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

Библиотека Вызов Что делает
Arduino RbAmp::writeLabel(label) / RbAmp::readLabel(out) запишите 8-байтовую метку (только BASIC); прочитайте её обратно
ESP-IDF rbamp_write_label() / rbamp_read_label() записать 8-символьную метку; прочитать её обратно
Python dev.set_label(label) / dev.read_label() запишите 8-байтовую метку; прочитайте её обратно
ESPHome — опция label не документирована

8.4 Широковещательный снимок GC + резервный свидетель

Text
# Send GC frame: A5 27  
S 0x00 W 0xA5 0x27 0x00 0x2A 0x00 P

# Wait 50 ms settle

# Witness check for every expected module
foreach module in [0x50, 0x51, 0x52]:
    S (module<<1)|W 0x07 Sr (module<<1)|R [VALID] P
    if VALID != 1:
        # Fall back to per-device snapshot
        S (module<<1)|W 0x01 0x27 P    # CMD_LATCH_PERIOD
В клиентских библиотеках

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

Библиотека Вызов Что делает
Arduino RbAmpFleet::gcLatch(group, tick, settle_ms) / RbAmpFleet::checkSync() отправьте кадр широковещательного снимка General Call; проверьте каждый модуль
ESP-IDF rbamp_fleet_gclatch() / rbamp_fleet_check_sync() отправьте кадр широковещательного снимка General Call; проверьте каждый модуль
Python fleet.gc_latch(group, tick, settle_ms) / fleet.check_sync(expected_tick) отправьте кадр широковещательного снимка General Call; проверьте каждый модуль
ESPHome fleet_gc_enable: / журнал проверки синхронности опциональный General Call снимок; строка журнала, подтверждающая синхронность модулей

8.5 Смена адреса в 5 шагов

Text
# 1. Stage candidate addr (0x51) → REG_I2C_ADDRESS
S 0xA0 W 0x30 0x51 P

# 2. Arm magic → ADDR_COMMIT_MAGIC
S 0xA0 W 0x31 0xA5 P

# 3. Issue CMD_COMMIT_ADDR (opcode 0x30) → REG_COMMAND
S 0xA0 W 0x01 0x30 P

# 4. Wait 700 ms flash write

# 5. Issue CMD_RESET (opcode 0x01) → REG_COMMAND
S 0xA0 W 0x01 0x01 P

# Wait ~300 ms boot

# Verify: probe the new addr
S 0xA2 W 0x55 Sr 0xA3 R [HW_VARIANT] P   # 0xA2 = 0x51 << 1
В клиентских библиотеках

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

Библиотека Вызов Что делает
Arduino RbAmp::prepareAddressChange(new_addr) / RbAmp::commitAddressChange() поставьте в очередь и взведите новый адрес, затем зафиксируйте его
ESP-IDF rbamp_prepare_address_change() / rbamp_commit_address_change() поставьте в очередь и взведите новый адрес, затем зафиксируйте его
Python dev.prepare_address_change(new_addr) / dev.commit_address_change() поставьте в очередь и взведите новый адрес, затем зафиксируйте его
ESPHome new_address: однократная смена адреса при загрузке; затем удалите этот параметр

8.6 Provisioning после первой прошивки

Text
# 1. Check fresh-flash state
S 0xA0 W 0x02 Sr 0xA1 R [0xFB] P   # ERR_FLASH_PARAMS_BAD — normal

# 2. Configure sensor_class
S 0xA0 W 0x25 0x01 P    # SCT_013

# 3. Stage CT model + bind ch0
S 0xA0 W 0x05 0x03 P    # SCT-013-030
S 0xA0 W 0x01 0x28 P    # CMD_SET_CT_MODEL_CH0
# Wait 5 ms

# 4. Save user_config
S 0xA0 W 0x01 0x32 P    # CMD_SAVE_USER_CONFIG
# Wait 700 ms

# 5. Verify: REG_ERROR should be 0x00 (read IMMEDIATELY before the next write)
S 0xA0 W 0x02 Sr 0xA1 R [0x00] P
В клиентских библиотеках

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

Библиотека Вызов Что делает
Arduino RbAmp::configureChannels(cls, models, n) / RbAmp::saveUserConfig() задайте класс и модели всех каналов; сохраните пользовательскую конфигурацию
ESP-IDF rbamp_configure_channels() / rbamp_save_user_config() задайте класс и модели всех каналов; сохраните пользовательскую конфигурацию
Python dev.configure_channels(cls, models) / dev.save_user_config() задайте класс и модели всех каналов; сохраните пользовательскую конфигурацию
ESPHome sensor_class: / ct_model: Параметры YAML для класса датчика и модели клещей CT

8.7 Круговой обмен DIGEST — настройка + чтение

Text
# 1. Configure digest mask: I_RMS + U_RMS + P_REAL (bits 0+1+2 = 0x07)
S 0xA0 W 0x29 0x07 P

# 2. Wait one RT-commit cycle (~100 ms from v1.2; waiting 200 ms covers all images; or poll STATUS.bit0)

# 3. Burst-read the digest window (22 bytes)
S 0xA0 W 0x70 Sr 0xA1 R [22 bytes] P

# Parse the layout per DIGEST_CONFIG = 0x07 on UI1 (N_I = 1):
#   byte[0]   = STATUS_MIRROR
#   byte[1]   = SEQ
#   byte[2..3]  = I_RMS[0] u16 (0.01 A units)
#   byte[4..5]  = U_RMS u16 (0.1 V units)
#   byte[6..7]  = P[0] i16 (1 W units)
#   byte[8..21] = unused (0x00)
В клиентских библиотеках

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

Библиотека Вызов Что делает
Arduino — окно дайджеста не выведено
ESP-IDF rbamp_set_digest_fields() / rbamp_read_digest() выберите поля дайджеста; прочитайте их одной транзакцией (BASIC)
Python — окно дайджеста не выведено
ESPHome — окно дайджеста не выведено

8.8 Поток событий порога — запись порога → срабатывание → сброс W1C

Text
# 1. Write current threshold = 30 A (0x0BB8 in 0.01 A units → 2 bytes LE)
S 0xA0 W 0x2C 0xB8 P    # LO byte
S 0xA0 W 0x2D 0x0B P    # HI byte

# 2. Unmask THRESH_I event (bit 1) → DRDY solid-LOW on trip
S 0xA0 W 0x2B 0x02 P    # EVENT_MASK = bit 1 only

# 3. (runtime) The master polls EVENT_FLAGS
S 0xA0 W 0x2A Sr 0xA1 R [event_flags] P
# event_flags == 0x02 → threshold tripped

# 4. (optional) Read context — REG_ERROR, RT block, etc.

# 5. Clear EVENT_FLAGS.bit1 via W1C
S 0xA0 W 0x2A 0x02 P
В клиентских библиотеках

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

Библиотека Вызов Что делает
Arduino RbAmp::setEventThresholds(i_amps, p_watts) / RbAmp::readEventFlags(out) установите пороги тока и мощности; читайте и сбрасывайте флаги событий
ESP-IDF rbamp_set_event_thresholds() / rbamp_read_event_flags() установите пороги тока и мощности; читайте и сбрасывайте флаги событий
Python dev.read_event_flags() прочитать и сбросить флаги событий (установщика порогов на устройстве нет)
ESPHome Пороговые тревоги в YAML / get_event_flags() пороговые автоматизации по значениям датчиков; флаги событий

8.9 Диагностическая пачка захвата сырых данных (CAPTURE_*)

CMD_CAPTURE_RAW (0x38) и регистры CAPTURE_* — диагностическое средство; в штатной работе не нужны, применяйте только по просьбе поставщика для захвата сырых выборок.

Text
# 1. Arm raw-capture
S 0xA0 W 0x01 0x38 P     # CMD_CAPTURE_RAW (opcode 0x38)
# Wait ~80 ms (3 DMA-TC cycles)

# 2. Check ready
S 0xA0 W 0x18 Sr 0xA1 R [status & 0x01] P   # bit 0 = ready

# 3. Select page 0 (16 raw I0 samples → CAPTURE_WINDOW)
S 0xA0 W 0x19 0x00 P

# 4. Burst-read CAPTURE_WINDOW (32 bytes = 16×u16 LE samples)
S 0xA0 W 0x1A Sr 0xA1 R [32 bytes] P

# Repeat steps 3-4 for pages 1..15 (256 samples total ≈ 1.3 mains periods)

8.10 Чтение зеркала проверки модели CT (проверка после привязки)

Text
# After the §6.2 sequence — verify the applied state per channel via 0x51..0x53 (burst):
S 0xA0 W 0x51 Sr 0xA1 R [model_ch0][model_ch1][model_ch2] P

# Expected on UI2 mixed-CT (e.g. ch0=SCT-013-005, ch1=SCT-013-030):
#   byte[0] = 0x01   # SCT-013-005 applied on ch0
#   byte[1] = 0x03   # SCT-013-030 applied on ch1
#   byte[2] = 0x00   # unused (UI2 N_I=2)
В клиентских библиотеках

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

Библиотека Вызов Что делает
Arduino RbAmp::readCTModelCh(channel, out) прочитайте модель CT, фактически применённую на канале
ESP-IDF rbamp_read_ct_model_ch() прочитайте модель CT, фактически применённую на канале
Python dev.read_ct_model_ch(ch) прочитайте модель CT, фактически применённую на канале
ESPHome журнал загрузки ct_model[0]: matches строки лога, подтверждающие, что класс датчика и модель применены

9 · Приёмка / допуск

Параметр Порог Источник
Дрейф часов микросхемы относительно часов мастера ≤ 30 % проверено на стенде
Частота отказов чтения при коммутации реле (EMI) до ~67 % при коммутации проверено на стенде
Доля NACK на шине (Linux/ESP I²C @ 100 kHz без повторов) до ~20 % характеристика на стороне хоста
Доля NACK на шине @ 50 кГц + 3× повтор < 0.8 % проверено на стенде
Значение REG_ERROR при загрузке с чистого flash 0xFB (FLASH_PARAMS_BAD) НОРМАЛЬНО для чистого модуля
Холодный запуск до первого действительного измерения ~250 мс типично

10 · История изменений

1.3.0 (2026-06-15) — первый публичный выпуск.

Эталонная прошивка: protocol_version = 1.3, schema_version = 2. Контракт страницы 0 заморожен.

Основные изменения v1.3 по сравнению с предыдущими внутренними версиями

  • Промежуточная запись CT_MODEL: REG_CT_MODEL (0x05) больше не применяется автоматически к ch0 при записи. Привязка происходит только через CMD_SET_CT_MODEL_CHn (порядок не важен).
  • Двухфазная фиксация адреса (допустимо в производстве): I2C_ADDRESS сохраняется через ADDR_COMMIT_MAGIC + CMD_COMMIT_ADDR. REG_I2C_ADDRESS при загрузке читает активный адрес.
  • REG_ERROR = результат последней записи (не липкий). EVENT_FLAGS.bit3 — устойчивый сигнал (липкий, W1C; взводится в пределах одного окна, ~100 мс, после отказа записи).
  • Неизвестные опкоды / значения перечислений вне диапазона → отклоняются: REG_ERROR = ERR_PARAM (0xFE) + EVENT.bit3. Самые ранние образы (1.2–1.4.3) молча игнорировали неизвестные опкоды.
  • Первичная настройка при чистом flash: ERR_FLASH_PARAMS_BAD (0xFB) на чистом модуле → сбрасывается через CMD_SAVE_USER_CONFIG.
  • Широковещательный снимок GC — включается для каждого модуля через FLEET_CONFIG.bit0 (по умолчанию ВЫКЛ.; действует после сброса). NACK при выключенной функции = жёсткая ошибка, а не молчаливый отказ.
  • Асимметрия чтения и записи по замыслу: ЧТЕНИЕ с авто-инкрементом ✅; ЗАПИСЬ требует побайтово ❌ (подтверждено на аппаратуре).
  • Регистр CAPABILITY (0x57/0x58, u16 LE): битовая карта функций — определяйте функции по отдельным битам (§3.2), никогда не сравнивая всё значение целиком; бит 12 = SCT_RATING_SELF (fw 1.4.20+).
  • Атомарность: блок RMS V03 + Digest имеют заморозку чтения (атомарная пакетная выборка); зеркала GC_TICK / I2C_ADDRESS / CT_MODEL_CHn читаются дважды с проверкой совпадения.
  • Семантика NF-клещей: I_RMS = 0.0 означает «ниже порога шума» — это допустимое измерение.
  • AC_FREQ по переходу через ноль на всех вариантах (включая I-only).
  • Интеграция мастер-энергии должна использовать собственные часы мастера, а не V03_PERIOD_LATCH_MS (0xEC) (диагностический таймер модуля — под нагрузкой может показывать меньше).

Конец документа.