mercury-base 2.0.0__py3-none-any.whl

mercury_base/__init__.py

@@ -0,0 +1,56 @@
+"""
+Набор инструментов для связи со счётчиками Инкотекс Меркурий по последовательной
+шине или TCP.
+
+Пакет — тонкий стек из двух слоёв. `DataTransport` передаёт байты устройству и
+обратно и ничего не знает о протоколе; `Meter` знает протокол своего устройства,
+проверяет кадры, которые вернул транспорт, и называет команды счётчика. `Meters`
+хранит набор счётчиков — это то, что нужно шлюзу, опрашивающему несколько
+устройств.
+
+Поддерживаются два протокола, каждый в своём подпакете: `mercury_v1` для
+однофазных счётчиков (200, 201, 203, 206) и `mercury_v2` для трёхфазных
+(203.2TD, 204, 208, 230, 231, 234, 236, 238). Протокол определяется по ответу
+самого счётчика, поэтому вызывающий передаёт только адрес.
+
+Copyright (c) 2023–2026 webtoucher
+Распространяется по лицензии BSD 3-Clause. Подробности в LICENSE.md.
+"""
+
+from mercury_base.exceptions import (
+    CheckSumError,
+    CommunicationError,
+    ConnectError,
+    MercuryError,
+    TransportError,
+    UnexpectedAddress,
+    UnexpectedCommand,
+    UnknownCommandError,
+)
+from mercury_base.meter import Meter, MeterInfo, Meters
+from mercury_base.transport import (
+    DataTransport,
+    SerialDataTransport,
+    TcpDataTransport,
+    transport_from_port,
+)
+
+__all__ = [
+    "Meter",
+    "MeterInfo",
+    "Meters",
+    "DataTransport",
+    "SerialDataTransport",
+    "TcpDataTransport",
+    "transport_from_port",
+    "MercuryError",
+    "TransportError",
+    "ConnectError",
+    "CommunicationError",
+    "UnexpectedAddress",
+    "UnexpectedCommand",
+    "CheckSumError",
+    "UnknownCommandError",
+]
+
+__version__ = "2.0.0"

mercury_base/exceptions.py

@@ -0,0 +1,54 @@
+"""
+Ошибки, которые вызывает набор инструментов.
+
+Они образуют два небольших дерева: `TransportError` означает, что кадр не дошёл
+до счётчика или ответ не вернулся, а `CommunicationError` — что что-то вернулось,
+но это не ответ на запрос. Перехват `MercuryError` покрывает оба случая, именно
+так и работает автоопределение счётчика.
+
+Copyright (c) 2023–2026 webtoucher
+Распространяется по лицензии BSD 3-Clause. Подробности в LICENSE.md.
+"""
+
+__all__ = [
+    "MercuryError",
+    "TransportError",
+    "ConnectError",
+    "CommunicationError",
+    "UnexpectedAddress",
+    "UnexpectedCommand",
+    "CheckSumError",
+    "UnknownCommandError",
+]
+
+
+class MercuryError(Exception):
+    """Общий предок всех ошибок набора инструментов."""
+
+
+class TransportError(MercuryError):
+    """Транспорт не удаётся открыть, либо открытый транспорт отказал."""
+
+
+class ConnectError(MercuryError):
+    """По адресу не ответил ни один известный счётчик, поэтому подключения нет."""
+
+
+class CommunicationError(MercuryError):
+    """Ответ не пришёл или он не соответствует запросу."""
+
+
+class UnexpectedAddress(CommunicationError):
+    """Ответ адресован другому счётчику — признак перепутанной шины."""
+
+
+class UnexpectedCommand(CommunicationError):
+    """Ответ несёт другую команду — признак запоздавшего ответа."""
+
+
+class CheckSumError(CommunicationError):
+    """Кадр не проходит CRC-16, то есть повреждён или обрезан в пути."""
+
+
+class UnknownCommandError(MercuryError, AttributeError):
+    """В протоколе счётчика нет команды с таким именем."""

mercury_base/mercury_v1/README.md

@@ -0,0 +1,187 @@
+# Однофазные счётчики Инкотекс Меркурий 200, 201, 203 и 206
+
+Драйвер `mercury_base.mercury_v1`. Кадр запроса — четырёхбайтовый сетевой адрес в
+сетевом порядке, байт команды и данные; кадр ответа — тот же адрес, тот же байт
+команды и данные. Числа счётчик присылает старшим байтом вперёд, а время и дату —
+двоично-десятичным кодом, поэтому одни ответы читаются как двоичные, а другие —
+как пары десятичных цифр.
+
+Разбор опирается на «Систему команд счётчиков М206» (Incotex, 01.04.2018) из
+[раздела документации по протоколам](https://www.incotexcom.ru/support/docs/protocol).
+Все команды проверены на живом счётчике Меркурий 206: кадры его ответов стали
+фикстурами тестов, а разобранные значения сошлись с конфигуратором прибора.
+
+## Команды
+
+Команды идут от базовых к продвинутым — в том же порядке, что и в
+`commands.py`: сначала опознание прибора и время, затем учёт энергии и
+мгновенные значения, после них лимиты, архивы и максимумы, а в конце
+расписания, индикация и журналы.
+
+### Опознание прибора
+
+| Команда                            | Код | Параметры        | Результат                                                                   |
+|------------------------------------|-----|------------------|-----------------------------------------------------------------------------|
+| interview                          | —   |                  | данные для автоопределения (`dict`) или `None`, если протокол не подошёл    |
+| get_serial_number                  | 2Fh |                  | серийный номер (`int`)                                                      |
+| get_info                           | 86h | 255              | модель (`str` или `None`) и комплектация (`list[str]`)                      |
+| get_group_address                  | 20h |                  | групповой адрес строкой из восьми шестнадцатеричных цифр (`str`)            |
+| get_manufacture_date               | 66h |                  | дата изготовления прибора, `Y-m-d` (`str`)                                  |
+| get_firmware_info                  | 28h |                  | версия прошивки и её дата (`dict`)                                          |
+| get_execution_word                 | 65h |                  | реле и второй датчик тока (`dict`)                                          |
+| get_tariffs_count                  | 2Eh |                  | число действующих тарифов (`int`)                                           |
+| get_timeout_multiplier             | 82h |                  | множитель таймаута обмена (`int`)                                           |
+
+### Время прибора
+
+| Команда                            | Код | Параметры        | Результат                                                                   |
+|------------------------------------|-----|------------------|-----------------------------------------------------------------------------|
+| get_datetime                       | 21h |                  | текущие дата и время, `Y-m-d H:M:S` (`str`)                                 |
+| get_is_seasonal_time               | 24h |                  | разрешён ли переход на летнее и зимнее время (`bool`)                       |
+| get_time_correction                | 25h |                  | предел коррекции хода часов в минутах (`int`)                               |
+
+### Учёт энергии
+
+| Команда                            | Код | Параметры        | Результат                                                                   |
+|------------------------------------|-----|------------------|-----------------------------------------------------------------------------|
+| get_energy_accumulators            | 27h |                  | тарифные аккумуляторы активной энергии 1–4 в киловатт-часах (`list[float]`) |
+| get_reactive_energy_accumulators   | 85h |                  | тарифные аккумуляторы реактивной энергии (`list[float]`)                    |
+| get_tariff                         | 60h |                  | действующий тариф (`int`)                                                   |
+| get_month_energy_slices            | 32h | 0…B              | показания на начало месяца по тарифам 1–4 (`list[float]`)                   |
+| get_reactive_month_energy_slices   | 38h | 0…B              | показания на начало месяца в реактивной энергии (`list[float]`)             |
+
+### Мгновенные значения
+
+| Команда                            | Код | Параметры        | Результат                                                                   |
+|------------------------------------|-----|------------------|-----------------------------------------------------------------------------|
+| get_load_power                     | 26h |                  | текущая мощность в нагрузке в киловаттах (`float`)                          |
+| get_vcp                            | 63h |                  | напряжение, ток и мощность в нагрузке (`dict`)                              |
+| get_reactive_power                 | 86h | 0                | реактивная мощность в киловарах (`float`)                                   |
+| get_full_power_and_cos_fi          | 86h | 2                | коэффициент мощности и полная мощность (`dict`)                             |
+| get_mains_parameters               | 81h |                  | частота сети, действующий тариф и флаги качества (`dict`)                   |
+| get_battery_voltage                | 29h |                  | напряжение на литиевой батарее в вольтах (`float`)                          |
+
+### Лимиты и управление нагрузкой
+
+| Команда                            | Код | Параметры        | Результат                                                                   |
+|------------------------------------|-----|------------------|-----------------------------------------------------------------------------|
+| get_power_limit                    | 22h |                  | лимит мощности в киловаттах (`float`)                                       |
+| get_month_energy_limit             | 23h |                  | лимит энергии за месяц в киловатт-часах (`float`)                           |
+| get_tariff_energy_limits           | 6Eh |                  | потарифные лимиты энергии и отметка превышения (`list[dict]`)               |
+| get_is_relay_on                    | 86h | 1                | включено ли реле (`bool`)                                                   |
+| get_relay_mode                     | 6Dh |                  | чем управляется реле: `limits`, `off` или `on` (`str`)                      |
+| get_output_optocoupler_function    | 2Dh |                  | назначение выходного оптрона (`int`)                                        |
+
+### Архивы и максимумы
+
+| Команда                            | Код | Параметры        | Результат                                                                   |
+|------------------------------------|-----|------------------|-----------------------------------------------------------------------------|
+| get_month_energy_slice             | 37h | 1, m, y          | те же показания, но с годом — срезы за четыре года (`dict`)                 |
+| get_daily_energy_slice             | 37h | 0, d, m, y       | показания на начало суток и их дата (`dict`)                                |
+| get_half_hour_energies             | 37h | 10h…15h, d, m, y | восемь получасовок на дату по 0,2 Вт·ч (`list[float]`)                      |
+| get_archive_type                   | 37h | E0h              | глубина архивов прибора (`int`)                                             |
+| get_maxima                         | 33h | 0, 1 и 2         | максимум величины и момент, когда он достигнут (`dict`)                     |
+
+### Расписания и индикация
+
+| Команда                            | Код | Параметры        | Результат                                                                   |
+|------------------------------------|-----|------------------|-----------------------------------------------------------------------------|
+| get_tariff_schedule                | 31h | 0…B7h            | точки переключения тарифов: время и номер тарифа (`list[dict]`)             |
+| get_holidays                       | 30h | 0 и 1            | праздничные дни в виде `m-d` (`list[str]`)                                  |
+| get_display_filters                | 2Ah |                  | маска индикации строкой из восьми битов (`str`)                             |
+| get_display_times                  | 67h |                  | время индикации четырёх экранов в секундах (`list[int]`)                    |
+| get_display_mode                   | 6Ah |                  | маска дополнительной индикации и её задержка (`dict`)                       |
+| get_is_under_battery_display       | 6Fh |                  | разрешена ли индикация под батарейкой (`bool`)                              |
+
+### Журналы и диагностика
+
+| Команда                            | Код | Параметры        | Результат                                                                   |
+|------------------------------------|-----|------------------|-----------------------------------------------------------------------------|
+| get_last_stop_datetime             | 2Bh |                  | время последнего отключения напряжения, `Y-m-d H:M:S` (`str`)               |
+| get_last_start_datetime            | 2Ch |                  | время последнего включения напряжения, `Y-m-d H:M:S` (`str`)                |
+| get_last_cover_open_datetime       | 61h |                  | время последнего вскрытия крышки, `Y-m-d H:M:S` (`str`)                     |
+| get_last_cover_close_datetime      | 62h |                  | время последнего закрытия крышки, `Y-m-d H:M:S` (`str`)                     |
+| get_last_parameterization_datetime | 6Bh |                  | время последней параметризации, `Y-m-d H:M:S` (`str`)                       |
+| get_operating_time                 | 69h |                  | наработка под напряжением и без него в часах (`dict`)                       |
+| get_modem_info                     | 6Ch |                  | номер модема и уровень сигнала (`dict`)                                     |
+| get_is_plc_modem_enabled           | 80h |                  | разрешён ли модем PLC2 (`bool`)                                             |
+| get_switch_events                  | 34h | 0…3Fh            | событие включения или выключения и его время (`dict`)                       |
+| get_cover_events                   | 35h | 0…3Fh            | событие вскрытия или закрытия крышки и его время (`dict`)                   |
+| get_parameterization_events        | 36h | 0…3Fh            | дата параметризации и коды записанных команд (`dict`)                       |
+| get_quality_events                 | 39h | ii6, ii7         | событие качества электроэнергии и его время (`dict`)                        |
+
+## Примечания
+
+- Команды `get_info`, `get_is_relay_on`, `get_full_power_and_cos_fi` и
+  `get_reactive_power` работают с байтом 86h; в описании протокола он есть, но
+  восстанавливать его пришлось по записям обмена с реальным счётчиком.
+  Незнакомый код модели оставляет `model` незаполненным, а список признаков —
+  пустым.
+- Мгновенные значения приходят целыми: лимит мощности и мощность в нагрузке — в
+  сотых долях киловатта (`mm,mm`), поэтому функция делит их на 100. Напряжение,
+  ток и мощность команды 63h передаются двоично-десятичным кодом и делятся на 10,
+  100 и 1000, то есть возвращаются в вольтах, амперах и киловаттах.
+- Лимит энергии за месяц — целые киловатт-часы без дробной части: наибольшее
+  значение поля, 9999 кВт⋅ч, счётчик держит, когда лимит не задан.
+- Аккумуляторы энергии приходят в десятках ватт-часов, поэтому функция делит их на
+  100 и возвращает киловатт-часы.
+- Время и дата — семь байтов двоично-десятичного кода `dow-hh-mm-ss-dd-mon-yy`:
+  день недели в них первый, поэтому команды отбрасывают один байт, а не два.
+  Год передаётся двумя последними цифрами.
+- Таблица праздников состоит из шестнадцати дат, разбитых на две половины; каждая
+  дата — число и месяц в двоично-десятичном коде, а пустая дата заполнена
+  единицами. Функция читает обе половины и разбирает дату без `strptime`: день
+  без года в нём допустим не во всех версиях Python.
+- Маска индикации: биты 0–3 разрешают индикацию тарифов 1–4, bit4 — суммы,
+  bit5 — мощности, bit6 — времени, bit7 — даты; нулевая маска оставляет только
+  индикацию текущего тарифа.
+- Групповой адрес позволяет одной командой настроить всю группу: такие счётчики
+  команду выполняют, но не отвечают.
+- Параметры команды занимают по одному байту, поэтому `get_holidays` и
+  `get_is_relay_on` передают номер половины таблицы и номер функции отдельными
+  вызовами.
+- `get_tariff` на однотарифном счётчике отвечает нулём, хотя описание протокола
+  обещает 1–4. Расписание (команда 31h) при этом хранится и делит сутки на зоны
+  `T1` и `T2`, но счётчик его не применяет и отвечает нулём и до границы 23:00,
+  и после неё.
+- Дата изготовления (66h) — три байта `dd-mon-yy`, как в паспорте прибора. Ключ
+  `date_of_manufacture` в ответе `get_firmware_info` — это не она, а дата версии
+  прошивки из команды 28h: на проверенном приборе они расходятся.
+- Наработка (69h) — две трёхбайтовые величины в часах: время под напряжением и
+  время без напряжения. Первое поле растёт, пока на счётчике есть питание.
+- Коэффициент мощности приходит двумя байтами двоично-десятичного кода, а знак —
+  старший бит старшего байта. На всех записанных кадрах знак был положительным,
+  а конфигуратор прибора показывает тот же модуль для индуктивной нагрузки со
+  знаком минус: минус — соглашение конфигуратора, а не поле кадра.
+- Расписание (31h) — шестнадцать пар «час-минута», и в двух старших битах часа
+  записан номер тарифа с нуля. Параметр — месяц в старшей тетраде и день недели
+  в младшей (0 — воскресенье, 7 — праздник). На проверенном приборе все дни и
+  месяцы отдают одну и ту же таблицу.
+- Максимумы (33h) — по две записи в ответе: несбрасываемый максимум и такой же,
+  который сбрасывает команда 12h. Каждая запись — два байта значения и шесть
+  байт времени. Мощность приходит полем «`mm,mm` кВт», как у команды 26h, поэтому
+  делится на 100, а не на 1000, как трёхбайтовая мощность команды 63h.
+- Срезы (32h, 37h, 38h) и аккумуляторы реактивной энергии (85h) — это не расход
+  за сутки или месяц, а показания счётчика на их начало. Расход — разность двух
+  соседних срезов: на проверенном приборе срез 01.11 дал 12984,11 кВт⋅ч, срез
+  15.11 — 13136,57, а текущие аккумуляторы — 13147,62 кВт⋅ч.
+- В команде 37h параметр `N48` выбирает архив: 0 — суточные срезы, 1 — месячные
+  срезы за четыре года (года у команды 32h нет), 10h–15h — группы получасовок с
+  10h, E0h — глубина архивов, F0h — «потерянные» получасовки. Ответ получасовок —
+  восемь записей по четыре байта: два байта энергии младшим байтом вперёд с
+  разрешением 0,2 Вт⋅ч и два байта контрольной суммы записи.
+- Журналы (34h–36h, 39h) отдают записи от свежих к старым, поэтому параметр 0 —
+  последнее событие. В журнале параметризации (36h) три слова битовых флагов
+  отвечают за команды 00h–0Fh, 10h–17h и 70h–7Fh: на проверенном приборе
+  выставлен бит команды 0Ah, которой записывают тариф.
+- В журнале качества (39h) событие лежит в двух старших битах часа: 80h — переход
+  порога, 40h — возврат к норме. Смысл параметров `ii6` и `ii7` описание не
+  раскрывает, поэтому функция называет их `index` и `kind` и передаёт как есть.
+- Потарифные лимиты (6Eh) — четыре записи по четыре байта: три байта лимита в
+  двоично-десятичном коде и байт флага, где AAh отмечает превышение. На приборе
+  лимит первого тарифа — 986852 кВт⋅ч, а конфигуратор показывает на 100000
+  меньше: разницу он вычитает как уже израсходованную энергию.
+- Не реализованы четыре кода из описания: 3Ah (журнал реле) и 86h с параметром 3
+  (автовключение реле) проверенный прибор оставляет без ответа; у 64h
+  (коэффициент коррекции хода) и 68h (режим лимита мощности) ответ приходит, но
+  знак и единицы первого и биты второго с конфигуратором не сходятся.

mercury_base/mercury_v1/__init__.py

@@ -0,0 +1,52 @@
+"""
+Протокол однофазных счётчиков: Меркурий 200, 201, 203 и 206.
+
+Кадр начинается с четырёхбайтового адреса в сетевом порядке, затем идёт один
+байт команды, затем данные и CRC-16 в конце. Адрес счётчика — это его серийный
+номер, поэтому сетевой адрес может содержать до восьми цифр.
+
+Copyright (c) 2023–2026 webtoucher
+Распространяется по лицензии BSD 3-Clause. Подробности в LICENSE.md.
+"""
+
+from struct import pack, unpack
+from typing import List
+
+from mercury_base.mercury_v1 import commands
+
+__all__ = [
+    "commands",
+    "prepare_address",
+    "format_address",
+    "extract_address",
+    "extract_command",
+    "extract_data",
+]
+
+#: Четыре байта в сетевом порядке.
+ADDRESS_FORMAT = "!I"
+
+
+def prepare_address(address: int) -> int:
+    """Вернуть адрес, который может нести протокол, — последние восемь цифр."""
+    return address % 100000000
+
+
+def format_address(address: int) -> bytes:
+    """Вернуть адрес в виде четырёх байтов, с которых начинается кадр."""
+    return pack(ADDRESS_FORMAT, address)
+
+
+def extract_address(message: bytes) -> int:
+    """Вернуть адрес, которому адресован кадр или с которого он пришёл."""
+    return unpack(ADDRESS_FORMAT, message[:4])[0]
+
+
+def extract_command(message: bytes) -> int:
+    """Вернуть байт команды, который несёт кадр."""
+    return message[4]
+
+
+def extract_data(message: bytes) -> List[int]:
+    """Вернуть данные кадра без адреса, команды и CRC."""
+    return list(message[5:-2])