Homebridge Dolphin Pool Cleaner

Control your Maytronics Dolphin pool cleaning robot through Apple HomeKit using Homebridge.

Features

• Start/Stop Cleaning - Control your robot with a simple switch in HomeKit
• Water Temperature - View pool water temperature (when robot is in water)
• Filter Status - Get notified when the filter bag needs cleaning
• Multiple Cleaning Modes - Choose from 8 cleaning modes
• Real-time Updates - Instant status via AWS IoT MQTT
• OTP/MFA Support - Full two-factor authentication support
• Assistant (optional) - Explains sign-in and verification errors in the setup wizard, using the AI provider you set up in Homebridge AI Kit
• Siri Integration - "Hey Siri, start pool cleaning"

Supported Models

This plugin works with all Maytronics Dolphin robots that use the MyDolphin Plus app:

| Series | Models | |--------|--------| | M Series | M400, M600, M700 | | S Series | S200, S300, S400 | | E Series | E50, E60, E70 | | Liberty | Liberty 300, Liberty 400 (cordless) | | Sigma | Sigma |

Note: Your robot must be IoT-enabled and connected to the MyDolphin Plus cloud service.

Installation

Via Homebridge UI (Recommended)

1. Open Homebridge UI
2. Go to Plugins tab
3. Search for dolphin pool cleaner
4. Click Install on @mp-consulting/homebridge-dolphin-pool-cleaner
5. Click Settings and use the setup wizard

Via Command Line

npm install -g @mp-consulting/homebridge-dolphin-pool-cleaner

Configuration

Setup Wizard (Recommended)

The plugin includes a custom UI wizard that guides you through:

1. Enter your MyDolphin Plus email and password
2. Complete OTP verification (if enabled on your account)
3. Your robot is automatically discovered
4. Configure options and save

Manual Configuration

Add to your Homebridge config.json:

{
  "platforms": [
    {
      "platform": "DolphinPoolCleaner",
      "name": "Dolphin Pool Cleaner",
      "email": "[email protected]",
      "password": "yourpassword",
      "pollingInterval": 60,
      "devices": [
        {
          "serialNumber": "ABC123XYZ",
          "name": "Pool Robot",
          "cleaningMode": "all",
          "enableTemperature": true,
          "enableFilterStatus": true
        }
      ]
    }
  ]
}

Platform Options

| Option | Required | Default | Description | |--------|----------|---------|-------------| | platform | Yes | - | Must be DolphinPoolCleaner | | email | No | - | MyDolphin Plus account email | | password | No* | - | MyDolphin Plus account password | | refreshToken | No* | - | Saved by the setup wizard; preferred over storing your password | | pollingInterval | No | 60 | Status poll interval in seconds (30-600) |

* Either refreshToken (set by the setup wizard) or email + password is required. The wizard is recommended: it never stores your password.

Device Options

| Option | Required | Default | Description | |--------|----------|---------|-------------| | serialNumber | Yes | - | Robot serial number (on power supply label) | | name | No | Robot name | Display name in HomeKit | | cleaningMode | No | all | Default cleaning mode (regular is accepted as an alias of all) | | enableTemperature | No | true | Show water temperature sensor | | enableFilterStatus | No | true | Show filter maintenance indicator |

Cleaning Modes

| Mode | Duration | Description | |------|----------|-------------| | all | 150 min | All surfaces - floor, walls, and waterline | | short | 60 min | Quick clean for light debris | | floor | 150 min | Floor only | | wall | 120 min | Walls only | | water | 150 min | Waterline only | | ultra | 150 min | Deep clean with extra passes | | cove | 120 min | Focus on floor-wall junction | | spot | 120 min | Concentrated area cleaning |

Note: Available modes depend on your robot model. The setup wizard shows only modes supported by your robot.

HomeKit Services

The plugin creates these HomeKit accessories for each robot:

| Service | Type | Description | |---------|------|-------------| | Cleaning Switch | Switch | Turn cleaning on/off | | Water Temperature | Temperature Sensor | Pool water temp (when in water) | | Filter Status | Filter Maintenance | Shows when filter needs cleaning |

How It Works

┌─────────────┐     ┌──────────────┐     ┌─────────────┐     ┌─────────┐
│  HomeKit    │────▶│  Homebridge  │────▶│  AWS IoT    │────▶│  Robot  │
│  (iPhone)   │◀────│  Plugin      │◀────│  MQTT       │◀────│  (PWS)  │
└─────────────┘     └──────────────┘     └─────────────┘     └─────────┘

1. Authentication: AWS Cognito authenticates your MyDolphin Plus credentials
2. Discovery: REST API retrieves your robot information and AWS credentials
3. Real-time Control: MQTT connection to AWS IoT Core for instant commands
4. State Sync: Thing Shadows maintain robot state even when offline

Troubleshooting

"Invalid email or password"

• Verify credentials work in the official MyDolphin Plus app
• Check for special characters that may need escaping
• Ensure no extra spaces in email/password

"OTP required"

Your account has two-factor authentication enabled. Use the setup wizard which handles OTP verification, or temporarily disable 2FA in the MyDolphin app.

Switch snaps back after toggling

Fixed in v1.0.14, refined in v1.0.15. The plugin applies an optimistic UI update (HomeKit reflects the new state immediately) and suppresses stale MQTT switch updates for 15 seconds after a command, while still allowing temperature and filter updates through. Update to the latest version.

Robot not responding to commands

1. Check robot's power supply is plugged in and has WiFi connection
2. Verify robot appears online in MyDolphin Plus app
3. Check Homebridge logs for connection errors
4. Try restarting Homebridge

Status shows "notConnected"

This is normal when the robot is out of the water or not docked on the power supply. The power supply reports connection status, not the robot itself.

Filter always shows "needs cleaning"

The filter indicator is based on the filterBagIndication.state value (0-100%). Values above 80% trigger the maintenance alert. Reset the filter indicator in the MyDolphin Plus app after cleaning the filter.

Temperature not showing

Water temperature is only available when the robot is actively in the water and its sensors are submerged.

Assistant

The setup wizard can explain sign-in problems with the Assistant. It is off until you set up an AI provider once for all MP Consulting plugins in Homebridge AI Kit (or the Homebridge Glass UI): the plugin reads the shared HomebridgeAiKit platform block from config.json and has no AI settings of its own. When it is not set up, the wizard looks exactly as before, with a small tip under the sign-in form.

When it is enabled, an Explain button appears under a failed "Send Verification Code" step and a failed code verification; the answer streams into an Assistant panel below.

What is sent to the provider: the error message and which wizard step failed. Your email address (also masked if it appears in an error), verification codes, refresh token and robot serial number are never sent, and the provider's API key stays on the Homebridge server.

The wizard has no "Describe Your Setup" helper: the configuration is mostly the devices list that the wizard itself fills in after sign-in.

Security

• All user-facing HTML output is sanitized to prevent XSS
• Image URLs are validated to allow only http/https protocols
• AWS credentials and tokens are never written to logs, even at debug level
• OTP sessions expire automatically after 5 minutes

Debug Logging

Enable debug logging in Homebridge to see detailed plugin activity:

DEBUG=* homebridge -D

Or add to your Homebridge startup arguments:

-D

Note: Debug logs are safe to share publicly. Sensitive credentials (AWS keys, tokens) are automatically redacted.

Development

# Clone repository
git clone https://github.com/mp-consulting/homebridge-dolphin-pool-cleaner.git
cd homebridge-dolphin-pool-cleaner

# Install dependencies
npm install

# Build
npm run build

# Link for local testing
npm link

# Run with auto-reload
npm run watch

The build copies @mp-consulting/homebridge-ui-kit (and Bootstrap's CSS) into homebridge-ui/public/lib/ with mp-ui-kit-copy. The Assistant routes come from @mp-consulting/homebridge-ai-core, the slim core of Homebridge AI Kit (its only runtime dependency is ajv), so the plugin does not pull in the MCP SDK, socket.io or zod.

Project Structure

src/
├── api/              # Maytronics API client and MQTT
│   └── auth/         # Authentication (Cognito, credentials)
├── devices/          # Robot device representation
├── accessories/      # HomeKit accessory implementation
├── parsers/          # Shadow state parsing
├── config/           # Constants and configuration
└── utils/            # Error handling utilities

Each module has a README with detailed documentation.

Debug Scripts

# Dump robot shadow data (requires test/hbConfig/config.json)
npm run build && node test/scripts/dump-shadow.mjs

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Submit a pull request

License

MIT License - see LICENSE file.

Disclaimer

This plugin is not affiliated with, endorsed by, or connected to Maytronics Ltd. "Dolphin" and "MyDolphin" are trademarks of Maytronics Ltd.

The MyDolphin Plus API is not officially documented. This plugin was developed through reverse engineering and may break if Maytronics changes their API.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Made with :swimming_man: by @mickael