Homebridge Eufy RoboVac

[!IMPORTANT] Homebridge <v1.8.4 Information

This plugin has a scoped name with a '.' in it. You'll need Homebridge v1.8.5 or greater to run it.

This is a plugin to control the Eufy RoboVac via Homebridge.

It is recommended to run this plugin as a child bridge.

Multiple child bridges will enable you to control multiple Eufy RoboVacs. To configure this scenario, you must manually edit Homebridge's config.json.

Configuration

This plugin can be configured using homebridge-config-ui-x. There are 4 required fields.

• Name - the name for your RoboVac
• IP Address - the IP address of your RoboVac. Configure your DHCP server to serve a static IP address to your RoboVac for the best experience.
• Tuya Device ID and Tuya Device Key - these can be obtained by following https://github.com/gtalusan/eufy-device-id-js

HomeKit (HAP)

The default accessory is a switch that will run the Eufy RoboVac in "auto" mode. As part of this accessory, a sub-switch is also available to turn on the vacuum's location beacon.

You may also create arbitrary room switches. A room switch will direct your Eufy RoboVac to clean an arbitrary set of rooms. Use a comma-delimited list corresponding to the room numbers on your Eufy RoboVac's map.

Matter over Thread (Homebridge 2.0+)

When running on Homebridge 2.0 (beta.85 or later) with Matter enabled, this plugin automatically exposes your Eufy RoboVac as a native Matter Robotic Vacuum Cleaner device. No additional configuration is required — if Matter is available and enabled, it just works alongside the existing HAP accessories.

Matter Capabilities

| Feature | Matter Cluster | Description | |---|---|---| | Run Mode | rvcRunMode | Idle / Cleaning modes | | Clean Mode | rvcCleanMode | Vacuum mode | | Operational State | rvcOperationalState | Running, Paused, Docked, Charging, Seeking Charger, Error | | Error State | rvcOperationalState | Mapped error codes with semantic details | | Battery | powerSource | Battery level (0.5% increments), charge level (Ok/Warning/Critical) | | Room Selection | serviceArea | Maps your configured room switches to Matter areas (see below) | | Play Sound to Locate | identify | Uses HomeKit's native "Play Sound to Locate" action to trigger the locate beacon |

Error State Mapping

This plugin maps all 21 Eufy RoboVac error codes to Matter.js RvcOperationalState.ErrorState enum values, providing semantic device error reporting:

| Eufy Error | Matter ErrorState | Meaning | |---|---|---| | no error | NoError (0) | Device operating normally | | wheel stuck / wheel suspended / device trapped | Stuck (65) | Device is mechanically stuck or trapped | | wheel module stuck | WheelsJammed (76) | Wheels are jammed | | side brush / rolling brush stuck | BrushJammed (77) | Brush mechanism is jammed | | low battery | LowBattery (72) | Battery level is critically low | | magnetic boundary / restricted area detected | CannotReachTargetArea (73) | Device cannot reach target area | | insert dust collector | DustBinMissing (66) | Dust bin is missing | | laser/wall sensor errors | NavigationSensorObscured (78) | Sensors are blocked or dirty | | base blocked | Stuck (65) | Charging dock is blocked |

Consumable Maintenance Alerts (battery, wheel module, brush, suction fan, sensors) are logged as warnings and do not trigger error states, as they represent maintenance needs rather than operational failures.

Room Selection via Matter

If you have roomSwitches configured, they are automatically mapped to Matter Service Areas:

• Each room switch becomes a selectable area in the Matter ecosystem
• All areas are assigned to a single floor map ("Home")
• Area names come directly from your room switch name field
• You can select/deselect areas and the vacuum will clean the corresponding rooms
• An empty area selection resets to "all areas"

Enabling Matter

1. Update to Homebridge 2.0 (beta.85+)
2. Enable Matter in your Homebridge settings
3. Run this plugin as a child bridge (recommended)
4. The plugin will log Matter is available and enabled. on startup