Beatbot smart home integration, free and open source
Control your Beatbot pool robots: status, battery, cleaning and alerts.
Published by prohand
- Devices
- Version 1.2.3
- Requires Gladys >=5.2.0
- ★ 0
This integration connects Gladys to your Beatbot pool robots (AquaSense, Sora… ranges) and their cleaning base station, through the Beatbot cloud.
Before you start
- Your robots must already work in the Beatbot app (account created, robot paired, Wi-Fi set up).
- Beatbot robots are controlled through the Beatbot cloud only: Gladys needs Internet access. There is no local control.
- A diving robot often loses Wi-Fi: it then shows as unreachable for a few minutes, which is expected.
Linking the account
- Open the Configuration tab of the integration.
- Click Connect next to Beatbot account.
- The Beatbot sign-in page opens: sign in and allow access. Your password is typed on Beatbot's page, it never goes through Gladys.
- Back in Gladys, the connection status turns green and your robots show up in the Discover tab: click Add to Gladys on each one.
The Test the connection button lists the robots found, their status and their battery.
The other settings
| Setting | What it is for |
|---|---|
| Region | Where your account is hosted (Europe, North America, China). Automatic reads it from the account: change it only when asked. |
| Full refresh | States arrive in real time. This full read (every 10 min by default) catches what a network outage made you miss. |
| OAuth client ID | Advanced. Keep the default unless Beatbot gave you another client ID. |
If Connect does nothing
Gladys opens the Beatbot sign-in page in a new tab. If no tab opens, the browser most likely blocked it as a pop-up (Safari on iPhone and iPad does it often): allow pop-ups for the address of your Gladys (on iPhone: Settings → Apps → Safari → Block Pop-ups, off), or use a computer, then click Connect again.
The home-assistant value of OAuth client ID is only the name of the
public client Beatbot publishes for home automation: you do not need Home
Assistant.
If the Beatbot page refuses the sign-in
The integration uses the "open API" access Beatbot publishes for home automation, with Beatbot's public client ID.
Known issue: "Whitelabel Error Page … status=400". After you type your email and password, the Beatbot page may show:
Whitelabel Error Page
There was an unexpected error (type=Bad Request, status=400).
- This is not your password: the Beatbot page checks the return address of Gladys only after the sign-in, and does not accept it yet for the public client ID.
- A request is open at Beatbot to accept Gladys: follow it on GitHub. Nothing can be fixed on the Gladys side until then.
- You are now signed in at Beatbot, so every new try goes straight to this
error. To start again from the sign-in page, use a private browser window
(or delete the cookies of
oauth.beatbot.com). - If Beatbot gives you a client ID for Gladys, type it in OAuth client ID, save, then click Connect again.
What you get
For every robot (and every station), depending on what the robot offers:
| Feature | Detail |
|---|---|
| State | Stopped, cleaning, paused, error, returning, charging, docked. |
| Cleaning | Start / pause the cleaning. |
| Return to base | Calls the robot back (to its base, or to the waterline for pickup). |
| Battery / Charging | Battery level in % and charging in progress (robots only, not the station). |
| Cleaning mode | The robot's modes (floor, walls, waterline…), named as Beatbot names them. |
| Child lock | Locks the robot's buttons. |
| Do not disturb | Turns the robot's voice prompts off (read-only when the robot does not allow it). |
Every robot carries a cloud badge when reachable, unreachable otherwise.
Scenes
The integration adds its own cards to the scene editor (Gladys 5.1 or later), under Integrations.
Triggers:
- Pool robot status changed — optionally filter on the robot and on the
new status. The next actions read
{{triggerEvent.data.status}},{{triggerEvent.data.previous_status}}and{{triggerEvent.data.detail}}(detailed status: diving, surfacing…). - Pool cleaning finished — a cycle ended normally. Variables:
{{triggerEvent.data.duration_minutes}}(empty when the cycle started before the integration did) and{{triggerEvent.data.battery}}. - Pool robot fault — a fault just appeared (robot stuck, basket full, motor
fault…). Filter on the faults you care about. Variables:
{{triggerEvent.data.error}},{{triggerEvent.data.label_en}}.
Actions (each one returns sent: false when the robot does not offer that
order):
- Start pool cleaning
- Pause pool cleaning
- Send the pool robot back
- Set the cleaning mode — type the mode name as shown on the device in Gladys.
Examples: "when the cleaning is finished, send me a message with its duration", or "when the robot is stuck, alert me".
Dashboard
In Dashboard → Edit → New widget, add the Pool robot widget (under Integration widgets) and pick the robot: it shows the live battery, the status, the current fault, the link, the mode and how long the last cleaning took, with Start, Pause and Return buttons.
When the robot lets its cleaning mode be changed, a Cleaning mode button opens a small form listing the modes of that robot, pre-filled with the current one: pick one and send it (Gladys 5.2 or later, required by the integration).
Troubleshooting
- "Click Connect…": no account linked, or the authorization expired or was revoked: click Connect again.
- "Your Beatbot account did not give its region": choose it in Region and save.
- "Beatbot cloud unreachable": check Gladys' Internet access; the integration retries on its own.
- States no longer move in real time: another software (Home Assistant for instance) may use the same Beatbot account and have taken the real-time connection. States are still updated at every full refresh.
- The integration logs are in its Logs tab in Gladys. They never contain your tokens.
Configuration settings
These are the settings Beatbot asks for in its configuration screen in Gladys.
| Setting | Type | Required | Description |
|---|---|---|---|
| Getting started | section | No | Your robots must already work in the Beatbot app. Click Connect and sign in with your Beatbot account: Gladys then finds every pool robot of the account. Beatbot robots are reached through the Beatbot cloud only, Internet access is required. |
| Beatbot account | oauth2 | No | Opens the Beatbot sign-in page. Your password never goes through Gladys. |
| Region | select | No | Where your Beatbot account is hosted. Automatic reads it from the account: change it only if the connection status asks you to. |
| Full refresh (minutes) | number | No | States arrive in real time; this periodic full read only catches what a network outage made you miss. |
| OAuth client ID (advanced) | string | No | Leave as is unless Beatbot gave you another client ID. "home-assistant" is only the name of the public client Beatbot publishes: you do not need Home Assistant. Click Connect again after changing it. |
How to install Beatbot in Gladys
- In Gladys, open Integrations: Beatbot appears in the catalog, next to the native integrations, with a community badge.
- Click Install. Gladys pulls the Docker image (
ghcr.io/prohand/gladys-beatbot:1.2.3), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration). - Open the Configuration screen of the integration, fill in the settings, and save.
- You can also install it directly from its repository URL: https://github.com/prohand/gladys-beatbot.
Beatbot requires Gladys >=5.2.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.
Not running Gladys yet? It is free and open source: follow the installation guide to get started.
About external integrations
Beatbot is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by prohand, not by the Gladys core team.
- Browse all integrations, native and community
- Build and publish your own external integration
- Source code on GitHub — source of this documentation