Skip to main content

MQTT client controlling SwitchBot button & curtain automators, compatible with's MQTT Switch & Cover platform

Project description

SwitchBot MQTT client

Code style: black CI Pipeline Status Coverage Status Last Release Compatible Python Versions

MQTT client controlling SwitchBot button automators and curtain motors

Compatible with Home Assistant's MQTT Switch and MQTT Cover platform.


$ pip3 install --user --upgrade switchbot-mqtt


$ switchbot-mqtt --mqtt-host HOSTNAME_OR_IP_ADDRESS

Use sudo hcitool lescan or select device settings > 3 dots on top right in SwitchBot app to determine your SwitchBot's mac address.

Button Automator

Send ON or OFF to topic homeassistant/switch/switchbot/aa:bb:cc:dd:ee:ff/set.

$ mosquitto_pub -h MQTT_BROKER -t homeassistant/switch/switchbot/aa:bb:cc:dd:ee:ff/set -m ON

The command-line option --fetch-device-info enables battery level reports on topic homeassistant/switch/switchbot/MAC_ADDRESS/battery-percentage after every command. The report may be requested manually by sending a MQTT message to the topic homeassistant/switch/switchbot/MAC_ADDRESS/request-device-info (requires --fetch-device-info)

Curtain Motor

Send OPEN, CLOSE, or STOP to topic homeassistant/cover/switchbot-curtain/aa:bb:cc:dd:ee:ff/set.

$ mosquitto_pub -h MQTT_BROKER -t homeassistant/cover/switchbot-curtain/aa:bb:cc:dd:ee:ff/set -m CLOSE

The command-line option --fetch-device-info enables position reports on topic homeassistant/cover/switchbot-curtain/MAC_ADDRESS/position after STOP commands and battery level reports on topic homeassistant/cover/switchbot-curtain/MAC_ADDRESS/battery-percentage after every command. These reports may be requested manually by sending a MQTT message to the topic homeassistant/cover/switchbot-curtain/MAC_ADDRESS/request-device-info (requires --fetch-device-info)

Device Passwords

In case some of your Switchbot devices are password-protected, create a JSON file mapping MAC addresses to passwords and provide its path via the --device-password-file option:

  "11:22:33:44:55:66": "password",
  "aa:bb:cc:dd:ee:ff": "secret",
  "00:00:00:0f:f1:ce": "random string"
$ switchbot-mqtt --device-password-file /some/where/switchbot-passwords.json …

MQTT Authentication

switchbot-mqtt --mqtt-username me --mqtt-password secret …
# or
switchbot-mqtt --mqtt-username me --mqtt-password-file /var/lib/secrets/mqtt/password …

⚠️ --mqtt-password leaks the password to other users on the same machine, if /proc is mounted with hidepid=0 (default).

Home Assistant 🏡


Why not use the official SwitchBot integration?

I prefer not to share the host's network stack with home assistant (more complicated network setup and additional netfilter rules required for isolation).

Sadly, docker run --network host even requires --userns host:

docker: Error response from daemon: cannot share the host's network namespace when user namespaces are enabled.

The docker image built from this repository works around this limitation by explicitly running as an unprivileged user.

The official home assistant image runs as root. This imposes an unnecessary security risk, especially when disabling user namespace remapping (--userns host). See for an alternative.


  # credentials, additional options…

- platform: mqtt
  name: switchbot_button
  command_topic: homeassistant/switch/switchbot/aa:bb:cc:dd:ee:ff/set
  state_topic: homeassistant/switch/switchbot/aa:bb:cc:dd:ee:ff/state
  icon: mdi:light-switch

- platform: mqtt
  name: switchbot_curtains
  command_topic: homeassistant/cover/switchbot-curtain/11:22:33:44:55:66/set
  state_topic: homeassistant/cover/switchbot-curtain/11:22:33:44:55:66/state

Docker 🐳

Pre-built docker images are available at

Annotation of signed tags docker/* contains docker image digests:

$ docker build -t switchbot-mqtt .
$ docker run --name spelunca_switchbot \
    --userns host --network host \
    switchbot-mqtt:latest \
    switchbot-mqtt --mqtt-host HOSTNAME_OR_IP_ADDRESS

Alternatively, you can use docker-compose:

version: '3.8'

    image: switchbot-mqtt
    container_name: switchbot-mqtt
    network_mode: host
    userns_mode: host
    - MQTT_HOST=localhost
    - MQTT_PORT=1883
    #- MQTT_USERNAME=username
    #- MQTT_PASSWORD=password
    restart: unless-stopped


Project details

Download files

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

Files for switchbot-mqtt, version 2.2.0
Filename, size File type Python version Upload date Hashes
Filename, size switchbot_mqtt-2.2.0-py3-none-any.whl (26.9 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size switchbot-mqtt-2.2.0.tar.gz (51.8 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page