@mibridge/matterbridge

Matterbridge plugin that exposes Xiaomi smart home devices as native Matter devices, built on top of the mibridge SDK.

Overview

@mibridge/matterbridge bridges the mibridge SDK with Matterbridge, making Xiaomi devices (starting with Dreame robot vacuums) available as Matter-native accessories in any compatible smart home controller — Apple Home, Google Home, Home Assistant, etc.

Device states and error codes are mapped to Matter 1.4 cluster semantics via @mibridge/core, so no per-device translation logic is needed in the plugin.

Prerequisites

• Matterbridge >= 3.4.0
• Node.js >= 20
• A Xiaomi account with linked devices
• Xiaomi Cloud session tokens (obtained via @mibridge/cli)

Installation

npm install -g @mibridge/matterbridge
matterbridge -add @mibridge/matterbridge

Getting your session tokens

Use the mibridge CLI to authenticate and retrieve your session tokens:

npm install -g @mibridge/cli
mibridge login --region de

This will produce a session with userId, ssecurity, and serviceToken — paste these into the plugin configuration.

Configuration

In the Matterbridge frontend, open the plugin settings and fill in:

| Field | Description | |-------|-------------| | session.userId | Your Xiaomi user ID | | session.ssecurity | Xiaomi ssecurity token | | session.serviceToken | Xiaomi serviceToken | | region | Xiaomi Cloud region (de, cn, us, sg, ru, tw, in, i2) | | pollInterval | Status polling interval in ms (default: 5000) | | verbose | Enable detailed logs at startup |

Supported devices

| Category | Models | |----------|--------| | Robot vacuum | Dreame (all MIoT-based models) |

Additional Xiaomi device categories will be added as @mibridge/core expands its coverage.

Matter integration

Devices are exposed using the following Matter clusters:

• RvcRunMode — idle / cleaning / mapping modes
• RvcCleanMode — vacuum / mop / vacuum+mop
• RvcOperationalState — docked / running / paused / seeking charger / error
• ServiceArea — per-room zone selection
• PowerSource — battery level

Error codes from the device are mapped to Matter VacuumErrorCode semantics (dust bin, water tank, mop pad, navigation errors, etc.) via @mibridge/core.

Related packages

| Package | Description | |---------|-------------| | @mibridge/core | SDK — device control, authentication, Matter-aligned state | | @mibridge/cli | CLI — terminal interface for devices and session management |

Source: github.com/iblur01/mibridge

License

MIT — see LICENSE for details.