[APP][Cloud & Pro] SwitchBot (Release 1.1.51, Test 1.1.56)

This app is used to control SwitchBot devices.
It supports both BLE and the hub methods for Curtains, Bots and the temperature / Humidity modules.

If you are interested in purchasing SwitchBot products and would like to support me then use the following link to their store as I will get 10% commission on your purchase.

SwitchBot | Homey

When adding BLE devices, it is strongly recommended that you keep Homey and the device as close together as possible. If the distance is too large then Homey may cache partial data about the device that makes it unrecognisable. Once that data is cached it can be hard to remove and might require a restart of Homey to clear it.

The limitations of the app:

  1. Hub: The SwitchBot hub API only allows 10000 accesses per day. That means the refresh of the current state to get changes is slow, and the more devices you have the slower the refresh as each device requires one access. It does however control the devices well.

  2. BLE: The maximum polling rate allowed on Homey’s BLE is 30 seconds, so updates can be slow. However, unlike the Hub, it doesn’t matter how many devices there are as all the information is gathered in one request.

  3. BLE: Range is quite small, due to the Low Energy nature, and Homey’s range is lower than other devices like your phone or the SwitchBot hub. So, it might be difficult to find a location that can reach the devices.

SwitchBot have now added support for some notifications via a webhook. This means that certain features on some devices are now much faster to activate on Homey. These include Motion detection on the Motion sensor, Contact operation on the Contact sensor (includes entering or leaving), all the colour bulb features and both values on the Temperature and Humidity sensors.
The webhook is supported in version 1.1.0 onwards.

Using the Hub
For versions before 1.0.0

To get the token required to access the SwitchBot API, go to SwitchBot phone app and select Profile –> Preferences then tap 10 times on “App Version”. A new Developer Options option will appear in the list. Tap on that and the token will be displayed.
Copy this token (it is quite long so use the Copy command on your device if you can)

Next, open the Configure App screen of the Homey SwitchBot app and paste the code in to the API TOKEN field.

For version 1.0.0. onwards

Use the normal procedure to add a device to Homey. During the process, you maybe redirected to a SwitchBot page to enter your username and password. Once you have done that and submitted the form, you can close the page. Providing the details are correct you will then be able to select the devices that have been added to your SwitchBot account.

Bot Switch Mode (Toggle / Press)
Versions 0.2.4 and later have been updated to work with the Push Button mode of the Bot. For the BLE version, this is automatic as the required information is provided in the data packet. For the Hub version, the information is not made available via the API, so there is a setting in the Advanced Settings page to enable it.
Note: The actual setting for the device has to be set via the SwitchBot phone app as there is nothing documented in the protocols to be able to change it from the Homey app.

Alternative BLE connection
I have created an app that runs on a ESP32, Arduino compatible board. I have made the app available on Github:

The boards are pretty cheap on Amazon, but the installation is medium complexity, so may not be for everyone.

Once the board is programmed, it is plug and play with the Homey SwitchBot app V0.2.4 and later. You just add BLE devices to Homey in the normal way.

The advantages of using an ESP32 board are:

  1. Very fast feed back of device state changes via a notification method. I can see the curtain position slider animate through several positions as the curtains open and close. Also, real-time feedback of contact sensor and motion sensor state changes.
  2. Connects to Homey via WiFi, so can be positioned to reach SwitchBot devices that are too far from Homeys built in BLE.
  3. Uses a local connection so can be used even if you internet connection is not working.

There are instruction in the Github repository to assist programming the board.

Version History


  • Initial release


  • Added BLE Temperature and Humidity


  • Added HUB Temperature and Humidity, HUB Bot and BLE Bot


  • Added Invert Position and Motion Mode to advanced settings for curtains


  • Fixed Invert Position for HUB connected curtains


  • Added Air Conditioner Remote


  • Fixed operation of the Switch Bot to honour the single press mode when selected in the SwitchBot app. BLE can detect the mode setting but for the hub you have to adjust the Advanced setting.


  • Fix for the Homey BLE caching issue.
    Note, this fix is only for devices that are in the app and will not help fix the issue of detection when adding devices, if Homey has cached bad data for the new device that makes it impossible to recognise it.


  • Added On/Off capability to curtains so they can be fully opened/closed by tapping on the tile


  • Added a check for a SwitchBot device with no service data in the discovery, so the entry in the BLE cache can be cleared ready for the next discovery.


  • Fix Bot state check when using Homey’s BLE.
  • Adding my BLE hub no longer disables Homey’s BLE checking so both are now used.
  • Added error handler around JSON parsing to cope with bad data.


  • Attempt to add devices based on the localName id there is no service data.


  • Changed logging to multi-level to make it easier to spot general issues.
  • Cleaned up the retries loops.


  • Ensure log level is initialised at start up.


  • Optimised for Homey V6 firmware, but still compatible with V5.


  • Optimised for activating multiple devices simultaneously.
  • Added Position value to information.
  • Added buttons to send the logs from the configuration page.


  • Added Position value to hub curtain information.
  • Fixed issue during pair curtains.


  • Added support for Scenes.
  • Added support for the DVD and Speaker remote devices.


  • Added ‘Run Scene’ action flow card so scenes can be run without needing to add them as a device.


  • Fix remote parameters and command switched.


  • Fixed TV, DVD and set top box that I broke in 0.3.5 because they didn’t need reversing.


  • Added support for the SwitchBot Humidifier


  • Added support for passwords on bots
  • Fixes for Humidifier


  • Added flow action card to select a specific channel number.


  • Separated On and Off to individual buttons for the AC device.
  • Decoded error messages reported in device view to prevent [object Object] being reported.


  • Fix On / Off flow actions for AC remote.


  • Added BLE Presence sensor
  • Added BLE Contact Sensor.

When used with Homey BLE, it can take up to 30 seconds for the state to change due to the limited refresh rate. With my ESP32 hub the state change is instant in Homey.


  • Updated BLE Contact Sensor (added contact left open, button press and fixed Bright).


  • Updated BLE Contact Sensor (added entry and exit).


  • Reduce Hub polling interval to improve responsiveness. Added Smart Fan and Remote Fan.


  • Added trigger flows for Fan remote.


  • Fix Remote On and Off action cards.


  • Fix AirCon On and Off action cards.

SwitchBot have published the BLE API for the Contact and Motion sensors so they should now be stable.

Now being published under the official SwitchBot account.


  • Big code reorganise in preparation for Possible Homey / Homey Bridge usage.
  • Added error handling around API calls that might have prevented polling timer from restarting.
  • Added Presence Sensor (Hub).
  • Added Contact Sensor (Hub).


  • Add Color Bulb (Hub).


  • Fixed ‘Set nebulization efficiency’ flow card.


  • Added support for custom IR remote controls.


  • Added support for connecting with your SwitchBot username and password instead of getting an API key


  • Added battery type information to devices.


  • Fixed setTimeout error.


  • Changed the default Curtain Motion mode to Performance.,
  • Report errors to control window when command fails.


  • Improved action card titles.


  • Deprecated contact and motion sensor to allow the app to be published (these will be resurrected when a reliable notification method has been created).


  • Revived contact and motion sensor.
  • Added the Light remote.


  • Added more diagnostics logging.


  • Set remote air conditioner temperature limits to prevent invalid values being sent.


  • Fix for curtain BLE data change with firmware version 3.9.


  • Added webhook for faster response to:
    Contact Sensor (HUB) - Door contact open / close,
    Motion Sensor (HUB) - Presence detection,
    Temperature & Humidity (HUB) - Temperature / Humidity change,
    Colour Bulb - All features (I nearly forgot this one)


  • Added Exited capability for the contact sensor the show true if the motion was detected before the contact was opened and false if motion was detected after the contact was opened. The capability is set to null when the contact is closed so the trigger can detect the new state even when it is the same as the old state.


  • Added extra tags for supported AC remotes.


  • The Bot class is now set to socket when the Bot is in Switch mode so it can be added to HomeKit.


  • Small changes to images and hint wording for publishing approval


  • Improved the error message shown for the device when a command fails.


  • Fixed start scene flow card.


  • Reset Left Open capability when contact open cleared.


  • Added camera motion sensor.


  • Fixed use of a function that is not available on older Homeys.
  • Attempt to register webhook every 2 seconds if it fails due to Homey connection issues.


  • Added support for Light Strips


  • Fix for DIY Air conditioner (only supports on and off).


  • Reverse On / Off commands for DIY Air conditioner.


  • Increased the number of buttons to 36 for a custom remote.
  • Added support for the SwitchBot Lock.


  • Change log levels…
  • Updated Contact webhook for new format.


  • Updated to API v1.1 so door lock can now be controlled.


  • Restores logging level at start up.
  • Added more webhook logging.


  • Added support for HUB 2 via Temperature & Humidity sensor.


  • Fixed an app crashing issue.


  • Unset warnings when device recovers.


  • New icon for Blind Tilt device.


  • Fix direction for Tilt device. Add flow cards for Tilt device.


  • Work around bug in API for Tilt device and convert ‘setPosition: down;0’ to ‘closeDown’.
  • Set dead zone in middle of slider to make it easier to select fully open.


  • Added Tilt BLE device.


  • Fix for Homey 2023 as it reports the long UUID instead of the short version.


  • Added battery information to devices that report it.


  • Added Projector remote control.


  • Supports Blind / Tilt firmware v2. This removes the requirement of getting the position by sending a command as it is now supplied in the advertisement data.


  • Fix for Get Device Log when no devices were found during the Add Device stage.


  • Added Air Purifier Remote.


  • Added luminance to Temperature and Humidity device when it is a Hub 2.
  • Added webhook support for more devices and reduced polling.


  • Added Alarm for door jammed. Changed Hub 2 luminance to Brightness as a percentage of it range.


  • Fix for new T & H I/O data format.


  • Fix for new T & H I/O temperature data format.


  • Enhanced performance for ESP32 BLE hub.


  • Update for new Bot BLE data format.


  • Update for new Curtain 3 Hub data format.


  • Added Light Level to Curtains BLE.


  • Fix for Curtains 3 hub not being found due to missing device type in API response.
  • Fix for BLE Curtain 3 not being found due to changed device id field.


  • Polling added for Curtains 3 hub as they don’t provide webhook data.
  • Fix Light Level changed trigger.",

Added support for Plug Mini.


  • Fixed image for Plug Mini.


  • Added door open alarm (not included in the webhook data so polled only).
  • Added general alarm for Lock when it is jammed.
  • Fix error when processing Lock webhook data.


  • Added Open/Pause/Close capability to curtains.
  • Fix Plug Min (US) and Plug Mini (JP) detection

Added support for the Vacuum Cleaner.


  • Added trigger with drop list for state plus a condition card with the state to the Vacuum Cleaner.
  • Fixed the dock command for the vacuum cleaner.


  • Fixed spelling error defined in the API document.


  • Added Curtain3 to list of curtain devices.


  • Added Curtain3 to list of curtain devices. Added Norwegian translations thanks to Philip Østli


  • Added Flow action card to move curtains at performance or quiet speed (thanks to Dennie de Groot)


  • Reduce Error information in the log. Added initial support for the Lock Pro. Changed the trigger card for vacuum to use ‘clearing’ instead of ‘cleaning’.


  • Added setting for curtain devices to change the class type to blind for better Google integration."


  • Trigger On/Off Flow card in Bot Press Mode, Added support for the Robot Vacuum Cleaner S10.


  • Added support for the Robot Vacuum Cleaner K10+.


  • Added Flow action card to move curtains at performance or quiet speed for the HUB variant.


  • Fix Lock door open/ closed detection for updated API format.


  • Added support for the SwitchBot Water Leak detector

If you have any requests or find any issues please get in touch on here.


I will add support for more SwitchBot devices in the future if there is a demand for it.


I had a reply from Switchbot:


Integrating SwitchBot with Homey would be a good idea. And the other request you mention, I have noted them down and reported them to our developers. They will consider those seriously.

Also, we have been considering publish the local API of the SwitchBot Hub Mini, so that users can access to the Hub locally. I don’t have the ETA for that but our developers are working on it. When it is ready, we will release it to the public.

Thank you for your interest and great support.

SwitchBot Team

So fingers crossed they will do something so I can improve the app.


It would be great if you could add the Hub+, switches and thermometer as well. At the moment I’m still integrating the switches into Homey via Home Assistant.


I have submitted a new version for test, but as the app has not been published yet it means it has to go through the review again.
So the link in the first post will be unavailable until Athom have accepted it again.

When it is there, it will be version 0.2.0 and it will have support for the Bot and the Temperature / Humidity module on both BLE and via the API (hub).

The BLE and hub limitations are still there so hopefully Athom and SwitchBot will fix those at some point.


I look forward to it. Switchbot is a very good system and your app will make Homey even better :+1::+1::+1::+1::+1:

Hi Adrian,

Thanks for this initiative! I have a Hub mini and a bot which I have integrated in Homey via IFTTT (I know…) and webhooks. But a direct integratiin would be very much appreciated.

Good luck!

I get the error message below when I try to install it on my Homey:

Er is een onbekende fout opgetreden [incompatible_app_version]

Any idea what could cause this?

The app is written for Homey firmware v5, so if you are still on v4 then you will see that message.

1 Like

Thanks for the quick reply.

Hopefully the Homey v5 firmware release will fix the BLE issues, which will not be fixed in v4. Therefore I didn’t see much point in making it v4 compatible as it would never work properly.

The new test version is now live.

1 Like

Added the app and could add my Hub mini and bot.

Tip: to get the token go to SwitchBot app → Profile –> Preferences and tap 10 times on “App Version”. It will generate the token for you.

1 Like

Oh yes, thank you for adding that as I completely forgot to mention it.


I have 4 thermostats,2 bot and the hub mini and if you could create an app with our Homey,will be very appreciated😊Thanks for your work!

If you install the current test version (assuming you are Homey v5 firmware), then you can control the bots via the hub and, with that number of devices, refresh the current values from all the devices about every 30 minutes.

Thanks for your reply,haven’t see on the first post the link,i will try😁

1 Like

@Adrian_Rockall Hi,

Great app, thanks for your hard work.

1 Like

Thanks!! Works fantastic!!!

1 Like

Many many thanks. The app works very well and saves me a detour via IFTTT and Home Assistant. Great work! Are you planning to include the Hub Plus infrared devices in the app at some point?

I will add support for any device provided by the API.
I had an email this morning to say their local API is in beta and will be available via GitHub when released. So fingers crossed that is soon.