⚠️ ⚠️ ⚠️ ⚠️ Attention following the creation of the official HomeAssisant integration I have decided that, if it is necessary, I will work to bring any features into the said integration, so unless something new comes along, this repository will soon become discontinued ⚠️ ⚠️ ⚠️ ⚠️
This (Py)Script allows you to control all (WIP) your SwitchBot devices via API calls (1.1).
For more info click here
Versions
- Clone this repository in your config folder
cd /config git clone https://github.com/SiriosDev/SwitchBot-API-Script-Caller.git - Include
pyscript/switchbot.yamlin yourpyscript/config.yamlunder theswitchbotsection# /config/pyscript/config.yaml allow_all_imports: true apps: # (...) # ↓↓↓ attention indentation switchbot: !include /config/SwitchBot-API-Script-Caller/pyscript/switchbot.yaml # (...)
- Set the authentication secrets in
secrets.yamlhomeassistant file- Random Value (
switchbot_nonc) (I suggest using an UUID generator, but any unique alphanumeric string is fine)
# secrets.yaml # (...) # Token and Secret Key : from `Developer Option` in the SwitchBot App (version ≥6.14) switchbot_token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx switchbot_sec: xxxxxxxxxxxx # Random Value: you can use a UUID generator, but any unique alphanumeric string is OK switchbot_nonc: xxxxxxxxxx
- Random Value (
- Link the files in the
pyscriptdirectory# use `mkdir -p /config/pyscript/apps/` if the directory doesn't exist cd /config/pyscript/apps/ # Create a symbolic link to the apps directory named switchbot ln -s /config/SwitchBot-API-Script-Caller/pyscript/apps/switchbot.py switchbot.py
By following this procedure, the script can then be updated with newer version using git.
cd SwitchBot-API-Script-Caller
git pull
The project is still in developpement and breaking changes may occurs.
-
In order to see the
Developper optionsin the Switchbot app (version ≥6.14), click repetively on the version number in the App's settings.Click here for detailed procedure
-
A symbolic link is symbolic and represent the exact path you enter, if you move the targeted file or if the target is outside of the container (e.g. when using docker) the link will not work. Make sure that you are using a relative path that is accessible for the host reading the link.
-
Ensure that
pyscriptis operational before to install this script. -
Except dirs strictly related to pyscript, all others dir are recommended, so organize them as you like, keeping in mind that changing the contents of the "
clone", could cause the update viagit pullto fail.
This script (for now) provides the following services in home assisant.
It is important to execute SwitchBot Refresh Devices first in order to be able to use the other features, as it will generate the required Home Assistant entities for your devices.
- SwitchBot Refresh Devices (
pyscript.switchbot_refresh_devices) - SwitchBot Turn ON (
pyscript.switchbot_turn_on) - SwitchBot Turn OFF (
pyscript.switchbot_turn_off) - SwitchBot IR HVAC Control (
pyscript.switchbot_hvac) - SwitchBot IR Light Control (
pyscript.switchbot_ir_light_control) - SwitchBot Generic Command (
pyscript.switchbot_generic_command)
Create Home Assistant switch entity for each IR Device connected with your SwitchBot Hubs. Devices are stored as switch.switchbot_remote_<device_name>.
<device_name> correspond to the name of the device in the SwitchBot app.
if <device_name> doesn't contains Alphanum characters (e.g is written in another alphabet), it is replaced by <deviceType>_<deviceId[-4:]> (e.g. switch.switchbot_remote_light_0D62)
The entities can then be used for sending commands using other functions of this pyscript.
Parameters: None
Turn a device ON
Parameters:
device
Turn a device OFF
Parameters:
device
Interface for infrared HVAC (heating, ventilation and air conditioning) device.
Parameters:
devicetemperature:- int value from
16to30
- int value from
mode:- int value between
1(auto),2(cool),3(dry),4(fan),5(heat)
- int value between
fan_speed:- int value between
1(auto),2(low),3(medium),4(high)
- int value between
state:- string value between
onandoff
- string value between
Interface for infrared Light (turnOn, turnOff, brightnessUp and brightnessDown) device.
Parameters:
devicecommand:- string value between
turnOn,turnOff,brightnessUpandbrightnessDown
- string value between
steps:- int value from
1to10, only works withbrightnessUp/Down, iterates the command as many times as selected.
- int value from
Allows you to send any request to the API. (See documentation)
Parameters:
devicecommand:- One of the command supported by the device. (see documentation)
parameter:(optional)- Parameter for the command, if required (e.g.
SetChannel) - use
defaultif not used
- Parameter for the command, if required (e.g.
commandType:commandfor standard commandscustomizefor custom commands
The script works fine, but everything is still WIP, including this file. For any problems open an Issue, (soon I will insert a template for that).
Fixed (#15) commandType parameters in Generic Command.
Suggest updating if you need to control custom remotes created in the mobile app.
Add service SwitchBot IR Light Control:
Send command via infrared to light device.
Corrected some descriptions.
Reworked the way Refresh Devices assigns Friendly Names.
Removed notifications to all channels in case of errors during Refresh Devices.
Now HVAC will have a dedicated icon once the dummy switch is created (Refresh Devices).
Renamed SwitchBot HVAC API Interface in SwitchBot IR HVAC Control: it doesn't affect function it's just a visual thing.
Renamed SwitchBot Generic Command API Interface in SwitchBot Generic Command: it doesn't affect function it's just a visual thing.
Add service SwitchBot Refresh Devices:
Retrieves your IR devices from the API. Services now requires device instead of deviceId. No need to copy paste the id manually anymore.
Previously:
- Services param was
deviceId
Now:
- Services Param is
device(home assistant ID for sensor, e.g.switch.switchbot_remote_my_light)
Make sure to run SwitchBot Refresh Devices before configuring anything else.
