pySwitchbot

Library to control Switchbot IoT devices https://www.switch-bot.com/

Setting up the environment

python3 -m venv .venv
source .venv/bin/activate
pip install .

Obtaining encryption key for Switchbot Locks

Using the script scripts/get_encryption_key.py you can manually obtain locks encryption key.

Usage:

$ python3 scripts/get_encryption_key.py MAC USERNAME
Key ID: XX
Encryption key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Where MAC is MAC address of the lock and USERNAME is your SwitchBot account username, after that script will ask for your password. If authentication succeeds then script should output your key id and encryption key.

Troubleshooting key retrieval

Key retrieval talks to SwitchBot's account API with your username and password. The most common failures are account-side, not bugs in this library:

Authentication failed: ... — the username/password were rejected. This happens when:
- Two-factor authentication (2FA) is enabled on the account. The API login used here does not support a verification code, so 2FA accounts cannot retrieve keys this way — temporarily disable 2FA, fetch the key, then re-enable it.
- The account was created via "Sign in with Apple"/Google and has no password set. Set a password in the SwitchBot app first, or use an email/password account.
- The username is an email but the account is registered to a phone number (or vice versa). Use the exact identifier you log in with.
Failed to retrieve encryption key from SwitchBot Account: ... — authentication succeeded but the key could not be read. Usually the account is not the device owner: keys are only returned to the owning account, not to shared/family members. Retrieve the key from the owner account, or transfer ownership in the app.

The key only needs to be fetched once; store the key_id and encryption key and reuse them — there is no need to call the script on every connection.

Examples:

WoLock (Lock-Pro)

Unlock:

import asyncio
from switchbot.discovery import GetSwitchbotDevices
from switchbot.devices import lock
from switchbot.const import SwitchbotModel

BLE_MAC="XX:XX:XX:XX:XX:XX" # The MAC of your lock
KEY_ID="XX" # The key-ID of your encryption-key for your lock
ENC_KEY="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" # The encryption-key with key-ID "XX"
LOCK_MODEL=SwitchbotModel.LOCK_PRO # Your lock model (here we use the Lock-Pro)


async def main():
    wolock = await GetSwitchbotDevices().get_locks()
    await lock.SwitchbotLock(
        wolock[BLE_MAC].device, KEY_ID, ENC_KEY, model=LOCK_MODEL
    ).unlock()


asyncio.run(main())

Lock:

import asyncio
from switchbot.discovery import GetSwitchbotDevices
from switchbot.devices import lock
from switchbot.const import SwitchbotModel

BLE_MAC="XX:XX:XX:XX:XX:XX" # The MAC of your lock
KEY_ID="XX" # The key-ID of your encryption-key for your lock
ENC_KEY="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" # The encryption-key with key-ID "XX"
LOCK_MODEL=SwitchbotModel.LOCK_PRO # Your lock model (here we use the Lock-Pro)


async def main():
    wolock = await GetSwitchbotDevices().get_locks()
    await lock.SwitchbotLock(
        wolock[BLE_MAC].device, KEY_ID, ENC_KEY, model=LOCK_MODEL
    ).lock()


asyncio.run(main())

WoCurtain (Curtain 3)

import asyncio
from pprint import pprint
from switchbot import GetSwitchbotDevices
from switchbot.devices import curtain


async def main():
    # get the BLE advertisement data of all switchbot devices in the vicinity
    advertisement_data = await GetSwitchbotDevices().discover()

    for i in advertisement_data.values():
        pprint(i)
        print()  # print newline so that devices' data is separated visually

    # find your device's BLE address by inspecting the above printed debug logs, example below
    ble_address = "9915077C-C6FD-5FF6-27D3-45087898790B"
    # get the BLE device (via its address) and construct a curtain device
    ble_device = advertisement_data[ble_address].device
    curtain_device = curtain.SwitchbotCurtain(ble_device, reverse_mode=False)

    pprint(await curtain_device.get_device_data())
    pprint(await curtain_device.get_basic_info())
    await curtain_device.set_position(100)


if __name__ == "__main__":
    asyncio.run(main())

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pyswitchbot-2.6.0.tar.gz (66.4 kB view details)

Uploaded Aug 24, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

pyswitchbot-2.6.0-py3-none-any.whl (97.2 kB view details)

Uploaded Aug 24, 2026 Python 3

File details

Details for the file pyswitchbot-2.6.0.tar.gz.

File metadata

Download URL: pyswitchbot-2.6.0.tar.gz
Upload date: Aug 24, 2026
Size: 66.4 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pyswitchbot-2.6.0.tar.gz
Algorithm	Hash digest
SHA256	`a470517eb6e10b952c7e80d2336b15b330af6985d0dbc4f857ae17b03dcc1cd8`
MD5	`bd61ac9e85fd4fd93fec7d7527a4077e`
BLAKE2b-256	`c6c7421840dd68ffda3c2524cb5f3fd74ce57dc3867ce8432d4b52539438c615`

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyswitchbot-2.6.0.tar.gz:

Publisher: ci.yml on sblibs/pySwitchbot

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: pyswitchbot-2.6.0.tar.gz
- Subject digest: a470517eb6e10b952c7e80d2336b15b330af6985d0dbc4f857ae17b03dcc1cd8
- Sigstore transparency entry: 2581738691
- Sigstore integration time: Aug 24, 2026
Source repository:
- Permalink: sblibs/pySwitchbot@5c2e6c881191b6a469bc4e2b74e0d338778e8576
- Branch / Tag: refs/heads/main
- Owner: https://github.com/sblibs
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: ci.yml@5c2e6c881191b6a469bc4e2b74e0d338778e8576
- Trigger Event: push