User Tools

Site Tools


Sidebar

supported_hardware:switchbot

Switchbot

The Switchbot is a BluetoothLE button pushing and switch toggling robot. The Switchbot plugin is not included in XTension but can be downloaded separately. It requires at least XTension version 9.4.8. This plugin connects to the Switchbot over Bluetooth LE so a Switchbot Hub is not needed. However, this does mean that your Switchbot must be within BluetoothLE range of your XTension machine in order to operate.

Download The Plugin

MD5 hash of the zip file: 521d43cc17b674c378c4dc60eeb2ff32

Installing

Download and decompress the above linked file. You should be left with a folder named “switchbot.isf” inside XTension pull down the “Database” menu and select “install plugin” A choose folder dialog will appear and you should select the switchbot.isf folder. XTension will copy the folder into your database and make it available for use. The same procedure can be used to upgrade an older version of the plugin. Since all plugin files and requirements are included in that folder as long as you’re backing up your XTension database you are also backing up your Switchbot plugin. Restoring your database to a new machine or a new hard drive is all that is necessary to get you back up and running again.

Uninstalling

First delete or change the device type of any switchbot interfaces you have created in XTension.

All files relating to this plugin are kept inside your databases plugin folder. To find that pull down XTension’s Database menu and select “Reveal plugins folder in this database” and the plugins folder will appear in the Finder. Open the plugins folder and delete the “switchbot.isf” folder that you will find inside of it.

You should then restart XTension so that the plugin no longer appears in the list of available device plugins.

Setup and Use

  • You should only need a single instance of the Switchbot plugin for control of any number of switchbots.
  • Open the “Interfaces” window from XTensions Windows menu. Click the “new” Interface button in the toolbar to open a New Interface window.
  • From the “Device” popup select Switchbot.
  • Save the interface, or click “apply” (note that there is a bug in XTension 9.4.8 that requires you to save the interface closing the window and then double click it in the list to re-open the window before you continue.)
  • Enable the interface by checking the enabled checkbox either in the Edit Interface window or the Interfaces list window.
  • Bring any switchbots that you want to use from XTension into range of the computer.
  • In the Edit Interface dialog enter the number of switchbots you wish to scan for. This isn’t required but it will scan for the entirety of the timeout period if it doesn’t know how many switchbots it’s looking for. If you enter the number then it will finish scanning as soon as the number of switchbots has been found. It can take a while to discover them as they are saving battery power and aren’t always immediately awake. If your switchbot doesn’t show up try increasing the timeout period and trying again.
  • Once a switchbot has been found XTension will automatically create a Unit representing the device. A new list window will open called “Switchbots” that will contain a unit representing any found switchbot devices.
  • Click the jewel icon of the new switchbot unit and select “edit” from the control dialog that will appear, or control click on the unit in the list and select “Edit“
  • At this point you can change the default name of the switchbot unit to be more descriptive as it will have just defaulted to “switchbot” and it’s long bluetooth uniqueID.
  • In the first tab of the Edit Unit dialog in the Device Options portion there will be a “behavior” popup. You can select “Press” or “Toggle”. If you select “Press” then turning on the unit in XTension will result in a button press being performed in the switchbot. It will extend it’s arm, pause for whatever time you have setup in it’s firmware, and then retract it’s arm. The XTension unit representing this device will return to the Off state as soon as the switchbot has accepted the command. If you select “Toggle” then sending an On command for the unit will extend the Switchbot’s arm and turning the unit off will retract it.
  • Don’t change the unit address. That must remain the BluetoothLE unique id for this switchbot.
  • Save the Edit Unit dialog and you’re ready to use your Switchbot.

Switchbot Info

XTension does not yet get any into about battery level or other internal status. I can add this later and will prioritize such things if people let me know that they need this.

You cannot set the press time from XTension. This is the value of how long the press of a button lasts before it backs off. If you set the press time with the regular Switchbot app it will remember it and the same settings will be used when pressing or toggling from XTension.

It can take some time for the Switchbot to respond to a command depending on it’s sleep cycle. At this moment the timeout for a command other than scanning is preset to 30 seconds. I can make this adjustable in the future if you have devices that regularly take longer to respond please let me know.

Known Issues

You will see some debug logging when you use the Begin Scan button. You can just ignore that.

There may be problems parsing the output for multiple switchbots when scanning. I only have the one to test with so I was not able to test that. If you have multiple switchbots and they are not properly created in XTension after doing a scan please turn debug mode on for the interface and perform another scan. Send me the log output from the results of that and I will better be able to make sure that is working.

The security pairing of the Switchbot is not supported. If you have turned on the pairing requirement in the switchbot app on your phone you’ll need to turn that off before it will be recognized by XTension.

History

  • The Switchbot plugin was first released after XTension version 9.4.8 on 8/10/2018 and requires at least that version
supported_hardware/switchbot.txt · Last modified: 2018/08/10 18:52 by James Sentman