search

thoukydides / homebridge-aeg-robot

AEG RX9 / Electrolux Pure i9 robot vacuum plugin for Homebridge
https://www.thouky.co.uk
ISC License
5 stars 0 forks source link
aeg cleaner electrolux homebridge homebridge-plugin pure-i9 pure-i9-1 pure-i9-2 robot robot-vacuum rx9 rx9-1 rx9-2 vacuum vacuum-cleaner

readme

homebridge-aeg-robot

npm npm npm Build and Lint verified-by-homebridge

AEG RX 9 / Electrolux Pure i9 robot vacuum plugin for Homebridge.

AEG, Electrolux, and Zanussi are trademarks of AB Electrolux.

Installation

  1. Use the AEG app to add the RX series robot vacuum to your AEG/Electrolux/Zanussi account.
  2. Install this plugin using: npm install -g homebridge-aeg-robot
  3. Edit config.json and add the Homebridge AEG Robot Vacuum platform (see example below).
  4. Run Homebridge.

Alternatively, use Homebridge Config UI X to install and configure this plugin.

Example config.json

{
    "platforms":
    [{
        "platform": "Homebridge AEG Robot Vacuum",
        "username": "rx@gmail.com",
        "password": "Passw0rd!"
    }]
}

The username and password should match those used to login to your account in the AEG iPhone app. All suitable robot vacuums associated with the account will be added to HomeKit (those reporting a model name of PUREi9). Unsupported appliances, such as air purifiers or RX8 robot vacuums, will be ignored.

Advanced Configuration

Additional settings can be included in config.json to customise the behaviour or enable special debug features:

{
    "platforms":
    [{
        "platform":       "Homebridge AEG Robot Vacuum",
        "username":       "rx@gmail.com",
        "password":       "Passw0rd!",
        "pollIntervals": {
            "statusSeconds":        5,
            "serverHealthSeconds":  60,
            "feedSeconds":          300,
            "cleanedAreaSeconds":   60,
        },
        "hideServices":   ["Battery", "Contact Sensor", "Fan", "Filter Maintenance", "Occupancy Sensor", "Switch Clean", "Switch Home"],
        "debug":          ["Run API Tests", "Run Unsafe API Tests", "Log API Headers", "Log API Bodies", "Log Debug as Info"]
    }]
}

The pollIntervals specify the time in seconds between successive polls of the AEG/Electrolux cloud API for appliance status updates (statusSeconds, default 5 seconds), the health of the cloud servers (serverHealthSeconds, default 60 seconds), the information feed (feedSeconds, default 300 seconds), or the history of cleaning sessions (cleanedAreaSeconds, default 60 seconds).

Any unwanted HomeKit Services (except for the Accessory Information) created by this plugin can be disabled by listing them in the hideServices array.

Do not set any of the debug options unless attempting to investigating a compatibility issue or other problem.

Compatibility

This plugin has only been tested with a single AEG RX9.2 robot vacuum (model RX9-2-4ANM, PNC 900 277 479, running firmware 43.23). The protocol was reverse-engineered from the the AEG iPhone app (which replaced the AEG Wellbeing app).

It will probably work with other AEG RX9.2 / Electrolux Pure i9.2 robot vacuums, although some fixes might be required for AEG RX9/RX9.1 / Electrolux Pure i9/i9.1 models. Older AEG RX8 / Electrolux Pure i8 robot vacuums are not supported.

Functionality

This plugin allows cleaning to be started and paused, selection of cleaning power mode, and requesting return to the charging dock. It also indicates whether the robot vacuum is cleaning, on its dock, the battery charge status, and whether the dust collection bin requires emptying.

Unfortunately, HomeKit does not support robot vacuum cleaners, so the mapping of functionality to HomeKit Services and Characteristics is slightly odd as described below.

Accessory Information

The Accessory Information Service provides information about the appliance and allows its name to be changed.

Battery

The Battery Service indicates the battery charge level and charging status.

Contact Sensor

The Contact Sensor Service is (ab)used to indicate when the robot is on its charging dock. (The Occupancy Sensor provides the same functionality using a different Service type.)

Fan

The Fan Service is (ab)used to start/stop cleaning and to adjust the cleaning power mode.

Filter Maintenance

The Filter Maintenance Service is (ab)used to indicate the dust collection bin status.

Occupancy Sensor

The Occupancy Sensor Service is (ab)used to indicate when the robot is on its charging dock. (The Contact Sensor provides the same functionality using a different Service type.)

Switch: Clean

One Switch Service is used to start or pause/resume cleaning.

Switch: Home

Another Switch Service is used to (stop cleaning and) initiate a return to the charging dock.

Limitations

This is an early prototype. Functionality, configuration options, and mapping to HomeKit services, may change between releases. It may be necessary to manually delete Homebridge cache files and/or modify the config.json file when upgrading.

Only the AEG/Electrolux cloud API is supported. This plugin cannot communicate directly with the robot via a local network connection.

Changelog

All notable changes to this project are documented in the CHANGELOG.md file.

License

ISC License (ISC)
Copyright © 2022-2024 Alexander Thoukydides

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.