Verification Request: homebridge-mitsubishi-heatpumpuest

[ukaratay]

Plugin Name

homebridge-mitsubishi-heatpump

Link To GitHub Repo

https://github.com/ukaratay/homebridge-mitsubishi-heatpump

Plugin Icon (Optional)

No response

The plugin does not offer the same nor less functionality than that of any existing verified plugin.

🟢 Yes

The plugin successfully installs and does not start unless it is configured.

🟢 Yes

The plugin does not require the user to run Homebridge in a TTY or with non-standard startup parameters, even for initial configuration.

🟢 Yes

The plugin does not contain any analytics or calls that enable you to track the user.

🟢 Yes

If the plugin needs to write files to disk (cache, keys, etc.), it stores them inside the Homebridge storage directory.

🟢 Yes

The plugin does not throw unhandled exceptions, the plugin must catch and log its own errors.

🟢 Yes

More Information

Relationship to homebridge-kumo (verified)

homebridge-kumo is verified and targets the same hardware, so I want to be upfront about it rather than have you find it.

It talks to the legacy Kumo Cloud API. In early 2025 Mitsubishi migrated to the Comfort v3 cloud, and homebridge-kumo has not worked against it since. Its issue tracker carries that as #116, #117, #118, #119 and #120, and on 2025-03-31 its maintainer said in #116:

It is but I just don't have the time to try to work on a new API. If HA can solve the problem, I'll see if it is easy to update the Homebridge plugin.

I'm happy to accept pull requests too.

Its last commit and last npm publish are both 2023-12-27, and #111 ("Homebridge v2.0 support") is still open. I am not asking you to un-verify it, and I would rather it were maintained than not. But users on current firmware have no working verified option today.

This plugin speaks Comfort v3 (REST + Socket.IO) and adds function that has no equivalent there:

	homebridge-kumo	this plugin
Cloud API	legacy Kumo Cloud (non-functional since 2025)	Comfort v3
Primary service	Thermostat	HeaterCooler with a real IDLE state
Fan speed	not exposed	5 speeds + fan-auto on a linked Fanv2
Vane / swing	not exposed	SwingMode + opt-in Slats tilt angles
Updates	polling	Socket.IO streaming, polling only as fallback
Wireless sensor	not exposed	temperature, humidity, battery + low-battery
Homebridge 2.x	open issue #111	supported, CI on 1.6-era and 2.x API surface

Relationship to homebridge-mitsubishi-comfort (not verified)

This is a hard fork of burtherman/homebridge-mitsubishi-comfort at v1.8.2, which is not verified and is actively maintained by its author. I am not asking for anything that affects it. Attribution, the Apache-2.0 §4(b) statement of changes, and the third-party notices are in NOTICE. The fork diverged on the HomeKit service graph (HeaterCooler rather than Thermostat), which is a breaking change for end users and is documented as such in the README.

Notes against the individual criteria

• Does not start unless configured. With no platform block, the platform is never constructed. With a partial block, validatePlatformConfig logs one error naming the remedy and the platform stays inert: no accessories, no timers, no network. Verified by installing 2.1.0 from the registry into a clean homebridge 2.2.1 with a second, unrelated platform plugin alongside, and starting it on a bare {"platform": "KumoV3"} block: the process stays up, the other plugin loads, and the bridge publishes. This was a real bug through 2.0.1, fixed in 2.1.0 — the constructor threw, and since Homebridge does not guard a platform constructor that took the whole process down. Please review 2.1.0 or later.
• Unhandled exceptions. The constructor cannot throw, pinned by test/config-validation.test.ts. Socket.IO handlers and HAP onGet/onSet handlers catch their own errors.
• Disk. The plugin writes no files at all, so the storage-directory rule is moot. Local-control credentials are held in memory only and deliberately never persisted.
• Analytics. The only outbound destinations are app-prod.kumocloud.com / socket-prod.kumocloud.com and, when localControl is enabled, the user's own units on the LAN. No telemetry, no version ping, no error reporting.
• Node. CI runs the full suite on 20.19, 22 and 24 (.github/workflows/test.yml). engines.node is ^20.19.0 || ^22.12.0 || >=24.0.0; the floor is require(esm), since the plugin builds to CommonJS and node-fetch v3 is ESM-only.
• Install. No preinstall / install / postinstall script anywhere in the runtime tree. Published with SLSA provenance through npm Trusted Publishing over OIDC (.github/workflows/publish.yml); there is no NPM_TOKEN in the repository.
• Transports. Declares supports-hap. It publishes HAP accessories only — vane and swing need FanControl features Homebridge does not yet expose over Matter, and those are the reason the plugin exists.

[github-actions]

🔴 Failed Checks

• GitHub Repo: could not check package.json version as Connect Timeout Error (attempted address: api.github.com:443, timeout: 10000ms)
• Config Schema JSON: schema is invalid - required should not be a boolean property on individual fields. In JSON Schema, required must be an array at the object level listing required property names. Remove "required": true/false from individual properties and use "required": ["property1", "property2"] at the object level instead.
• GitHub Repo: should contain releases

🟢 Passed Checks

• Installation: successfully installed
• Package JSON: homepage exists
• Package JSON: bugs.url exists and seems a valid URL
• Package JSON: keywords exist and contain 'homebridge-plugin'
• Package JSON: keywords declare the supported transports ('supports-hap' and/or 'supports-matter')
• Package JSON: 'preinstall' in scripts is not present
• Package JSON: 'install' in scripts is not present
• Package JSON: 'postinstall' in scripts is not present
• Package JSON: engines.node property is compatible with Node 22
• Package JSON: engines.node property is compatible with Node 24
• Package JSON: engines.homebridge property is compatible with Homebridge 2.2.1
• Package JSON: initializer function found
• NPM Package: has not been deprecated
• Config Schema JSON: exists and is valid JSON
• Config Schema JSON: contains a valid pluginAlias
• Config Schema JSON: pluginAlias matches the platform/accessory registered in code
• Config Schema JSON: the pluginType is set to 'platform'
• Config Schema JSON: contains a name schema property
• Dependencies: homebridge is not declared as a runtime/peer/bundled dependency
• Dependencies: hap-nodejs is not declared as a runtime/peer/bundled dependency
• Security: no known vulnerabilities in dependencies
• Security: no unsafe code patterns detected
• Security: no privilege escalation attempts detected
• GitHub Repo: repository is public
• GitHub Repo: repository is not archived
• GitHub Repo: issues are enabled

ℹ️ Check Details

• These checks were run against v2.1.0 of the plugin.
• Link to the run workflow: visit →.

📋 Next Steps

• Once you have fixed these failures, comment /check on this issue to run the checks again — your request will not move forward until the checks are re-run.
• If updating your package.json and config.schema.json files, don't forget to publish a new version to NPM.
• Remember this is an automatic script: if you think something has been marked as a failure in error, let us know with a reply.
• Feel free to ask any questions you have by replying to this issue.

[ukaratay]

Thanks — one of the three was a real bug on my side, and I think the other two were transient. Details below, and I've published v2.1.1 with the fix.

Config Schema JSON: required should not be a boolean property on individual fields — real, fixed in v2.1.1.

config.schema.json was marking name, username, password and both ends of a mirror entry with draft-3 style "required": true on each property. Both levels now use the array form on the enclosing object:

"schema": {
  "type": "object",
  "required": ["name", "username", "password"],
  "properties": { ... }
}

It survived this long because nothing broke — the UI runs convertSchemaToDraft6 before rendering, so the form enforced the fields either way. Your check reads the file as JSON Schema rather than as UI input, which is the correct reading. There's now a regression test on the shape (test/config-schema.test.ts), verified by reintroducing the old form and confirming it fails.

GitHub Repo: could not check package.json version as Connect Timeout Error — this looks like a network blip on the runner: attempted address: api.github.com:443, timeout: 10000ms.

GitHub Repo: should contain releases — I believe this is collateral from the same timeout, since both failures are api.github.com calls in the same run. The repo has three published, non-draft releases, and a fourth now:

$ curl -s https://api.github.com/repos/ukaratay/homebridge-mitsubishi-heatpump/releases | jq -r '.[] | "\(.tag_name) draft=\(.draft)"'
v2.1.1 draft=false
v2.1.0 draft=false
v2.0.1 draft=false
v2.0.0 draft=false

Happy to be told otherwise if the check is looking for something else. Re-running now.

/check

[github-actions]

🟢 Passed Checks

• Installation: successfully installed
• Package JSON: homepage exists
• Package JSON: bugs.url exists and seems a valid URL
• Package JSON: keywords exist and contain 'homebridge-plugin'
• Package JSON: keywords declare the supported transports ('supports-hap' and/or 'supports-matter')
• Package JSON: 'preinstall' in scripts is not present
• Package JSON: 'install' in scripts is not present
• Package JSON: 'postinstall' in scripts is not present
• Package JSON: engines.node property is compatible with Node 22
• Package JSON: engines.node property is compatible with Node 24
• Package JSON: engines.homebridge property is compatible with Homebridge 2.2.1
• Package JSON: initializer function found
• NPM Package: has not been deprecated
• GitHub Repo: version in package.json (v2.1.1) matches NPM version (v2.1.1)
• Config Schema JSON: exists and is valid JSON
• Config Schema JSON: contains valid JSON Schema
• Config Schema JSON: schema has valid type property
• Config Schema JSON: schema has valid properties for object type
• Config Schema JSON: contains a valid pluginAlias
• Config Schema JSON: pluginAlias matches the platform/accessory registered in code
• Config Schema JSON: the pluginType is set to 'platform'
• Config Schema JSON: contains a name schema property
• Dependencies: homebridge is not declared as a runtime/peer/bundled dependency
• Dependencies: hap-nodejs is not declared as a runtime/peer/bundled dependency
• Security: no known vulnerabilities in dependencies
• Security: no unsafe code patterns detected
• Security: no privilege escalation attempts detected
• Runtime: homebridge installed successfully
• Runtime: no config - homebridge should start without plugin configuration and plugin should not load
• Runtime: platform only - plugin should start with just platform property
• Runtime: minimal required - plugin should start with minimal required configuration
• Runtime: full config - plugin should start with comprehensive configuration
• Runtime: network resilience - plugin should handle network failures without crashing
• Runtime: plugin shuts down cleanly within 12s of SIGTERM
• Runtime: plugin restarts cleanly without port conflicts
• GitHub Repo: repository is public
• GitHub Repo: repository is not archived
• GitHub Repo: issues are enabled
• GitHub Repo: contains releases

ℹ️ Check Details

• These checks were run against v2.1.1 of the plugin.
• Link to the run workflow: visit →.
• External HTTP requests detected:
  • 📡 https://app-prod.kumocloud.com/v3/login
    Methods: POST | Count: 3 | Scenarios: full config, minimal required, network resilience

📋 Next Steps

All checks passed successfully, nice work! Your plugin and/or icon will now be manually reviewed by the Homebridge team.