matterbridge-aeg-robot

A Matterbridge plugin that connects AEG RX 9 / Electrolux Pure i9 robot vacuums
to the Matter smart home ecosystem.

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

Installation

Step 1 - Create Account and Setup Robot Vacuum

Use the AEG iPhone or Android app to create an account. (It may be necessary to logout and login again to complete account creation.)
Add the RX series robot vacuum to your AEG/Electrolux/Zanussi account.

Step 2 - Obtain Electrolux Web API Credentials

Login to the Electrolux Group Developer Portal using the same account as used for the AEG mobile app.
On the Dashboard page enter an Api Key Name and click CREATE NEW API KEY. Copy the Api key.
Click on GENERATE TOKEN. Copy the Access Token and Refresh Token values.

Step 3 - Matterbridge Plugin Installation

Open the Matterbridge web interface, e.g. at http://localhost:8283/.
Under Install plugins type matterbridge-aeg-robot in the Plugin name or plugin path search box, then click Install ⬇️.
Click 🔄 Restart Matterbridge to apply the change.
Open the matterbridge-aeg-robot ⚙️ Plugin config.
Set the API Key, Access Token, and Refresh Token to the values obtained from the Electrolux Group Developer Portal Dashboard.
Click CONFIRM to save the configuration and restart Matterbridge again.

[!WARNING] The Apple Home app only supports robot vacuums when they are standalone individually-paired Matter nodes. Attempting to pair a Matterbridge instance with multiple robot vacuums, or a robot vacuum plus other device types, can cause the Home app to crash or fail to properly recognise some of the devices. If you are using HomeKit with a robot vacuum then configure a separate Matterbridge instance for each robot vacuum.

Separate Matterbridge Instance per Robot Vacuum

Separate Matterbridge Instances

Each additional Matterbridge instance should specify the following command line options:

Command Line Options	Default	Description
`-homedir <directory>`	`$HOME` or `USERPROFILE`	Matterbridge defaults to creating `Matterbridge`, `.matterbridge`, and `.mattercert` directories within the user's home directory. A different "home" directory is required by each Matterbridge instance.
`-port <number>`	`5540`	The port number for the Matterbridge commissioning server. This should be unique for each instance to allow pairing with a Matter controller.
`-frontend <number>`	`8283`	The port number for the Matterbridge frontend. This should be unique for each instance to allow use of the web interface.
`-vendorName "<name>"`	`"Matterbridge"`	Apple Home uses the vendor name of the Matter bridge for robot vacuums; use this option to override Matterbridge's default with `AEG`.
`-productName "<name>"`	`"Matterbridge aggregator"`	Apple Home uses the product name of the Matter bridge for robot vacuums; use this option to override Matterbridge's default with model name of your robot vacuum.

If you have multiple AEG/Electrolux robot vacuums then select one for each instance using the whiteList plugin configuration option.

Example `systemd` Configuration

The following example assumes that:

systemd is being used to launch Matterbridge (instead of via Docker or other means).
Matterbridge is run as user matterbridge and group matterbridge.
Matterbridge configuration files for this instance are being kept under /var/lib/matterbridge-aeg-robot.
The commissioning server will be on port 5541 and the web frontend on port 8284.
This instance is for an AEG RX9.2 robot vacuum.

Modify as appropriate to suit your setup.

Create a directory for this instance's configuration files:

sudo mkdir /var/lib/matterbridge-aeg-robot
sudo chown matterbridge:matterbridge /var/lib/matterbridge-aeg-robot

Create a /etc/systemd/system/matterbridge-aeg-robot.service file containing:

[Unit]
Description=Matterbridge AEG Robot
After=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/matterbridge -service -nosudo -novirtual -homedir /var/lib/matterbridge-aeg-robot -port 5541 -frontend 8284 -vendorName 'AEG' -productName 'RX9.2'
WorkingDirectory=/var/lib/matterbridge-aeg-robot
StandardOutput=inherit
StandardError=inherit
Restart=always
RestartSec=10s
TimeoutStopSec=30s
User=matterbridge
Group=matterbridge

[Install]
WantedBy=multi-user.target

Reload the systemd service files and enable the new unit:

sudo systemctl daemon-reload
sudo systemctl enable --now matterbridge-aeg-robot.service

Command Line Installation

Installation using Command Line

Stop Matterbridge:
sudo systemctl stop matterbridge
Install the plugin:
npm install -g matterbridge-aeg-robot
Register it with Matterbridge:
sudo -u matterbridge matterbridge -add matterbridge-aeg-robot
Restart Matterbridge:
sudo systemctl start matterbridge

Example `matterbridge-aeg-robot.config.json`

{
    "name":                     "matterbridge-aeg-robot",
    "type":                     "DynamicPlatform",
    "version":                  "1.0.0",
    "apiKey":                   "<API Key>",
    "accessToken":              "<Authorization Access Token>",
    "refreshToken":             "<Authorization Refresh Token>",
    "pollIntervalSeconds":      30,
    "blackList":                [],
    "whiteList":                [],
    "debug":                    false,
    "debugFeatures":            [],
    "unregisterOnShutdown":     false
}

Advanced Configuration Options

Advanced Configuration

You can include additional settings in matterbridge-aeg-robot.config.json to customise the behaviour or enable special debug features:

Key	Default	Description
`name` `type` `version`	n/a	These are managed by Matterbridge and do not need to be set manually.
`apiKey`	(no default)	API Key obtained from the Electrolux Group Developer Portal Dashboard.
`accessToken`	(no default)	Access Token obtained from the Electrolux Group Developer Portal Dashboard.
`refreshToken`	(no default)	Refresh Token obtained from the Electrolux Group Developer Portal Dashboard.
`pollIntervalSeconds`	`30`	The time in seconds between successive polls of the Electrolux Group API for each robot vacuum.
`blackList`	`[]`	If the list is not empty, then any robot vacuums with matching serial numbers will not be exposed as Matter devices.
`whiteList`	`[]`	If the list is not empty, then only robot vacuums with matching serial numbers (and not on the `blacklist`) will be exposed as Matter devices.
`debug`	`false`	Sets the logger level for this plugin to Debug, overriding the global Matterbridge logger level setting.
`debugFeatures`	`[]`	Miscellaneous options to control the information logged. None of these should be set unless you are investigating a compatibility issue or other problem.
`unregisterOnShutdown`	`false`	Unregister all exposed devices on shutdown. This is used during development and testing; do not set it for normal use.

All supported robot vacuums associated with the account (those reporting a model name of PUREi9) will be added to Matterbridge. Unsupported appliances, such as air purifiers or RX8 robot vacuums, will be ignored. Exclude or include specific robot vacuums by listing their serial numbers in either the blackList or whiteList.

The API has a strict rate limit of 5000 calls/day. The default value is 30 seconds, which results in 2880 calls/day for polling the state of a single appliance. If you have multiple robot vacuum cleaners in your account, or use the same API Key for other purposes, then scale the value appropriately: 60 seconds for two, 90 seconds for three, etc. More rapid polling is performed for a short period after a command has been sent to the robot vacuum; this is not configurable.

The supported debugFeatures are:

Debug Feature	Description
`Run API Tests`	Performs a test of each idempotent Electrolux Group API endpoint (those just reading appliance information and status) once during plugin start-up. This is useful for detecting changes to the API implementation that may affect operation of this plugin.
`Run Unsafe API Tests`	If `Run API Tests` is set then this additionally tests non-idempotent API endpoints (a `home` command is issued).
`Log Endpoint Debug`	Sets the `debug` flag to the Matterbridge/Matter.js endpoint implementation.
`Log API Headers`	Logs HTTP headers for each Electrolux Group API request. Rarely useful. (Requires Debug level logging.)
`Log API Bodies`	Logs message bodies for each Electrolux Group API request. Useful for diagnosing interoperability issues. (Requires Debug level logging.)
`Log Appliance IDs`	Product identifier and serial numbers are automatically redacted in the log by default. This setting causes these values to be logged verbatim.
`Log Debug as Info`	Redirect Debug level logging to Info level. This makes it visible in the Matterbridge frontend.

Functionality

This plugin supports starting, pausing, stopping cleaning, and returning the vacuum to its charging dock. It also reports whether the vacuum is actively cleaning, the current power level, docked status, battery level, and any active errors.

Unfortunately, the Electrolux Group API only allows basic control of robot vacuums: Play, Stop, Pause, and Home. It does not support any other control (such as selection of power modes, spot cleaning, or zones), so these cannot be controlled via this plugin.

Matter Clusters

This plugin exposes each robot vacuum as a Matter 1.4 device, supporting the following clusters:

Bridged Device Basic Information Cluster

The Bridged Device Basic Information cluster provides information about the appliance:

HardwareVersion / HardwareVersionString: The robot vacuum's hardware platform version.
ManufacturingDate: The date that the robot vacuum cleaner was installed.
NodeLabel: The name set by the user for the robot vacuum.
PartNumber: The robot vacuum's PNC.
ProductAppearance: The (approximate) colour and finish of the robot vacuum cleaner.
ProductLabel: The robot vacuum's model family (if it can be identified from its PNC) and colour.
ProductName: The robot vacuum's model name (if it can be identified from its PNC).
ProductURL: URL for this plugin's homepage.
Reachable: Indicates whether it is possible to communicate with the robot vacuum (plugin connected to the Electrolux Group API, robot vacuum connected to cloud servers, and robot vacuum enabled).
SerialNumber: The robot vacuum's serial number.
SoftwareVersion / SoftwareVersionString: The robot vacuum's firmware version.
UniqueId: Opaque identifier used by Matter to identify the device (derived from a SHA-256 hash of the API applianceId).
VendorName: The robot vacuum's manufacturer.

It also generates an event:

ReachableChanged: Triggered when the Reachable attribute changes.

Power Source Cluster

The Power Source cluster provides information about the battery and charging status:

Status: Indicates whether the battery is currently being used.
BatChargeRemaining: Indicates a coarse ranking of the battery charge level.
BatChargeLevel: The battery charge level as a percentage.
BatChargeState: The charging status:
- IsCharging = Actively charging the battery.
- IsNotCharging = Not currently charging. The battery is not fully charged.
- IsAtFullCharge = The battery is fully charged.

The following mapping from values reported by the Electrolux Group API is used:

Reported Battery Level	Status	BatChargeRemaining	BatChargeLevel
`Dead`	Unavailable	0%	Critical
`Critical Low`	Active	20%	Critical
`Low`	Active	40%	Warning
`Medium`	Active	60%	OK
`High`	Active	80%	OK
`Fully Charged`	Active	100%	OK

RVC Run Mode Cluster

The RVC Run Mode cluster indicates whether the robot vacuum is cleaning:

CurrentMode: Idle = Indicates that the robot is not performing a cleaning operation. Cleaning = Indicates that the robot is actively cleaning (including paused, charging, or returning to the dock for charging, during a cleaning operation).

It supports a single command:

ChangeToMode: Set CurrentMode: Idle: Attempt to stop a cleaning operation (but do not return to the dock). Cleaning: Attempt to start a new cleaning operation.

RVC Clean Mode Cluster

The RVC Clean Mode Cluster indicates the type of clean being performed:

RX9.1	RX9.2	Full Clean	Full Clean ModeTags	Spot Clean	Spot Clean ModeTags	Description
`ECO mode`	`Quiet`	Quiet	Vacuum, Quiet, LowNoise, LowEnergy, Min	QuietSpot	+Quick	Lower energy consumption and quieter
n/a	`Smart`	Smart	Vacuum, Auto	SmartSpot	+Quick	Cleans quietly on hard surfaces, uses full power on carpets
`Not ECO mode`	`Power`	Power	Vacuum, Max, DeepClean	PowerSpot	+Quick	Optimal cleaning performance, higher energy consumption

Although the ChangeToMode command is defined, it will always return an error since the Electrolux API does not support selecting power modes or triggering spot cleans.

RVC Operational State Cluster

The RVC Operational State Cluster indicates the detailed robot vacuum status:

OperationalState: Indicates the current state of the robot vacuum:

Reported Status	OperationalState
`Charging` `Pitstop`	Charging
`Cleaning` `SpotCleaning`	Running
`Error`	Error
`FirmwareUpgrade`	FirmwareUpgrade (non-standard)
`ManualSteering`	ManualSteering (non-standard)
`PausedCleaning` `PausedSpotCleaning` `PausedReturn` `PausedReturnForPitstop`	Paused
`Return` `ReturnForPitstop`	SeekingCharger
`Sleeping` (off dock)	Stopped
`Sleeping` (on dock)	Docked

OperationalError: Indicates details of a non-transient problem with the robot vacuum when OperationalState is Error.

It supports three commands:

Pause: Attempt to pause a cleaning operation (including returning to the charging dock).
Resume: Attempt to resume cleaning, if currently paused.
GoHome: Attempt to stop any cleaning operation in progress and initiate a return to the charging dock.

It also generates two events:

OperationCompletion: Triggered when RVC Run Mode transitions from Cleaning to Idle indicating the end of a cleaning operation.
OperationalError: Triggered when a new OperationalError occurs.

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). It should work with other AEG RX9/RX9.1/RX9.2 or Electrolux Pure i9/i9.1/i9.2 models.

Matter controllers vary in their support for Matter 1.4 RVCs. This plugin is only tested with Apple HomeKit and the Apple Home app.

Apple Home Limitations

Robot Vacuums in Apple Home App

The Apple Home app in iOS/iPadOS 18.4 and macOS Sequoia has limited Matter support and exhibits multiple idiosyncrasies.

The Home app expects each robot vacuum to be a standalone, individually-paired Matter node implementing a single endpoint. However, Matterbridge acts as a Matter bridge - either a single bridge node for all plugins (bridge mode), or a separate bridge node per plugin (childbridge mode) - with each plugin's device exposed as an additional child endpoint. This causes a few issues when using this plugin with the Home app:

Multiple bridged devices: A Matter bridge that exposes a robot vacuum plus other devices can crash the Home app. Hence, a separate Matterbridge instance is required for each robot vacuum. This plugin should be the only one enabled in each instance, and only a single robot vacuum device should be configured in each instance.
Device-specific information is ignored: The Home app shows the bridge device information from Matterbridge's own root Device Basic Information cluster, ignoring the plugin's Bridged Device Basic Information cluster. As a result, the Home app displays the bridge's name, manufacturer, model, serial number, and firmware version; not those of the robot vacuum. The correct values can be specified using Matterbridge's command line options.

Other quirks in the Home app:

Delayed docking: The Send to Dock button first sets RVC Run Mode to Idle (which maps to stop in the Electrolux Group API), followed by a GoHome command (home). The Electrolux Group API silently ignores commands sent too quickly in succession, so this plugin inserts a 5-second delay between them. This causes the robot vacuum to pause briefly before returning to the dock.
Incorrect RVC Clean Mode display: The Home app displays ModeTag values (e.g. Deep Clean, Quick) rather than the advertised modes (Smart, PowerSpot, etc) reported by the robot vacuum. Worse, it only shows these when not cleaning, even though the Electrolux Group API only provides meaningful values during cleaning.

Changelog

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

Reporting Issues

If you have discovered an issue or have an idea for how to improve this project, please open a new issue using the appropriate issue template.

Pull Requests

As explained in CONTRIBUTING.md, this project does NOT accept pull requests. Any PRs submitted will be closed without discussion.

ISC License (ISC)

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.