02 · Инициализация и запуск
rbAmp начинает измерять сразу после включения питания. Мастеру нужно только:
- Поднимите шину I²C (стандартная инициализация
Wire/ HAL). - Подождите ~250 мс или опрашивайте
DATA_VALID = 1в регистре0xCE. - По желанию прочитайте версию прошивки из
0x03как проверку здравомыслия. - Данные чтения — готовы.
Команда запуска и регистровая настройка микросхемы не требуются. Заводская калибровка загружается автоматически при включении, поэтому модуль выдаёт корректные значения в физических единицах уже с первого считывания.
Важно для модулей 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)
Все приведённые ниже примеры используют три небольших вспомогательных функции, которые легко реализовать на любой платформе:
// 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)
Вспомогательные функции
#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();
}
Проверка работы (один модуль)
#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):
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)
#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); клиентские библиотеки отклоняют их на всех прошивках.
Канал и его клещи — пара. Каждые клещи помечены каналом, к которому относятся. Не переносите клещи на другой канал и не подключайте другие клещи к каналу: калибровка действует только для заводской пары. Номиналы фиксированы, выбирать номинал не нужно.
Последовательность запуска
- Подключите клещи (стрелка к нагрузке — см. hardware-connection.md) и подайте питание на модуль.
- Прочитайте класс (
SENSOR_CLASS,0x25):2= серия CT-клещей. - Прочитайте применённую модель каждого канала (
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 |
Используйте номинал, чтобы масштабировать диапазоны отображения и проверять показания; модуль уже выдаёт значения в амперах.
- Опрашивайте так же, как любой модуль 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 мс |
Порядок действий
- Подключите токовые клещи CT к разъёму (разъёмам) модуля (стрелкой к нагрузке — см. hardware-connection.md).
-
Задайте класс датчика(однократно, если ещё не задано):
C++rb_write_u8(0x50, 0x25, 0x01); // SCT_013 -
Для каждого канала модуль предоставляет:
- Промежуточно записать код модели CT в
CT_MODEL:C++rb_write_u8(0x50, 0x05, 0x03); // example: SCT-013-030 - Привяжите его к каналу с соответствующим
CMD_SET_CT_MODEL_CHn:C++rb_write_u8(0x50, 0x01, 0x28); // CMD_SET_CT_MODEL_CH0 delay(5); - Повторите для ch1 / ch2, если они есть в варианте (каналы независимы — коды моделей можно смешивать по каналам).
-
Сохранитьзаписать во flash с
CMD_SAVE_USER_CONFIG:C++rb_write_u8(0x50, 0x01, 0x32); delay(700); // flash erase/write -
Готово — с оговоркой для прошивок до 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:
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 модуля):
-
Обнаружьте перезапуск — бит события
UPTIME_S/RESET_OCCURRED, см. period-metering.md → Обнаружение перезапуска модуля. -
Заново запишите промежуточно и зафиксируйте модель 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 |
Работа с одним модулем
- Подключите модуль по hardware-connection.md.
- Для модулей BASIC серии SCT запишите модель датчика один раз (предыдущий раздел).
- Прошейте мастер скетчем проверки работоспособности.
- Откройте монитор последовательного порта — вы должны видеть U/I/P каждую секунду.
- Если показания кажутся неверными, см. troubleshooting.md.
Настройка нескольких модулей
Сценарий: три модуля rbAmp на одной шине для контроля разных участков дома (главный ввод, водонагреватель, кондиционер).
Шаг 1 — адреса
Из коробки все три модуля имеют адрес 0x50. Их нужно переадресовывать по одному. Подключайте к шине только один модуль, пока переадресация не завершена.
Шаг 2 — проверка работы с одним модулем
Используйте раздел выше. Убедитесь, что один модуль работает правильно.
Шаг 3 — смена адреса (и при необходимости установка модели CT)
Используйте процедуру смены адреса, описанную ниже. Если модули работают с разными датчиками SCT-013, перед сменой адреса задайте модель CT на каждом из них.
Шаг 4 — цикл опроса нескольких модулей
#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);
}
Ожидаемый вывод:
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 мс. |
Порядок действий
- Подключите только один модуль (по-прежнему на
0x50) к шине. -
Поставьте новый адрес в очередь:
C++rb_write_u8(0x50, 0x30, 0x51); // candidate address → RAM staging -
Взведите фиксацию:
C++rb_write_u8(0x50, 0x31, 0xA5); // ADDR_COMMIT_MAGIC -
Проблема
CMD_COMMIT_ADDR(opcode0x30):C++rb_write_u8(0x50, 0x01, 0x30); -
Ожидание≥ 700 мсдля стирания/записи флеша:
C++delay(700); -
Проблема
CMD_RESET(opcode0x01) —CMD_COMMIT_ADDRделаетне auto-reset:C++rb_write_u8(0x50, 0x01, 0x01); -
Подождите ~300 мс для окна загрузки. Не выдавайте команды в этом окне.
-
Убедитесь, что модуль подтверждает 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"); -
Пометьте плату новым адресом восковым карандашом или наклейкой, чтобы физически определять модуль.
Важные замечания
- Оба этапа обязательны. Одна только запись кандидата в
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 |
Полный пример смены адреса
#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 на модуле:
- Установите бит 0 в
FLEET_CONFIG:C++rb_write_u8(0x50, 0x27, 0x01); // bit0 = GC_ENABLE
Примечание о значении 0x27: это адрес регистра FLEET_CONFIG. Тот же байт 0x27 совпадает с кодом операции CMD_LATCH_PERIOD (отдельное пространство имён — опкоды записываются в REG_COMMAND по адресу 0x01). Совпадение чисто случайное; на уровне провода адрес и опкод никогда не путаются.
-
(По желанию) задать
GROUP_IDдля разбиения парка на группы —0x00принимает общий вызов:C++rb_write_u8(0x50, 0x28, 0x00); // all-call -
Persist:
C++rb_write_u8(0x50, 0x01, 0x32); // CMD_SAVE_USER_CONFIG delay(700); -
Выполните сброс и проверьте, что бит записан:
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 имеют фиксированную структуру магического байта и опкода:
addr 0x00 | A5 27
A5— магический байт кадра (ведомый отклоняет любой другой байт).27— опкод (CMD_LATCH_PERIOD).— целевая группа (0x00= вызов всех; иначе должен совпадать сGROUP_IDмодуля).— 16-битный счётчик тактов на стороне мастера, зеркалируется в регистрGC_TICK (0x59)каждого модуля для обнаружения пропущенных кадров.
По замыслу кадры GC несут только команду снимка — разрушающие коды операций (SAVE_*, COMMIT_ADDR, FACTORY_RESET) через общий вызов не выполняются.
Пример широковещательного снимка (после enable)
// 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 для включения общего вызова и идентификатора группы |
Рекомендуемая последовательность развёртывания нескольких модулей
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-битная карта регистров.
— та же задача без доступа к регистрам:
| Библиотека | Вызов | Что делает |
|---|---|---|
| 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):
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 — накопление тарифной энергии