No Description

dependabot[bot] 2d93c5140b build(deps): bump aiohttp from 3.9.1 to 3.9.5 (#227) 1 day ago
.github 8d95a74397 build(deps): bump docker/setup-buildx-action from 3.2.0 to 3.3.0 (#226) 1 week ago
switchbot_mqtt d7cc345117 upgrade mypy from 1.6.1 to 1.8.0 2 months ago
tests 8329e53782 require `PySwitchbot>=0.14.0,<0.41` instead of `PySwitchbot>=0.10.0,<0.13` & replace bluepy with bleak 5 months ago
.dockerignore 046e59cda6 docker: no longer require build arg SWITCHBOT_MQTT_VERSION 4 years ago
.gitignore 3b5ea00bf0 pipeline / pipenv: explicitly specify python version to workaround pipenv picking highest available 3 years ago
.pylintrc b7197cbc67 pylint: enable various optional checks/extensions 1 year ago e5633b5044 readme: adapt section about network stack/namespace & home assistant; fix instructions for docker; changelog: document now required access to D-Bus system socket 5 months ago
COPYING cb2596d32e standard python project tech stack (pipenv, pytest, pylint etc.); mqtt connect; GPLv3+ 4 years ago
Dockerfile 137130b030 container image: fix build on arm 5 months ago
Makefile 870cac5cfc refactor makefile: rename variables (including removal of "DOCKER_" prefixes) 3 years ago
Pipfile 1bf4899bba runtime env: remove unexpected marker breaking pipeline on python>3.10 5 months ago
Pipfile.lock 2d93c5140b build(deps): bump aiohttp from 3.9.1 to 3.9.5 (#227) 1 day ago e5633b5044 readme: adapt section about network stack/namespace & home assistant; fix instructions for docker; changelog: document now required access to D-Bus system socket 5 months ago
mypy.ini c6bc41e1c3 add additional (internal) type hints to enable mypy's strict mode 2 years ago 3558fc372c drop compatibility with python3.8 (untested cause pySwitchbot v0.17.2 added constraint bleak-retry-connector>=1.1.1 requiring python>=3.9); revert env 5 months ago

SwitchBot MQTT client

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
# or
$ switchbot-mqtt --mqtt-host HOSTNAME_OR_IP_ADDRESS --mqtt-disable-tls

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

Or a position in percent (0 fully closed, 100 fully opened) to topic homeassistant/cover/switchbot-curtain/aa:bb:cc:dd:ee:ff/position/set-percent:

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

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).

MQTT Topic

By default, switchbot-mqtt prepends homeassistant/ to all MQTT topics. This common prefix can be changed via --mqtt-topic-prefix:

# listens on living-room/switch/switchbot/aa:bb:cc:dd:ee:ff/set
switchbot-mqtt --mqtt-topic-prefix living-room/ …
# listens on switch/switchbot/aa:bb:cc:dd:ee:ff/set
switchbot-mqtt --mqtt-topic-prefix '' …

Service Status Report

After connecting to the MQTT broker, switchbot-mqtt will report online on topic homeassistant/switchbot-mqtt/status. When disconnecting (graceful shutdown or unexpected loss of connection), offline will be reported on the same topic.

Home Assistant 🏡


Why not use the official SwitchBot integration?

Older versions of pySwitchbot (before bleak replaced bluepy) required access to the host's network stack. I prefer not to share the host's network stack with home assistant's container (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 official home assistant image runs as root. This imposes an unnecessary security risk, especially when disabling user namespace remapping (--userns host).


  # 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
  set_position_topic: homeassistant/cover/switchbot-curtain/aa:bb:cc:dd:ee:ff/position/set-percent
  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 \
    -v /var/run/dbus/system_bus_socket:/var/run/dbus/system_bus_socket \
    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
    userns_mode: host
    - MQTT_HOST=localhost
    - MQTT_PORT=1883
    #- MQTT_USERNAME=username
    #- MQTT_PASSWORD=password
    - /var/run/dbus/system_bus_socket:/var/run/dbus/system_bus_socket
    restart: unless-stopped