homebridge-panasonic-ecocute-bath-extra-command 0.2.0

package/README.md

@@ -0,0 +1,136 @@
+# Homebridge Panasonic Ecocute Bath Extra Command
+
+Homebridge platform plugin for Panasonic Ecocute bath extra commands via Panasonic Cloud API.
+
+This is an unofficial plugin and is not supported by Panasonic.
+Panasonic may change the cloud API at any time. Use at your own risk.
+
+## Features
+
+- Exposes Panasonic Ecocute bath extra commands to HomeKit as Valve accessories.
+- Supports Bath Reheating / 追いだき.
+- Supports Warmth Charge / ぬくもりチャージ.
+- Uses one shared API Host / Device ID / Bearer Token at platform level.
+- Creates multiple HomeKit accessories from the `commands` array.
+- Reads remaining hot water information and can expose it as a Battery Service.
+- Blocks Warmth Charge ON when `warmthCharge.permission` is not true.
+- Does not mark the Valve as faulted when Warmth Charge is unavailable, to avoid unnecessary HomeKit grey-out.
+
+## Security Notice
+
+Do not publish or share your Device ID, Bearer Token, Authorization header, cookies, refresh tokens, passwords, or hashedCorporationPassword.
+
+## Platform Configuration
+
+```json
+{
+  "platform": "PanasonicEcocuteBathExtra",
+  "name": "Panasonic Ecocute Bath Extra",
+  "apiHost": "https://app.dhw.apws.panasonic.com",
+  "deviceId": "YOUR_DEVICE_ID",
+  "bearerToken": "YOUR_BEARER_TOKEN",
+  "statusPollSeconds": 10,
+  "activePollSeconds": 5,
+  "advancedStatus": {
+    "statusCacheTtlSeconds": 2,
+    "statusRetryDelayMs": 800,
+    "statusErrorLogThrottleSeconds": 60
+  },
+  "lowWaterLevelThreshold": 20,
+  "batteryLevelMode": "liter_div_10",
+  "commands": [
+    {
+      "name": "エコキュート 追いだき",
+      "commandType": "bathReheating",
+      "valveType": "shower"
+    },
+    {
+      "name": "エコキュート ぬくもりチャージ",
+      "commandType": "warmthCharge",
+      "valveType": "shower",
+      "permissionSensorType": "none"
+    }
+  ]
+}
+```
+
+## Commands
+
+### Bath Reheating / 追いだき
+
+- Endpoint: `PUT /api/v1/devices/<DEVICE_ID>/properties/bathReheating`
+- ON body: `{ "bathReheating": true }`
+- OFF body: `{ "bathReheating": false }`
+
+### Warmth Charge / ぬくもりチャージ
+
+- Endpoint: `PUT /api/v1/devices/<DEVICE_ID>/properties/warmthCharging`
+- ON body: `{ "warmthCharge": { "status": true } }`
+- OFF body: `{ "warmthCharge": { "status": false } }`
+- `warmthCharge.status` means Warmth Charge is currently active.
+- `warmthCharge.permission` means Warmth Charge is currently allowed.
+
+If `warmthCharge.permission` is not true, HomeKit ON is blocked and no PUT request is sent.
+
+## Warmth Charge Permission Sensor
+
+`permissionSensorType` can be one of:
+
+- `none`
+- `contact`
+- `occupancy`
+- `motion`
+- `leak`
+
+Light Sensor is intentionally not provided because `warmthCharge.permission` is boolean.
+Leak Sensor may look like a leak warning in HomeKit, so use it only if that behavior is acceptable.
+
+## Getting Device ID and Bearer Token
+
+Use the official Panasonic app and an HTTPS proxy tool such as Proxyman or mitmproxy.
+Temporarily set the iPhone Wi-Fi HTTP proxy, operate the official app, and look for:
+
+```text
+/api/v1/devices/<DEVICE_ID>/properties
+Authorization: Bearer <TOKEN>
+```
+
+Copy only the Device ID and Bearer Token into Homebridge. Turn the iPhone Wi-Fi HTTP proxy off after capture.
+
+## Screenshots
+
+Screenshots below show the v0.2.0 platform UI and verified HomeKit behavior.
+
+![HomeKit bath extra room tiles](docs/images/homekit-bath-extra-room-tiles.jpg)
+
+![Warmth Charge control](docs/images/homekit-warmth-charge-control.jpg)
+
+![Bath Reheating active detail](docs/images/homekit-reheating-active-detail.jpg)
+
+## Future Work
+
+Possible future additions:
+
+- Bath Auto / ふろ自動 via Panasonic Cloud API, after confirming the real endpoint, request body, and status fields.
+- `entrySign` support as a HomeKit Occupancy Sensor for bathroom entry detection.
+
+## Version History
+
+### 0.2.0
+
+- Converted `PanasonicEcocuteBathExtra` to a platform plugin.
+- Moved API Host / Device ID / Bearer Token to shared platform-level settings.
+- Added `commands` array for Bath Reheating and Warmth Charge.
+- Kept direct compatibility accessory aliases for advanced/manual use.
+- Improved platform child logs to include each accessory name.
+- Avoided HomeKit grey-out by keeping Valve `StatusFault` as `NO_FAULT` when Warmth Charge is unavailable.
+
+### 0.1.0
+
+- Initial integrated package.
+- Added Warmth Charge command support.
+- Integrated old Bath Reheating behavior.
+
+## License
+
+MIT

package/config.schema.json

@@ -0,0 +1,207 @@
+{
+  "pluginAlias": "PanasonicEcocuteBathExtra",
+  "pluginType": "platform",
+  "singular": false,
+  "schema": {
+    "type": "object",
+    "properties": {
+      "name": {
+        "title": "Platform Name",
+        "type": "string",
+        "default": "Panasonic Ecocute Bath Extra"
+      },
+      "apiHost": {
+        "title": "API Host",
+        "type": "string",
+        "default": "https://app.dhw.apws.panasonic.com",
+        "description": "Panasonic Cloud API host shared by all commands in this platform."
+      },
+      "deviceId": {
+        "title": "Device ID",
+        "type": "string",
+        "format": "password",
+        "required": true,
+        "description": "Panasonic Ecocute Device ID shared by all commands in this platform."
+      },
+      "bearerToken": {
+        "title": "Bearer Token",
+        "type": "string",
+        "format": "password",
+        "required": true,
+        "description": "Panasonic Cloud Bearer Token shared by all commands in this platform. Do not share this value."
+      },
+      "statusPollSeconds": {
+        "title": "通常状態更新間隔 秒",
+        "type": "integer",
+        "default": 10,
+        "minimum": 5
+      },
+      "activePollSeconds": {
+        "title": "動作中の状態更新間隔 秒",
+        "type": "integer",
+        "default": 5,
+        "minimum": 2
+      },
+      "advancedStatus": {
+        "title": "状態GET詳細設定",
+        "type": "object",
+        "properties": {
+          "statusCacheTtlSeconds": {
+            "title": "状態GETキャッシュ 秒",
+            "type": "integer",
+            "default": 2,
+            "minimum": 0
+          },
+          "statusRetryDelayMs": {
+            "title": "状態GETリトライ待機 ミリ秒",
+            "type": "integer",
+            "default": 800,
+            "minimum": 0
+          },
+          "statusErrorLogThrottleSeconds": {
+            "title": "状態GETエラーログ抑制 秒",
+            "type": "integer",
+            "default": 60,
+            "minimum": 5
+          }
+        }
+      },
+      "lowWaterLevelThreshold": {
+        "title": "残湯低下しきい値 %",
+        "type": "integer",
+        "default": 20,
+        "minimum": 0,
+        "maximum": 100
+      },
+      "batteryLevelMode": {
+        "title": "残湯表示方式",
+        "type": "string",
+        "default": "liter_div_10",
+        "oneOf": [
+          {
+            "title": "湯量L ÷ 10（540L→54%）",
+            "enum": [
+              "liter_div_10"
+            ]
+          },
+          {
+            "title": "API rate × 10（9→90%）",
+            "enum": [
+              "rate_x10"
+            ]
+          }
+        ]
+      },
+      "commands": {
+        "title": "Bath Commands / おふろ操作",
+        "type": "array",
+        "default": [
+          {
+            "name": "エコキュート 追いだき",
+            "commandType": "bathReheating",
+            "valveType": "shower"
+          },
+          {
+            "name": "エコキュート ぬくもりチャージ",
+            "commandType": "warmthCharge",
+            "valveType": "shower",
+            "permissionSensorType": "none"
+          }
+        ],
+        "items": {
+          "type": "object",
+          "properties": {
+            "name": {
+              "title": "Accessory Name",
+              "type": "string",
+              "default": "エコキュート ぬくもりチャージ"
+            },
+            "commandType": {
+              "title": "Bath Extra Command / おふろ追加操作",
+              "type": "string",
+              "default": "warmthCharge",
+              "oneOf": [
+                {
+                  "title": "Warmth Charge / ぬくもりチャージ",
+                  "enum": [
+                    "warmthCharge"
+                  ]
+                },
+                {
+                  "title": "Bath Reheating / 追いだき",
+                  "enum": [
+                    "bathReheating"
+                  ]
+                }
+              ]
+            },
+            "valveType": {
+              "title": "Valve Type",
+              "type": "string",
+              "default": "shower",
+              "oneOf": [
+                {
+                  "title": "Faucet / 水栓",
+                  "enum": [
+                    "faucet"
+                  ]
+                },
+                {
+                  "title": "Shower / シャワー",
+                  "enum": [
+                    "shower"
+                  ]
+                },
+                {
+                  "title": "Sprinkler / スプリンクラー",
+                  "enum": [
+                    "sprinkler"
+                  ]
+                }
+              ],
+              "description": "HomeKit Valve display type only."
+            },
+            "permissionSensorType": {
+              "title": "Warmth Charge Permission Sensor Type",
+              "type": "string",
+              "default": "none",
+              "oneOf": [
+                {
+                  "title": "None / 表示しない",
+                  "enum": [
+                    "none"
+                  ]
+                },
+                {
+                  "title": "Contact Sensor",
+                  "enum": [
+                    "contact"
+                  ]
+                },
+                {
+                  "title": "Occupancy Sensor",
+                  "enum": [
+                    "occupancy"
+                  ]
+                },
+                {
+                  "title": "Motion Sensor",
+                  "enum": [
+                    "motion"
+                  ]
+                },
+                {
+                  "title": "Leak Sensor",
+                  "enum": [
+                    "leak"
+                  ]
+                }
+              ],
+              "description": "Optional HomeKit sensor for warmthCharge.permission. Light Sensor is intentionally not provided because permission is boolean."
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/index.js

@@ -0,0 +1,805 @@
+'use strict';
+
+let Service;
+let Characteristic;
+
+const PLUGIN_NAME = 'homebridge-panasonic-ecocute-bath-extra-command';
+const ACCESSORY_EXTRA_NAME = 'PanasonicEcocuteBathExtra';
+const ACCESSORY_REHEATING_NAME = 'PanasonicEcocuteBathReheating';
+const ACCESSORY_WARMTH_CHARGE_NAME = 'PanasonicEcocuteWarmthCharge';
+
+module.exports = (api) => {
+  Service = api.hap.Service;
+  Characteristic = api.hap.Characteristic;
+  api.registerPlatform(PLUGIN_NAME, ACCESSORY_EXTRA_NAME, PanasonicEcocuteBathExtraPlatform);
+  api.registerAccessory(PLUGIN_NAME, ACCESSORY_REHEATING_NAME, PanasonicEcocuteBathReheatingValve);
+  api.registerAccessory(PLUGIN_NAME, ACCESSORY_WARMTH_CHARGE_NAME, PanasonicEcocuteWarmthChargeValve);
+};
+
+class PanasonicEcocuteBathReheatingValve {
+  constructor(log, config) {
+    this.log = log;
+    this.config = config || {};
+
+    this.name = this.config.name || 'エコキュート 追いだき';
+    this.apiHost = String(this.config.apiHost || 'https://app.dhw.apws.panasonic.com').replace(/\/+$/, '');
+    this.deviceId = String(this.config.deviceId || '');
+    this.bearerToken = String(this.config.bearerToken || '');
+
+    this.statusPollSeconds = Math.max(5, Number(this.config.statusPollSeconds || 10));
+    this.activePollSeconds = Math.max(2, Number(this.config.activePollSeconds || 5));
+        this.statusCacheTtlSeconds = Math.max(0, Number(this.config.statusCacheTtlSeconds ?? 2));
+    this.statusRetryDelayMs = Math.max(0, Number(this.config.statusRetryDelayMs ?? 800));
+    this.statusErrorLogThrottleSeconds = Math.max(5, Number(this.config.statusErrorLogThrottleSeconds ?? 60));
+
+    this.lowWaterLevelThreshold = Math.max(0, Math.min(100, Number(this.config.lowWaterLevelThreshold ?? 20)));
+    this.batteryLevelMode = String(this.config.batteryLevelMode || 'liter_div_10');
+    this.httpTimeoutMs = Math.max(5000, Number(this.config.httpTimeoutMs || 15000));
+
+    this.currentReheating = false;
+    this.currentWaterHeating = false;
+    this.currentBatteryLevel = 0;
+
+    this.commandInFlight = false;
+    this.pollTimer = null;
+
+    this.statusCache = null;
+    this.statusCacheAt = 0;
+    this.statusFetchPromise = null;
+
+    this.lastStatusErrorKey = '';
+    this.lastStatusErrorAt = 0;
+    this.statusErrorSuppressed = 0;
+
+    this.informationService = new Service.AccessoryInformation()
+      .setCharacteristic(Characteristic.Manufacturer, 'Panasonic')
+      .setCharacteristic(Characteristic.Model, 'Ecocute Bath Reheating Cloud Valve')
+      .setCharacteristic(Characteristic.SerialNumber, 'panasonic-ecocute-bath-reheating')
+      .setCharacteristic(Characteristic.FirmwareRevision, '0.2.0');
+
+    this.valveService = new Service.Valve(this.name);
+    this.valveService
+      .setCharacteristic(Characteristic.ValveType, ({sprinkler: Characteristic.ValveType.IRRIGATION, shower: Characteristic.ValveType.SHOWER_HEAD, faucet: Characteristic.ValveType.WATER_FAUCET}[String(this.config.valveType || "shower").toLowerCase()] || Characteristic.ValveType.SHOWER_HEAD))
+      .setCharacteristic(Characteristic.Name, this.name);
+
+    this.valveService.getCharacteristic(Characteristic.Active)
+      .onGet(this.handleGetActive.bind(this))
+      .onSet(this.handleSetActive.bind(this));
+
+    this.valveService.getCharacteristic(Characteristic.InUse)
+      .onGet(this.handleGetInUse.bind(this));
+
+    const BatteryServiceClass = Service.BatteryService || Service.Battery;
+    if (BatteryServiceClass) {
+      this.batteryService = new BatteryServiceClass(`${this.name} 残湯`, 'remaining-hot-water');
+
+      this.batteryService.getCharacteristic(Characteristic.BatteryLevel)
+        .onGet(async () => {
+          await this.refreshStatus({ allowCache: true });
+          return this.currentBatteryLevel;
+        });
+
+      this.batteryService.getCharacteristic(Characteristic.StatusLowBattery)
+        .onGet(async () => {
+          await this.refreshStatus({ allowCache: true });
+          return this.currentBatteryLevel <= this.lowWaterLevelThreshold
+            ? Characteristic.StatusLowBattery.BATTERY_LEVEL_LOW
+            : Characteristic.StatusLowBattery.BATTERY_LEVEL_NORMAL;
+        });
+
+      this.batteryService.getCharacteristic(Characteristic.ChargingState)
+        .onGet(async () => {
+          await this.refreshStatus({ allowCache: true });
+          return this.currentWaterHeating
+            ? Characteristic.ChargingState.CHARGING
+            : Characteristic.ChargingState.NOT_CHARGING;
+        });
+    } else {
+      this.batteryService = null;
+      this.log.warn('BatteryService is not available; remaining hot water display is disabled.');
+    }
+
+    this.log.info(
+      `initialized v0.2.0 Valve ` +
+      `statusPollSeconds=${this.statusPollSeconds} activePollSeconds=${this.activePollSeconds} ` +
+      `cacheTtl=${this.statusCacheTtlSeconds}s retryDelay=${this.statusRetryDelayMs}ms ` +
+      `errorThrottle=${this.statusErrorLogThrottleSeconds}s ` +
+      `deviceId=${this.mask(this.deviceId)} token=${this.bearerToken ? '***SET***' : '***EMPTY***'}`
+    );
+
+    if (!this.deviceId || !this.bearerToken) {
+      this.log.warn('deviceId or bearerToken is empty. Configure them in Homebridge UI.');
+    }
+
+    this.refreshStatus({ force: true }).finally(() => this.scheduleNextPoll(2));
+  }
+
+  getServices() {
+    return [
+      this.informationService,
+      this.valveService,
+      ...(this.batteryService ? [this.batteryService] : [])
+    ];
+  }
+
+  sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+
+  mask(value) {
+    if (!value) return '***EMPTY***';
+    if (value.length <= 8) return '***MASKED***';
+    return `${value.slice(0, 4)}...${value.slice(-4)}`;
+  }
+
+  url(path) {
+    return `${this.apiHost}${path}`;
+  }
+
+  headers(json = true) {
+    const h = {
+      'Authorization': `Bearer ${this.bearerToken}`,
+      'Accept': 'application/json, application/problem+json; charset=utf-8',
+      'Accept-Language': 'ja',
+      'User-Agent': 'CFNetwork/3860.600.12 Darwin/25.5.0'
+    };
+    if (json) {
+      h['Content-Type'] = 'application/json; charset=utf-8';
+    }
+    return h;
+  }
+
+  sanitizeErrorText(text) {
+    return String(text || '')
+      .replace(this.bearerToken || '__NO_TOKEN__', '***TOKEN***')
+      .replace(this.deviceId || '__NO_DEVICE__', '<DEVICE_ID>');
+  }
+
+  async request(method, property, body) {
+    if (!this.deviceId || !this.bearerToken) {
+      throw new Error('deviceId or bearerToken is empty');
+    }
+
+    const encodedDeviceId = encodeURIComponent(this.deviceId);
+    const path = property
+      ? `/api/v1/devices/${encodedDeviceId}/properties/${property}`
+      : `/api/v1/devices/${encodedDeviceId}/properties`;
+
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.httpTimeoutMs);
+
+    try {
+      const options = {
+        method,
+        headers: this.headers(true),
+        signal: controller.signal
+      };
+
+      if (body !== undefined) {
+        options.body = JSON.stringify(body);
+      }
+
+      const res = await fetch(this.url(path), options);
+      const text = await res.text();
+
+      let data = null;
+      try {
+        data = text ? JSON.parse(text) : {};
+      } catch (e) {
+        data = { raw: text };
+      }
+
+      if (!res.ok) {
+        const err = new Error(`HTTP ${res.status} ${res.statusText}: ${this.sanitizeErrorText(text)}`);
+        err.status = res.status;
+        err.code = data && data.code;
+        err.bodyText = text;
+        throw err;
+      }
+
+      return data;
+    } catch (e) {
+      if (e.name === 'AbortError') {
+        const err = new Error(`HTTP timeout after ${this.httpTimeoutMs}ms`);
+        err.status = 0;
+        throw err;
+      }
+      throw e;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  isRetryableStatusError(e) {
+    return e && (
+      e.status === 502 ||
+      e.status === 503 ||
+      e.status === 504 ||
+      e.code === 'Q2E07-00009'
+    );
+  }
+
+  async getProperties() {
+    try {
+      return await this.request('GET', '', undefined);
+    } catch (e) {
+      if (this.isRetryableStatusError(e)) {
+        this.log.debug(`status GET retry after ${this.statusRetryDelayMs}ms: ${this.sanitizeErrorText(e.message)}`);
+        await this.sleep(this.statusRetryDelayMs);
+        return await this.request('GET', '', undefined);
+      }
+      throw e;
+    }
+  }
+
+  async putBathReheating(value) {
+    return this.request('PUT', 'bathReheating', { bathReheating: Boolean(value) });
+  }
+
+  clampPercent(n) {
+    const x = Number(n);
+    if (!Number.isFinite(x)) return 0;
+    return Math.max(0, Math.min(100, Math.round(x)));
+  }
+
+  calcBatteryLevel(data) {
+    const liter = Number(data.availableHotWaterLiter);
+    const rate = Number(data.availableHotWaterRate);
+
+    if (this.batteryLevelMode === 'rate_x10' && Number.isFinite(rate)) {
+      return this.clampPercent(rate * 10);
+    }
+
+    if (Number.isFinite(liter)) {
+      return this.clampPercent(liter / 10);
+    }
+
+    if (Number.isFinite(rate)) {
+      return this.clampPercent(rate * 10);
+    }
+
+    return this.currentBatteryLevel;
+  }
+
+  hasOwn(data, key) {
+    return data && Object.prototype.hasOwnProperty.call(data, key);
+  }
+
+  applyStatus(data, source) {
+    if (!data || typeof data !== 'object') return;
+
+    const nextReheating = this.hasOwn(data, 'bathReheating')
+      ? Boolean(data.bathReheating)
+      : this.currentReheating;
+
+    const nextWaterHeating = this.hasOwn(data, 'waterHeatingStatus')
+      ? Boolean(data.waterHeatingStatus)
+      : this.currentWaterHeating;
+
+    const nextBatteryLevel = (
+      this.hasOwn(data, 'availableHotWaterLiter') ||
+      this.hasOwn(data, 'availableHotWaterRate')
+    ) ? this.calcBatteryLevel(data) : this.currentBatteryLevel;
+
+    if (this.currentReheating !== nextReheating) {
+      this.log.info(`bathReheating changed by ${source}: ${this.currentReheating} => ${nextReheating}`);
+    }
+
+    if (this.currentWaterHeating !== nextWaterHeating) {
+      this.log.info(`waterHeatingStatus changed by ${source}: ${this.currentWaterHeating} => ${nextWaterHeating}`);
+    }
+
+    this.currentReheating = nextReheating;
+    this.currentWaterHeating = nextWaterHeating;
+    this.currentBatteryLevel = nextBatteryLevel;
+
+    this.valveService.updateCharacteristic(
+      Characteristic.Active,
+      nextReheating ? Characteristic.Active.ACTIVE : Characteristic.Active.INACTIVE
+    );
+
+    this.valveService.updateCharacteristic(
+      Characteristic.InUse,
+      nextReheating ? Characteristic.InUse.IN_USE : Characteristic.InUse.NOT_IN_USE
+    );
+
+    if (this.batteryService) {
+      this.batteryService.updateCharacteristic(Characteristic.BatteryLevel, nextBatteryLevel);
+      this.batteryService.updateCharacteristic(
+        Characteristic.StatusLowBattery,
+        nextBatteryLevel <= this.lowWaterLevelThreshold
+          ? Characteristic.StatusLowBattery.BATTERY_LEVEL_LOW
+          : Characteristic.StatusLowBattery.BATTERY_LEVEL_NORMAL
+      );
+      this.batteryService.updateCharacteristic(
+        Characteristic.ChargingState,
+        nextWaterHeating
+          ? Characteristic.ChargingState.CHARGING
+          : Characteristic.ChargingState.NOT_CHARGING
+      );
+    }
+  }
+
+  statusCacheFresh() {
+    if (!this.statusCache) return false;
+    if (this.statusCacheTtlSeconds <= 0) return false;
+    return (Date.now() - this.statusCacheAt) < (this.statusCacheTtlSeconds * 1000);
+  }
+
+  logStatusError(e) {
+    const now = Date.now();
+    const msg = this.sanitizeErrorText(e && e.message ? e.message : String(e));
+    const key = msg;
+    const throttleMs = this.statusErrorLogThrottleSeconds * 1000;
+
+    if (this.lastStatusErrorKey === key && (now - this.lastStatusErrorAt) < throttleMs) {
+      this.statusErrorSuppressed += 1;
+      return;
+    }
+
+    const suffix = this.statusErrorSuppressed > 0
+      ? `; suppressed ${this.statusErrorSuppressed} similar status errors`
+      : '';
+
+    this.statusErrorSuppressed = 0;
+    this.lastStatusErrorKey = key;
+    this.lastStatusErrorAt = now;
+
+    this.log.warn(`status failed: ${msg}${suffix}`);
+  }
+
+  clearStatusErrorAfterSuccess() {
+    if (this.statusErrorSuppressed > 0) {
+      this.log.info(`status recovered; suppressed ${this.statusErrorSuppressed} previous status errors`);
+    }
+    this.statusErrorSuppressed = 0;
+    this.lastStatusErrorKey = '';
+    this.lastStatusErrorAt = 0;
+  }
+
+  async refreshStatus(options = {}) {
+    const force = Boolean(options.force);
+    const allowCache = options.allowCache !== false;
+
+    if (!force && allowCache && this.statusCacheFresh()) {
+      return this.statusCache;
+    }
+
+    if (this.statusFetchPromise) {
+      return this.statusFetchPromise;
+    }
+
+    this.statusFetchPromise = (async () => {
+      try {
+        const data = await this.getProperties();
+        this.statusCache = data;
+        this.statusCacheAt = Date.now();
+        this.applyStatus(data, 'cloud-status');
+        this.clearStatusErrorAfterSuccess();
+
+        this.log.debug(
+          `status bathReheating=${Boolean(data.bathReheating)} ` +
+          `waterHeatingStatus=${Boolean(data.waterHeatingStatus)} ` +
+          `availableHotWaterLiter=${data.availableHotWaterLiter} ` +
+          `availableHotWaterRate=${data.availableHotWaterRate} ` +
+          `bathTemperature=${data.bathTemperature} bathOperationMode=${data.bathOperationMode}`
+        );
+
+        return data;
+      } catch (e) {
+        this.logStatusError(e);
+        return null;
+      } finally {
+        this.statusFetchPromise = null;
+      }
+    })();
+
+    return this.statusFetchPromise;
+  }
+
+  clearPollTimer() {
+    if (this.pollTimer) {
+      clearTimeout(this.pollTimer);
+      this.pollTimer = null;
+    }
+  }
+
+  scheduleNextPoll(delaySeconds) {
+    this.clearPollTimer();
+
+    const interval = Number.isFinite(delaySeconds)
+      ? delaySeconds
+      : (this.currentReheating ? this.activePollSeconds : this.statusPollSeconds);
+
+    this.pollTimer = setTimeout(async () => {
+      try {
+        await this.refreshStatus({ allowCache: false });
+      } finally {
+        this.scheduleNextPoll();
+      }
+    }, Math.max(1, interval) * 1000);
+  }
+
+  async handleGetActive() {
+    await this.refreshStatus({ allowCache: true });
+    return this.currentReheating
+      ? Characteristic.Active.ACTIVE
+      : Characteristic.Active.INACTIVE;
+  }
+
+  async handleGetInUse() {
+    await this.refreshStatus({ allowCache: true });
+    return this.currentReheating
+      ? Characteristic.InUse.IN_USE
+      : Characteristic.InUse.NOT_IN_USE;
+  }
+
+  async handleSetActive(value) {
+    const desired = Number(value) === Characteristic.Active.ACTIVE;
+
+    if (this.commandInFlight) {
+      this.log.warn('command already in flight; refreshing status instead');
+      await this.refreshStatus({ force: true });
+      return;
+    }
+
+    this.commandInFlight = true;
+    this.log.info(`HomeKit Valve set ${desired ? 'ACTIVE/ON' : 'INACTIVE/OFF'}; sending REAL bathReheating=${desired}`);
+
+    try {
+
+      const data = await this.putBathReheating(desired);
+      this.log.info(`REAL command ok bathReheating=${Boolean(data.bathReheating)}`);
+
+      this.statusCache = data;
+      this.statusCacheAt = Date.now();
+      this.applyStatus(data, 'homekit-command');
+
+      setTimeout(() => {
+        this.refreshStatus({ force: true }).catch(() => {});
+      }, 1500);
+    } catch (e) {
+      this.log.error(`set failed: ${this.sanitizeErrorText(e.message)}`);
+      await this.refreshStatus({ force: true });
+      throw e;
+    } finally {
+      this.commandInFlight = false;
+      this.scheduleNextPoll(this.currentReheating ? this.activePollSeconds : 2);
+    }
+  }
+}
+
+
+
+class PanasonicEcocuteWarmthChargeValve extends PanasonicEcocuteBathReheatingValve {
+  constructor(log, config) {
+    super(log, Object.assign({
+      name: 'エコキュート ぬくもりチャージ',
+      valveType: 'shower'
+    }, config || {}));
+
+    this.currentPermission = false;
+    this.permissionSensorType = String(this.config.permissionSensorType || 'none').toLowerCase();
+    this.permissionService = this.createPermissionService();
+
+    this.informationService
+      .setCharacteristic(Characteristic.Model, 'Ecocute Warmth Charge Cloud Valve')
+      .setCharacteristic(Characteristic.SerialNumber, 'panasonic-ecocute-warmth-charge')
+      .setCharacteristic(Characteristic.FirmwareRevision, '0.2.0');
+
+    this.valveService.getCharacteristic(Characteristic.StatusFault)
+      .onGet(async () => {
+        await this.refreshStatus({ allowCache: true });
+        return Characteristic.StatusFault.NO_FAULT;
+      });
+
+    this.log.info('warmthCharge mode enabled endpoint=warmthCharging');
+  }
+
+  async putBathReheating(value) {
+    return this.request('PUT', 'warmthCharging', {
+      warmthCharge: {
+        status: Boolean(value)
+      }
+    });
+  }
+
+  applyStatus(data, source) {
+    if (!data || typeof data !== 'object') return;
+
+    const warmth = data.warmthCharge && typeof data.warmthCharge === 'object'
+      ? data.warmthCharge
+      : null;
+
+    const nextActive = warmth && this.hasOwn(warmth, 'status')
+      ? Boolean(warmth.status)
+      : this.currentReheating;
+
+    const nextPermission = warmth && this.hasOwn(warmth, 'permission')
+      ? Boolean(warmth.permission)
+      : this.currentPermission;
+
+    const nextWaterHeating = this.hasOwn(data, 'waterHeatingStatus')
+      ? Boolean(data.waterHeatingStatus)
+      : this.currentWaterHeating;
+
+    const nextBatteryLevel = (
+      this.hasOwn(data, 'availableHotWaterLiter') ||
+      this.hasOwn(data, 'availableHotWaterRate')
+    ) ? this.calcBatteryLevel(data) : this.currentBatteryLevel;
+
+    if (this.currentReheating !== nextActive) {
+      this.log.info(`warmthCharge.status changed by ${source}: ${this.currentReheating} => ${nextActive}`);
+    }
+
+    if (this.currentPermission !== nextPermission) {
+      this.log.info(`warmthCharge.permission changed by ${source}: ${this.currentPermission} => ${nextPermission}`);
+    }
+
+    if (this.currentWaterHeating !== nextWaterHeating) {
+      this.log.info(`waterHeatingStatus changed by ${source}: ${this.currentWaterHeating} => ${nextWaterHeating}`);
+    }
+
+    this.currentReheating = nextActive;
+    this.currentPermission = nextPermission;
+    this.currentWaterHeating = nextWaterHeating;
+    this.currentBatteryLevel = nextBatteryLevel;
+
+    this.valveService.updateCharacteristic(
+      Characteristic.Active,
+      nextActive ? Characteristic.Active.ACTIVE : Characteristic.Active.INACTIVE
+    );
+
+    this.valveService.updateCharacteristic(
+      Characteristic.InUse,
+      nextActive ? Characteristic.InUse.IN_USE : Characteristic.InUse.NOT_IN_USE
+    );
+
+    this.valveService.updateCharacteristic(
+      Characteristic.StatusFault,
+      Characteristic.StatusFault.NO_FAULT
+    );
+
+    this.updatePermissionService(nextPermission);
+
+    if (this.batteryService) {
+      this.batteryService.updateCharacteristic(Characteristic.BatteryLevel, nextBatteryLevel);
+      this.batteryService.updateCharacteristic(
+        Characteristic.StatusLowBattery,
+        nextBatteryLevel <= this.lowWaterLevelThreshold
+          ? Characteristic.StatusLowBattery.BATTERY_LEVEL_LOW
+          : Characteristic.StatusLowBattery.BATTERY_LEVEL_NORMAL
+      );
+      this.batteryService.updateCharacteristic(
+        Characteristic.ChargingState,
+        nextWaterHeating
+          ? Characteristic.ChargingState.CHARGING
+          : Characteristic.ChargingState.NOT_CHARGING
+      );
+    }
+  }
+
+  async handleSetActive(value) {
+    const desired = Number(value) === Characteristic.Active.ACTIVE;
+
+    if (this.commandInFlight) {
+      this.log.warn('command already in flight; refreshing status instead');
+      await this.refreshStatus({ force: true });
+      return;
+    }
+
+    this.commandInFlight = true;
+    this.log.info(`HomeKit Valve set ${desired ? 'ACTIVE/ON' : 'INACTIVE/OFF'}; sending REAL warmthCharging=${desired}`);
+
+    try {
+      if (desired) {
+        const latest = await this.refreshStatus({ force: true });
+        const allowed = latest &&
+          latest.warmthCharge &&
+          typeof latest.warmthCharge === 'object' &&
+          latest.warmthCharge.permission === true;
+
+        if (!allowed) {
+          this.log.warn('BLOCK warmthCharge permission=false_or_unknown');
+          this.currentReheating = false;
+          this.currentPermission = false;
+          this.valveService.updateCharacteristic(Characteristic.Active, Characteristic.Active.INACTIVE);
+          this.valveService.updateCharacteristic(Characteristic.InUse, Characteristic.InUse.NOT_IN_USE);
+          this.valveService.updateCharacteristic(Characteristic.StatusFault, Characteristic.StatusFault.NO_FAULT);
+          this.updatePermissionService(false);
+          return;
+        }
+      }
+
+      const data = await this.putBathReheating(desired);
+      const result = Boolean(data && data.warmthCharge && data.warmthCharge.status);
+
+      this.log.info(`REAL command ok warmthCharge.status=${result}`);
+
+      this.statusCache = data;
+      this.statusCacheAt = Date.now();
+      this.applyStatus(data, 'homekit-command');
+
+      setTimeout(() => {
+        this.refreshStatus({ force: true }).catch(() => {});
+      }, 1500);
+    } catch (e) {
+      this.log.error(`set failed: ${this.sanitizeErrorText(e.message)}`);
+      await this.refreshStatus({ force: true });
+      throw e;
+    } finally {
+      this.commandInFlight = false;
+      this.scheduleNextPoll(this.currentReheating ? this.activePollSeconds : 2);
+    }
+  }
+}
+
+
+
+PanasonicEcocuteWarmthChargeValve.prototype.createPermissionService = function() {
+  const sensorName = `${this.name} 可能`;
+
+  if (this.permissionSensorType === 'contact') {
+    const svc = new Service.ContactSensor(sensorName, 'warmth-charge-permission-contact');
+    svc.getCharacteristic(Characteristic.ContactSensorState)
+      .onGet(async () => {
+        await this.refreshStatus({ allowCache: true });
+        return this.currentPermission
+          ? Characteristic.ContactSensorState.CONTACT_DETECTED
+          : Characteristic.ContactSensorState.CONTACT_NOT_DETECTED;
+      });
+    return svc;
+  }
+
+  if (this.permissionSensorType === 'occupancy') {
+    const svc = new Service.OccupancySensor(sensorName, 'warmth-charge-permission-occupancy');
+    svc.getCharacteristic(Characteristic.OccupancyDetected)
+      .onGet(async () => {
+        await this.refreshStatus({ allowCache: true });
+        return this.currentPermission
+          ? Characteristic.OccupancyDetected.OCCUPANCY_DETECTED
+          : Characteristic.OccupancyDetected.OCCUPANCY_NOT_DETECTED;
+      });
+    return svc;
+  }
+
+  if (this.permissionSensorType === 'motion') {
+    const svc = new Service.MotionSensor(sensorName, 'warmth-charge-permission-motion');
+    svc.getCharacteristic(Characteristic.MotionDetected)
+      .onGet(async () => {
+        await this.refreshStatus({ allowCache: true });
+        return Boolean(this.currentPermission);
+      });
+    return svc;
+  }
+
+  if (this.permissionSensorType === 'leak') {
+    const svc = new Service.LeakSensor(sensorName, 'warmth-charge-permission-leak');
+    svc.getCharacteristic(Characteristic.LeakDetected)
+      .onGet(async () => {
+        await this.refreshStatus({ allowCache: true });
+        return this.currentPermission
+          ? Characteristic.LeakDetected.LEAK_DETECTED
+          : Characteristic.LeakDetected.LEAK_NOT_DETECTED;
+      });
+    return svc;
+  }
+
+  return null;
+};
+
+PanasonicEcocuteWarmthChargeValve.prototype.updatePermissionService = function(value) {
+  if (!this.permissionService) return;
+
+  if (this.permissionSensorType === 'contact') {
+    this.permissionService.updateCharacteristic(
+      Characteristic.ContactSensorState,
+      value
+        ? Characteristic.ContactSensorState.CONTACT_DETECTED
+        : Characteristic.ContactSensorState.CONTACT_NOT_DETECTED
+    );
+    return;
+  }
+
+  if (this.permissionSensorType === 'occupancy') {
+    this.permissionService.updateCharacteristic(
+      Characteristic.OccupancyDetected,
+      value
+        ? Characteristic.OccupancyDetected.OCCUPANCY_DETECTED
+        : Characteristic.OccupancyDetected.OCCUPANCY_NOT_DETECTED
+    );
+    return;
+  }
+
+  if (this.permissionSensorType === 'motion') {
+    this.permissionService.updateCharacteristic(Characteristic.MotionDetected, Boolean(value));
+    return;
+  }
+
+  if (this.permissionSensorType === 'leak') {
+    this.permissionService.updateCharacteristic(
+      Characteristic.LeakDetected,
+      value
+        ? Characteristic.LeakDetected.LEAK_DETECTED
+        : Characteristic.LeakDetected.LEAK_NOT_DETECTED
+    );
+  }
+};
+
+PanasonicEcocuteWarmthChargeValve.prototype.getServices = function() {
+  const baseServices = PanasonicEcocuteBathReheatingValve.prototype.getServices.call(this);
+  return [
+    ...baseServices,
+    ...(this.permissionService ? [this.permissionService] : [])
+  ];
+};
+
+
+class PanasonicEcocuteBathExtra {
+  constructor(log, config) {
+    const cfg = config || {};
+    const commandType = String(cfg.commandType || cfg.commandKind || 'warmthCharge').toLowerCase();
+
+    if (commandType === 'bathreheating' || commandType === 'bath_reheating' || commandType === 'reheating') {
+      return new PanasonicEcocuteBathReheatingValve(log, Object.assign({}, cfg, { commandType: 'bathReheating' }));
+    }
+
+    if (commandType !== 'warmthcharge' && commandType !== 'warmth_charge') {
+      log.warn(`unknown commandType=${commandType}; using warmthCharge`);
+    }
+
+    return new PanasonicEcocuteWarmthChargeValve(log, Object.assign({}, cfg, { commandType: 'warmthCharge' }));
+  }
+}
+
+
+class PanasonicEcocuteBathExtraPlatform {
+  constructor(log, config) {
+    this.log = log;
+    this.config = config || {};
+  }
+
+  childLog(name) {
+    const parent = this.log;
+    const prefix = "[" + String(name || "Accessory") + "] ";
+    const fmt = (args) => prefix + Array.from(args).map((v) => typeof v === "string" ? v : JSON.stringify(v)).join(" ");
+    const child = function() {
+      if (typeof parent === "function") return parent(fmt(arguments));
+      if (parent && typeof parent.info === "function") return parent.info(fmt(arguments));
+    };
+    for (const level of ["info","warn","error","debug","success"]) {
+      child[level] = function() {
+        if (parent && typeof parent[level] === "function") return parent[level](fmt(arguments));
+        return child.apply(null, arguments);
+      };
+    }
+    return child;
+  }
+
+  accessories(callback) {
+    const commonKeys = ["apiHost","deviceId","bearerToken","statusPollSeconds","activePollSeconds","statusCacheTtlSeconds","statusRetryDelayMs","statusErrorLogThrottleSeconds","lowWaterLevelThreshold","batteryLevelMode"];
+    const common = {};
+    for (const key of commonKeys) {
+      if (this.config[key] !== undefined) common[key] = this.config[key];
+    }
+
+    if (this.config.advancedStatus && typeof this.config.advancedStatus === "object") {
+      Object.assign(common, this.config.advancedStatus);
+    }
+
+    const commands = Array.isArray(this.config.commands) ? this.config.commands : [];
+    const accessories = commands.map((cmd) => {
+      const cfg = Object.assign({}, common, cmd || {});
+      const type = String(cfg.commandType || "warmthCharge").toLowerCase();
+      if (type === "bathreheating" || type === "bath_reheating" || type === "reheating") {
+        cfg.commandType = "bathReheating";
+        return new PanasonicEcocuteBathReheatingValve(this.childLog(cfg.name || "Bath Reheating"), cfg);
+      }
+      cfg.commandType = "warmthCharge";
+      return new PanasonicEcocuteWarmthChargeValve(this.childLog(cfg.name || "Warmth Charge"), cfg);
+    });
+
+    this.log.info(`platform created ${accessories.length} bath extra accessories`);
+    callback(accessories);
+  }
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "homebridge-panasonic-ecocute-bath-extra-command",
+  "version": "0.2.0",
+  "description": "Homebridge platform for Panasonic Ecocute bath extra commands via Panasonic Cloud API",
+  "main": "index.js",
+  "keywords": [
+    "homebridge-plugin",
+    "homebridge",
+    "panasonic",
+    "ecocute",
+    "bath",
+    "reheating",
+    "valve"
+  ],
+  "engines": {
+    "homebridge": ">=1.6.0",
+    "node": ">=18.0.0"
+  },
+  "license": "MIT",
+  "files": [
+    "README.md",
+    "index.js",
+    "config.schema.json",
+    "docs/images/homekit-bath-extra-room-tiles.jpg",
+    "docs/images/homekit-warmth-charge-control.jpg",
+    "docs/images/homekit-reheating-active-detail.jpg"
+  ]
+}