homebridge-kobold

This is a plugin for homebridge to control your Vorwerk Kobold VR300 vacuum robot. You can download it via npm.

It is based on a fork of naofireblade's homebridge-neato, merged with the oAuth authentication mechanism from nicoh88's homebridge-vorwerk.

The interaction with the Server is handled by the underlying node-kobold-control module.

Features

• House Cleaning

  • Eco mode
  • Extra care navigation
  • Nogo lines

• Zone cleaning 1

• Spot cleaning

  • Individual spot size 2
  • Clean twice 2

• Return to dock

• Find the robot

• Schedule (de)activation

• Robot information

  • Battery level
  • Charging state
  • Dock occupancy
  • Model and firmware version

• Automatic or periodic refresh of robot state

• Multiple robots

• Native Matter robotic vacuum accessory on Homebridge 2

  • Run and clean modes
  • Pause, resume, and return to dock
  • Operational, charging, and battery state
  • Room selection through Matter Service Areas
  • Identify/play-sound support

• German, English or French Language Setting

2 You can send the robot from one room to another as well. He will return to the base, wait there some seconds and then starts cleaning the next room.

3 You need a third party app like eve to access these features.

Installation

1. Install homebridge using: npm install -g homebridge
2. Install this plugin using: npm install -g homebridge-kobold
3. Update your configuration file. See the sample below.

Development

The development workflow follows the Homebridge plugin template. It uses the globally installed Homebridge and Config UI at runtime while keeping Homebridge as a local development dependency for TypeScript API definitions.

Install and activate Node.js 24 with nvm, then install or update the global tools and this repository's dependencies:

nvm install 24
nvm use
npm install -g homebridge@latest homebridge-config-ui-x@latest
npm ci

The plugin and its development workflow support Node.js 24 only. The repository's .nvmrc makes nvm use select the correct runtime.

Create a private local Homebridge configuration before the first run:

mkdir -p test/hbConfig
cp config.dev.example.json test/hbConfig/config.json

Replace YOUR_KOBOLD_TOKEN in test/hbConfig/config.json. The entire test directory is ignored because Homebridge writes credentials and pairing state there; never commit it.

Start the watch environment:

npm run watch

This builds the plugin, links it into the active global Node.js installation, watches src for TypeScript changes, and restarts the isolated Homebridge test server after each build. Its configuration and state live under test/hbConfig, and the local web interface is available at http://localhost:8581.

Stop any other Homebridge development instance first if it uses the same ports. Press Ctrl+C to stop the watcher and its Homebridge/UI child processes.

Configuration

Add the following information to your config file. Adapt the value for token.

Simple

"platforms": [
  {
    "platform": "KoboldVacuumRobot",
    "token": "YourToken",
    "language": "de"
  }
]

You can get a token using the GUI tool Kobold Token Getter or using the following two curl commands:

# This will trigger the email sending
curl -X "POST" "https://mykobold.eu.auth0.com/passwordless/start" \
     -H 'Content-Type: application/json' \
     -d '{
  "send": "code",
  "email": "ENTER_YOUR_EMAIL_HERE",
  "client_id": "KY4YbVAvtgB7lp8vIbWQ7zLk3hssZlhR",
  "connection": "email"
}'

==== wait for the email to be received ====

# this will generate a token using the numbers you received via email
# replace the value of otp 123456 with the value you received from the email
curl -X "POST" "https://mykobold.eu.auth0.com/oauth/token" \
     -H 'Content-Type: application/json' \
     -d '{
  "prompt": "login",
  "grant_type": "http://auth0.com/oauth/grant-type/passwordless/otp",
  "scope": "openid email profile read:current_user",
  "locale": "en",
  "otp": "123456",
  "source": "vorwerk_auth0",
  "platform": "ios",
  "audience": "https://mykobold.eu.auth0.com/userinfo",
  "username": "ENTER_YOUR_EMAIL_HERE",
  "client_id": "KY4YbVAvtgB7lp8vIbWQ7zLk3hssZlhR",
  "realm": "email",
  "country_code": "DE"
}'

From the output, you want to copy the id_token value.

The language can be de for German, en for English, or fr for French.

Matter migration

Matter support follows Homebridge's robotic-vacuum Matter API. It requires Homebridge 2, Node.js 24, and Matter external-accessory support enabled for the main bridge or this plugin's child bridge. Protocol exposure belongs to the bridge configuration: the plugin always provides its established HAP accessory and automatically adds the Matter robotic vacuum when api.isMatterEnabled() reports that Matter is active.

Choose the bridge configuration that matches the desired exposure:

• HAP only: leave Matter disabled for the bridge.
• HAP + Matter: leave HAP enabled and enable Matter → External Accessories for the bridge. Pairing both versions to the same home can create duplicate robot tiles.
• Matter only: put Kobold on a dedicated child bridge, disable HAP for that child bridge, and enable Matter → External Accessories. Matter accessories are managed in Apple Home or another Matter controller and do not appear in the Homebridge Accessories screen.

Per-plugin protocol selection is intentionally unavailable on a shared main bridge because Homebridge owns protocol advertisement at bridge level. Use a dedicated child bridge when Kobold needs different HAP/Matter settings from other plugins. The plugin never edits _bridge, HAP, or Matter settings automatically.

Enabling only Matter → External Accessories is sufficient. Homebridge represents that external-only mode as matter: { "enabled": false, "externalsOnly": true }: it does not advertise an aggregate Matter bridge, but it still exposes the Matter API used by Kobold's per-robot external accessories.

The plugin portion of the configuration remains independent of the bridge's protocol settings:

"platforms": [
  {
    "platform": "KoboldVacuumRobot",
    "token": "YourToken",
    "refresh": "auto"
  }
]

Restart Homebridge after changing bridge settings. Each Kobold robotic vacuum receives its own Matter pairing QR code. In the Homebridge UI, open Plugins → Homebridge Kobold → ⋮ Actions → External Accessories, then select the robot to view its QR code, manual pairing code, and pairing status. Homebridge Matter is not CSA-certified, so controllers may show an uncertified-accessory warning; pairing also requires Homebridge and the controller to share a network with working mDNS and IPv6.

The Matter accessory exposes normal and eco vacuum modes, start/pause/resume, return to dock, battery and charging state, Identify, and polygon map boundaries as selectable rooms. Schedule control, NoGo-line selection, Extra Care, and configurable spot-cleaning dimensions do not have faithful standard Matter RVC controls; they remain available only through the HAP accessory when HAP is enabled for the bridge.

Advanced

Below are explanations for advanced parameters to adjust the plugin to your needs. All parameters are optional.

refresh
Timer for periodic refresh of robot state. The default is auto. The options are:
auto Updates the robot state when a cleaning was started via homekit so that you can activate automations based on a successful cleaning.
120 Or any other time in seconds (minimum 60) is required if you want to receive robot state updates after starting the cleaning from outside of homekit (e.g. neato app or schedule).
0 Disables background updates completely.

hidden
List of plugin features that you don't want to use in HomeKit (e.g. dock, dockstate, eco, nogolines, extracare, schedule, find, spot). This setting does not remove Matter clusters.

"platforms": [
  {
    "platform": "KoboldVacuumRobot",
    "token": "YourToken",
    "refresh": "120",
    "hidden": ["dock", "dockstate", "eco", "nogolines", "extracare", "schedule", "find", "spot"],
    "language": "de"
  }
]

Tested robots

• Vorwerk Kobold VR300