rbAmp
RU
Магазин
Документация
Обновлено · Редактировать на GitHub (Edit on GitHub)

11 · Журнал изменений

Эта страница повторяет CHANGELOG.md из репозитория.

1.6.1 — 2026-11-01

Учёт периода теперь работает на STD-модулях теми же вызовами, что и на BASIC; добавлены вызовы latch-банков, а вызовы только для BASIC на STD-модулях корректно отклоняются.

Добавлено

  • Учёт периодов на модулях STD (read_period_snapshot, read_period_avg_power / read_period_avg_p, read_period_max_power, is_period_valid, latch_period, dev.energy). Источник выбирается один раз в begin(): модуль со счётчиками на устройстве использует разность двух показаний счётчиков по расписанию мастера (команда latch не отправляется); модуль только с банками latch фиксирует банк 0 (от latch до latch, с паузой не меньше 300 мс); модуль без того и другого выбрасывает RbAmpNotSupportedError. Смена поколения счётчиков или банк, потерявший взведение после сброса модуля, заново привязываются, и этот период пропускается (RbAmpStaleError). Снимок периода получает avg_p_total, wh_net и module_restarted. У периода по счётчикам нет пиковой мощности, а среднее по каналу — только на одноканальном модуле.
  • Вызовы latch-банков доступны, когда модуль сообщает банки: dev.std_arm_banks(mask), dev.std_latch(bank), dev.std_read_latch(bank) (RbAmpStdLatch: P/Q/S, пики, энергия в mW·samples, энергия и средняя мощность по каналам) и RbAmp.std_latch_wh(snap, dt_ms, ch). Флаг валидности банка «липкий», а не флаг свежести: читайте банк минимум через 300 мс после latch.
  • Модели датчиков 11 (50 А) и 13 (100 А) класса клещей охарактеризованы с номинальными, полномасштабными и пиковыми пределами. Модель 12 (80 А) не изменилась.

Фиксировано

  • Вызовы, которые существуют только на карте регистров BASIC (конфигурация класса датчика / модели CT, сброс и смена адреса, регистры идентификации, канал ошибок / событий, хелперы флота и General-Call, read_period_latch_ms, wait_ready), теперь возбуждают RbAmpNotSupportedError на модуле STD вместо чтения или записи не того адреса.
  • set_ct_model_ch_force() на заводски спаренном модуле возбуждает RbAmpModeError ("factory-paired module: configuration locked"), когда прошивка отклоняет запись. Путь force работает только в заводском режиме.

1.6.0 — 2026-10-22

Примечание

Публичные выпуски возобновляются с этой версии; промежуточные версии (1.4.x, 1.5.x) выпускались только внутри компании.

Добавляет линейку модулей STD (16-битная карта регистров) наряду с существующими модулями, учёт энергии по периодам по каналам для модулей на 5/7 каналов и коррекцию по номиналу SCT-013. Один класс RbAmp обслуживает обе линейки; тип модуля определяется автоматически в begin().

Добавлено

  • SCT-013-060 и -100 принимаются (раньше на стороне клиента отклонялись как зарезервированные); границы клипирования модели датчика обновлены по измеренным значениям.
  • Линейка модулей STD (16-битная карта), определяется автоматически. Общие читатели (voltage, current, power, power_factor, frequency) работают на каждом модуле; вызовы только для STD возбуждают RbAmpNotSupportedError на модуле, который их не предоставляет.
  • Энергия на устройстве: dev.read_std_energy() (активный импорт/экспорт/нетто + реактивная, Wh/mWh/µWh, по каналам); RbAmp.std_energy_delta(prev, now) (устойчив к отключению питания).
  • Многофазные: dev.read_voltage_angle(phase), dev.read_phase_sequence(), dev.read_reactive(ch), dev.read_apparent(ch).
  • Стартовый ток: dev.get_start_current() / dev.set_start_current(µA) + dev.save_config().
  • dev.read_std_voltage/channel/totals/config/health(), dev.set_time(), dev.is_std; объекты-значения RbAmpStdEnergy/Voltage/Channel/Config/Health; RbAmpNotSupportedError.
  • Проверено на CPython (smbus2); путь MicroPython 16 бит реализован, но ещё не проверен на железе.
  • Учёт энергии за период по каналам на 5/7-канальных модулях: dev.read_period_avg_power(ch) охватывает каждый канал; снимок периода и накопитель Wh покрывают все каналы.
  • Коррекция по номиналу SCT-013: при переключении канала на другую модель датчика ток, мощность и энергия пересчитываются к выбранной модели относительно усиления, которое применяет модуль; коэффициент мощности и напряжение не меняются. Автоматически; dev.set_rating_correction(), dev.ct_rating_scale(ch), dev.ct_rating_status(ch). Прошивка, которая делает это сама, распознаётся и не трогается.
  • Защита read-before-write при записи класса датчика / модели CT; dev.set_ct_model_ch_force(), dev.read_sensor_class().

Фиксировано

  • Снимок периода на модулях на 5/7 каналов больше не выдавал ошибку для каналов, начиная с третьего.

1.5.0 — 2026-09-04

Назначение модели CT по каналам для всех каналов, поддержка старших SKU (UI5/UI7), реестр моделей датчиков и исправление сохранения. Прошивка: v1.4.18+.

Добавлено

  • Поддержка UI5 / UI7 (старшие SKU): определяется автоматически через REG_TOPOLOGY + REG_HW_VARIANT; dev.channels возвращает 5 или 7; все читатели в реальном времени и периода работают одинаково для ch 0..channels-1.

  • Модель CT по каналам, любой канал: dev.set_ct_model_ch(channel, code) и dev.read_ct_model_ch(channel) теперь принимают channel 0..channels-1. Каналы 0–2 используют плоский путь регистров; каналы 3 и выше — окно доступа к каналам (поле 15).

  • Валидация моделей на основе реестра: реестр моделей теперь единственный источник кодов моделей CT. Генерируется автоматически в rbamp/_sensor_models.py; прежний вручную поддерживаемый словарь _CT_ACCEPTED удалён.

  • RbAmpWindowField.CT_MODEL = 15 (публичный enum).

  • RbAmpFleet.aligned_snapshot() заполняет списки по каналам на полную ширину каналов модуля.

Фиксировано

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

1.4.0 — 2026-08-19

Поддержка старших артикулов (UI5/UI7), RT-метрики старших каналов, снимки флота, согласованные для многоканальных модулей.

1.3.1 — 2026-07-30

Изменено

  • Обновлены многомодульные примеры (examples_cpython/03_multi_module_broadcast.py, examples_upy/03_multi_module.py) и примеры сводного энергобаланса дома (examples_cpython/07_home_energy_balance.py, examples_upy/08_home_energy_balance.py) под согласованный General-Call latch v1.3 (CAP_GC_LATCH): RbAmpFleet.enable_gc_all() → gc_latch() → check_sync(), вместо прежних последовательных latch по устройствам до v1.3. Пример сводного энергобаланса теперь также публикует MQTT-топик home/energy/sync/in_sync. Только правка примеров — API библиотеки не меняется.

1.3.0 — флот + протокол v1.3

Приведён пакет rbamp Python в соответствие с контрактом проводного протокола rbAmp v1.3 и кросс-платформенной эталонной моделью (Arduino / ESP-IDF / ESPHome / STM32 HAL). Набор mock-тестов: 179/179 PASS.

Добавлено

  • RbAmpFleet — менеджер нескольких модулей на стороне хоста: scan() (с детектором конфликтов и сторожевым индикатором Tier-2), add(), find(), count, итерация; пакетный poll_all() (изоляция сбоев, устойчив к MISS); общие для флота total_power() / total_energy_wh() / poll_errors(); синхронизация General-Call (enable_gc_all() / gc_latch() / check_sync()); assign_address() / check_conflict(). Мягкое ограничение: RBAMP_FLEET_MAX_MODULES = 16.

  • Структуры POD: RbAmpFleetPoll (результат опроса одного члена флота), RbAmpFleetSync (свидетель синхронизации GC для члена флота).

  • Идентичность / возможности: read_variant() (байт HW_VARIANT 0x55, 1..6 = UI1/UI2/UI3/I1/I2/I3), read_capability() (битовая карта u16 LE; ветвитесь по битам, а не по эвристикам версий), read_product_id() (0x01 = семейство датчиков rbAmp), read_uid() (12 байт), read_label() / set_label() (8-байтовый ASCII через побайтовую запись).

  • Канал событий и ошибок (двухканальная модель v1.3): read_last_error() (байт REG_ERROR устройства, одно чтение по проводу), read_event_flags(), clear_event_flags(mask), has_error() (помощник для залипающего bit3), clear_error() (CMD_CLEAR_ERROR).

  • Настройка CT по каналам: configure_channels(class, models, n) (пакетно, одна терминальная запись SAVE во flash; ограничение по варианту; клиентская проверка по классу _validate_ct_code); read_ct_model_ch(ch) (чтение зеркала применённой модели из 0x51-0x53).

  • Примитивы флота на уровне устройства: enable_gc(enable=True) (RMW флага GC_ENABLE регистра FLEET_CONFIG + сохранение + сброс; ~1 с блокировки; идемпотентно — ничего не делает, если уже верно), read_fleet_config(), set_group_id() / read_group_id(), read_gc_tick() (u16-свидетель; 0xFFFF = никогда не получал), статический RbAmp.broadcast_latch_group(bus, group, tick) (5-байтный кадр GC A5 27 g tl th).

  • Иерархия исключений: базовый RbAmpError + RbAmpIOError, RbAmpTimeoutError, RbAmpStaleError, RbAmpParamError, RbAmpModeError, RbAmpVersionError.

Изменено

  • Энергия интегрируется по настенным часам мастера, никогда не по диагностическому latch_ms модуля (диагностический таймер, не для энергии). На CPython используйте time.monotonic(); на MicroPython — time.ticks_ms() + time.ticks_diff(). При устаревшем чтении (PERIOD_VALID = 0) библиотека возбуждает RbAmpStaleError и НЕ сбрасывает якорь; следующий валидный снимок покрывает весь интервал, прошивка сохраняет накопитель → математика интегрирования остаётся точной, без двойного или пропущенного учёта.

  • Коды модели CT — это допустимый набор для каждого класса (SCT_013 {1,2,3,4,5,6,7}, WIRED_CT {1,2,3}, BUILTIN_CT ∅); код вне набора класса заставляет библиотеку возбудить RbAmpParamError до любой операции I²C. REG_CT_MODEL — только постановка в очередь: привязка через команду по каналу, а привязка нескольких каналов не зависит от порядка на прошивке v1.3 (на устаревших v1.x осторожный нисходящий паттерн сохранён в цикле set_ct_model_ch).

  • Смена адреса — производственная двухфазная фиксация с magic; режим завода не требуется. prepare_address_change() взводит кандидата и окно magic 0xA5 на 5 секунд; commit_address_change() выполняет CMD_COMMIT_ADDR + сброс. Библиотека гарантирует сброс состояния взведения через try/finally при частичном сбое; истёкшее окно → RbAmpTimeoutError. Совместимо со старыми прошивками v1.x через запасной путь, зависящий от возможностей.

  • Определение варианта — read_variant() читает REG_HW_VARIANT (канонический байт артикула v1.3). Путь зондирования NACK удалён (прошивка никогда не отвечает NACK на чтение; неотображённые чтения → 0x00).

  • Многобайтная ЗАПИСЬ побайтно. set_label() библиотеки записывает 8 байт LABEL циклом по байтам автоматически (rbAmp не автоинкрементирует записи).

Устойчивость на стенде (Stage 1B)

  • CPython SMBusBackend предоставляет общий повтор при NACK (retry_attempts=3, retry_gap_ms=2) с диагностикой retry_count_total + retry_exhaustion_count. Он используется на всех операциях с шиной (записи конфигурации следуют той же дисциплине, что и чтения — иначе запись конфигурации, молча отброшенная на занятой шине, осталась бы невидимой).

  • MicroPython-on-ESP32 MachineI2CBackend сохраняет 50 кГц-дисциплину IDF i2c_master (повтор при NACK с короткой паузой между попытками, чтобы занятая шина не теряла запись молча). См. 09 · API Reference → «Wire-protocol details» — полный контракт.

Примечания

  • Ненадёжная шина / хосты на ESP32: тот же драйвер IDF i2c_master, что в нативных проектах ESP-IDF, — он может зависнуть на удерживаемой шине ниже уровня библиотеки. Рекомендуем внешние подтяжки ~4.7 kΩ, без отладчика NRST в продакшене и сторожевой таймер задачи уровня приложения на задаче опроса как способ восстановления. См. главу 10 · Troubleshooting.

1.1.0 — расширенный снимок периода

Расширенный снимок периода (максимум P, диагностика latch_ms), учёт Wh на стороне мастера.

1.0.0 — первый выпуск

Мониторинг одного устройства в реальном времени (RMS U / I / P / PF / частота), интегрирование энергии за период (Wh), конфигурация типа CT и класса датчика, смена I²C-адреса. Двойной бэкенд (CPython smbus2 / MicroPython machine.I2C).


Исходники и задачи: rb-amp/rbamp-python · эта страница в репозитории: docs/11_changelog.md (v1.6.1)