Skip to content
BranchesTags
 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

98 Commits
.github
.github
 
 
pyscript
pyscript
 
 
CHANGELOG.md
CHANGELOG.md
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 

Repository files navigation

License Maintenance Activity Donation

SwitchBot API Script Caller (v 0.3)

This (Py)Script allows you to control all (WIP) your SwitchBot devices via API calls (1.1).

Warning
At the moment not all API-compatible models are implemented, if you have the capability do a fork and implement it (and request a PR), otherwise open an issue with "TEST|Model_Name" in the title.

For more info click here

Requirements

  • HACS (docs)
    • PyScript Integration (docs)

Installation

Procedure

  1. Clone this repository in your config folder

    cd /config
git clone https://github.com/SiriosDev/SwitchBot-API-Script-Caller.git

  2. Check if you have a pyscript/config.yaml file. If not, create one and then add the following in your main top-level configuration.yaml file.

    pyscript: !include pyscript/config.yaml

  3. Include pyscript/switchbot.yaml in your pyscript/config.yaml under the switchbot section

    # /config/pyscript/config.yaml
allow_all_imports: true
apps:
  # (...)
  # ↓↓↓ attention indentation
  switchbot: !include /config/SwitchBot-API-Script-Caller/pyscript/switchbot.yaml
# (...)

  4. Set the authentication secrets in secrets.yaml homeassistant 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

  5. Link the files in the pyscript directory

    # 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

Further Updates

By following this procedure, the script can then be updated with newer version using git.

cd SwitchBot-API-Script-Caller
git pull

Warning
The project is still under development, and breaking changes may frequently occur.

If you update from one of the following versions there have been breaking changes:

Versions

Installation Notes

  • In order to see the Developer options in the Switchbot app (version ≥6.14), click repetively on the version number in the App's settings.

    Click here for detailed procedure

    SwitchBot

  • 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 pyscript is 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 via git pull to fail.

How To Use

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.

Summary

SwitchBot Refresh Devices

Warning
(API call consumed: 1*execution)

This service lists all the devices registered in your Switchbot Hubs™ connected to your account.

The new entities will have a type corresponding to that of the switchbot app, following the best type-domain association, in case of mismatch will be assigned to the domain switch.

Note
These devices are stored as <entity_domain>.switchbot_remote_<device_name>.
e.g. A SwitchBot Curtain™ will become cover.switchbot_remote_bedroom_curtains.

Note
The <device_name> corresponds to the name of the device in the SwitchBot app, (with _ instead of ).
If it does not contains Alphanum characters, it is replaced by <deviceType>_<deviceId[-4:]>
(e.g. switch.switchbot_remote_light_0D62) The <deviceId> is an internal unique code.

Warning
The entities can then be used for sending commands or getting status using other functions of this pyscript.
Not working stand alone.

If this service does not find all the devices it had previously found, it will alert you with a persistent notification in the HA WebUi.

Example

service: pyscript.switchbot_refresh_devices

Service Data

None

Switchbot Get Status

pyscript.switchbot_get_status

Gets the state of Switchbot Bots, Contact Sensors, Curtains and Meters. Runs every five minutes generating 288 API calls per sensor per day. Switchbot limits API calls to 10,000 per day. So, this limits the number of devices to 34 (excluding IR devices.) See the SwitchbotAPI API for the data returned from a status call.

Parameters: None

SwitchBot Turn On

pyscript.switchbot_turn_on

Turn a device ON.

Parameters:

SwitchBot Turn Off

pyscript.switchbot_turn_off

Turn a device OFF.

Parameters:

SwitchBot Bot Control

pyscript.switchbot_bot_command

Interface for "Classic" Bot (turnOn, turnOff, press) devices.

Parameters:

  • device
  • command:
    • string value between turnOn, turnOff, press
  • repetition:
    • int value from 1 to 10, only works with press, iterates the command as many times as selected.

Switchbot Curtain Control

pyscript.switchbot_curtain_command

Interface for Curtain (turnOn, turnOff, setPosition) devices.

  • device
  • command:
    • string value between turnOn, turnOff, setPosition
  • index:
    • [wip] int value between ????? (required for "setPosition" command, otherwise it will be ignored)
  • mode:
    • string value between Performance, Silent, Default (required for "setPosition" command, otherwise it will be ignored)
  • position:
    • int value (in percentage) between 0 and 100 (required for "setPosition" command, otherwise it will be ignored)

SwitchBot IR HVAC Control

pyscript.switchbot_hvac

Interface for infrared HVAC (heating, ventilation and air conditioning) devices.

Parameters:

  • device
  • state:
    • string value between on and off
  • temperature:
    • int value from 16 to 30
  • mode:
    • string value between Auto, Cool, Dry, Fan, Heat
  • fan_speed:
    • int value between Auto, Low, Medium, High

SwitchBot IR Light Control

pyscript.switchbot_ir_light_control

Interface for infrared Light (turnOn, turnOff, brightnessUp and brightnessDown) devices.

Parameters:

  • device
  • command:
    • string value between turnOn, turnOff, brightnessUp and brightnessDown
  • steps:
    • int value from 1 to 10, only works with brightnessUp/Down, iterates the command as many times as selected.

SwitchBot Generic Command

pyscript.switchbot_generic_command

Allows you to send any request to the API. (See documentation)

Parameters:

  • device
  • command:
    • One of the commands supported by the device. (see documentation)
  • parameter: (optional)
    • Parameter for the command, if required (e.g. SetChannel)
    • use default if not used
  • commandType:
    • command for standard commands
    • customize for custom commands

Work in Progress

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).

Changelog

v? (🟢 New Features)

Add support for non-IR devices : Bot, Contact Sensor, Curtain and Meter.

Add service 'Switchbot Curtains Command' : Send command to Curtain device.

Add time trigger to get the status of Bots, Contact Sensors, Curtains and Meters every 5 minutes. This will show in the Logbook even if you only have IR devices. However, the API calls will only be made for non-IR devices.

Add time trigger to run 'Refresh Devices' at startup.

2023.02.19 v0.2.1 (🛠️ Some Fixes)

Fixed (#15) commandType parameters in Generic Command.
Suggest updating if you need to control custom remotes created in the mobile app.

2023.01.16 v0.2.0 (🟢 New Features and 🛠️ Some Fixes)

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.

2023.01.14 v0.1.0 (⚠️ Breaking changes)

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.

Full Changelog History here

SwitchBot API Script Caller is an unofficial, community-driven script NOT affiliated, endorsed or supported by Wonderlabs, Inc. Some images used in this app are copyrighted and are supported under fair use. SwitchBot and SwitchBot model names are trademarks of Wonderlabs. No copyright infringement intended.
© SwitchBot Global.
© Wonderlabs.

PyScript is distributed under Licenselicense.
The APIs are distributed under License license.
HomeAssistant is distributed under License license.

The License at the top of this document refers only to the code in this repository

About

This (Py)Script allows you to control all (WIP) your SwitchBot devices via API calls (1.1)

Topics

apihassiohome-assistanthome-automationhomeassistantpyscriptswitchbot

Resources

Readme
License
Activity

Stars

14 stars

Watchers

3 watching

Forks

4 forks
Report repository

Sponsor this project

Contributors

Languages