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

02 · Инициализация и запуск

rbAmp начинает измерять сразу после включения питания. Мастеру нужно только:

  1. Поднимите шину I²C (стандартная инициализация Wire / HAL).
  2. Подождите ~250 мс или опрашивайте DATA_VALID = 1 в регистре 0xCE.
  3. По желанию прочитайте версию прошивки из 0x03 как проверку здравомыслия.
  4. Данные чтения — готовы.

Команда запуска и регистровая настройка микросхемы не требуются. Заводская калибровка загружается автоматически при включении, поэтому модуль выдаёт корректные значения в физических единицах уже с первого считывания.

Последовательность от подачи питания до первого действительного показания.

Примечание

Важно для модулей BASIC SCT-серии, работающих с датчиками SCT-013: после первой установки нужно записать модель датчика в регистр модели. Модулю нужна модель, чтобы применить правильный коэффициент мВ на ампер. Код модели хранится во флеш и переживает перезагрузки. На прошивках до 1.4.20 (бит 12 в CAPABILITY сброшен) применённое масштабирование откатывается к заводскому значению после перезапуска модуля — мастер, выбравший не заводскую модель, должен заново её зафиксировать после каждого обнаруженного перезапуска модуля (см. Что сохраняется при перезапуске и правило обнаружения перезапуска в period-metering.md); с прошивки 1.4.20 смена модели переживает перезапуск. На прошивках до 1.4.20 энергия будет неверной после любого перезапуска модуля, если CT_MODEL не будет зафиксирована повторно. Клиентские библиотеки обрабатывают оба случая за вас. Подробности в разделе Настройка класса датчика и модели CT ниже.

Модули BASIC CT-серии поставляются в паре со своими датчиками, настроены и откалиброваны под этот датчик на заводе; они запускаются без инициализации.

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

Библиотека Вызов Что делает
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; компонент опрашивает модуль при настройке

Вспомогательные функции (платформенно-независимый C)

Все приведённые ниже примеры используют три небольших вспомогательных функции, которые легко реализовать на любой платформе:

C
// Read one byte from a slave register.
uint8_t rb_read_u8(uint8_t addr, uint8_t reg);

// Read a little-endian float32 (4 bytes from reg, reg+1, reg+2, reg+3).
// rbAmp supports READ auto-increment — both per-byte access and a single
// 4-byte burst-read are valid. The helpers below show per-byte for clarity;
// production code often uses burst-read for atomicity guarantees (see ch 11).
float rb_read_float_le(uint8_t addr, uint8_t reg);

// Write one byte to a slave register.
void rb_write_u8(uint8_t addr, uint8_t reg, uint8_t val);

Запуск на Arduino (Wire.h)

Вспомогательные функции

C++
#include 

uint8_t rb_read_u8(uint8_t addr, uint8_t reg) {
  Wire.beginTransmission(addr);
  Wire.write(reg);
  Wire.endTransmission(false);   // repeated start, do not release bus
  Wire.requestFrom(addr, (uint8_t)1);
  return Wire.read();
}

float rb_read_float_le(uint8_t addr, uint8_t reg) {
  uint8_t buf[4];
  for (int i = 0; i < 4; i++) {
    buf[i] = rb_read_u8(addr, reg + i);
  }
  float f;
  memcpy(&f, buf, 4);            // little-endian host (AVR, ESP32, ARM)
  return f;
}

void rb_write_u8(uint8_t addr, uint8_t reg, uint8_t val) {
  Wire.beginTransmission(addr);
  Wire.write(reg);
  Wire.write(val);
  Wire.endTransmission();
}

Проверка работы (один модуль)

C++
#include 
#define RB_ADDR 0x50

void setup() {
  Serial.begin(115200);
  Wire.begin();
  Wire.setClock(50000);
  delay(300);                           // wait for module boot

  // Wait DATA_VALID bit
  while ((rb_read_u8(RB_ADDR, 0xCE) & 0x01) == 0) {
    Serial.println("waiting for DATA_VALID...");
    delay(50);
  }

  uint8_t ver = rb_read_u8(RB_ADDR, 0x03);
  Serial.printf("rbAmp ready, version 0x%02X\n", ver);
}

void loop() {
  float u_rms = rb_read_float_le(RB_ADDR, 0x86);
  float i_rms = rb_read_float_le(RB_ADDR, 0x8E);
  float p     = rb_read_float_le(RB_ADDR, 0xA6);
  float pf    = rb_read_float_le(RB_ADDR, 0xB2);

  Serial.printf("U=%.1f V  I=%.3f A  P=%.1f W  PF=%.3f\n",
                u_rms, i_rms, p, pf);
  delay(1000);
}

Используйте нагрузку не менее ~1 % от номинала датчика — при меньшей нагрузке показания становятся шумными, и класс точности не обеспечивается (лампа 60 Вт — это всего 0.9 % от 30 A клещей; см. таблицу характеристик). Для клещей на 30 A подойдёт чайник 2 кВт как проверочная нагрузка. Для модулей серии BASIC SCT с датчиком SCT-013 задайте класс датчика и модель клещей CT до проверки (см. Настройка класса датчика и модели клещей CT) — без модели показания тока не имеют смысла.

Ожидаемый вывод (чайник 2 кВт при 230 V, клещи 30 A):

Text
rbAmp ready, version 0x04
U=229.8 V  I=8.72 A  P=2004 W  PF=0.999
U=230.1 V  I=8.73 A  P=2008 W  PF=0.999
...

Запуск на STM32 HAL (C)

C
#include "stm32f1xx_hal.h"
extern I2C_HandleTypeDef hi2c1;

#define RB_ADDR_8BIT (0x50 << 1)        // HAL expects 8-bit address format

uint8_t rb_read_u8(uint8_t reg) {
  uint8_t v;
  HAL_I2C_Mem_Read(&hi2c1, RB_ADDR_8BIT, reg, I2C_MEMADD_SIZE_8BIT, &v, 1, 100);
  return v;
}

float rb_read_float_le(uint8_t reg) {
  uint8_t buf[4];
  for (int i = 0; i < 4; i++) {
    HAL_I2C_Mem_Read(&hi2c1, RB_ADDR_8BIT, reg + i, I2C_MEMADD_SIZE_8BIT,
                     &buf[i], 1, 100);
  }
  float f;
  memcpy(&f, buf, 4);
  return f;
}

void main_app(void) {
  while ((rb_read_u8(0xCE) & 0x01) == 0) HAL_Delay(50);

  uint8_t ver = rb_read_u8(0x03);
  printf("rbAmp version: 0x%02X\n", ver);

  while (1) {
    float u = rb_read_float_le(0x86);
    float i = rb_read_float_le(0x8E);
    float p = rb_read_float_le(0xA6);
    printf("U=%.1f V  I=%.3f A  P=%.1f W\n", u, i, p);
    HAL_Delay(1000);
  }
}

Модули серии CT: запуск без конфигурации

Модуль CT-серии поставляется с каждым токовым каналом, уже настроенным: класс датчика, номинал и калибровка записаны на заводе для клещей, упакованных с этим каналом. Записи при инициализации не требуются — хост только читает.

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

⚠ Не записывайте класс датчика и модель датчика на модуле CT-серии. - Запись модели в канал заменяет заводскую калибровку этого канала на общий предустановленный профиль: текущая погрешность становится −2…+3 %, а порог малого тока неверен. - Запись класса сбрасывает модель всех каналов.

На прошивке 1.4.22 и новее модуль серии CT отклоняет запись класса и модели в штатном режиме с ERR_PARAM (0xFE); клиентские библиотеки отклоняют их на всех прошивках.

Канал и его клещи — пара. Каждые клещи помечены каналом, к которому относятся. Не переносите клещи на другой канал и не подключайте другие клещи к каналу: калибровка действует только для заводской пары. Номиналы фиксированы, выбирать номинал не нужно.

Последовательность запуска

  1. Подключите клещи (стрелка к нагрузке — см. hardware-connection.md) и подайте питание на модуль.
  2. Прочитайте класс (SENSOR_CLASS, 0x25): 2 = серия CT-клещей.
  3. Прочитайте применённую модель каждого канала (0x51..0x53, один регистр на канал; UI5/UI7 каналы 3 и выше: через окно доступа к каналам, поле CT_MODEL) и сопоставьте её с номиналом:
Код модели 0x06 0x07 0x08 0x09 0x0A 0x0B 0x0D
Номинал 1 A 5 A 10 A 20 A 30 A 50 A 100 A

Используйте номинал, чтобы масштабировать диапазоны отображения и проверять показания; модуль уже выдаёт значения в амперах.

  1. Опрашивайте так же, как любой модуль BASIC: окно измерения 100 мс, пин готовности данных или периодическое чтение (см. realtime-polling.md); учёт периодов — как в period-metering.md.

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

Замена клещей или модуля

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

Настройка класса датчика и модели CT

Примечание

Требуется только для модулей BASIC SCT-серии, используемых с датчиками SCT-013. Модули BASIC CT-серии поставляются парой с датчиками: всё предустановлено и откалибровано на заводе для конкретного датчика, и они запускаются без инициализации — этот раздел можно пропустить.

Два регистра описывают внешний датчик: SENSOR_CLASS (семейство — накладные датчики SCT-013, серия проводных CT-клещей, встроенный CT) и CT_MODEL (конкретный код модели внутри семейства). В v1.3 модель записывается по схеме чистой постановки в очередь — запись CT_MODEL сама по себе не применяет её; отдельная команда для канала фиксирует поставленное в очередь значение.

Регистры

Имя Адрес Тип Примечания
SENSOR_CLASS 0x25 u8, чтение/запись 0 = Unset, 1 = SCT_013, 2 = WIRED_CT (серия CT-клещей), 3 = BUILTIN_CT (встроенный датчик, заводская калибровка для каждого экземпляра — без кода модели). Смена класса сбрасывает CT_MODEL в 0.
CT_MODEL 0x05 u8, чтение/запись Код модели клещей CT — только регистр промежуточной записи. Простая запись не применяется.

Выбор датчика

Купите одну из моделей SCT-013 с выходом по напряжению из таблицы ниже (вилка 3.5 мм) — не вариант с выходом по току. Выбирайте клещи наименьшего номинала, который выше вашего наибольшего ожидаемого тока; для заявленного класса нагрузка не должна опускаться ниже примерно 1 % номинала (см. таблицу точности).

Коды моделей CT — семейство SCT-013 (SENSOR_CLASS = 1)

Код Датчик Номинальный ток Начало ограничения RMS Предел пика
0x00 не задано (по умолчанию на заводских модулях BASIC SCT-серии) — — —
0x01 SCT-013-005 5 A 5.8 A 8.2 A
0x02 SCT-013-010 10 A 11.6 A 16.4 A
0x03 SCT-013-030 30 A 34.8 A 49.2 A
0x04 SCT-013-050 50 A 58 A 82 A
0x05 SCT-013-100 100 A 116 A 164 A
0x06 SCT-013-020 20 A 23.2 A 32.8 A
0x07 SCT-013-060 60 A 69.6 A 98.4 A
Примечание

Коды 0x06 и 0x07 немонотонны по номиналу — они добавлены после исходного набора 0x01..0x05. Всегда выбирайте по нужному номиналу, а не по порядку кодов.

Семантика пределов: номинальный ток и начало ограничения RMS предполагают синусоидальную нагрузку; измеренное начало ограничения ≈ 1.16 × номинала. Предел пика (≈ 1.64 × номинала) — реальный потолок: искажённая нагрузка (высокий пик-фактор) начинает ограничиваться при peak / crest factor, то есть ниже значений RMS. Для заявленной точности держитесь на номинале или ниже: показания ограничиваются примерно на уровне 115–120 % номинала.

Данные по каждому номиналу (минимальный измеряемый порог, класс, допуск датчика, точка ограничения) приведены в таблице точности в overview.md. Смена модели датчика — это запись кода модели в модуль; больше ничего не требуется, шага перекалибровки нет.

Коды моделей CT — серия проводных CT-клещей (SENSOR_CLASS = 2)

Модули CT-серии поставляются как заводской откалиброванный комплект со своими клещами: класс и модель уже заданы и входят в калибровку — см. Модули CT-серии: запуск без конфигурации. Не записывайте их. Таблица ниже — справочная для чтения применённой модели; на модуле CT-серии пользователь ничего не выбирает.

Код Клещи Номинальный ток Окно
0x01..0x05 устаревшие пресеты проводных CT — —
0x06 Токовые клещи, 1 A 1 A 6 мм
0x07 CT-клещи, 5 А 5 A 6 мм
0x08 Токовые клещи, 10 A 10 A 6 мм
0x09 Токовые клещи, 20 A 20 A 10 мм
0x0A CT-клещи, 30 А 30 A 10 мм
0x0B CT-клещи, 50 А 50 A 10 мм
0x0D CT-клещи, 100 А 100 A 16 мм
Примечание

Размер окна определяется номинальным током (6 мм для 1–10 А, 10 мм для 20–50 А, 16 мм для 100 А) и не влияет на калибровку.

Команды

Имя Код операции Эффект Ожидание
CMD_SET_CT_MODEL_CH0 0x28 Привяжите промежуточное значение CT_MODEL к каналу 0 ~5 мс
CMD_SET_CT_MODEL_CH1 0x29 Привязка к каналу 1 (UI2/UI3/I2/I3) ~5 мс
CMD_SET_CT_MODEL_CH2 0x2A Привяжите к каналу 2 (UI3/I3) ~5 мс
CMD_SAVE_USER_CONFIG 0x32 Сохранить блок пользовательской конфигурации (класс датчика, модель CT, адрес, метка) во flash ~700 мс

Порядок действий

  1. Подключите токовые клещи CT к разъёму (разъёмам) модуля (стрелкой к нагрузке — см. hardware-connection.md).
  2. Задайте класс датчика(однократно, если ещё не задано):

    C++
    rb_write_u8(0x50, 0x25, 0x01);    // SCT_013
    

  3. Для каждого канала модуль предоставляет:

  4. Промежуточно записать код модели CT вCT_MODEL:
    C++
    rb_write_u8(0x50, 0x05, 0x03);    // example: SCT-013-030
    
  5. Привяжите его к каналу с соответствующимCMD_SET_CT_MODEL_CHn:
    C++
    rb_write_u8(0x50, 0x01, 0x28);    // CMD_SET_CT_MODEL_CH0
    delay(5);
    
  6. Повторите для ch1 / ch2, если они есть в варианте (каналы независимы — коды моделей можно смешивать по каналам).
  7. Сохранитьзаписать во flash сCMD_SAVE_USER_CONFIG:

    C++
    rb_write_u8(0x50, 0x01, 0x32);
    delay(700);                          // flash erase/write
    

  8. Готово — с оговоркой для прошивок до 1.4.20 (бит 12 CAPABILITY сброшен): там сохранённый код модели переживает перезагрузки, но применённое масштабирование — нет (см. ниже раздел Что сохраняется при перезапуске): если вы выбрали нестандартную модель, повторяйте шаг 3 (промежуточная запись + фиксация) после каждого обнаруженного перезапуска модуля; CMD_SAVE_USER_CONFIG повторять не нужно. Начиная с fw 1.4.20 переключение модели переживает перезапуски.

Независимость от порядка каналов

: в v1.3 можно вызывать CMD_SET_CT_MODEL_CH0/1/2 в любом порядке. Обходной путь с порядком по убыванию не нужен (это было внутренним артефактом ранних прошивок).

Поведение с текущими клиентскими библиотеками

Клиентские библиотеки rbAmp (Arduino, ESP-IDF, ESPHome, Python) оборачивают эту процедуру и добавляют:

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

  • Модули с заводской парой не принимают смену класса и модели. У исполнений, поставляемых как заводской откалиброванный комплект со своим датчиком тока (CT-серия), класс и модель датчика входят в калибровку: модуль (прошивка 1.4.22 и новее) отклоняет запись с ERR_PARAM (0xFE) в штатном режиме, а библиотеки отклоняют её до отправки на всех прошивках. Замена датчика с перепарой — заводская услуга.

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

Проверка

После привязки применённая модель CT на каждом канале отражается в 0x51..0x53 (зеркала только для чтения и проверки). Это НЕ регистр постановки 0x05:

C++
uint8_t ch0 = rb_read_u8(0x50, 0x51);  // applied on ch0
uint8_t ch1 = rb_read_u8(0x50, 0x52);  // applied on ch1
uint8_t ch2 = rb_read_u8(0x50, 0x53);  // applied on ch2
Serial.printf("Applied: ch0=0x%02X ch1=0x%02X ch2=0x%02X\n", ch0, ch1, ch2);
Безопасность

⚠ Обратное чтение ≠ сохранение. Успешное чтение 0x51..0x53 подтверждает, что значение активно в RAM, но не то, что оно дошло до flash. Чтобы проверить сохранение, выполните CMD_RESET (или отключите питание) и перечитайте после окна загрузки. Полный шаблон — в period-metering.md.

При вводе в эксплуатацию нового модуля проверьте его на известной резистивной нагрузке (например, лампе накаливания 100 Вт): I_rms ≈ 100 Вт / U_rms ≈ 0.43 А и P_real ≈ 100 Вт. Если показания отличаются в разы, скорее всего, неверен код модели.

Что сохраняется при перезапуске

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

Позиция Сохраняется при перезапуске?
Адрес I²C да
Метка модуля да
Класс датчика + код модели CT (читается обратно) да
Применённое масштабирование по модели до fw 1.4.20: нет — сбрасывается к заводскому значению; с 1.4.20 (бит 12 CAPABILITY установлен): да
FLEET_CONFIG (включение GC) + GROUP_ID да (через CMD_SAVE_USER_CONFIG; действует после сброса)
конфигурация только в RAM (пороги событий, конфигурация дайджеста) нет

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

  1. Обнаружьте перезапуск — бит события UPTIME_S / RESET_OCCURRED, см. period-metering.md → Обнаружение перезапуска модуля.

  2. Заново запишите промежуточно и зафиксируйте модель CT на каждом канале (CT_MODEL + CMD_SET_CT_MODEL_CHn), затем заново примените всю конфигурацию, существующую только в RAM.

Клиентские библиотеки реализуют именно это в пути возобновления. Начиная с прошивки 1.4.20 (бит 12 в CAPABILITY, SCT_RATING_SELF) смена модели сохраняет калибровку устройства и переживает перезапуски — шаг 2 для модели CT тогда не нужен; конфигурация только в RAM по-прежнему требует повторной инициализации. Модули, работающие на заводской модели (включая все CT-серии с заводской парой), не затрагиваются на любой прошивке — заводское масштабирование является правильным.

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

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

Библиотека Вызов Что делает
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

Работа с одним модулем

  1. Подключите модуль по hardware-connection.md.
  2. Для модулей BASIC серии SCT запишите модель датчика один раз (предыдущий раздел).
  3. Прошейте мастер скетчем проверки работоспособности.
  4. Откройте монитор последовательного порта — вы должны видеть U/I/P каждую секунду.
  5. Если показания кажутся неверными, см. troubleshooting.md.

Настройка нескольких модулей

Сценарий: три модуля rbAmp на одной шине для контроля разных участков дома (главный ввод, водонагреватель, кондиционер).

Шаг 1 — адреса

Из коробки все три модуля имеют адрес 0x50. Их нужно переадресовывать по одному. Подключайте к шине только один модуль, пока переадресация не завершена.

Шаг 2 — проверка работы с одним модулем

Используйте раздел выше. Убедитесь, что один модуль работает правильно.

Шаг 3 — смена адреса (и при необходимости установка модели CT)

Используйте процедуру смены адреса, описанную ниже. Если модули работают с разными датчиками SCT-013, перед сменой адреса задайте модель CT на каждом из них.

Шаг 4 — цикл опроса нескольких модулей

C++
#include 

const uint8_t modules[] = {0x50, 0x51, 0x52};   // main, boiler, AC
const char* labels[]    = {"MAIN", "BOIL", "AC  "};
const int N = sizeof(modules) / sizeof(modules[0]);

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

  for (int i = 0; i < N; i++) {
    Wire.beginTransmission(modules[i]);
    uint8_t rc = Wire.endTransmission();
    Serial.printf("Module %s (0x%02X): %s\n",
                  labels[i], modules[i], rc == 0 ? "OK" : "MISSING");
  }
}

void loop() {
  for (int i = 0; i < N; i++) {
    float u = rb_read_float_le(modules[i], 0x86);
    float p = rb_read_float_le(modules[i], 0xA6);
    Serial.printf("[%s] U=%.1f  P=%.1f W\n", labels[i], u, p);
  }
  Serial.println();
  delay(1000);
}

Ожидаемый вывод:

Text
Module MAIN (0x50): OK
Module BOIL (0x51): OK
Module AC   (0x52): OK
[MAIN] U=229.8  P=850.3 W
[BOIL] U=229.7  P=1850.0 W
[AC  ] U=229.9  P=0.0 W
...
В клиентских библиотеках

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

Библиотека Вызов Что делает
Arduino RbAmpFleet::scan(match_product, added) / RbAmpFleet::pollAll(snaps, status, capacity, n_ok) найдите модули на шине; читайте все они за один проход
ESP-IDF rbamp_fleet_scan() / rbamp_fleet_poll_all() найдите модули на шине; читайте все они за один проход
Python fleet.scan(match_product=True) / fleet.poll_all() найдите модули на шине; читайте все они за один проход
ESPHome rbamp: (list) один блок rbamp: на модуль, каждый со своим id и address

Смена адреса

Заводской адрес 0x50 хранится в блоке пользовательской конфигурации во флеш. В v1.3 используется двухфазная фиксация, чтобы случайная смена адреса была затруднена: сначала новый адрес-кандидат попадает в регистр постановки в RAM, его нужно взвести магическим байтом, и только затем явной командой зафиксировать во флеш. Сброс заново перечисляет модуль по новому адресу.

Двухфазная смена адреса: поставьте в очередь новый адрес, взведите его, зафиксируйте и сделайте сброс.

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

Имя Адрес / опкод Тип Цель
REG_I2C_ADDRESS 0x30 u8, чтение/запись Промежуточный регистр для кандидата адреса (0x08..0x77). Правило: до сброса 0x30 повторяет промежуточного кандидата; после загрузки читает активный адрес.
ADDR_COMMIT_MAGIC 0x31 u8 W Взведите фиксацию значением 0xA5. Расходуется (сбрасывается) при попытке фиксации.
CMD_COMMIT_ADDR опкод 0x30, записанный в REG_COMMAND (0x01) команда Проверяет поставленный адрес по магическому значению и сохраняет его во флеш.
CMD_RESET код операции 0x01, записанный в REG_COMMAND (0x01) команда Мягкий сброс. Модуль заново регистрируется на новом адресе через ~300 мс.

Порядок действий

  1. Подключите только один модуль (по-прежнему на 0x50) к шине.
  2. Поставьте новый адрес в очередь:

    C++
    rb_write_u8(0x50, 0x30, 0x51);    // candidate address → RAM staging
    

  3. Взведите фиксацию:

    C++
    rb_write_u8(0x50, 0x31, 0xA5);    // ADDR_COMMIT_MAGIC
    

  4. ПроблемаCMD_COMMIT_ADDR (opcode 0x30):

    C++
    rb_write_u8(0x50, 0x01, 0x30);
    

  5. Ожидание≥ 700 мсдля стирания/записи флеша:

    C++
    delay(700);
    

  6. ПроблемаCMD_RESET (opcode 0x01) — CMD_COMMIT_ADDRделаетне auto-reset:

    C++
    rb_write_u8(0x50, 0x01, 0x01);
    

  7. Подождите ~300 мс для окна загрузки. Не выдавайте команды в этом окне.

  8. Убедитесь, что модуль подтверждает ACK на новом адресе:

    C++
    uint8_t ver = rb_read_u8(0x51, 0x03);    // VERSION should be 0x04 on v1.3
    if (ver == 0x04) Serial.println("Address change OK");
    

  9. Пометьте плату новым адресом восковым карандашом или наклейкой, чтобы физически определять модуль.

Важные замечания

  • Оба этапа обязательны. Одна только запись кандидата в 0x30 ничего не сохраняет — она попадает только в RAM и теряется при следующем сбросе. Именно пара «магическое значение + фиксация» действительно перезаписывает флеш.
  • Заданный адрес должен лежать в диапазоне 0x08..0x77 (допустимый 7-битный I²C). Запись вне диапазона отклоняется с ERR_PARAM; модуль сохраняет текущий адрес.
  • Зарезервированные адреса I²C: 0x00 (общий вызов, см. ниже), 0x01..0x07 (зарезервировано CBus), 0x78..0x7F (10-битное резервирование). Не используйте их.
  • Правило одного обратного чтения: до сброса 0x30 повторяет промежуточного кандидата; после загрузки читает активный адрес.
  • Взведённое магическое значение истекает через 5 с без фиксации (глава 11 §6.1) — взводите заново, если ждали слишком долго.
  • Напоминание о пространствах имён — одно и то же значение байта может быть адресом и опкодом:
Байт Как адрес регистра Как опкод (записывается в 0x01)
0x27 FLEET_CONFIG CMD_LATCH_PERIOD
0x28 GROUP_ID CMD_SET_CT_MODEL_CH0
0x30 REG_I2C_ADDRESS CMD_COMMIT_ADDR

Полный пример смены адреса

C++
#include 

bool change_address(uint8_t old_addr, uint8_t new_addr) {
  if (new_addr < 0x08 || new_addr > 0x77) {
    Serial.println("ERROR: invalid address");
    return false;
  }

  Serial.printf("Changing 0x%02X -> 0x%02X\n", old_addr, new_addr);

  rb_write_u8(old_addr, 0x30, new_addr);   // 1. stage candidate
  rb_write_u8(old_addr, 0x31, 0xA5);       // 2. arm magic
  rb_write_u8(old_addr, 0x01, 0x30);       // 3. CMD_COMMIT_ADDR
  delay(700);                              // 4. flash erase/write
  rb_write_u8(old_addr, 0x01, 0x01);       // 5. CMD_RESET (mandatory)
  delay(300);                              // 6. boot window

  Wire.beginTransmission(new_addr);
  if (Wire.endTransmission() == 0) {
    Serial.printf("OK, module now at 0x%02X\n", new_addr);
    return true;
  }
  Serial.printf("FAIL: module not found at 0x%02X\n", new_addr);
  return false;
}

void setup() {
  Serial.begin(115200);
  Wire.begin();
  delay(300);
  change_address(0x50, 0x51);
}
В клиентских библиотеках

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

Библиотека Вызов Что делает
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: однократная смена адреса при загрузке; затем удалите этот параметр

Общий вызов (широковещательно, адрес 0x00)

Протокол I²C резервирует адрес 0x00 (общий вызов) — кадры на этот адрес одновременно получают все ведомые на шине. rbAmp может сделать свой снимок периода по кадру общего вызова, но только после явного включения функции на модуле.

Включение по выбору (по умолчанию ВЫКЛ.)

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

  1. Установите бит 0 вFLEET_CONFIG:
    C++
    rb_write_u8(0x50, 0x27, 0x01);    // bit0 = GC_ENABLE
    
Примечание

Примечание о значении 0x27: это адрес регистра FLEET_CONFIG. Тот же байт 0x27 совпадает с кодом операции CMD_LATCH_PERIOD (отдельное пространство имён — опкоды записываются в REG_COMMAND по адресу 0x01). Совпадение чисто случайное; на уровне провода адрес и опкод никогда не путаются.

  1. (По желанию) задатьGROUP_IDдля разбиения парка на группы —0x00принимает общий вызов:

    C++
    rb_write_u8(0x50, 0x28, 0x00);    // all-call
    

  2. Persist:

    C++
    rb_write_u8(0x50, 0x01, 0x32);    // CMD_SAVE_USER_CONFIG
    delay(700);
    

  3. Выполните сброс и проверьте, что бит записан:

    C++
    rb_write_u8(0x50, 0x01, 0x01);    // CMD_RESET
    delay(300);
    uint8_t cfg = rb_read_u8(0x50, 0x27);
    if (cfg & 0x01) Serial.println("GC enabled");
    

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

Кадры снимка GC имеют фиксированную структуру магического байта и опкода:

Раскладка байтов кадра снимка General Call.

Text
addr 0x00 | A5 27   
  • A5 — магический байт кадра (ведомый отклоняет любой другой байт).
  • 27 — опкод (CMD_LATCH_PERIOD).
  • — целевая группа (0x00 = вызов всех; иначе должен совпадать с GROUP_ID модуля).
  • — 16-битный счётчик тактов на стороне мастера, зеркалируется в регистр GC_TICK (0x59) каждого модуля для обнаружения пропущенных кадров.

По замыслу кадры GC несут только команду снимка — разрушающие коды операций (SAVE_*, COMMIT_ADDR, FACTORY_RESET) через общий вызов не выполняются.

Пример широковещательного снимка (после enable)

C++
// All modules with GC enabled take their snapshots at once.
Wire.beginTransmission(0x00);
Wire.write(0xA5);                       // frame magic
Wire.write(0x27);                       // CMD_LATCH_PERIOD opcode
Wire.write(0x00);                       // group_id = all-call
Wire.write(tick & 0xFF);                // tick_lo
Wire.write((tick >> 8) & 0xFF);         // tick_hi
uint8_t rc = Wire.endTransmission();
if (rc != 0) {
  // NACK at GC level → no module on the bus has GC enabled.
  // Fall back to per-module sequential snapshot.
}

После широковещательной команды каждый модуль независимо обновляет свой снимок. Затем мастер читает каждый модуль по его отдельному адресу. Проверка свидетелем (рекомендуется): через ~50 мс после установления прочитайте V03_PERIOD_VALID (0x07) на каждом ожидаемом модуле — 1 подтверждает, что снимок принят; 0 переводит только этот модуль на снимок по модулю.

Применение: точная синхронизация периодов для балансировки энергии нескольких модулей (например, mains_input − solar_output), где момент снимка должен быть одинаковым для всех модулей.

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

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

Библиотека Вызов Что делает
Arduino RbAmp::enableGc(enable) / RbAmpFleet::gcLatch(group, tick, settle_ms) включить общий вызов на модуле; отправить кадр снимка на весь парк
ESP-IDF rbamp_enable_gc() / rbamp_fleet_gclatch() включить общий вызов на модуле; отправить кадр снимка на весь парк
Python dev.enable_gc(enable=True) / fleet.gc_latch(group, tick, settle_ms) включить общий вызов на модуле; отправить кадр снимка на весь парк
ESPHome fleet_gc_enable: / group_id: Параметры YAML для включения общего вызова и идентификатора группы
Text
Step 1: Unbox all modules — every module is on address 0x50.

Step 2: For each module, one at a time:
   a) Connect only this module to the bus.
   b) If it is a BASIC SCT-series module: set SENSOR_CLASS (0x25), stage CT_MODEL (0x05),
      issue CMD_SET_CT_MODEL_CHn for each channel, then CMD_SAVE_USER_CONFIG.
   c) On images before fw 1.4.20 (`CAPABILITY` bit 12 clear): after any later reset of this
      module, re-stage and re-commit CT_MODEL on each channel (see the persistence table above).
   d) Run change_address(0x50, ).
   e) Verify the module responds at the new address.
   f) Physically mark the module (label with 0x51, 0x52, ...).
   g) Disconnect and move to the next module.

Step 3: After readdressing all modules, connect them in parallel.
        With four or more modules (or a longer bus), cut the built-in
        pull-up jumpers on all but one (see hardware-connection.md → I2C pull-ups).

Step 4: At master boot, run a scan loop and verify every readdressed
        module responds at its expected address.

BASIC или STD?

Линейка STD rbAmp отвечает на той же шине, но использует другую карту регистров, 16-битную. Прежде чем применять приведённое ниже определение BASIC, можно различить линейки: отправьте 16-битный указатель 0x00 0x00 и прочитайте 2 байта — модуль STD вернёт ASCII-пару 'S','T' (0x53 0x54); модуль BASIC — нет (он трактует байты как 8-битные записи регистров и возвращает обычные данные). Модули STD описаны в собственной справочной документации.

Вам не нужно делать это самостоятельно, если используете клиентскую библиотеку. Библиотеки (Arduino, ESP-IDF, Python, ESPHome) сами распознают линейку модулей и работают с разными размерами регистров — вам не нужно думать о том, 8-битная или 16-битная карта регистров.

Как отличить модуль BASIC от модуля STD во время работы.

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

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

Библиотека Вызов Что делает
Arduino RbAmp::line() / RbAmp::begin() линия обнаружена в begin(); прочитайте её обратно из кэшированного значения
ESP-IDF rbamp_line() / rbamp_begin() линия определена в begin; прочитайте её из кэшированного значения
Python dev.is_std / dev.begin() линия определена в begin(); прочитайте её обратно из свойства
ESPHome — не выведено — обнаружение автоматическое, в YAML ничего не настраивается

Автоопределение варианта модуля

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

⚠ Не определяйте вариант, проверяя NACK при чтении регистров. Прошивка никогда не отвечает NACK на чтение регистров — неотображённые адреса возвращают 0x00 (см. главу 11 §5.2). Проверка по NACK всегда сообщает «канал есть».

Используйте каноническую пару HW_VARIANT (0x55) + CAPABILITY (0x57/0x58):

C++
struct VariantInfo {
  uint8_t hw_variant;     // 1=UI1, 2=UI2, 3=UI3, 4=I1, 5=I2, 6=I3
  uint8_t n_current;      // 1..3
  bool    has_voltage;    // true on UI*, false on I*
};

VariantInfo detect_variant(uint8_t addr) {
  VariantInfo v = {0, 0, false};
  uint8_t product = rb_read_u8(addr, 0x54);             // PRODUCT_ID
  if (product != 0x01) return v;                         // not an rbAmp sensor
  v.hw_variant = rb_read_u8(addr, 0x55);                 // HW_VARIANT
  uint8_t hw = v.hw_variant;
  v.n_current = (hw == 1 || hw == 4) ? 1
              : (hw == 2 || hw == 5) ? 2
              : (hw == 3 || hw == 6) ? 3 : 0;
  uint8_t cap_hi = rb_read_u8(addr, 0x58);               // CAPABILITY high byte
  v.has_voltage = (cap_hi & 0x01) != 0;                  // bit 8 of u16 = voltage-HW
  return v;
}

HW_VARIANT 1..3 — варианты с напряжением (has_voltage == true); 4..6 — варианты только с током (has_voltage == false). Несоответствие семейства HW_VARIANT и CAPABILITY.bit8 означает повреждённый или неправильно прошитый модуль.

AC_FREQ (0x20) работает на всех вариантах — сигнал перехода через ноль поступает с отдельного пина перехода через ноль сети, независимого от входа напряжения.

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

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

Библиотека Вызов Что делает
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() строка варианта и битовая карта функций из поверхности идентификации

Далее

  • realtime-polling.md — подробно об опросе в реальном времени (окно 100 мс, DRDY)
  • period-metering.md — накопление тарифной энергии