homebridge-kumo-custom

Custom Homebridge platform plugin that talks directly to Mitsubishi Kumo Cloud indoor units over the local network. Use it to surface heater/cooler, fan, and vane controls inside Apple HomeKit through the standard Homebridge Plugin Browser.

Features

• Discovers multiple Kumo units and exposes each as a HeaterCooler service
• Full set of characteristics: power, heating/cooling mode, temperature setpoints, fan speed, and swing/vane control
• Optional Kumo Cloud credential support to auto-import unit IP/password/crypto serial details
• Local HTTP communication with retry/backoff, fault detection, and automatic cleanup when accessories are removed

Installation

1. Make sure Homebridge is running v1.3+ and Node.js v14+.
2. Install via npm:

sudo npm install -g homebridge-kumo-custom

3. Restart Homebridge and add/update the platform config (see below).

Configuration

Option A – Use Kumo Cloud credentials (recommended)

{
  "platform": "KumoCustom",
  "name": "Kumo Custom",
  "useCloud": true,
  "cloudEmail": "[email protected]",
  "cloudPassword": "your-kumo-password",
  "updateInterval": 30
}

• On startup the plugin logs into app.kumocloud.com, pulls each zone's IP, encrypted password, and crypto serial, and then talks to the indoor unit locally.
• Your credentials remain on your Homebridge server only; store them on a trusted machine.

Option B – Manual unit definitions

{
  "platform": "KumoCustom",
  "name": "Kumo Custom",
  "updateInterval": 30,
  "units": [
    {
      "name": "Living Room AC",
      "ip": "192.168.1.245",
      "password": "optionalEncryptedPassword",
      "cryptoSerial": "optionalCryptoSerial"
    }
  ]
}

• updateInterval defaults to 30 seconds; minimum is 10 seconds.
• password/cryptoSerial are only needed when your indoor unit enforces local auth.

Development

npm install
# add your preferred lint/test scripts if needed

• The plugin entry point is index.js. Config UI metadata lives in config.schema.json.
• Each configured unit gets its own KumoAccessory handler; polling begins after Homebridge finishes launching.

Publishing & Plugin Browser Availability

1. GitHub

   • Create/push to https://github.com/Meteteus/KUMO-Homebridge (this repo).

2. npm

   • Ensure npm whoami shows the publisher account.
   • Update package.json version for each release.
   • Publish with npm publish --access public.
   • Once on npm with the homebridge-plugin keyword (already included), Homebridge Plugin Browser lists it automatically.

3. Updating

   • Bump the version field.
   • Run npm publish again.
   • Users can update directly from the Homebridge UI.

License

MIT © Mat - Braz Sound LLC