Справочник по проводному протоколу 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:
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
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 Канонический алгоритм обнаружения
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) —не документировано— они относятся к заводскому стенду, а не к пользовательской части.
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. |
Четыре ловушки — прочитайте это до написания кода
- ⛔ Плоский 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+ доступны только через окно доступа к каналам. - Выбирайте перед каждым чтением.
REG_CHANNEL_DATA— это снимок, взятый в момент записи селектора, а не живое представление. Опрос0x3C..0x3Fв цикле без повторной записи0x32возвращает замороженное значение навсегда. Каждое новое показание требует новой записи в0x32. 0x32адрес регистра ≠0x32код операции.CMD_SAVE_USER_CONFIGиспользует опкод0x32, записываемый вREG_COMMAND(0x01) — это другое адресное пространство, чемREG_CHANNEL_SELECT(находящийся по адресу регистра0x32). Никогда не указывайте0x32без пояснения, о каком пространстве речь.- Для каналов 3+ период/энергия поступают только из поля
13(CHFIELD_PERIOD_AVG_P). РегистрыV03_PERIOD_AVG_P*(0xC2/0xC6/0xDC) покрывают только ch0/ch1/ch2. ПлоскогоV03_PERIOD_AVG_P_CH3не существует — вместо него читайте поле 13 через окно.
Пример на уровне кадров — чтение действующего тока канала 3
# 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.
# --- 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 в десятичной записи):
# CORRECT: low byte first (LE)
write(addr=0x2C, value=0x34) # LO byte
write(addr=0x2D, value=0x12) # HI byte
Пример НЕПРАВИЛЬНО / ПРАВИЛЬНО (псевдокод)
# 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 — разовый захват после операции (результат именно этой операции):
write target_reg(...)
err = read_u8(0x02) # IMMEDIATELY after the operation, before the next write
Шаблон 2 — долговременный мониторинг (канонический для постоянно работающего мастера):
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).
Пакетное чтение этих диапазонов безопасно — между двумя последовательными фиксациями нет разорванного снимка.
5.4.2 Без заморозки чтения — рекомендуется read-twice-agree
Эти регистры обновляются асинхронно, без заморозки внутри чтения. Однобайтовые чтения допустимы, но значение может измениться между транзакциями:
GC_TICK (0x59)— счётчик тиков GC.I2C_ADDRESS (0x30)— зеркало промежуточного регистра в RAM.CT_MODEL_CH0/1/2 (0x51..0x53)— зеркала для проверки.
Шаблон для надёжного чтения:
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 хронология такая же (выполняется полный конечный автомат сброса).
Последовательность инициализации мастера:
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):
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):
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 Последовательность включения (однократно на модуль)
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
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:
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 — последовательный снимок + общее установление (любая прошивка)
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:
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) и решает по коду:
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):
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 + ожидание загрузки + повторное чтение:
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) — диагностический таймер модуля; под нагрузкой может занижать — для энергии используйте часы мастера.
Канонический учёт энергии мастером:
# 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сохраняется → следующий успешный снимок охватывает весь интервал, заданный мастером.
Следствие: мастер не теряет данные при устаревшем снимке. Шаблон интеграции мастера:
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 % случаев (измерено на аппаратуре). В установившемся режиме чтения надёжны. Шина восстанавливается сама, зависания не происходит, модули не теряются.
Шаблон мастера — повтор на уровне приложения (обязателен при переключении индуктивных нагрузок):
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
# 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, все каналы)
# 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 побайтно
# 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 + резервный свидетель
# 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 шагов
# 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 после первой прошивки
# 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 — настройка + чтение
# 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
# 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_* — диагностическое средство; в штатной работе не нужны, применяйте только по просьбе поставщика для захвата сырых выборок.
# 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 (проверка после привязки)
# 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)(диагностический таймер модуля — под нагрузкой может показывать меньше).