homebridge-enertalk-km81 1.0.0

package/LICENSE

@@ -0,0 +1,28 @@
+MIT License
+
+Copyright (c) 2026 Km81
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Portions of this software are derived from:
+  - homebridge-xiaomi-fan (Marcin, MIT)         — fan device implementations
+  - homebridge-miot (merdok, MIT)               — miio low-level protocol
+  - homebridge-mi-humidifier (nt0xa, MIT)       — humidifier model definitions

package/README.md

@@ -0,0 +1,83 @@
+# homebridge-enertalk-km81
+
+EnerTalk(Encored) 전력 미터를 Homebridge/HomeKit 으로 노출하는 플러그인.
+
+에너톡 제조사 앱은 앱스토어에서 내려갔고 개발자 포털(developer.enertalk.com)도 폐쇄됐지만,
+기기는 여전히 클라우드로 실시간 데이터를 올리고 있고 `api2.enertalk.com` / `auth2.enertalk.com`
+은 살아있습니다. 이 플러그인은 **에너톡 앱 로그인 이메일/비밀번호**만으로 토큰을 발급받아
+데이터를 가져옵니다. (별도 개발자 등록 불필요)
+
+> 참고: 에너톡 앱 화면에서 사용량이 0 으로만 보이더라도, 그건 앱의 유료 "베이직 서비스"
+> 구독이 만료돼 **앱 UI 만** 가려진 것입니다. 원시 API 는 실시간 값을 그대로 내려줍니다.
+
+## 노출되는 값
+
+기본은 **Outlet 서비스 + Eve 커스텀 특성**으로 노출됩니다. **Eve 앱**에서 확인하세요.
+
+| 특성 | 의미 | 원시 필드 |
+|---|---|---|
+| Consumption (W) | 실시간 소비전력 | `activePower` /1000 |
+| Total Consumption (kWh) | 당월 누적(검침일 기준) | `usage` /1e6 |
+| Voltage (V) | 전압 | `voltage` /1000 |
+| Electric Current (A) | 전류 | `current` /1000 |
+
+Eve 앱은 실시간 W 를 자동으로 히스토리 그래프로 쌓아줍니다.
+
+### Apple '홈' 앱에서 숫자를 보고 싶다면
+
+홈킷에는 전력 표준 특성이 없어 Apple 기본 '홈' 앱은 위 값을 숫자로 못 보여줍니다.
+`exposeLightSensors` 를 켜면 **조도센서(lux) 트릭**으로 실시간 W 와 당월 kWh 를 추가 노출해
+홈 앱 기본화면에서 숫자를 볼 수 있습니다 (단위는 lux 로 표시됨).
+
+## 설치
+
+```bash
+npm install -g homebridge-enertalk-km81
+```
+
+(이 저장소 서브폴더에서 직접 쓰는 경우: `npm install -g ./homebridge-enertalk-km81`)
+
+## 설정
+
+Homebridge UI 의 플러그인 설정 화면(`EnerTalkKm81`)에서 이메일/비밀번호를 입력하거나,
+`config.json` 의 `platforms` 에 아래를 추가합니다.
+
+```json
+{
+  "platform": "EnerTalkKm81",
+  "name": "EnerTalk",
+  "email": "you@example.com",
+  "password": "your-enertalk-password",
+  "pollingInterval": 30,
+  "billingInterval": 300,
+  "exposeLightSensors": false
+}
+```
+
+| 항목 | 기본 | 설명 |
+|---|---|---|
+| `email` / `password` | (필수) | 에너톡 앱 로그인 자격증명 |
+| `pollingInterval` | 30 | 실시간 W 조회 주기(초) |
+| `billingInterval` | 300 | 당월 누적 kWh/요금 조회 주기(초) |
+| `exposeLightSensors` | false | 홈 앱용 조도센서 미러 노출 |
+| `clientId` / `clientSecret` | (선택) | 비우면 앱 기본값 사용 |
+
+계정에 연결된 site 가 여러 개면 각각 액세서리로 등록됩니다.
+
+## 동작 방식
+
+1. `POST https://auth2.enertalk.com/token` — `grant_type=password` 로 access_token 발급
+   (만료 시 자동 재발급, 401 시 1회 재로그인).
+2. `GET https://api2.enertalk.com/sites` — site 목록.
+3. 주기적으로 `/sites/{id}/usages/realtime` (실시간) 과 `/usages/billing` (당월 누적) 폴링.
+
+## 보안 메모
+
+- 플러그인이 사용하는 client_id/secret 은 에너톡 앱(APK)에 공개적으로 포함된 값이라
+  노출돼도 계정 위험과 무관합니다.
+- 다만 **에너톡 계정 비밀번호**는 `config.json` 에 평문 저장되니, Homebridge 호스트
+  접근 권한을 신뢰할 수 있는 환경에서만 사용하세요.
+
+## 라이선스
+
+MIT

package/config.schema.json

@@ -0,0 +1,77 @@
+{
+  "pluginAlias": "EnerTalkKm81",
+  "pluginType": "platform",
+  "singular": true,
+  "customUi": true,
+  "headerDisplay": "EnerTalk(Encored) 전력 미터를 HomeKit 으로 노출합니다. 에너톡 앱 로그인 이메일/비밀번호만 있으면 됩니다. 실시간 소비전력(W)과 당월 누적 사용량(kWh)은 **Eve 앱**에서 그래프까지 확인할 수 있고, 홈 앱 기본화면에서 숫자를 보고 싶으면 아래 '조도센서 노출'을 켜세요.",
+  "footerDisplay": "developer.enertalk.com 이 폐쇄돼도 auth2/api2 는 동작합니다. client_id/secret 은 비워두면 앱 기본값을 사용합니다.",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "name": {
+        "title": "액세서리 이름",
+        "type": "string",
+        "default": "EnerTalk",
+        "description": "비워두면 site 이름(예: F3000DB8)을 사용합니다."
+      },
+      "email": {
+        "title": "에너톡 이메일",
+        "type": "string",
+        "required": true,
+        "format": "email"
+      },
+      "password": {
+        "title": "에너톡 비밀번호",
+        "type": "string",
+        "required": true,
+        "x-schema-form": { "type": "password" }
+      },
+      "pollingInterval": {
+        "title": "실시간 폴링 주기(초)",
+        "type": "integer",
+        "default": 30,
+        "minimum": 10,
+        "maximum": 3600,
+        "description": "실시간 소비전력(W) 조회 주기. 너무 짧게 두지 마세요(권장 30초)."
+      },
+      "billingInterval": {
+        "title": "당월 사용량 폴링 주기(초)",
+        "type": "integer",
+        "default": 300,
+        "minimum": 60,
+        "maximum": 86400,
+        "description": "당월 누적 사용량(kWh)/요금 조회 주기(권장 300초)."
+      },
+      "exposeLightSensors": {
+        "title": "조도센서(lux) 미러 노출 — 홈 앱 기본화면용",
+        "type": "boolean",
+        "default": false,
+        "description": "켜면 실시간 W 와 당월 kWh 를 조도센서 값(lux)으로도 노출해 Apple '홈' 앱에서 숫자를 볼 수 있습니다. Eve 앱만 쓰면 꺼두어도 됩니다."
+      },
+      "clientId": {
+        "title": "client_id (고급, 선택)",
+        "type": "string",
+        "description": "비워두면 앱 기본 client_id 사용."
+      },
+      "clientSecret": {
+        "title": "client_secret (고급, 선택)",
+        "type": "string",
+        "x-schema-form": { "type": "password" },
+        "description": "비워두면 앱 기본 client_secret 사용."
+      }
+    },
+    "required": ["email", "password"]
+  },
+  "layout": [
+    "name",
+    "email",
+    "password",
+    {
+      "type": "fieldset",
+      "title": "고급 설정",
+      "expandable": true,
+      "expanded": false,
+      "items": ["pollingInterval", "billingInterval", "exposeLightSensors", "clientId", "clientSecret"]
+    }
+  ]
+}

package/homebridge-ui/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/homebridge-ui/public/index.html

@@ -0,0 +1,81 @@
+<!DOCTYPE html>
+<html lang="ko">
+<head>
+  <meta charset="utf-8">
+  <style>
+    .et-card { border: 1px solid #d9dde2; border-radius: 10px; padding: 14px 16px; margin-bottom: 16px; }
+    .et-title { font-weight: 600; margin-bottom: 6px; }
+    .et-sub { color: #6c757d; font-size: 0.83rem; line-height: 1.5; margin: 0 0 12px 0; }
+    .et-result { margin-top: 12px; padding: 10px 12px; border-radius: 8px; font-size: 0.88rem; line-height: 1.5; display: none; }
+    .et-result.show { display: block; }
+    .et-result.ok   { background: #e6f4ea; color: #1e7e34; border: 1px solid #bfe3c9; }
+    .et-result.none { background: #fdecea; color: #b02a37; border: 1px solid #f3c4c0; }
+    .et-result.wait { background: #fff6e5; color: #946200; border: 1px solid #f0dcb0; }
+  </style>
+</head>
+<body>
+  <div class="et-card">
+    <div class="et-title">EnerTalk 연결 테스트</div>
+    <p class="et-sub">
+      아래 폼에 <b>에너톡 앱 이메일/비밀번호</b>를 입력한 뒤 <b>연결 테스트</b>를 누르면,
+      로그인·사이트 조회·현재 실시간값(W/V/A)·당월 누적(kWh)을 저장 전에 바로 확인합니다.
+      <br>사용하는 client_id/secret 은 앱 공개값이라 비워두면 됩니다.
+    </p>
+    <button id="etTestBtn" class="btn btn-primary btn-sm" type="button">연결 테스트 / 사이트 조회</button>
+    <div id="etResult" class="et-result"></div>
+  </div>
+
+  <script>
+    (async () => {
+      // 표준 설정 폼(이메일/비밀번호/주기 등)을 그대로 렌더링
+      homebridge.showSchemaForm();
+
+      const resultEl = document.getElementById('etResult');
+      const setResult = (cls, html) => {
+        resultEl.className = 'et-result show ' + cls;
+        resultEl.innerHTML = html;
+      };
+
+      document.getElementById('etTestBtn').addEventListener('click', async () => {
+        const cfgs = await homebridge.getPluginConfig();
+        const c = (cfgs && cfgs[0]) || {};
+        if (!c.email || !c.password) {
+          setResult('none', '먼저 위 폼에 이메일/비밀번호를 입력하세요.');
+          return;
+        }
+        homebridge.showSpinner();
+        setResult('wait', '로그인 및 조회 중…');
+        try {
+          const r = await homebridge.request('/test', {
+            email: c.email,
+            password: c.password,
+            clientId: c.clientId,
+            clientSecret: c.clientSecret,
+          });
+          if (!r || !r.ok) {
+            setResult('none', '실패: ' + ((r && r.error) || '알 수 없는 오류'));
+          } else {
+            let html = '<b>연결 성공 ✓</b><br>사이트 ' + r.sites.length + '개';
+            if (r.sites.length) {
+              html += ': ' + r.sites.map((s) => s.name + ' (' + String(s.id).slice(0, 8) + '…)').join(', ');
+            }
+            if (r.realtime) {
+              html += '<br>실시간: <b>' + r.realtime.watts + ' W</b> / ' + r.realtime.volts + ' V / ' + r.realtime.amps + ' A';
+            }
+            if (r.billing) {
+              html += '<br>당월 누적: <b>' + r.billing.kwh + ' kWh</b>'
+                + (r.billing.charge != null ? (' / ' + r.billing.charge + '원') : '');
+            }
+            setResult('ok', html);
+            homebridge.toast.success('EnerTalk 연결 성공');
+          }
+        } catch (e) {
+          setResult('none', '오류: ' + (e && e.message ? e.message : e));
+        } finally {
+          homebridge.hideSpinner();
+        }
+      });
+    })();
+  </script>
+</body>
+</html>

package/homebridge-ui/server.js

@@ -0,0 +1,72 @@
+/*
+ * Homebridge Custom UI 서버 (ESM).
+ *
+ * 설정 화면에서 '연결 테스트' 버튼을 누르면, 입력한 이메일/비밀번호로 EnerTalk 클라우드에
+ * 로그인해 site 목록과 현재 실시간값/당월 누적을 조회해 돌려준다. 실제 인증이 되는지,
+ * 어느 site 가 잡히는지 저장 전에 바로 확인할 수 있다.
+ *
+ * @homebridge/plugin-ui-utils v2 는 ESM 전용이라 이 파일도 ESM 으로 작성한다
+ * (homebridge-ui/package.json 의 "type":"module"). 본체 플러그인(index.js/lib)은
+ * CommonJS 이며 createRequire 로 지연 로드한다.
+ */
+
+import { HomebridgePluginUiServer } from '@homebridge/plugin-ui-utils';
+import { createRequire } from 'module';
+
+const require = createRequire(import.meta.url);
+
+function round(n, d) {
+  const f = Math.pow(10, d);
+  return Math.round(Number(n || 0) * f) / f;
+}
+
+class UiServer extends HomebridgePluginUiServer {
+  constructor() {
+    super();
+    this.onRequest('/test', this.handleTest.bind(this));
+    this.ready();
+  }
+
+  async handleTest(payload) {
+    const EnerTalkApi = require('../lib/EnerTalkApi.js');
+    const { email, password, clientId, clientSecret } = payload || {};
+    if (!email || !password) {
+      return { ok: false, error: '이메일과 비밀번호를 입력하세요.' };
+    }
+    try {
+      const client = new EnerTalkApi({ email, password, clientId, clientSecret });
+      await client.login();
+
+      const sitesRaw = await client.getSites();
+      const sites = Array.isArray(sitesRaw)
+        ? sitesRaw.map((s) => ({ id: s.id, name: s.name || s.id }))
+        : [];
+
+      let realtime = null;
+      let billing = null;
+      if (sites.length) {
+        try {
+          const rt = await client.getRealtime(sites[0].id);
+          realtime = {
+            watts: round(EnerTalkApi.toWatts(rt.activePower), 1),
+            volts: round(EnerTalkApi.toVolts(rt.voltage), 1),
+            amps: round(EnerTalkApi.toAmps(rt.current), 2),
+          };
+        } catch (e) { /* 실시간 실패는 치명적이지 않음 */ }
+        try {
+          const b = await client.getBilling(sites[0].id);
+          billing = {
+            kwh: round(EnerTalkApi.toKwh(b.usage), 2),
+            charge: b && b.bill ? b.bill.charge : null,
+          };
+        } catch (e) { /* billing 실패도 무시 */ }
+      }
+
+      return { ok: true, sites, realtime, billing };
+    } catch (e) {
+      return { ok: false, error: e && e.message ? e.message : String(e) };
+    }
+  }
+}
+
+(() => new UiServer())();

package/index.js

@@ -0,0 +1,254 @@
+/**
+ * homebridge-enertalk-km81
+ *
+ * EnerTalk(Encored) 전력 미터를 Homebridge/HomeKit 으로 노출한다.
+ * 제조사 앱/개발자포털이 사실상 종료됐지만, 기기는 여전히 클라우드로 실시간 업로드 중이고
+ * api2.enertalk.com 이 살아있어, 앱 번들의 공개 client 자격증명 + password grant 로
+ * 이메일/비밀번호만으로 데이터를 끌어온다.
+ *
+ * 노출 방식:
+ *  - 기본: Outlet 서비스 + Eve 커스텀 특성
+ *      · Consumption(W)       = 실시간 소비전력
+ *      · Total Consumption(kWh)= 당월 누적(검침일 기준)
+ *      · Voltage(V) / Electric Current(A)
+ *    → Eve 앱에서 실시간 W + 전력량 그래프까지 보인다.
+ *  - 옵션(exposeLightSensors): Apple '홈' 앱 기본 화면에서 숫자를 보고 싶을 때
+ *      조도센서(lux) 트릭으로 실시간 W / 당월 kWh 를 추가 노출한다.
+ */
+
+'use strict';
+
+const packageJson = require('./package.json');
+const EnerTalkApi = require('./lib/EnerTalkApi.js');
+const buildEveCharacteristics = require('./lib/EveCharacteristics.js');
+
+const PLUGIN_NAME = packageJson.name;      // homebridge-enertalk-km81
+const PLATFORM_NAME = 'EnerTalkKm81';      // config.schema.json 의 pluginAlias
+
+module.exports = (homebridge) => {
+  homebridge.registerPlatform(PLUGIN_NAME, PLATFORM_NAME, EnerTalkPlatform, true /* dynamic */);
+};
+
+class EnerTalkPlatform {
+  constructor(log, config, api) {
+    this.log = log;
+    this.config = config || {};
+    this.api = api;
+    this.hap = api.hap;
+    this.accessories = new Map(); // uuid -> PlatformAccessory (캐시 복원본)
+    this.contexts = new Map();    // uuid -> { services..., timers } 런타임 상태
+
+    this.Eve = buildEveCharacteristics(this.hap);
+
+    // 설정값
+    this.pollingInterval = Math.max(10, Number(this.config.pollingInterval) || 30); // 초, 실시간
+    this.billingInterval = Math.max(60, Number(this.config.billingInterval) || 300); // 초, 당월 누적
+    this.exposeLightSensors = this.config.exposeLightSensors === true;
+
+    if (!this.config.email || !this.config.password) {
+      this.log.error('[EnerTalk] config 에 email/password 가 없습니다. 플러그인을 시작하지 않습니다.');
+      this.enabled = false;
+    } else {
+      this.enabled = true;
+      this.client = new EnerTalkApi({
+        email: this.config.email,
+        password: this.config.password,
+        clientId: this.config.clientId,
+        clientSecret: this.config.clientSecret,
+        log: this.log,
+      });
+    }
+
+    if (this.api) {
+      this.api.on('didFinishLaunching', () => this._start().catch((e) => {
+        this.log.error('[EnerTalk] 시작 실패:', e && e.message ? e.message : e);
+      }));
+      this.api.on('shutdown', () => this._stopAllTimers());
+    }
+  }
+
+  /** Homebridge 가 캐시된 액세서리를 복원할 때 호출 */
+  configureAccessory(accessory) {
+    this.accessories.set(accessory.UUID, accessory);
+  }
+
+  async _start() {
+    if (!this.enabled) return;
+
+    let sites;
+    try {
+      sites = await this.client.getSites();
+    } catch (e) {
+      this.log.error('[EnerTalk] site 목록 조회 실패 — 이메일/비밀번호를 확인하세요:', e.message);
+      return;
+    }
+    if (!Array.isArray(sites) || sites.length === 0) {
+      this.log.error('[EnerTalk] 연결된 site 가 없습니다.');
+      return;
+    }
+
+    const seen = new Set();
+    for (const site of sites) {
+      if (!site || !site.id) continue;
+      const label = this.config.name || site.name || site.id;
+      const uuid = this.api.hap.uuid.generate(`${PLUGIN_NAME}:${site.id}`);
+      seen.add(uuid);
+      this._setupSiteAccessory(uuid, site, label);
+    }
+
+    // config 에서 사라졌거나 계정에 없는 캐시 액세서리 정리
+    for (const [uuid, acc] of this.accessories) {
+      if (!seen.has(uuid)) {
+        this.log.info('[EnerTalk] 사용하지 않는 액세서리 제거:', acc.displayName);
+        this.api.unregisterPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, [acc]);
+        this.accessories.delete(uuid);
+      }
+    }
+  }
+
+  _setupSiteAccessory(uuid, site, label) {
+    const { Service, Characteristic } = this.hap;
+    let accessory = this.accessories.get(uuid);
+    const isNew = !accessory;
+
+    if (isNew) {
+      accessory = new this.api.platformAccessory(label, uuid);
+      this.accessories.set(uuid, accessory);
+    }
+    accessory.context.siteId = site.id;
+
+    // AccessoryInformation
+    const info = accessory.getService(Service.AccessoryInformation)
+      || accessory.addService(Service.AccessoryInformation);
+    info
+      .setCharacteristic(Characteristic.Manufacturer, 'Encored / EnerTalk')
+      .setCharacteristic(Characteristic.Model, 'EnerTalk Energy Meter')
+      .setCharacteristic(Characteristic.SerialNumber, String(site.id).slice(0, 16))
+      .setCharacteristic(Characteristic.FirmwareRevision, packageJson.version);
+
+    // ── 메인: Outlet + Eve 특성 ────────────────────────────────
+    const outlet = accessory.getService(Service.Outlet)
+      || accessory.addService(Service.Outlet, label);
+    outlet.setCharacteristic(Characteristic.Name, label);
+    // 상시 ON/사용중으로 고정 (전력 미터는 스위치가 아님)
+    outlet.getCharacteristic(Characteristic.On)
+      .onGet(() => true)
+      .onSet(() => { /* 스위치 아님 — 무시하고 항상 ON 유지 */ });
+    outlet.updateCharacteristic(Characteristic.On, true);
+    this._ensureCharacteristic(outlet, Characteristic.OutletInUse).onGet(() => true);
+    outlet.updateCharacteristic(Characteristic.OutletInUse, true);
+    this._ensureCharacteristic(outlet, this.Eve.CurrentConsumption);
+    this._ensureCharacteristic(outlet, this.Eve.TotalConsumption);
+    this._ensureCharacteristic(outlet, this.Eve.Voltage);
+    this._ensureCharacteristic(outlet, this.Eve.ElectricCurrent);
+
+    // ── 옵션: 홈 앱 기본화면용 조도센서(lux) 미러 ──────────────
+    let powerLux = null;
+    let usageLux = null;
+    if (this.exposeLightSensors) {
+      powerLux = accessory.getServiceById(Service.LightSensor, 'power')
+        || accessory.addService(Service.LightSensor, `${label} 실시간전력`, 'power');
+      powerLux.setCharacteristic(Characteristic.Name, `${label} 실시간전력(W)`);
+
+      usageLux = accessory.getServiceById(Service.LightSensor, 'usage')
+        || accessory.addService(Service.LightSensor, `${label} 당월사용량`, 'usage');
+      usageLux.setCharacteristic(Characteristic.Name, `${label} 당월사용량(kWh)`);
+    } else {
+      // 옵션 껐을 때 이전에 만든 조도센서 제거
+      for (const sid of ['power', 'usage']) {
+        const s = accessory.getServiceById(Service.LightSensor, sid);
+        if (s) accessory.removeService(s);
+      }
+    }
+
+    if (isNew) {
+      this.api.registerPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, [accessory]);
+      this.log.info('[EnerTalk] 액세서리 등록:', label);
+    } else {
+      this.log.info('[EnerTalk] 액세서리 복원:', label);
+    }
+
+    // 런타임 컨텍스트 + 폴링 시작
+    this._stopTimers(uuid);
+    const ctx = { accessory, site, outlet, powerLux, usageLux, timers: [] };
+    this.contexts.set(uuid, ctx);
+
+    const pollRealtime = () => this._pollRealtime(uuid).catch((e) =>
+      this.log.debug('[EnerTalk] realtime 폴링 오류:', e.message));
+    const pollBilling = () => this._pollBilling(uuid).catch((e) =>
+      this.log.debug('[EnerTalk] billing 폴링 오류:', e.message));
+
+    pollRealtime();
+    pollBilling();
+    ctx.timers.push(setInterval(pollRealtime, this.pollingInterval * 1000));
+    ctx.timers.push(setInterval(pollBilling, this.billingInterval * 1000));
+  }
+
+  _ensureCharacteristic(service, Ctor) {
+    if (!service.testCharacteristic(Ctor)) {
+      service.addCharacteristic(Ctor);
+    }
+    return service.getCharacteristic(Ctor);
+  }
+
+  async _pollRealtime(uuid) {
+    const ctx = this.contexts.get(uuid);
+    if (!ctx) return;
+    const data = await this.client.getRealtime(ctx.site.id);
+
+    const watts = EnerTalkApi.toWatts(data.activePower);
+    const volts = EnerTalkApi.toVolts(data.voltage);
+    const amps = EnerTalkApi.toAmps(data.current);
+
+    ctx.outlet.getCharacteristic(this.Eve.CurrentConsumption).updateValue(round(watts, 1));
+    ctx.outlet.getCharacteristic(this.Eve.Voltage).updateValue(round(volts, 1));
+    ctx.outlet.getCharacteristic(this.Eve.ElectricCurrent).updateValue(round(amps, 2));
+
+    if (ctx.powerLux) {
+      ctx.powerLux.getCharacteristic(this.hap.Characteristic.CurrentAmbientLightLevel)
+        .updateValue(clampLux(watts));
+    }
+    this.log.debug(`[EnerTalk] realtime: ${round(watts, 1)}W / ${round(volts, 1)}V / ${round(amps, 2)}A`);
+  }
+
+  async _pollBilling(uuid) {
+    const ctx = this.contexts.get(uuid);
+    if (!ctx) return;
+    const data = await this.client.getBilling(ctx.site.id);
+
+    const kwh = EnerTalkApi.toKwh(data.usage);
+    ctx.outlet.getCharacteristic(this.Eve.TotalConsumption).updateValue(round(kwh, 3));
+
+    if (ctx.usageLux) {
+      ctx.usageLux.getCharacteristic(this.hap.Characteristic.CurrentAmbientLightLevel)
+        .updateValue(clampLux(kwh));
+    }
+    const charge = data && data.bill && data.bill.charge != null ? `${data.bill.charge}원` : 'n/a';
+    this.log.debug(`[EnerTalk] billing: ${round(kwh, 2)}kWh / ${charge}`);
+  }
+
+  _stopTimers(uuid) {
+    const ctx = this.contexts.get(uuid);
+    if (ctx && ctx.timers) {
+      for (const t of ctx.timers) clearInterval(t);
+      ctx.timers = [];
+    }
+  }
+
+  _stopAllTimers() {
+    for (const uuid of this.contexts.keys()) this._stopTimers(uuid);
+  }
+}
+
+function round(n, digits) {
+  const f = Math.pow(10, digits);
+  return Math.round(Number(n || 0) * f) / f;
+}
+
+/** 조도센서 특성은 0.0001~100000 lux 범위. W/kWh 를 그 안으로 클램프. */
+function clampLux(v) {
+  const x = Number(v || 0);
+  if (x < 0.0001) return 0.0001;
+  if (x > 100000) return 100000;
+  return round(x, 4);
+}

package/lib/EnerTalkApi.js

@@ -0,0 +1,149 @@
+'use strict';
+
+/**
+ * EnerTalk cloud API client.
+ *
+ * 인증은 앱(kr.encored.enertalk) 번들에 박혀 있는 공개 client 자격증명 + password grant 를
+ * 그대로 사용한다. 개발자 포털(developer.enertalk.com)이 폐쇄됐어도 auth2/api2 는 살아있어
+ * 이메일/비밀번호만으로 access_token 을 발급받을 수 있다.
+ *
+ *   POST https://auth2.enertalk.com/token
+ *     Authorization: Basic base64(clientId:clientSecret)
+ *     { "grant_type": "password", "credentials": { "email", "password" } }
+ *
+ * 데이터:
+ *   GET https://api2.enertalk.com/sites
+ *   GET https://api2.enertalk.com/sites/{siteId}/usages/realtime   (accept-version: 2.0.0)
+ *   GET https://api2.enertalk.com/sites/{siteId}/usages/billing    (accept-version: 2.0.0)
+ *
+ * 원시 값 단위(실측 확인):
+ *   activePower / billingActivePower : mW   → W  = /1000
+ *   voltage                          : mV   → V  = /1000
+ *   current                          : mA   → A  = /1000
+ *   billing.usage / positiveEnergy   : mWh  → kWh= /1e6
+ *   bill.charge                      : KRW (원, 정수)
+ */
+
+const DEFAULT_CLIENT_ID = 'a29hbnNhbmdAZ21haWwuY29tX0VuZXJ0YWxrS3I=';
+const DEFAULT_CLIENT_SECRET = 'ak1bb5bh00s48d8hz5zw9r882b5bf36y34x6mk1';
+const AUTH_BASE = 'https://auth2.enertalk.com';
+const API_BASE = 'https://api2.enertalk.com';
+
+class EnerTalkApi {
+  constructor({ email, password, clientId, clientSecret, log } = {}) {
+    if (!email || !password) {
+      throw new Error('EnerTalkApi: email 과 password 는 필수입니다.');
+    }
+    this.email = email;
+    this.password = password;
+    this.clientId = clientId || DEFAULT_CLIENT_ID;
+    this.clientSecret = clientSecret || DEFAULT_CLIENT_SECRET;
+    this.log = log || console;
+
+    this.accessToken = null;
+    this.refreshToken = null;
+    this.expiresAt = 0;
+    this._authPromise = null;
+  }
+
+  _basicAuth() {
+    return 'Basic ' + Buffer.from(`${this.clientId}:${this.clientSecret}`).toString('base64');
+  }
+
+  async _fetch(url, opts = {}, timeoutMs = 15000) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+      return await fetch(url, { ...opts, signal: ctrl.signal });
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  /** password grant 로 새 토큰 발급. 동시 호출은 하나로 합친다. */
+  async login() {
+    if (this._authPromise) return this._authPromise;
+    this._authPromise = (async () => {
+      const res = await this._fetch(`${AUTH_BASE}/token`, {
+        method: 'POST',
+        headers: {
+          'Authorization': this._basicAuth(),
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          grant_type: 'password',
+          credentials: { email: this.email, password: this.password },
+        }),
+      });
+      if (!res.ok) {
+        const text = await res.text().catch(() => '');
+        throw new Error(`EnerTalk 로그인 실패: HTTP ${res.status} ${text}`.trim());
+      }
+      const data = await res.json();
+      if (!data || !data.access_token) {
+        throw new Error('EnerTalk 로그인 응답에 access_token 이 없습니다.');
+      }
+      this.accessToken = data.access_token;
+      this.refreshToken = data.refresh_token || null;
+      const expiresIn = Number(data.expires_in) || 3600;
+      // 만료 60초 전에는 갱신하도록 여유를 둔다.
+      this.expiresAt = Date.now() + Math.max(60, expiresIn - 60) * 1000;
+      return data;
+    })().finally(() => { this._authPromise = null; });
+    return this._authPromise;
+  }
+
+  async _ensureToken() {
+    if (!this.accessToken || Date.now() >= this.expiresAt) {
+      await this.login();
+    }
+  }
+
+  async _apiGet(path) {
+    await this._ensureToken();
+    const doRequest = () => this._fetch(`${API_BASE}${path}`, {
+      headers: {
+        'Authorization': `Bearer ${this.accessToken}`,
+        'accept-version': '2.0.0',
+      },
+    });
+
+    let res = await doRequest();
+    if (res.status === 401) {
+      // 토큰 만료/무효 → 재로그인 후 1회 재시도
+      await this.login();
+      res = await doRequest();
+    }
+    if (!res.ok) {
+      const text = await res.text().catch(() => '');
+      throw new Error(`EnerTalk API ${path} 실패: HTTP ${res.status} ${text}`.trim());
+    }
+    return res.json();
+  }
+
+  /** 계정에 연결된 site 목록. [{ id, name, ... }] */
+  getSites() {
+    return this._apiGet('/sites');
+  }
+
+  /** 실시간 사용량(원시 단위). */
+  getRealtime(siteId) {
+    return this._apiGet(`/sites/${encodeURIComponent(siteId)}/usages/realtime`);
+  }
+
+  /** 검침일 기준 당월 누적 사용량 + 요금. */
+  getBilling(siteId) {
+    return this._apiGet(`/sites/${encodeURIComponent(siteId)}/usages/billing`);
+  }
+
+  // ── 단위 변환 헬퍼 ───────────────────────────────────────────────
+  static toWatts(raw) { return Number(raw || 0) / 1000; }
+  static toVolts(raw) { return Number(raw || 0) / 1000; }
+  static toAmps(raw) { return Number(raw || 0) / 1000; }
+  static toKwh(rawMilliWh) { return Number(rawMilliWh || 0) / 1e6; }
+}
+
+EnerTalkApi.DEFAULT_CLIENT_ID = DEFAULT_CLIENT_ID;
+EnerTalkApi.DEFAULT_CLIENT_SECRET = DEFAULT_CLIENT_SECRET;
+
+module.exports = EnerTalkApi;

package/lib/EveCharacteristics.js

@@ -0,0 +1,76 @@
+'use strict';
+
+/**
+ * Elgato Eve 커스텀 특성 정의.
+ *
+ * HomeKit 에는 "전력(W)/전력량(kWh)" 표준 특성이 없어서, Eve 앱이 읽는
+ * Elgato 커스텀 UUID 를 그대로 쓴다. Eve 앱에서 실시간 W 와 kWh 그래프(히스토리)까지 보인다.
+ *
+ * 반환: { CurrentConsumption, TotalConsumption, Voltage, ElectricCurrent }
+ * homebridge 의 hap(Characteristic/Formats/Perms)을 넘겨 호출한다.
+ */
+module.exports = function buildEveCharacteristics(hap) {
+  const { Characteristic, Formats, Perms } = hap;
+
+  class CurrentConsumption extends Characteristic {
+    constructor() {
+      super('Consumption', CurrentConsumption.UUID, {
+        format: Formats.FLOAT,
+        unit: 'W',
+        minValue: 0,
+        maxValue: 1000000,
+        minStep: 0.1,
+        perms: [Perms.PAIRED_READ, Perms.NOTIFY],
+      });
+      this.value = this.getDefaultValue();
+    }
+  }
+  CurrentConsumption.UUID = 'E863F10D-079E-48FF-8F27-9C2605A29F52';
+
+  class TotalConsumption extends Characteristic {
+    constructor() {
+      super('Total Consumption', TotalConsumption.UUID, {
+        format: Formats.FLOAT,
+        unit: 'kWh',
+        minValue: 0,
+        maxValue: 1000000000,
+        minStep: 0.001,
+        perms: [Perms.PAIRED_READ, Perms.NOTIFY],
+      });
+      this.value = this.getDefaultValue();
+    }
+  }
+  TotalConsumption.UUID = 'E863F10C-079E-48FF-8F27-9C2605A29F52';
+
+  class Voltage extends Characteristic {
+    constructor() {
+      super('Voltage', Voltage.UUID, {
+        format: Formats.FLOAT,
+        unit: 'V',
+        minValue: 0,
+        maxValue: 1000,
+        minStep: 0.1,
+        perms: [Perms.PAIRED_READ, Perms.NOTIFY],
+      });
+      this.value = this.getDefaultValue();
+    }
+  }
+  Voltage.UUID = 'E863F10A-079E-48FF-8F27-9C2605A29F52';
+
+  class ElectricCurrent extends Characteristic {
+    constructor() {
+      super('Electric Current', ElectricCurrent.UUID, {
+        format: Formats.FLOAT,
+        unit: 'A',
+        minValue: 0,
+        maxValue: 1000,
+        minStep: 0.01,
+        perms: [Perms.PAIRED_READ, Perms.NOTIFY],
+      });
+      this.value = this.getDefaultValue();
+    }
+  }
+  ElectricCurrent.UUID = 'E863F126-079E-48FF-8F27-9C2605A29F52';
+
+  return { CurrentConsumption, TotalConsumption, Voltage, ElectricCurrent };
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "homebridge-enertalk-km81",
+  "version": "1.0.0",
+  "description": "Homebridge plugin for EnerTalk (Encored) energy meters — realtime power (W) and monthly usage (kWh) via the EnerTalk cloud API, exposed with Eve energy characteristics.",
+  "main": "index.js",
+  "engines": {
+    "node": ">=18.15.0",
+    "homebridge": ">=1.6.0"
+  },
+  "keywords": [
+    "homebridge-plugin",
+    "enertalk",
+    "encored",
+    "energy",
+    "power",
+    "electricity",
+    "eve",
+    "homekit"
+  ],
+  "author": "Km81",
+  "license": "MIT",
+  "dependencies": {
+    "@homebridge/plugin-ui-utils": "^2.0.0"
+  },
+  "files": [
+    "index.js",
+    "config.schema.json",
+    "lib/",
+    "homebridge-ui/",
+    "LICENSE",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Km81/homebridge-enertalk-km81.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Km81/homebridge-enertalk-km81/issues"
+  },
+  "homepage": "https://github.com/Km81/homebridge-enertalk-km81#readme"
+}