Skip to content
BranchesTags

Repository files navigation

Homebridge Dreame Vacuum

npm version Build Status License

This Homebridge plugin allows you to control your Dreame robot vacuum through Apple's Home app and Siri. It supports both cloud-based connection via Xiaomi Mi Home or direct local IP connection.

Features

  • Main Control via Fan Service: The vacuum appears as a fan in HomeKit, allowing you to turn it on/off and adjust suction power.
  • Suction Power Control: 4 power levels (Silent, Standard, Turbo, Max).
  • Room, Zone, and Spot Cleaning: Create switches for specific rooms, zones, or spot cleaning.
  • Water Level Control (optional): If your vacuum is compatible, enable a service to adjust the mop water flow (Low, Medium, High).
  • Battery Monitoring: View battery level, charging status, and receive low battery alerts.
  • Maintenance Tracking: Monitor filter and brush wear directly from HomeKit.
  • Cloud Connection: Automatic device discovery via Mi Cloud with email/password authentication.
  • Local Control: Direct IP connection when cloud is not available or preferred.

Prerequisites

  • Homebridge installed
  • Node.js v14 or higher
  • A compatible Dreame robot vacuum
  • Device authentication token (for local connection) or Mi Home account (for cloud connection)

Device Setup

Option 1: Cloud Connection (Recommended)

  1. Install the Mi Home app on your mobile device
  2. Log in with your Mi Home account
  3. Ensure your vacuum is properly set up and visible in the app
  4. Note: Two-factor authentication is supported if enabled on your account

Option 2: Local Connection (Advanced)

  1. Install the Mi Home app on your mobile device
  2. Connect to the same network as your vacuum
  3. Go to app settings
  4. Tap multiple times on "About" to enable developer mode
  5. Navigate to "Plugins" > "Get Token"
  6. Select your vacuum and note the displayed token

Installation

  1. Install the plugin via Homebridge UI or by running: 
    npm install -g homebridge-dreame-vacuum

Alpha Install

For alpha testing builds:

npm install -g homebridge-dreame-vacuum@next

  1. Create a configuration file in your Homebridge config directory (usually ~/.homebridge/config.json) using the example below.

  2. Restart Homebridge to apply the changes.

Configuration

Cloud Connection (Recommended)

{
  "platforms": [
    {
      "platform": "DreameVacuumPlatform",
      "name": "Dreame Vacuum",
      "email": "your_email@example.com",
      "password": "your_password",
      "countryCode": "us",
      "refreshInterval": 60,
      "debug": false
    }
  ]
}

Local Connection (Advanced)

{
  "platforms": [
    {
      "platform": "DreameVacuumPlatform",
      "name": "Dreame Vacuum",
      "token": "your_device_token_here",
      "deviceId": "your_device_id_here",
      "address": "192.168.1.100",
      "countryCode": "us",
      "refreshInterval": 60,
      "debug": false
    }
  ]
}

Advanced Configuration

{
  "platforms": [
    {
      "platform": "DreameVacuumPlatform",
      "name": "Dreame Vacuum",
      "token": "your_device_token_here",
      "deviceId": "your_device_id_here",
      "countryCode": "us",
      "refreshInterval": 60,
      "debug": false,
      "enableMop": true,
      "rooms": [
        {
          "id": "16",
          "name": "Kitchen"
        },
        {
          "id": "17",
          "name": "Living Room"
        }
      ],
      "zones": [
        {
          "name": "Living Room Carpet",
          "coordinates": [2500, 2500, 3500, 3500],
          "cleanings": 2
        }
      ],
      "spots": [
        {
          "name": "Under Table",
          "coordinates": [2750, 2750]
        }
      ]
    }
  ]
}

Configuration Options

Required Parameters

  • platform: Must be "DreameVacuumPlatform"
  • name: Display name for your device in HomeKit

Cloud Connection

  • email: Your Mi Home account email
  • password: Your Mi Home account password

Local Connection

  • token: Device authentication token
  • deviceId: Unique device identifier
  • address: Local IP address of your vacuum

Optional Parameters

  • countryCode: Region code (e.g., "us", "fr", "de"). Default: "us"
  • refreshInterval: State refresh interval in seconds. Default: 60
  • debug: Enable debug logging. Default: false
  • enableMop: Enable mop control if your device supports it. Default: false

Room, Zone, and Spot Cleaning

  • rooms: For room cleaning (automatically discovered from device)

    • id: Room identifier (provided by the vacuum)
    • name: Room name (as shown in the Mi Home app)

  • zones (optional): For custom rectangular cleaning areas

    • name: Switch name in HomeKit
    • coordinates: Array of 4 numbers [x1, y1, x2, y2] defining the zone
    • cleanings: Number of cleaning passes (default: 1)

  • spots (optional): For spot cleaning specific points

    • name: Switch name in HomeKit
    • coordinates: Array of 2 numbers [x, y] defining the center point

Usage with HomeKit

Main Vacuum Control

  • The vacuum appears as a Fan service in HomeKit
    • On/Off: Start/stop cleaning
    • Rotation Speed: Adjust suction power (Silent, Standard, Turbo, Max)

Battery Service

  • Displays current battery level
  • Shows charging status
  • Provides low battery alerts

Maintenance Service

  • Tracks filter life
  • Provides maintenance notifications

Mop Control (if enabled)

  • Appears as a separate switch
  • Controls water flow for mopping (Low, Medium, High)
  • Rooms, Zones, Spots: Each configured room, zone, or spot appears as a switch in HomeKit. Toggle it to start the corresponding cleaning action. The switch will automatically turn off when done.
  • Water Level: If enabled, an additional fan service appears to control the water flow.

HomeKit Automation

Leverage HomeKit's powerful automation capabilities to schedule cleanings and create smart rules.

Automation Examples:

  • Scheduled Cleaning: "Every day at 10 AM, turn on the 'Kitchen' switch."
  • Location-Based: "When the last person leaves home, turn on the 'Living Room' and 'Bedroom' switches."
  • Battery Alerts: "When battery level drops below 20%, send a notification."
  • After Cleaning: "When vacuum returns to dock, turn off all room switches."
  • Custom Scenes: Create a "Full Clean" scene that activates all desired room switches at once.

Troubleshooting

Common Issues

  1. Connection Issues

    • Ensure your vacuum is connected to the same network as your Homebridge server
    • Verify your token and device ID are correct
    • Check if your vacuum's firmware is up to date

  2. Missing Features

    • Some features may not be available on all Dreame vacuum models
    • Ensure you're using the latest version of the plugin

  3. Cloud Connection Problems

    • Verify your email and password are correct
    • Check if your region is properly set in the Mi Home app
    • Two-factor authentication is supported - follow the prompts in the Homebridge log

Support

For support, please open an issue on GitHub.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the ISC License - see the LICENSE file for details.

Advanced Configuration

Optional Parameters

  • debug: Enable debug logging (default: false)
  • enableMop: Enable mop-related services (default: false)
  • zones: Array for configuring custom cleaning zones
  • spots: Array for configuring custom spot cleaning points

Testing

To test the plugin locally:

  1. Start Homebridge in debug mode:

    DEBUG=* homebridge -D

  2. Check the logs for any errors or warnings

  3. Verify all services appear correctly in the Home app

  4. Test each feature to ensure proper functionality

Environment Variables (for tests and local dev)

These variables are read by the test setup in test/setup.js and can be used during local development:

MIHOME_EMAIL=your_email@example.com
MIHOME_PASSWORD=your_password
DEVICE_IP=192.168.1.100
DEVICE_TOKEN=abcdef0123456789abcdef0123456789

Notes:

  • Tests skip cloud-dependent cases automatically if MIHOME_EMAIL and MIHOME_PASSWORD are not set.
  • Runtime production behavior is not affected by test-only code; any test-specific logic is gated and disabled in production.

Version History

1.0.0

  • Initial release with cloud and local connection support
  • Complete HomeKit integration with all major features
  • Support for room, zone, and spot cleaning
  • Battery and maintenance monitoring

Development

To set up the development environment:

  1. Clone the repository
  2. Install dependencies: 
    npm install
  3. Build the project: 
    npm run build
  4. Link for local development: 
    npm link

Credits

  • miio - For the Xiaomi device communication library
  • homebridge - For the HomeKit bridge framework

Disclaimer

This project is not affiliated with, authorized, maintained, sponsored or endorsed by Dreame or Xiaomi or any of its affiliates or subsidiaries. This is an independent and unofficial plugin.

Security

Important Security Notes

  1. Token Security

    • Your device token is sensitive information. Never share your config.json file or commit it to version control.
    • Add config.json to your .gitignore file.

  2. Network Security

    • Ensure your Homebridge server is running on a secure network.
    • Use a strong password for your Mi Home account when using cloud connection.

  3. Two-Factor Authentication

    • It's highly recommended to enable two-factor authentication on your Mi Home account.
    • The plugin supports 2FA and will prompt for the verification code when needed.

Additional Resources

License

ISC

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

4 stars

Watchers

0 watching

Forks

2 forks
Report repository

Releases

Packages

Contributors

Languages