Verification Request: homebridge-dyson-vis-nav

[rummeyer]

Plugin Name

homebridge-dyson-vis-nav

Link To GitHub Repo

https://github.com/rummeyer/homebridge-dyson-vis-nav

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

What it does

Exposes the Dyson 360 Vis Nav robot vacuum to Apple Home as a native Matter
robot vacuum cleaner, using the Matter support added in Homebridge 2.0. It
connects through Dyson's AWS IoT MQTT gateway, which is the only way to reach
this model — unlike the older 360 Eye and 360 Heurist, the Vis Nav does not
accept local connections.

How it differs from existing verified plugins

The two verified Dyson plugins, homebridge-dyson-pure-cool and
homebridge-dyson-bp01, cover air treatment devices. No verified plugin covers
a Dyson robot vacuum, which is a different device class, a different protocol
and a different Matter device type.

The approach itself is not novel here — homebridge-roborock-matter,
homebridge-xiaomi-roborock-matter and homebridge-aeg-robot-matter are
already verified and present their robots the same way. This does for Dyson what
those do for their manufacturers.

The reason it has to be done this way is that HAP has no robot vacuum service at
all. Apple added robot vacuums to the Home app through Matter rather than to
HomeKit, so plugins predating Homebridge 2.0 could only present a vacuum as a
fan or a set of switches. This plugin publishes the RoboticVacuumCleaner device type with the
rvcRunMode, rvcCleanMode, rvcOperationalState, serviceArea and
powerSource clusters, so the robot appears as what it is: start, pause,
resume, return to dock, cleaning modes, battery and charging state, per-room
cleaning, and faults reported in the Home app's own vocabulary rather than as a
generic error.

Two things a reviewer should know up front

Matter must be enabled on whichever bridge the plugin runs on. Because there
is no HAP equivalent, the plugin cannot expose anything without it: it logs a
clear error saying so and does nothing further, rather than registering a
misleading accessory. The README recommends giving the plugin its own child
bridge and enabling Matter there, which leaves the user's main bridge untouched.

The robot pairs separately. Apple Home does not accept bridged robot
vacuums, so Homebridge publishes it as a standalone Matter node with its own
pairing code. This is Homebridge's own handling of external accessories, not
something the plugin arranges, but it does mean the robot is not added along
with the Homebridge bridge. The README covers this as its own numbered step.

Testing

CI builds, lints and runs the checks on Node 22, 24 and 26
Three checks beyond the compiler cover what a Homebridge plugin needs but no
compiler can see: the settings-UI flags and file layout, the configuration the
custom UI hands to the Dyson client, and that the custom UI's server process
starts and signals ready
A recorded MQTT session from a physical Vis Nav is replayed in CI through the
device layer, checking it reaches every state it is known to reach — cleaning,
mapping, docking, charging, faults — with nothing logged as a warning or error
Verified end to end against a physical Dyson 360 Vis Nav paired with the Apple
Home app
On maturity, so it is not something you have to discover: the plugin was
published recently and has been exercised against one physical robot. The Dyson
protocol layer is not new code — see below — but the Matter layer is.

Credit

The Dyson cloud API and MQTT protocol handling is carried over from
matterbridge-dyson-robot
by Alexander Thoukydides, under its ISC licence, with the import paths rewritten
and the scope narrowed to this one model. The repository keeps a tool and a
documented procedure for adopting upstream fixes, so the two do not drift.
Attribution is in the licence, the README and every ported file.

[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.4.0
• Package JSON: initializer function found
• NPM Package: has not been deprecated
• GitHub Repo: version in package.json (v0.4.0) matches NPM version (v0.4.0)
• 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: code patterns flagged for manual review
• 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: 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

🔍 For Manual Review

The following items were detected and require manual review. We understand that these items may be false positives.

• Security: accesses environment files in dist/settings.js

ℹ️ Check Details

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

📋 Next Steps

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

[rummeyer]

Thanks — the flagged item is resolved rather than explained away.

dist/settings.js read a DYSON_TOKEN environment variable, carried over from the upstream project this plugin's Dyson protocol layer comes from, where it seeds an account token for integration testing. Nothing here used it and nothing documented it, so it is removed in v0.4.1 rather than kept as a false positive. There is now one documented way to supply credentials: the authorisation flow in the settings UI, which stores its token under the Homebridge storage directory.

The plugin no longer reads process.env anywhere.

/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.4.0
• Package JSON: initializer function found
• NPM Package: has not been deprecated
• GitHub Repo: version in package.json (v0.4.1) matches NPM version (v0.4.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: 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 v0.4.1 of the plugin.
• Link to the run workflow: visit →.

📋 Next Steps

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

[rummeyer]

Adding the plugin icon, which I left blank in the original request.

100×100 PNG, square with opaque corners so the UI's own rounding applies
cleanly. Original artwork, AI-generated, carrying no Dyson wordmark, logo
or product livery.

[rummeyer]

Updating this request: v1.0.0 changes the behaviour described above.

The original text says the plugin "cannot expose anything without [Matter] … rather than registering a misleading accessory". That is no longer accurate. With Matter disabled the plugin now publishes the robot over HAP as a switch (on starts a clean, off returns it to the dock), its battery, and a contact sensor for a robot that needs attention. Cleaning modes, room cleaning and pause/resume have no HAP equivalent and are deliberately left out rather than mapped onto a control that would mean something else, and the log states which of the two representations is active on every start.

package.json declares supports-hap alongside supports-matter accordingly.

What has not changed is the case for verification: with Matter enabled the robot is still published as a native RoboticVacuumCleaner node with the rvcRunMode, rvcCleanMode, rvcOperationalState, serviceArea and powerSource clusters, and that remains what distinguishes this from the two verified Dyson plugins, which cover air treatment devices. The HAP switch is a fallback for bridges without Matter, not the plugin's purpose.

Cached HAP accessories are adopted across restarts rather than republished, and are removed again when Matter is switched on, so a user never ends up with two tiles for one robot.

/check