kWh 판독값을 위한 로컬 에너지 이력 API
title: kWh 판독값을 위한 로컬 에너지 이력 API
abstract: 30분 단위 kWh 이력을 로컬에서 읽어 오프라인으로 분석합니다.
language: ko
author: Jessica
소개
자체 대시보드, 자동화, 오프라인 분석 도구를 만드는 사용자에게는 실제 에너지 데이터가 안정적인 간격으로 제공될 때 더 유용합니다. 실시간 전력 판독값 하나는 지금 무슨 일이 일어나는지 보여 줄 뿐이지만, 30분 단위 kWh 이력은 시간에 따라 전력 수입(import)과 수출(export)이 어떻게 변하는지 이해하는 데 도움이 됩니다.
2026년 6월 2일에 출시된 펌웨어 버전 i.91.063TS8.bin부터 IAMMETER는 새로운 로컬 API인 GET /api/energyhistory를 지원합니다. 이 API는 UTC 30분 경계를 기준으로 샘플링되어 로컬에 캐시된 kWh 판독값을 반환하므로, 클라우드 측 이력에만 의존하지 않고 최근 에너지 사용량을 더 쉽게 분석할 수 있습니다.
이 기능은 특히 태양광 모니터링, 가정 에너지 모니터링, 사용자 지정 에너지 관리 워크플로에 유용합니다. 이런 환경에서는 수입, 수출, 상(phase)별 에너지 데이터를 비교하고자 하기 때문입니다. IAMMETER는 단순한 모니터가 아닙니다. 이 데이터를 수집하는 목적은 사용자가 에너지 사용을 최적화하고, 태양광 자가소비를 높이고, 전기 요금을 줄일 수 있도록 돕는 것입니다.
에너지 이력 API가 제공하는 것
새 엔드포인트는 다음과 같습니다:
GET /api/energyhistory
이 API는 kWh 단위의 에너지 판독값을 다음 UTC 30분 경계를 기준으로 샘플링하여 반환합니다:
00:0000:3001:0001:30- 등등
펌웨어는 최대 96개의 레코드를 보관하며, 이는 30분 간격으로 48시간의 이력에 해당합니다. 레코드는 Wi-Fi 모듈의 RAM에 저장되므로 기기가 재부팅되면 사라집니다.
일반적인 응답에는 다음이 포함됩니다:
utc: 현재 모듈 UTC 타임스탬프timeSynced: 모듈에 유효한 UTC 시간이 있는지 여부interval: 샘플링 간격, 현재1800초count: 사용 가능한 이력 레코드 수order: 현재newest_firstunit: 현재kWhchannels: 각 값에 대응하는 채널 이름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"]
순 계량(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": []
}
이 응답은 부팅 후 정상입니다. 로컬 대시보드나 스크립트는 이 상태를 처리하고 새로운 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 레코드를 로컬 데이터베이스에 저장하는 것입니다. 이를 통해 로컬 대시보드, 사용자 지정 리포트, 오프라인 분석 스크립트를 지원할 수 있습니다.
또 다른 유용한 시나리오는 태양광 자가소비 분석입니다. 30분 구간별 수입 및 수출 kWh 값을 비교하면, 가정 부하가 태양광 발전을 현지에서 소비하는 시점과 잉여 에너지가 수출되는 시점을 더 잘 파악할 수 있습니다. 이는 유연한 부하를 태양광 발전량이 많은 시간대로 옮기는 등 더 나은 자동화 결정을 뒷받침할 수 있습니다.
로컬 통합을 만드는 경우 로컬 API, Modbus/TCP 및 MQTT와 IAMMETER 로컬 API 탐색기도 참고하세요.
에너지 관리에서 이 기능의 위치
에너지 이력 API의 가치는 단순히 더 많은 데이터를 노출한다는 데 있지 않습니다. 핵심은 사용자가 그 데이터로 무엇을 할 수 있느냐입니다.
30분 단위 kWh 이력을 사용하면 최근 전력 수입과 수출을 분석하고, 사용 패턴을 파악하고, 태양광 또는 부하 제어 전략이 실제로 도움이 되는지 평가할 수 있습니다. 이는 에너지 모니터링 데이터를 에너지 효율을 높이고 전기 요금을 줄이는 실질적인 결정으로 전환한다는 IAMMETER의 더 큰 목표를 뒷받침합니다.
IAMMETER를 자동화 플랫폼과 함께 사용하는 경우, 로컬 에너지 이력은 제어 로직을 테스트하고 검증할 수 있는 편리한 데이터 계층을 제공할 수도 있습니다. 예를 들어 태양광 잉여 전력 사용을 최적화하는 Home Assistant 사용자는 최근 kWh 변화량을 자동화 동작과 함께 검토할 수 있습니다. 관련 사용 사례는 IAMMETER를 활용한 Home Assistant 태양광 에너지 자동화를 참고하세요.
FAQ
이 API가 장기 에너지 이력을 대체할 수 있나요?
아니요. 이 API는 최대 96개 레코드, 즉 30분 단위 데이터 48시간을 RAM에 저장합니다. 최근 로컬 이력을 위해 설계되었습니다. 데이터는 재부팅 후 사라집니다.
부팅 후 Datas가 비어 있는 이유는 무엇인가요?
부팅 후 모듈은 이력 샘플을 기록하기 전에 유효한 UTC 시간과 유효한 미터 프레임이 필요합니다. 충분한 유효 샘플이 수집될 때까지 API는 빈 Datas 배열을 반환할 수 있습니다.
타임스탬프가 현지 시간 기준인가요?
아니요. 샘플링 구간은 UTC 30분 경계에 맞춰져 있습니다.
소프트웨어가 values 배열을 어떻게 해석해야 하나요?
항상 channels 필드를 먼저 읽으세요. 각 Datas[].values 배열의 값은 채널 이름과 동일한 순서를 따릅니다.
