Локальный API истории энергопотребления для показаний в кВт·ч

title: Локальный API истории энергопотребления для показаний в кВт·ч

abstract: Чтение получасовой истории в кВт·ч локально для офлайн-анализа.

language: ru

author: Jessica

Введение

Для пользователей, которые создают собственные дашборды, автоматизации или инструменты офлайн-анализа, реальные данные об энергопотреблении полезнее, когда они доступны с постоянным интервалом. Единичное измерение мощности в реальном времени показывает, что происходит сейчас, но получасовая история в кВт·ч помогает понять, как импорт и экспорт электроэнергии меняются со временем.

Начиная с версии прошивки i.91.063TS8.bin, выпущенной 2 июня 2026 года, IAMMETER поддерживает новый локальный API: GET /api/energyhistory. Этот API возвращает локально кэшированные показания в кВт·ч, снятые около получасовых границ UTC, что упрощает анализ недавнего энергопотребления без опоры только на облачную историю.

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

Что предоставляет API истории энергопотребления

Новая конечная точка:

GET /api/energyhistory

Она возвращает показания энергии в kWh, снятые около следующих получасовых границ UTC:

00:00
00:30
01:00
01:30
и так далее

Прошивка хранит до 96 записей, что соответствует 48 часам истории с 30-минутным интервалом. Записи хранятся в ОЗУ Wi-Fi модуля, поэтому они теряются после перезагрузки устройства.

Типичный ответ включает:

utc: текущая временная метка UTC модуля
timeSynced: синхронизировано ли время UTC модуля
interval: интервал выборки, сейчас 1800 секунд
count: количество доступных записей истории
order: сейчас newest_first
unit: сейчас kWh
channels: названия каналов, соответствующие каждому значению
Datas: получасовые записи истории

Каждый элемент в Datas содержит временную метку UTC и массив значений в кВт·ч. Значения следуют в том же порядке, что и массив channels.

Почему получасовая история в кВт·ч важна

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

Например, пользователь может с помощью локальных данных:

Просматривать недавно импортированную и экспортированную энергию, не дожидаясь облачных отчётов.
Экспортировать последние 48 часов показаний в кВт·ч в локальную базу данных или CSV-файл.
Сравнивать профили экспорта солнечной энергии с потреблением домохозяйства.
Проверять, меняет ли стратегия автоматизации потребление электроэнергии в определённые периоды.
Создать локальный дашборд недавней истории энергопотребления.

Для более широких сценариев мониторинга солнечной энергии см. решение IAMMETER для мониторинга солнечной энергии. Для мониторинга электроэнергии в жилых домах см. решение IAMMETER для мониторинга энергопотребления дома.

Поддерживаемые схемы каналов

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

Однофазный

["imp", "exp"]

Двухфазный (Split Phase)

["a_imp", "a_exp", "b_imp", "b_exp"]

Трёхфазный

["a_imp", "a_exp", "b_imp", "b_exp", "c_imp", "c_exp"]

Трёхфазный с включённым учётом сальдо (Net Metering)

["a_imp", "a_exp", "b_imp", "b_exp", "c_imp", "c_exp", "nem_imp", "nem_exp"]

Поскольку имена каналов возвращаются в ответе, пользовательское ПО должно сначала прочитать массив channels, а затем соответствующим образом сопоставить каждое значение в Datas[].values.

Примеры исходных ответов API

Два следующих примера показывают исходные возвращаемые значения API для пустого ответа и ответа с данными.

Пример пустого ответа

После загрузки устройства массив истории может быть пустым, пока не будут доступны корректное время UTC и корректные кадры данных счётчика. В этом случае API может вернуть count: 0 и пустой массив Datas.

{
  "utc": 1780023600,
  "timeSynced": 1,
  "interval": 1800,
  "count": 0,
  "order": "newest_first",
  "unit": "kWh",
  "source": "wifi",
  "channels": ["a_imp", "a_exp", "b_imp", "b_exp", "c_imp", "c_exp"],
  "Datas": []
}

Такой ответ нормален после загрузки. Локальный дашборд или скрипт должен обрабатывать это состояние и ожидать новых получасовых выборок.

Пример ответа с данными

Следующий пример показывает две получасовые записи с трёхфазного счётчика. Ответ упорядочен от новых записей к старым.

{
  "utc": 1780023700,
  "timeSynced": 1,
  "interval": 1800,
  "count": 2,
  "order": "newest_first",
  "unit": "kWh",
  "source": "wifi",
  "channels": ["a_imp", "a_exp", "b_imp", "b_exp", "c_imp", "c_exp"],
  "Datas": [
    {
      "utc": 1780023600,
      "values": [11.337, 11.201, 11.039, 10.908, 10.975, 10.846]
    },
    {
      "utc": 1780021800,
      "values": [11.330, 11.198, 11.030, 10.900, 10.970, 10.840]
    }
  ]
}

В самой новой записи a_imp равно 11.337 kWh, a_exp — 11.201 kWh и так далее. Значение каждого элемента определяется массивом channels.

Использование возвращаемых значений в программном обеспечении

Приведённых выше примеров исходных ответов достаточно для создания простой логики локального анализа. Главное — сначала прочитать channels, а затем применить этот порядок к каждому элементу в Datas.

Сопоставление `channels` и `values`

При разработке ПО на основе этого API избегайте жёсткого кодирования позиций, если конфигурация счётчика не является фиксированной. Более надёжный подход — преобразовать список каналов и массив значений в объект с именованными полями.

const response = await fetch("http://<meter-ip>/api/energyhistory").then((res) => res.json());
const latest = response.Datas[0];

const latestByChannel = Object.fromEntries(
  response.channels.map((name, index) => [name, latest.values[index]])
);

console.log(latest.utc, latestByChannel);

Для приведённого выше примера ответа трёхфазного счётчика latestByChannel будет содержать:

{
  "a_imp": 11.337,
  "a_exp": 11.201,
  "b_imp": 11.039,
  "b_exp": 10.908,
  "c_imp": 10.975,
  "c_exp": 10.846
}

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

Расчёт изменения в кВт·ч за полчаса

Если вы используете возвращаемые значения в кВт·ч как накопленные показания энергии, изменение между двумя соседними записями можно рассчитать, вычтя более старое значение из более нового для одного и того же канала.

Используя приведённый выше пример для трёхфазного счётчика:

a_imp change = 11.337 - 11.330 = 0.007 kWh
a_exp change = 11.201 - 11.198 = 0.003 kWh
b_imp change = 11.039 - 11.030 = 0.009 kWh
b_exp change = 10.908 - 10.900 = 0.008 kWh

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

Важные особенности выборки

История энергопотребления формируется локально Wi-Fi модулем. Особенности выборки важны при создании интеграций или инструментов анализа:

Выборка выполняется на основе корректных кадров данных счётчика, полученных по UART.
Модуль сохраняет выборку, ближайшую к каждой получасовой границе UTC.
Время UTC должно быть корректным, прежде чем записи истории будут сохранены.
Если timeSynced равно 0, новые выборки истории не записываются.
После загрузки Datas может быть пустым, пока не будет получено достаточно корректных выборок.
Текущее хранилище основано на ОЗУ, поэтому API предназначен для недавней локальной истории, а не для долгосрочного хранения.

Это делает API подходящим для локального опроса, краткосрочного анализа и тестирования интеграций. Для долгосрочных отчётов об энергопотреблении пользователям по-прежнему следует иметь постоянный источник данных, например облачные данные IAMMETER или собственную базу данных.

Примеры идей для интеграции

Разработчики и продвинутые пользователи могут использовать /api/energyhistory как простой локальный источник данных для недавней истории в кВт·ч.

Один из распространённых подходов — периодически опрашивать конечную точку, читать список channels и сохранять новые записи Datas в локальную базу данных. Это может обеспечивать работу локальных дашбордов, пользовательских отчётов или скриптов офлайн-анализа.

Ещё один полезный сценарий — анализ самопотребления солнечной энергии. Сравнивая значения импортированных и экспортированных кВт·ч по получасовым интервалам, пользователи могут лучше понять, когда домашние нагрузки потребляют солнечную генерацию на месте, а когда избыточная энергия экспортируется. Это помогает принимать более обоснованные решения об автоматизации, например переносить гибкие нагрузки на периоды с более высокой выработкой солнечной энергии.

Если вы создаёте локальные интеграции, также см. Локальный API, Modbus/TCP и MQTT и IAMMETER Local API Explorer.

Как это вписывается в управление энергопотреблением

Ценность API истории энергопотребления не только в том, что он предоставляет больше данных. Главное — что пользователи могут с этими данными делать.

С получасовой историей в кВт·ч пользователи могут анализировать недавний импорт и экспорт электроэнергии, выявлять модели потребления и оценивать, действительно ли стратегии использования солнечной энергии или управления нагрузкой дают эффект. Это соответствует более широкой цели IAMMETER: превращать данные мониторинга энергопотребления в практические решения, которые повышают энергоэффективность и снижают счета за электроэнергию.

Для пользователей, которые объединяют IAMMETER с платформами автоматизации, локальная история энергопотребления также может служить удобным слоем данных для тестирования и проверки логики управления. Например, пользователи Home Assistant, оптимизирующие использование избытка солнечной энергии, могут сопоставить недавние изменения в кВт·ч с поведением автоматизации. См. Автоматизация солнечной энергии в Home Assistant с IAMMETER для соответствующего примера использования.

Часто задаваемые вопросы

Может ли этот API заменить долгосрочную историю энергопотребления?

Нет. API хранит до 96 записей, то есть 48 часов получасовых данных, в ОЗУ. Он предназначен для недавней локальной истории. Данные теряются после перезагрузки.

Почему `Datas` пуст после загрузки?

После загрузки модулю требуются корректное время UTC и корректные кадры данных счётчика, прежде чем выборки истории смогут быть записаны. Пока не будет получено достаточно корректных выборок, API может возвращать пустой массив Datas.

Основаны ли временные метки на местном времени?

Нет. Интервалы выборки выровнены по получасовым границам UTC.

Как ПО должно интерпретировать массив значений?

Всегда сначала читайте поле channels. Значения в каждом массиве Datas[].values следуют в том же порядке, что и имена каналов.