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.

Compatibility

This plugin has been verified with Panasonic Ecocute models that support and have been set up with the official “スマホでおふろ” app.

For unsupported Panasonic models or other ECHONET Lite compatible Ecocute devices, please use homebridge-echonetlite2mqtt-valve instead.

⚠️ Migration Warning: Remove the old ECHONET Lite / MQTT bath valve first

⚠️ Important: remove the old ECHONET Lite / MQTT bath valve before using this plugin.

Remove old homebridge-echonetlite2mqtt-valve accessories from Homebridge config, then remove the old child bridge from the Apple Home app. Do not control the same Ecocute command from both plugins at the same time.

Recommended migration steps:

1. Remove the old homebridge-echonetlite2mqtt-valve accessory from Homebridge config.
2. Restart Homebridge.
3. Remove the old child bridge from the Apple Home app on iPhone/iPad.
4. Add or keep only the Panasonic Cloud accessories from this plugin.
5. Confirm that the old bridge name, such as お風呂, no longer appears.

Features

• Exposes Panasonic Ecocute bath extra commands to HomeKit as Valve accessories.
• Supports Bath Auto / ふろ自動 via Panasonic Cloud API automaticBathOperation.
• 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, access tokens, refresh tokens, ID tokens, passwords, or hashedCorporationPassword.

Recommended credential handling:

• Prefer tokenFile instead of pasting a long Bearer Token directly into config.json.
• Keep token and OAuth refresh files under a private local path such as /homebridge/secrets/.
• Never include token files, mitmproxy captures, cookies, or Homebridge config.json with real credentials in npm packages, GitHub repositories, screenshots, issues, or support requests.
• oauthClientId is an advanced override and is normally left blank. It is not your Club Panasonic ID or password.

Platform Configuration

Example platform configuration:

{
  "platform": "PanasonicEcocuteBathExtra",
  "name": "Panasonic Ecocute Bath Extra",
  "apiHost": "https://app.dhw.apws.panasonic.com",
  "deviceId": "YOUR_DEVICE_ID",
  "tokenFile": "/homebridge/secrets/panasonic_ecocute_cloud.env",
  "autoRefresh": true,
  "oauthRefreshFile": "/homebridge/secrets/panasonic_ecocute_oauth_refresh.env",
  "refreshBeforeExpireHours": 24,
  "commands": [
    {
      "type": "bathReheating",
      "name": "エコキュート 追いだき",
      "displayName": "追いだき"
    },
    {
      "type": "warmthCharge",
      "name": "エコキュート ぬくもりチャージ",
      "displayName": "ぬくもりチャージ"
    }
  ],
  "entrySignOccupancySensorEnabled": true,
  "entrySignOccupancySensorName": "浴室在室モニター"
}

Authentication-related options:

• tokenFile: recommended Bearer Token file. The file may contain PANASONIC_ECOCUTE_BEARER_TOKEN=... or bearerToken=....
• bearerTokenFile: legacy alias for tokenFile. Usually leave this blank.
• bearerToken: legacy direct token setting. Prefer tokenFile for normal use.
• autoRefresh: enables OAuth refresh when a valid local OAuth refresh file is configured.
• oauthRefreshFile: local secret env file containing the OAuth refresh token and client ID captured from the user’s own official app session.
• refreshBeforeExpireHours: how many hours before token expiration to refresh. Default is 24. Minimum is 1. Only whole-hour values are supported in the Homebridge UI.
• oauthTokenUrl: advanced OAuth token endpoint override. Usually leave the default value.
• oauthClientId: advanced override. Usually leave this blank because the plugin reads PANASONIC_ECOCUTE_CLIENT_ID from oauthRefreshFile.
• refreshRetrySeconds: log throttle for repeated refresh failures.

OAuth auto refresh is optional. Users who do not configure autoRefresh can continue updating tokenFile manually.

Commands

Supported command types:

• automaticBathOperation: Bath Auto / ふろ自動.
  • ON sends { "automaticBathOperation": true }.
  • OFF sends { "automaticBathOperation": false }.
  • State is based on automaticBathOperation true/false.
  • bathOperationMode is not exposed as a HomeKit sensor.
• warmthCharge: Warmth Charge / ぬくもりチャージ.
  • ON/OFF uses Panasonic Cloud API warmthCharging.
  • State is based on warmthCharge.status.
  • ON is blocked when warmthCharge.permission is not true.
• bathReheating: Bath Reheating / 追いだき.
  • ON/OFF uses Panasonic Cloud API bathReheating.
  • State is based on bathReheating true/false.

Platform Common Sensors

These sensors are configured at the platform level, not inside each command.

Warmth Charge Permission Sensor

• Optional HomeKit sensor for warmthCharge.permission.
• Applied only to the Warmth Charge command.
• Only the sensor type is configurable. The sensor name is fixed because HomeKit may display additional service names using the parent accessory name.
• This avoids showing Warmth Charge specific settings when configuring Bath Reheating.

Entry Sign Occupancy Sensor

• Exposes Panasonic API entrySign as one HomeKit Occupancy Sensor.
• This is a platform-common sensor, not a per-command Valve setting.
• entrySign: true means occupancy detected.
• entrySign: false means occupancy not detected.
• This sensor is read-only and does not send any control command.

Screenshots

Screenshots below show the platform UI and verified HomeKit behavior.

OAuth Auto Refresh

Version 0.5.0 can refresh the Panasonic Cloud access token when autoRefresh is enabled and oauthRefreshFile contains a valid refresh token and client ID from the user’s own official app session.

The plugin does not ask for or store your Club Panasonic password. Do not enter your Club Panasonic ID or password into the Homebridge UI.

When an access token is rejected by Panasonic Cloud with an authentication error, the plugin attempts OAuth refresh, updates the local token files, and retries safe GET status requests. Non-GET HomeKit write requests are not automatically retried after refresh.

Future Work

Possible future additions can be added after confirming more Panasonic Cloud API capabilities.

Bathroom Occupancy Sensor Note

The bathroom occupancy sensor follows the Panasonic app/device behavior. In local testing, occupancy was detected after about 15 seconds and remained active for several minutes.

Version History

0.5.0

• Added OAuth auto refresh support for Panasonic Cloud access tokens.
• Added autoRefresh, oauthRefreshFile, refreshBeforeExpireHours, oauthTokenUrl, oauthClientId, and refreshRetrySeconds platform settings.
• Added tokenFile support as the recommended Bearer Token storage method.
• Kept bearerTokenFile as a legacy alias for tokenFile.
• Added authentication guard behavior for 401 / 403 / Q2E05 Panasonic Cloud authentication errors.
• Blocks HomeKit real write commands while Panasonic Cloud authentication is in an error state.
• Reloads the Bearer Token from tokenFile before requests so externally updated tokens can be applied without editing the Homebridge UI.
• Retries safe GET status requests after successful OAuth refresh.
• Does not automatically retry non-GET HomeKit write requests after OAuth refresh.
• Uses refreshBeforeExpireHours in the Homebridge UI with a minimum of 1 hour. Only whole-hour values are exposed.
• Improved credential handling documentation and npm package secret-file audit checks.

0.4.5

Stable release consolidating the post-0.4.1 local fixes and startup tuning.

• Improved HomeKit read handler responsiveness by returning cached values immediately.
• Avoided Homebridge characteristic write errors during temporary Panasonic Cloud command failures.
• Added fixed startup cloud status refresh order after Homebridge restart.
• Added per-command startup delay settings:
  • Bath Auto / ふろ自動
  • Bath Reheating / 追いだき
  • Warmth Charge / ぬくもりチャージ
  • Bathroom Occupancy / 浴室在室
• Verified final local startup delays of 2s / 4s / 6s / 8s with Panasonic Cloud and the official app remaining stable.
• Kept normal polling balanced at status polling 120s, active polling 60s, cache TTL 10s, and error log throttle 300s.
• Improved migration documentation for users moving from homebridge-echonetlite2mqtt-valve.
• Added a prominent migration warning with a red badge and HTML warning block.
• Documented that the old ECHONET Lite / MQTT child bridge should be removed from the Apple Home app.

0.4.1

• Added support notes for the bathroom occupancy sensor behavior.
• Improved default cloud polling/cache/error-throttle settings for Panasonic Cloud API stability.
• Avoid throwing Homebridge characteristic write-handler errors on temporary Panasonic Cloud command failures.
• Improved HomeKit read handlers so cached values are returned immediately instead of waiting for Panasonic Cloud status requests.
• Added a red migration warning for users moving from homebridge-echonetlite2mqtt-valve.
• Documented that the old ECHONET Lite / MQTT child bridge should be removed from the Apple Home app.
• Documented that duplicate control of automaticBathOperation from multiple plugins should be avoided.

0.4.0

• Added Bath Auto / ふろ自動 as a HomeKit Valve command.
• Added Panasonic Cloud API automaticBathOperation support.
• Bath Auto ON sends { "automaticBathOperation": true }.
• Bath Auto OFF sends { "automaticBathOperation": false }.
• Bath Auto state is based only on automaticBathOperation.
• bathOperationMode is not exposed as a HomeKit sensor.
• Added compatibility guidance for Panasonic Ecocute models set up with the official “スマホでおふろ” app.

0.3.0

• Added platform-common HomeKit Occupancy Sensor support for Panasonic API entrySign.
• Moved Warmth Charge permission sensor type to platform-common settings.
• Platform-common sensor settings are no longer shown per Bath Command.
• Cleaned up normal logs so Warmth Charge related state is easier to read.
• Moved waterHeatingStatus change logs to debug level.
• No change to automatic Warmth Charge behavior.

0.2.3

• Changed npm README screenshots to equal-width three-column thumbnails.
• Screenshots are clickable and open the full-size images.
• No functional code changes from 0.2.2.

0.2.2

• Reduced README screenshot display size on npm.
• Changed screenshots to clickable HTML thumbnails with fixed widths.
• No functional code changes from 0.2.1.

0.2.1

• Fixed npm README screenshot links by using absolute package CDN URLs.

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

• Local test: Warmth Charge OFF from HomeKit is treated as no-op when warmthCharge is not currently active, avoiding unnecessary Cloud OFF commands after a blocked ON.