2025.4.4
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:

  1. Open the SwitchBot app.
  2. Open device settings.
  3. Click on “Device Info”.
  4. 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

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)

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 and LED Strip Light.

Color Bulb

Features:

  • turn on or off
  • change brightness
  • change color temperature
  • change color

LED Strip Light

Features:

  • turn on or off
  • change brightness
  • change color

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

Lock Pro

This is an encrypted device.

Features:

  • Lock or unlock
  • open or closed state
  • auto-lock paused state
  • 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

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.

Lock state

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

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

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