matterbridge-dreame-vacuum

Matterbridge plugin for Dreame robot vacuums using Dreame Cloud for commands and Dreame MQTT for live state updates.

This is a fresh Matterbridge port started from the existing homebridge-dreame-vacuum-matter codebase. The Dreame integration layer is intentionally kept close to the original plugin so model-specific behavior can be carried over.

Current Status

• Reuses Dreame Cloud login, token refresh, discovery, MIoT commands, map parsing, MQTT state updates, polling fallback, and state parser.
• Reuses the existing Matter RVC state mapping for run mode, clean mode, operational state, power source, and service areas.
• Adds a Matterbridge DynamicPlatform entry point in src/module.ts.
• Adds a Matterbridge endpoint adapter around RoboticVacuumCleaner.
• Adds command bindings for identify, run mode, clean mode, pause, resume, go home, select areas, and skip area.

The exact Matterbridge RVC helper and cluster APIs should be validated against the Matterbridge version installed on the target machine. The adapter code is intentionally isolated under src/matterbridge/ so any API shape corrections stay small.

Development

npm install
npm link matterbridge
npm run build
matterbridge --add .
matterbridge

Matterbridge's development guide recommends linking Matterbridge from a local Matterbridge checkout instead of installing it as a dependency of the plugin. This avoids loading a second copy of Matterbridge or matter.js at runtime.

Configuration

{
  "name": "matterbridge-dreame-vacuum",
  "type": "DynamicPlatform",
  "username": "[email protected]",
  "password": "your-password",
  "country": "eu",
  "endpointMode": "server",
  "exposeServiceArea": true,
  "mapOverrides": []
}

Credentials can also be provided with DREAME_EMAIL and DREAME_PASSWORD.

endpointMode defaults to server. Matterbridge documents this mode as the workaround for Apple Home robotic vacuum compatibility issues because the vacuum is exposed as an independent Matter device instead of a bridged endpoint.

For Apple Home stability, the plugin updates only dynamic attributes after startup. Static RVC metadata such as supported modes, operational state list, and room map data is created with the endpoint and is not rewritten on every MQTT/poll update.

Porting Notes

The Homebridge-specific files were not copied. Matterbridge equivalents are:

• src/module.ts: plugin entry point and platform lifecycle.
• src/matterbridge/endpoint-factory.ts: creates the Matterbridge RVC endpoint.
• src/matterbridge/command-bindings.ts: connects Matterbridge commands to Dreame command handlers.
• src/matterbridge/state-sink.ts: pushes normalized Dreame state into Matterbridge clusters.

The old HomeKit automation sensors and dock switch are intentionally omitted for now. They can be recreated later as separate Matter endpoints if Apple Home automations need them.