This app is used to control SwitchBot devices.
It supports both BLE and the hub methods for Curtains, Bots and the temperature / Humidity modules.
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:
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.
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.
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:
- 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.
- Connects to Homey via WiFi, so can be positioned to reach SwitchBot devices that are too far from Homeys built in BLE.
- 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.
- 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.
If you have any requests or find any issues please get in touch on here.