Skip to main content

SwitchBot smart home integration, free and open source

SwitchBot integration for Gladys Assistant

SwitchBot devices through the official cloud API: bots, plugs, curtains, locks, sensors, lights.

View on GitHubAll external integrations

Control your SwitchBot devices from Gladys through the official SwitchBot cloud API (v1.1): bots, plugs, curtains and blinds, locks, thermometers, contact, motion and water leak sensors, lights, humidifier, air purifier, fans, robot vacuums, and the infrared remotes of your hubs.

Developed without the hardware: feedback welcome. This integration was built and tested on the responses documented by SwitchBot and on the test data of the Home Assistant integration, not on physical devices nor on a real SwitchBot account. If something does not work as described, say so on the Gladys forum or in the issues.

Not affiliated with SwitchBot (Wonderlabs). SwitchBot is a trademark of its owner.

What you need​

  • Gladys Assistant 5.1.0 or later, with an Internet connection (the integration talks to the SwitchBot cloud, not to the devices on your network).
  • A SwitchBot account and the SwitchBot app, version 9 or later.
  • For the devices that talk Bluetooth (Bot, Curtain, Meter, Contact Sensor, Lock...): a SwitchBot hub (Hub Mini, Hub 2, Hub 3...) and Cloud Services turned on for each device in the SwitchBot app. Wi-Fi devices (plugs, lights, Hub 2...) need nothing more.
  • Optional, for real time: a Gladys Plus subscription (see below).

Configuration​

  1. Install the integration: in Gladys, Integrations → Install from GitHub with https://github.com/guim31/gladys-switchbot, or from the catalog once it is listed.
  2. In the SwitchBot app: Profile → Preferences → About, tap App Version 10 times, then open Developer Options: the app shows a token and a secret key.
  3. In Gladys: Integrations → SwitchBot → Configuration, paste the token and the secret key, save. The status turns green and the integration reads your device list.
  4. Open the Discovery tab: every supported device is there, with the name given in the SwitchBot app. Click Add, choose a room, save. Only the devices you add are read.
  5. The Test the connection button shows what the integration found: devices, those not supported, IR remotes, the refresh pace and the API calls of the day.

Other settings:

  • IR remotes: also publishes the virtual infrared remotes of your hubs (see below).
  • Allow locking and unlocking: off by default, the locks are then read only (see below).
  • Language of the feature names: the names given to the features of the devices added after the change (French by default). The other texts follow the language of your Gladys.

The token and the secret key stay in the Gladys configuration: they sign every request and never appear in the logs. Generating a new token in the app invalidates the old one: paste the new one.

Refresh interval and quota​

SwitchBot allows 10,000 API calls per day and per account, every app using the same token included. Over it, SwitchBot refuses every call until midnight. The integration reads each added device once per period (one call per device):

  • Automatic (default): every 2 minutes at least, and slower when you have many devices, so that polling never uses more than half of the quota. Examples: 10 devices every 3 minutes, 26 every 8 minutes, 50 every 15 minutes.
  • A fixed interval (1 minute to 1 hour) is lengthened when it would use more than half of the quota.

The other half stays for your commands, the reads after each command (one call, a few seconds later), the real-time reads and your other apps. The integration counts its calls (saved under /data, so a restart does not forget them): past 9,000 calls, polling pauses until midnight and commands keep working. It cannot see the calls of your other apps (Home Assistant, scripts...): lengthen the interval if you share the token.

Real time with Gladys Plus (optional)​

Without it, a change made outside Gladys (a door opened, a button pressed on the device) shows up at the next read. With a Gladys Plus subscription, SwitchBot can tell Gladys at once:

  1. In Gladys Plus, create an Open API key (Settings → Open API).
  2. In the SwitchBot integration configuration, paste it in the Gladys Plus webhooks block.
  3. Turn on Real time through Gladys Plus and save.

The integration then registers the Gladys Plus address at SwitchBot. Each change notice triggers a read of that device through the API (a notice is a trigger, never applied as is), and those devices are polled every 30 minutes only, to catch a lost notice. SwitchBot keeps a single webhook per account: registering this one removes the one another app (Home Assistant...) had registered. Turning the option off removes the Gladys address.

What each device offers​

DeviceFeatures in Gladys
BotPress / switch (in press mode any command presses, then the state falls back to off), battery
Plug, Relay Switch 1On/off
Plug Mini (US, JP)On/off, power draw (W), voltage (V), current (A)
Plug Mini (EU), Relay Switch 1PMOn/off, power draw, voltage, current, energy used today (kWh)
Curtain, Curtain 3, Roller Shade, Blind TiltPosition (100 = open), open / close / stop, battery (not on the Blind Tilt)
Lock, Lock Pro, Lock Ultra, Lock Vision...Lock state, door (not on the Lock Lite), battery; lock / unlock with the option
Meter, Meter Plus, Outdoor Meter, Meter ProTemperature, humidity, battery
Meter Pro CO2Temperature, humidity, CO2 (ppm), battery
Hub 2, Hub 3Temperature, humidity, light level (1 to 20); motion on the Hub 3
Contact SensorOpening (open / closed), motion, battery
Motion SensorMotion, battery
Water Leak DetectorWater leak, battery
Color Bulb, Strip Light 3, Floor Lamp, RGBICWW strip / lampOn/off, brightness, colour, colour temperature
Strip Light, RGBIC neon rope lightsOn/off, brightness, colour
Ceiling Light, Ceiling Light ProOn/off, brightness, colour temperature
HumidifierOn/off, humidity, temperature, water tank (low when empty)
Air Purifier (VOC, PM2.5, table models)On/off, mode (normal, auto, sleep, pet)
Circulator Fan, Battery Circulator Fan, Standing FanOn/off, speed (1 to 100 %, switches the fan to direct mode), battery on battery models
Robot Vacuum S1, S1 Plus, K10+, K10+ ProState, cleaning (start / stop), return to base, battery
Robot Vacuum S10, S20, K10+ Pro Combo, K20+ Pro, K11+State, return to base, battery (start them from the SwitchBot app)

Other SwitchBot devices (Hub Mini without sensors, cameras, keypads...) are not published: the Test the connection button lists them. Some features are refreshed with a delay: after a command, the device is read again 5 seconds later (15 seconds for a curtain).

Curtains and blinds​

Gladys reads a position as 100 = open, 0 = closed: the integration converts SwitchBot's positions, which count the other way. A Blind Tilt is open at its middle position and closed at both ends: its position reads 100 when the slats are open, and setting a position keeps the direction (up or down) it last used. Only the curtains can stop on command.

Locks​

A door lock is a security device: by default the integration only reads it (locked, unlocked, moving, jammed or half-locked, and the door state). To lock and unlock from Gladys (dashboard, scenes, voice assistants linked to Gladys), turn on Allow locking and unlocking, then add the lock (or update it from the Discovery tab). Think about who and what can reach those commands.

IR remotes​

With the IR remotes option, every virtual remote of your hubs (TV, air conditioner, fan, light...) becomes a device with an on/off button and the last command sent. SwitchBot gives no state for them: the on/off shows the last command sent, not the appliance. Any other button, custom ones included, is sent with the Send a SwitchBot IR command scene action. The "Others" remotes only have custom buttons.

Dashboard widget​

The SwitchBot widget shows, at a glance:

  • up to six temperatures (live tiles of your thermometers and hubs);
  • open doors and windows (and those left open), locks not locked or jammed, water leaks, low batteries;
  • the API calls of the day, and the SwitchBot cloud when it refuses or does not answer.

It reads nothing from SwitchBot by itself: it shows the last reads.

Scene triggers​

In the scene editor, Integrations category:

  • SwitchBot door or window: a contact sensor reports open, closed, or left open (the delay set in the SwitchBot app, which a simple state cannot tell). Filters: the sensor, the states. Variables: device name, state.
  • SwitchBot motion detected: a motion sensor, the motion detector of a contact sensor or a Hub 3 starts seeing motion. Variable: device name.
  • SwitchBot water leak: a leak detector goes from dry to wet. Variable: device name.
  • SwitchBot battery low: a battery falls to 20 % or less, once, until it goes back above 30 %. Variables: device name, battery.

They fire on a change only, never at start-up. Without real time, a change shorter than the refresh interval (a short motion) can go unnoticed: use the Gladys Plus option for motion.

Scene actions​

  • Press a SwitchBot Bot: one press of the chosen Bot, whatever its mode.
  • Send a SwitchBot IR command: a remote (with the IR remotes option), a command and an optional parameter. Standard commands: turnOn, turnOff, volumeAdd, volumeSub, channelAdd, channelSub, setMute, Play, Pause, Stop, Next, Previous, swing, lowSpeed, middleSpeed, highSpeed, brightnessUp, brightnessDown, SetChannel (parameter: the channel) and setAll for an air conditioner (parameter: temperature,mode,fan,power, for example 26,2,1,on: mode 1 auto, 2 cool, 3 dry, 4 fan, 5 heat; fan 1 auto, 2 low, 3 medium, 4 high). Any other name is a custom button of the remote, case-sensitive.

Scene examples​

  • Door left open: trigger SwitchBot door or window, state Left open → send a message "{{triggerEvent.data.device_name}} is still open".
  • Water leak: trigger SwitchBot water leak → message "Water leak: {{triggerEvent.data.device_name}}", then turn off the washing machine plug.
  • Morning coffee: at 7:00 on weekdays → Press a SwitchBot Bot (the coffee maker's Bot), then open the living room curtain to 100 %.
  • Cool down: when the bedroom temperature goes above 27 °C → Send a SwitchBot IR command, setAll with 24,2,1,on to the air conditioner remote.
  • Batteries: trigger SwitchBot battery low → message "Change the battery of {{triggerEvent.data.device_name}} ({{triggerEvent.data.battery}} %)".

Troubleshooting​

  • "SwitchBot refused the credentials": check the token and the secret key (copy them again from the app; a new token invalidates the old one). The same answer comes when the daily quota is spent: wait for midnight, and lengthen the interval if you share the token with another app. The integration retries every 30 minutes.
  • "The SwitchBot cloud does not answer": check the Internet connection of Gladys. The integration retries every 5 minutes.
  • A device is missing from Discovery: it may not be supported (see Test the connection), or its Cloud Services are off in the SwitchBot app. Search again from the Discovery tab once fixed.
  • A device shows as unreachable: SwitchBot says the device or its hub is offline (out of battery, out of Bluetooth range of the hub, hub unplugged).
  • Values are late: that is the refresh interval (see Test the connection); turn on the Gladys Plus real time for doors and motion.
  • Real time does not work: check that the Open API key is pasted in the Gladys Plus webhooks block and the option is on; another app may have registered its own webhook since (SwitchBot keeps one): save the configuration again.
  • Logs: set LOG_LEVEL=debug on the integration to see every read; the token and the secret key never appear in them.

Limits​

  • Cloud only: no local Bluetooth control, the devices need a hub and an Internet connection, and SwitchBot's servers must answer.
  • 10,000 API calls a day per account: values are refreshed every few minutes, not instantly, unless the Gladys Plus real time is on.
  • The SwitchBot API is for personal use (see its terms).
  • No state for the IR remotes; no cleaning programs for the newer robot vacuums; no fan modes, night lights or child locks; no keypads, cameras, video doorbells, thermostats or Relay Switch 2PM yet.
  • The integration only counts its own API calls, not those of your other apps.
  • Developed without the hardware nor a SwitchBot account: field names and values come from the SwitchBot documentation and from the Home Assistant tests.

Configuration settings​

These are the settings SwitchBot asks for in its configuration screen in Gladys.

SettingTypeRequiredDescription
Your SwitchBot tokensectionNoIn the SwitchBot app (version 9 or later): Profile, Preferences, About, tap App Version 10 times, then Developer Options: copy the token and the secret key below. Devices that talk Bluetooth need a SwitchBot hub and their cloud service turned on in the app.
TokensecretYesThe token shown under Developer Options in the SwitchBot app.
Secret keysecretYesThe secret key shown under the token. It signs every request and never leaves Gladys.
Refresh intervalselectNoHow often each device is read. SwitchBot allows 10,000 calls a day per account: automatic stays within half of it, and a shorter interval is lengthened when it would not.
Real time through Gladys PlusbooleanNoNeeds Gladys Plus and its Open API key in the webhooks block. SwitchBot keeps ONE webhook per account: this replaces the one of another app (Home Assistant...).
IR remotesbooleanNoAlso publish the virtual infrared remotes of your hubs (TV, air conditioner...), for their power button and the "Send an IR command" scene action.
Allow locking and unlockingbooleanNoOff: the locks are read only. On: the locks added afterwards can be locked and unlocked from Gladys, its scenes and its assistants.
Language of the feature namesselectNoNames given to the features of new devices (Temperature, Position, Battery...).

How to install SwitchBot in Gladys​

  1. In Gladys, open Integrations: SwitchBot appears in the catalog, next to the native integrations, with a community badge.
  2. Click Install. Gladys pulls the Docker image (ghcr.io/guim31/gladys-switchbot:1.0.1), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration).
  3. Open the Configuration screen of the integration, fill in the settings, and save.
  4. You can also install it directly from its repository URL: https://github.com/guim31/gladys-switchbot.

SwitchBot requires Gladys >=5.1.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​

SwitchBot 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 guim31, not by the Gladys core team.

Subscribe to the Gladys Assistant newsletter

A few emails per month about new releases and project news. Sent by Pierre-Gilles Leymarie, founder of the project. Unsubscribe anytime 🙂
Last updated on