Skip to content

Latest commit

 

History

History
232 lines (177 loc) · 9.78 KB

README.md

File metadata and controls

232 lines (177 loc) · 9.78 KB
Raw

License All rights to the API belong to OpenWonderLabs.

⚠️⚠️⚠️⚠️ 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 ⚠️⚠️⚠️⚠️

SwitchBot API Script Caller (v 0.2.1)

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

‼️‼️At the moment we have implemented all the devices that we can test, so if you want to be a tester please open an issue with "test" in the title or if you are also able to develop go ahead and do a PR‼️‼️

For more info click here

Requirements

  • HACS (docs)
    • PyScript Integration (docs)

Installation

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

Versions

Procedure

  1. Clone this repository in your config folder 
    cd /config
git clone https://github.com/SiriosDev/SwitchBot-API-Script-Caller.git
  2. 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
# (...)
  3. 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
  4. 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 Update

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

cd SwitchBot-API-Script-Caller
git pull

⚠️ See changelog before updating.
The project is still in developpement and breaking changes may occurs.

Installation Notes

  • In order to see the Developper 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

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. ⚠️ Not working stand alone ⚠️ In case the device doesn't exist in the future, you will be notified on your devices.

Parameters: None

🔸SwitchBot Turn On

Turn a device ON

Parameters:

🔸SwitchBot Turn Off

Turn a device OFF

Parameters:

🔸SwitchBot IR HVAC Control

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

Parameters:

  • device
  • temperature:
    • int value from 16 to 30
  • mode:
    • int value between 1 (auto), 2 (cool), 3 (dry), 4 (fan), 5 (heat)
  • fan_speed:
    • int value between 1 (auto), 2 (low), 3 (medium), 4 (high)
  • state:
    • string value between on and off

🔸SwitchBot IR Light Control

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

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

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

Parameters:

  • device
  • command:
    • One of the command 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

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