Локален API за история на енергията за отчитане в kWh

title: Локален API за история на енергията за отчитане в kWh

abstract: Четете 30-минутната kWh история локално за офлайн анализ.

language: bg

author: Jessica

Въведение

За потребителите, които изграждат собствени табла, автоматизации или инструменти за офлайн анализ, реалните данни за енергията са по-полезни, когато са налични на стабилен интервал. Едно единствено отчитане на мощността в реално време може да покаже какво се случва в момента, но 30-минутната kWh история помага на потребителите да разберат как вносът и износът на електроенергия се променят във времето.

Започвайки от версия на фърмуера i.91.063TS8.bin, публикувана на 2 юни 2026 г., IAMMETER поддържа нов локален API: GET /api/energyhistory. Този API връща локално кеширани kWh отчитания, взети около 30-минутните граници по UTC, което улеснява анализа на скорошното потребление на енергия, без да се разчита само на историята от страната на облака.

Това е особено полезно за мониторинг на слънчева енергия, мониторинг на битова енергия и персонализирани работни процеси за управление на енергията, при които потребителите искат да сравняват данни за внос, износ и енергия по фази. IAMMETER не е само измервателен уред; целта на събирането на тези данни е да помогне на потребителите да оптимизират използването на енергия, да подобрят собственото потребление на слънчева енергия и да намалят сметките за електроенергия.

Какво предоставя API за история на енергията

Новата крайна точка е:

GET /api/energyhistory

Той връща отчитания на енергията в kWh, взети около следните 30-минутни граници по UTC:

00:00
00:30
01:00
01:30
и така нататък

Фърмуерът съхранява до 96 записа, което се равнява на 48 часа история с 30-минутни интервали. Записите се съхраняват в RAM паметта на Wi-Fi модула, така че се губят след рестартиране на устройството.

Типичният отговор включва:

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

Всеки елемент в Datas включва UTC времеви отпечатък и масив от kWh стойности. Стойностите следват същия ред като масива channels.

Защо 30-минутната kWh история е важна

30-минутните данни за енергията са практични, защото дават на потребителите компактен, но смислен поглед върху енергийното поведение. Вместо да съхраняват всяка точка в реално време, потребителите могат да анализират натрупаните стойности за внос и износ за фиксирани времеви интервали.

Например потребителят може да използва локалните данни, за да:

Прегледа скорошната внесена и изнесена енергия, без да чака отчети от облака.
Експортира последните 48 часа kWh отчитания в локална база данни или 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"]

Трифазен с активирано нетно измерване

["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": []
}

Този отговор е нормален след стартиране. Локално табло или скрипт трябва да обработва това състояние и да изчака нови 30-минутни проби.

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

Следващият пример показва два 30-минутни записа от трифазен измервателен уред. Отговорът е подреден от най-новия към най-стария.

{
  "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
}

Това улеснява съхраняването, показването или експортирането на данните към локален инструмент за анализ.

Изчисляване на 30-минутната промяна в kWh

Ако използвате върнатите kWh стойности като натрупани отчитания на енергията, промяната между два съседни записа може да се изчисли, като извадите по-старата стойност от по-новата за същия канал.

Използвайки трифазния пример по-горе:

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

Такова изчисление може да помогне на потребителите да създадат отчет за скорошен внос/износ, да сравнят промените в енергията по фази или да проверят колко енергия е внесена или изнесена през конкретен 30-минутен интервал.

Важно поведение при вземане на проби

Историята на енергията се генерира локално от Wi-Fi модула. Поведението при вземане на проби е важно при изграждането на интеграции или инструменти за анализ:

Вземането на проби се задвижва от валидни UART кадри от измервателния уред.
Модулът съхранява пробата, най-близка до всяка 30-минутна граница по UTC.
UTC времето трябва да е валидно, преди да се съхраняват исторически записи.
Ако timeSynced е 0, не се записват нови исторически проби.
След стартиране Datas може да е празен, докато не бъдат уловени достатъчно валидни проби.
Текущото съхранение е базирано на RAM, така че API е предназначен за скорошна локална история, а не за дългосрочно съхранение.

Това прави API подходящ за локално периодично запитване, краткосрочен анализ и тестване на интеграции. За дългосрочни отчети за енергията потребителите все още трябва да поддържат постоянен източник на данни, като данните в облака на IAMMETER или собствена база данни.

Примерни идеи за интеграции

Разработчиците и напредналите потребители могат да използват /api/energyhistory като прост локален източник на данни за скорошна kWh история.

Често срещан подход е периодично да се запитва крайната точка, да се прочете списъкът channels и всеки нов запис от Datas да се запази в локална база данни. Това може да поддържа локални табла, персонализирани отчети или скриптове за офлайн анализ.

Друг полезен сценарий е анализът на собственото потребление на слънчева енергия. Чрез сравняване на внесените и изнесените kWh стойности по 30-минутни интервали потребителите могат да разберат по-добре кога домакинските товари консумират слънчевата генерация локално и кога излишната енергия се изнася. Това може да подпомогне по-добри решения за автоматизация, като например преместване на гъвкави товари към периоди с по-висока слънчева продукция.

Ако изграждате локални интеграции, вижте също Локален API, Modbus/TCP и MQTT и IAMMETER Local API Explorer.

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

Стойността на един API за история на енергията не е само в това, че предоставя повече данни. Ключовият момент е какво могат да правят потребителите с тези данни.

С 30-минутна kWh история потребителите могат да анализират скорошния внос и износ на електроенергия, да идентифицират модели на потребление и да преценят дали стратегиите за слънчева енергия или за управление на товарите действително помагат. Това подкрепя по-широката цел на IAMMETER: превръщането на данните от мониторинга на енергията в практични решения, които подобряват енергийната ефективност и намаляват сметките за електроенергия.

За потребителите, които комбинират IAMMETER с платформи за автоматизация, локалната история на енергията може също да осигури удобен слой от данни за тестване и валидиране на логиката за управление. Например потребителите на Home Assistant, които оптимизират използването на излишъка от слънчева енергия, могат да прегледат скорошните промени в kWh заедно с поведението на автоматизацията. Вижте Автоматизация на слънчева енергия с Home Assistant и IAMMETER за свързан случай на употреба.

ЧЗВ

Може ли този API да замени дългосрочната история на енергията?

Не. API съхранява до 96 записа, или 48 часа 30-минутни данни, в RAM. Той е предназначен за скорошна локална история. Данните се губят след рестартиране.

Защо `Datas` е празен след стартиране?

След стартиране модулът се нуждае от валидно UTC време и валидни кадри от измервателния уред, преди да могат да се записват исторически проби. Докато не бъдат уловени достатъчно валидни проби, API може да върне празен масив Datas.

Базирани ли са времевите отпечатъци на местното време?

Не. Интервалите за вземане на проби са подравнени към 30-минутните граници по UTC.

Как софтуерът трябва да интерпретира масива със стойности?

Винаги първо прочитайте полето channels. Стойностите във всеки масив Datas[].values следват същия ред като имената на каналите.