Home ▸ Integrations ▸

SwitchBot Bluetooth

The SwitchBot integration allows you to control SwitchBot devices such as sensors, locks, shades, lights, plugs, robot vacuums, hubs and etc.

How you can use this integration

The SwitchBot integration lets you do many things, such as switching devices on and off, changing device modes, monitoring sensor data and energy usage in the Home Assistant dashboards, and controlling device configurations manually or via automations.

Prerequisites

In order to use this integration, it is required to have working Bluetooth set up on the device running Home Assistant. A SwitchBot Hub is not required for this integration.

If you have multiple devices of the same type, you need to get the BTLE MAC address of your device to tell your devices apart. You can find the address for your device using the following steps:

Open the SwitchBot app.
Open device settings.
Click on “Device Info”.
Write down the BTLE MAC address of your device.

Please note, device names configured in the SwitchBot app are not transferred into Home Assistant.

Some SwitchBot devices need to be configured within the app before being controlled by Home Assistant, such as calibrating the cover open/close limits or pairing two covers to move together.

Adding encrypted SwitchBot devices

Some types of the SwitchBot devices are encrypted for improved security. More types and models will be added as encrypted devices in the future.

An encrypted SwitchBot device can be set up in Home Assistant in two different ways. You can enter the key ID and encryption key yourself, or Home Assistant can import them from your SwitchBot account.

SwitchBot account (recommended)

Using this option you can provide your SwitchBot account login credentials and Home Assistant will import the appropriate encryption key from your account.

Username

SwitchBot account username

Password

SwitchBot account password

Important

This integration doesn’t support SSO accounts (Login with Google, etc.) only username and password accounts.

Enter the lock encryption key manually

This option is for those that would rather obtain the encryption key themselves, and/or want to know exactly where and how are their account credentials used.

Key ID

Locks’ encryption key ID

Encryption key

Locks’ encryption key

For instructions on how to obtain the encryption key, see README in PySwitchbot project.

Configuration

To add the SwitchBot Bluetooth integration to your Home Assistant instance, use this My button:

Manual configuration steps

If the above My button doesn’t work, you can also perform the following steps manually:

Browse to your Home Assistant instance.
Go to Settings > Devices & Services.
In the bottom right corner, select the Add Integration button.
From the list, select SwitchBot Bluetooth.
Follow the instructions on screen to complete the setup.

Supported devices

Plugs and switches

Cover

Lights

Locks

Humidifiers

Sensors

Meter
Meter Plus (WoSensorTH)
Indoor/Outdoor Meter (WoIOSensorTH)
Meter Pro
Meter Pro CO2 Monitor
Contact Sensor (WoContact)
Motion Sensor (WoPresence)
Water Leak Detector
Remote (WoRemote) (currently only supports battery level monitoring)

Hubs

Hub 2 (WoHub2) (currently only supports retrieving sensor data, does not yet support device control)
Hub Mini Matter Enabled(currently only supports retrieving sensor data, does not yet support device control)
Hub 3 (WoHub3)(currently only supports retrieving sensor data, does not yet support device control)

Fans

Circulator Fan

Vacuums

Air purifiers

Works with Home Assistant

SwitchBot is committed to making sure their products are up-to-date and ready to use in Home Assistant. Devices are certified for both Bluetooth and Matter.

The following devices are certified for Bluetooth:

To see the list of SwitchBot Matter certified devices, visit the SwitchBot Matter page.

Supported functionality

Common

Options

Retry count: How many times to retry sending commands to your SwitchBot devices.

Attributes

last_run_success: Returns true if the last action sent to the SwitchBot succeeded. This attribute is useful for error trapping when Bluetooth connectivity is intermittent. If false, see home-assistant.log for specific error messages.

Plugs and switches

Switch entities are added for Bot, Plug Mini, and Relay Switch.

Bot

Password protection: You can set a device password in the SwitchBot app to prevent people nearby take control of your device. When a password is set, you need to enter the correct password in order to add it to the integrations.

Features:

turn on or off
press
get battery level

Attributes:

Switch mode: Specifies the mode of the device. If true, the device is in Pull/Retract mode for toggle switches otherwise the device is in momentary switch mode.

Plug Mini

Features:

turn on or off
get power consumption readings

Relay Switch 1

This is an encrypted device.

Features:

turn on or off

Relay Switch 1PM

This is an encrypted device.

Features:

turn on or off
get power
get voltage
get current

Cover

Cover entities are added for Curtain, Curtain 3, Blind Tilt, and Roller Shade.

Curtain

Features:

open/close/pause
set position
get position
get light level
get battery level
get calibration state

Curtain 3

Features:

open/close/pause
set position
get position
get light level
get battery level
get calibration state

Blind Tilt

Features:

close up/close down/pause
set position
get position
get light level
get battery level
get calibration state

The blind tilt is exposed as a cover entity with control of the tilt position only:

Tilt Position	Blind State
100%	Closed Up
50%	Fully Open
0%	Closed Down

The close button will close the blinds to the closest closed position (either 0% or 100%), and defaults to closing down if the blinds are fully open. Because Home Assistant believes 100% is open, the default cards will disable the open button when the tilt is at 100%, but the action will still work and open the blind to 50%.

Simple cover template entity

Some integrations may expose your SwitchBot Blind Tilt to other actions which expect that 100% is open and 0% is fully closed. Using a Cover Template, a proxy entity can be created which will be open at 100% and closed at 0%. This template entity is limited to closing in one direction.

# Example configuration.yaml entry
cover:
  - platform: template
    covers:
      example_blinds_simple:
        device_class: blind
        friendly_name: Example Blinds (Simple Down)
        open_cover:
          action: cover.set_cover_tilt_position
          data:
            tilt_position: 50
          target:
            entity_id: cover.example_blinds
        close_cover:
          action: cover.set_cover_tilt_position
          data:
            tilt_position: 0
          target:
            entity_id: cover.example_blinds
        position_template: >
          {{ int(states.cover.example_blinds.attributes.current_tilt_position)*2 }}
        set_cover_position:
          action: cover.set_cover_tilt_position
          data:
            tilt_position: "{{position/2}}"
          target:
            entity_id: cover.example_blinds

Roller Shade

The Roller Shade is exposed as a cover entity with control of the position only:

position	Roller Shade state
<=20%	Open
>20%	Close

Features:

open/close/pause
set position
get position
get battery level

Sensors

Sensor entiteis are added for thermometer and hygrometer devices, motion sensor, contact sensor, leak sensor, and remote button.

Meter

Features:

get temperature
get humidity
get battery level

Meter Plus

Features:

get temperature
get humidity
get battery level

Indoor/Outdoor Meter

Features:

get temperature
get humidity
get battery level

Meter Pro

Features:

get temperature
get humidity
get battery level

Meter Pro CO2 Monitor

Features:

get temperature
get humidity
get carbon dioxide
get battery level

Contact Sensor

Features:

open or closed state
motion detection state
get battery level

Motion Sensor

Features:

motion detection state
get battery level

Water Leak Detector

This is an encrypted device.

Features:

leak or dry state
get battery level

Remote

Features:

get battery level

Lights

Light entities are added for Color Bulb, LED Strip Light, and Ceiling Light.

Ceiling Light

Features:

turn on or off
change brightness
change color temperature

Color Bulb

Features:

turn on or off
change brightness
change color temperature
change color
set effect

LED Strip Light

Features:

turn on or off
change brightness
change color
set effect

Strip Light 3

This is an encrypted device.

Features:

turn on or off
change brightness
change color temperature
change color
set effect

Floor Lamp

This is an encrypted device.

Features:

turn on or off
change brightness
change color temperature
change color
set effect

Locks

Note: The integration currently only uses the primary lock state; in dual lock mode, not all things might work properly.

Lock

This is an encrypted device.

Features:

Lock or unlock
open or closed state
auto-lock paused state
calibration state
get battery level

Options:

To enable nightlatch operation mode, go to Settings > Devices & services.
Under Integration entries, find the lock and select Configure.
In the Options dialog, configure the nightlatch operation mode.

Lock Pro

This is an encrypted device.

Features:

Lock or unlock
open or closed state
auto-lock paused state
calibration state
get battery level

Options:

To enable nightlatch operation mode, go to Settings > Devices & services.
Under Integration entries, find the lock and select Configure.
In the Options dialog, configure the nightlatch operation mode.

Lock Ultra

This is an encrypted device.

Features:

Lock or unlock
open or closed state
auto-lock paused state
calibration state
get battery level

Options:

To enable nightlatch operation mode, go to Settings > Devices & services.
Under Integration entries, find the lock and select Configure.
In the Options dialog, configure the nightlatch operation mode.

Lock Lite

This is an encrypted device.

Features:

Lock or unlock
calibration state
get battery level

Hubs

Some of the hubs can be served as a bridge while the sensor data can be retrieved via Bluetooth connection. Hub 2 displays temperature and humidity through a sensor cable. Without a digital display, Hub Mini Matter Enabled can also read from a sensor cable.

Hub 2

Features:

get temperature
get humidity
get light level

Hub Mini Matter Enabled

Features:

get temperature
get humidity

Hub3

Features:

get temperature
get humidity
get light level
motion detection state

Fans

Fan entities are added for Battery Circulator Fan/Circulator Fan, Air Purifier, and Air Purifier Table

Battery Circulator Fan/Circulator Fan

Features:

turn on
turn off
set speed
set mode
oscillate left and right
get battery level (Battery Circulator Fan only)

Air Purifier

This is an encrypted device.

Features:

turn on
turn off
set mode

Air Purifier Table

This is an encrypted device.

Features:

turn on
turn off
set mode

Vacuums

Vacuum entities are added for K10+, K10+ Pro, K10+ Pro Combo, K20, S10.

Features:

get states, including cleaning, docked, idle, paused, returning, and error; refer to Known limitations for more details
start
return to base
get battery

Humidifiers

Humidifier entities are added for Humidifier and Evaporative Humidifier.

Humidifier

Features:

turn on
turn off
set mode
set humidity

Evaporative Humidifier

This is an encrypted device. Note: Not all modes support unless you bind the temperature and humidity sensor.

Features:

turn on
turn off
set mode
set humidity

Data updates

SwitchBot devices utilize a local push strategy to maintain real-time status updates. When devices detect state changes, they actively push updates to Home Assistant for immediate synchronization. For user-initiated actions through Home Assistant (for example, when turning a device on/off), the integration performs an additional proactive status fetch to ensure instant confirmation of the new state. The integration connects locally to the devices without going via the SwitchBot Cloud.

Known limitations

Slow connection times

Move the device closer, or replace the Bluetooth adapter with a faster one. See Improving connection times for more information.

Device names not synced

Device names configured in the SwitchBot app are not transferred into Home Assistant.

Battery level

Due to firmware limitations, early models such as Lock and Lock Lite report the battery level in coarse ranges rather than an exact value:

< 10 % → 10
10 % – 20 % → 20
20 % – 60 % → 60
≥ 60 % → 100

Refer to the latest version of the OpenAPI doc for precise definitions.

Lock state

The integration currently only uses the primary lock state; in dual lock mode, not all things might work properly.

Vacuum state

For robot vacuum K10+ and K10+ Pro, due to firmware implementation, it only returns these states, cleaning and docked

Troubleshooting

The SwitchBot integration will automatically discover devices once the Bluetooth integration is enabled and functional.

Config flow could not be loaded

Possible custom integration conflict, using a different version of PySwitchbot; Try uninstalling the custom integration.

No unconfigured devices found

Make sure your devices are powered on and are in range.

Examples

Automation ideas

You can create all sort of automations using sensors as triggers and switches, shades, and lights as actions.

Turn on or turn off lights and switches when motion is detected.
Turn on or turn off the Bot to control a fan, AC remote, or circulator when temperature or humidity are too low.
Close the curtain when the temperature is too high.
Turn off Relay Switch when power consumption is too high.
Change the color of LED Strip Lights or Color Bulb or turn on the circulator using Bot or Relay Switch if carbon dioxide is too high.

Removing the integration

This integration follows standard integration removal. No extra steps are required.

To remove an integration instance from Home Assistant

Go to Settings > Devices & services and select the integration card.
From the list of devices, select the integration instance you want to remove.
Next to the entry, select the three dots menu. Then, select Delete.

Help us improve our documentation

Suggest an edit to this page, or provide/view feedback for this page.

Edit Provide feedback View pending feedback