homebridge-toshiba-plugin

Homebridge dynamic platform plugin for Toshiba Home AC Control cloud devices.

• Uses the same cloud login (username/email + password) as the official Android/iOS app.
• Connects to Toshiba cloud services (mobileapi.toshibahomeaccontrols.com) and Azure IoT AMQP push channel.
• Auto-discovers registered AC units from your cloud account.
• Exposes devices to Apple Home with real-time updates + fallback polling.
• Mirrors key cloud API flow from decompiled app assemblies (Login, RegisterMobileDevice, GetConsumerACMappingV2, GetCurrentACStateV2, GetCurrentACStateByUniqueDeviceIdV2).

Features

• Cloud authentication + automatic SAS token refresh.
• Login payload includes Toshiba BrandId and mobile registration uses username-prefixed device id format (app parity).
• Mobile cloud registration supports both response formats used by the app backend (SasToken or HostName + DeviceId + PrimaryKey).
• Startup self-recovery for transient cloud/network errors with exponential retry backoff.
• Device auto-discovery and cache reconciliation.
• Resilient discovery parsing (malformed cloud entries are skipped instead of aborting discovery).
• Automatic AMQP reconnect with exponential backoff after cloud disconnects.
• AMQP operation timeout guards (connect/send/disconnect) with failure-triggered recovery.
• Poll/discovery overlap protection to avoid queue buildup during slow cloud responses.
• Per-device polling endpoint failover between GetCurrentACStateByUniqueDeviceIdV2 and GetCurrentACStateV2 (one device's 403 no longer forces global fallback).
• If both polling endpoints return 403 for a device, polling is temporarily paused for that device and retried later while AMQP remains active.
• Command coalescing (500ms debounce) to mirror native app command burst behavior.
• No-op command suppression (skips AMQP send when requested state already matches current effective state).
• Command preflight online check (GetAllDeviceState) before AMQP sends, with offline protection.
• Short-lived connection-state cache on command precheck to reduce command latency and cloud rate-limit pressure.
• If online precheck itself fails (timeout/network/transient cloud error), command falls back to best-effort send instead of hard-failing control.
• Command-send retries with detailed logs for transient AMQP send failures.
• Defensive payload parsing and malformed-cloud-update guards.
• Single accessory model: each Toshiba AC is exposed as one HomeKit HeaterCooler service (no extra Fan/Switch/Sensor services).
• HeaterCooler control:
  • Power (Active)
  • Mode (Auto, Cool, Heat)
  • Target temperature
  • Fan speed
  • Swing mode
  • Indoor temperature
• Robust error handling and detailed Homebridge logs.

RotationSpeed Mapping Profile

The plugin keeps a single HomeKit HeaterCooler tile and maps Toshiba-specific behavior from RotationSpeed:

• 0%:
  • fan AUTO
  • eco OFF
  • high power OFF
  • indoor silent OFF
  • outdoor silent OFF
• > 0% && <= 10%:
  • indoor silent ON (QUIET fan)
  • outdoor silent ON (CDU_SILENT_1/2)
  • eco requested by profile, but Toshiba MeritA is single-choice so this band prioritizes outdoor silent
• > 10% && <= 20%:
  • indoor silent ON (QUIET fan)
  • eco ON (ECO)
  • outdoor silent OFF
• > 20% && <= 30%:
  • indoor silent OFF
  • eco ON (ECO)
  • outdoor silent OFF
• > 30% && < 100%:
  • eco OFF
  • high power OFF
  • indoor silent OFF
  • outdoor silent OFF
• 100%:
  • high power ON (HIGH_POWER)
  • eco OFF
  • indoor silent OFF
  • outdoor silent OFF
• Power selection is derived from RotationSpeed:
  • 0% => middle (POWER_75)
  • 1..33% => POWER_50
  • 34..66% => POWER_75
  • 67..100% => POWER_100
• Fan mode selection for non-silent speeds uses nearest discrete Toshiba step by absolute difference.
• Rotation slider stability:
  • Plugin keeps your last explicit Home app slider percentage while cloud state still matches the same mapped Toshiba tuple.
  • This prevents Home app “jumping” to quantized fan buckets after a successful set.

Note: Toshiba Merit A is a single field in cloud payload, so overlapping low-speed modes use precedence: HIGH_POWER > CDU_SILENT_1/2 > ECO > OFF.

Install

npm install
npm run build

For local Homebridge development:

npm link
homebridge -D

Homebridge Config

{
  "platform": "ToshibaSmartAC",
  "name": "Toshiba Smart AC",
  "username": "[email protected]",
  "password": "your-password",
  "pollIntervalSeconds": 120,
  "discoveryRefreshMinutes": 30,
  "requestTimeoutSeconds": 60,
  "httpRetries": 5
}

Notes

• This plugin controls devices via Toshiba cloud, not local LAN.
• Real-time state updates come from cloud AMQP; polling is only a fallback.
• Some Toshiba app features are not directly representable by native HomeKit HeaterCooler characteristics and are not exposed as separate tiles/services.
• Not mapped on purpose: Pure/ionizer, self-cleaning, floor/comfort/fireplace variants, and other non-HeaterCooler native controls.

Development

npm run lint
npm run build

Publish

# Optional: bump version first
npm run version:bump:revision
# or
npm run version:bump:minor
npm run version:bump:major

# Preview publish
npm run publish:plugin:dry-run

# Publish to npm (latest tag)
npm run publish:plugin

Optional flags:

# Use a custom dist-tag
npm run publish:plugin -- --tag beta

# If npm account uses 2FA
npm run publish:plugin -- --otp 123456

Troubleshooting

• Verify your Toshiba app credentials.
• Check Homebridge logs for HTTP API / AMQP API messages.
• If a child bridge appears to stop with empty plugin logs, make sure you are running the latest plugin build:
  • npm run build
  • restart Homebridge after updating.
• If login works but no accessories appear, confirm devices are visible in the official Toshiba app account.
• If accessories become stale, restart Homebridge and verify cloud connectivity.