# SwitchBot MQTT client
[](https://github.com/psf/black)
[](https://github.com/fphammerle/switchbot-mqtt/actions)
[](https://coveralls.io/github/fphammerle/switchbot-mqtt?branch=master)
[](https://pypi.org/project/switchbot-mqtt/#history)
[](https://pypi.org/project/switchbot-mqtt/)
MQTT client controlling [SwitchBot button automators](https://www.switch-bot.com/bot)
and [curtain motors](https://www.switch-bot.com/products/switchbot-curtain)
Compatible with [Home Assistant](https://www.home-assistant.io/)'s
[MQTT Switch](https://www.home-assistant.io/integrations/switch.mqtt/)
and [MQTT Cover](https://www.home-assistant.io/integrations/cover.mqtt/) platform.
## Setup
```sh
$ pip3 install --user --upgrade switchbot-mqtt
```
## Usage
```sh
$ switchbot-mqtt --mqtt-host HOSTNAME_OR_IP_ADDRESS --mqtt-enable-tls
# 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](https://play.google.com/store/apps/details?id=com.theswitchbot.switchbot)
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`.
```sh
$ 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`:
```sh
$ 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`:
```sh
$ 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:
```json
{
"11:22:33:44:55:66": "password",
"aa:bb:cc:dd:ee:ff": "secret",
"00:00:00:0f:f1:ce": "random string"
}
```
```sh
$ switchbot-mqtt --device-password-file /some/where/switchbot-passwords.json …
```
### MQTT Authentication
```sh
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`:
```sh
# 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 🏡
### Rationale
Why not use the official [SwitchBot integration](https://www.home-assistant.io/integrations/switchbot/)?
I prefer not to share the host's **network stack** with home assistant
(more complicated network setup
and additional [netfilter](https://en.wikipedia.org/wiki/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](https://hub.docker.com/r/homeassistant/home-assistant)
runs as `root`.
This imposes an unnecessary security risk, especially when disabling user namespace remapping
(`--userns host`).
See https://github.com/fphammerle/docker-home-assistant for an alternative.
### Setup
```yaml
# https://www.home-assistant.io/docs/mqtt/broker/#configuration-variables
mqtt:
broker: BROKER_HOSTNAME_OR_IP_ADDRESS
# credentials, additional options…
# https://www.home-assistant.io/integrations/switch.mqtt/#configuration-variables
switch:
- 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
# http://materialdesignicons.com/
icon: mdi:light-switch
cover:
- 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 https://hub.docker.com/r/fphammerle/switchbot-mqtt/tags
Annotation of signed tags `docker/*` contains docker image digests: https://github.com/fphammerle/switchbot-mqtt/tags
```sh
$ 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`:
```yaml
version: '3.8'
services:
switchbot-mqtt:
image: switchbot-mqtt
container_name: switchbot-mqtt
network_mode: host
userns_mode: host
environment:
- MQTT_HOST=localhost
- MQTT_PORT=1883
#- MQTT_USERNAME=username
#- MQTT_PASSWORD=password
#- FETCH_DEVICE_INFO=yes
restart: unless-stopped
```
## Alternatives
* https://github.com/binsentsu/switchbot-ctrl
* https://github.com/OpenWonderLabs/python-host/blob/master/switchbot_py3.py
* https://gist.github.com/aerialist/163a5794e95ccd28dc023161324009ed
* https://gist.github.com/mugifly/a29f34df7de8960d72245fcb124513c7
Raw data
{
"_id": null,
"home_page": "https://github.com/fphammerle/switchbot-mqtt",
"name": "switchbot-mqtt",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "IoT,automation,bluetooth,button,click,cover,curtain,home-assistant.io,home-automation,mqtt,press,push,switchbot",
"author": "Fabian Peter Hammerle",
"author_email": "fabian@hammerle.me",
"download_url": "https://files.pythonhosted.org/packages/8e/50/5a0a3f4978929583cb4e06679e56eb80989a7ee87356bce50b2a7be69471/switchbot-mqtt-3.3.1.tar.gz",
"platform": null,
"description": "# SwitchBot MQTT client\n\n[](https://github.com/psf/black)\n[](https://github.com/fphammerle/switchbot-mqtt/actions)\n[](https://coveralls.io/github/fphammerle/switchbot-mqtt?branch=master)\n[](https://pypi.org/project/switchbot-mqtt/#history)\n[](https://pypi.org/project/switchbot-mqtt/)\n\nMQTT client controlling [SwitchBot button automators](https://www.switch-bot.com/bot)\nand [curtain motors](https://www.switch-bot.com/products/switchbot-curtain)\n\nCompatible with [Home Assistant](https://www.home-assistant.io/)'s\n[MQTT Switch](https://www.home-assistant.io/integrations/switch.mqtt/)\nand [MQTT Cover](https://www.home-assistant.io/integrations/cover.mqtt/) platform.\n\n## Setup\n\n```sh\n$ pip3 install --user --upgrade switchbot-mqtt\n```\n\n## Usage\n\n```sh\n$ switchbot-mqtt --mqtt-host HOSTNAME_OR_IP_ADDRESS --mqtt-enable-tls\n# or\n$ switchbot-mqtt --mqtt-host HOSTNAME_OR_IP_ADDRESS --mqtt-disable-tls\n```\n\nUse `sudo hcitool lescan`\nor select device settings > 3 dots on top right in\n[SwitchBot app](https://play.google.com/store/apps/details?id=com.theswitchbot.switchbot)\nto determine your SwitchBot's **mac address**.\n\n### Button Automator\n\nSend `ON` or `OFF` to topic `homeassistant/switch/switchbot/aa:bb:cc:dd:ee:ff/set`.\n\n```sh\n$ mosquitto_pub -h MQTT_BROKER -t homeassistant/switch/switchbot/aa:bb:cc:dd:ee:ff/set -m ON\n```\n\nThe command-line option `--fetch-device-info` enables battery level reports on topic\n`homeassistant/switch/switchbot/MAC_ADDRESS/battery-percentage` after every command.\nThe report may be requested manually by sending a MQTT message to the topic\n`homeassistant/switch/switchbot/MAC_ADDRESS/request-device-info` (requires `--fetch-device-info`)\n\n### Curtain Motor\n\nSend `OPEN`, `CLOSE`, or `STOP` to topic `homeassistant/cover/switchbot-curtain/aa:bb:cc:dd:ee:ff/set`:\n\n```sh\n$ mosquitto_pub -h MQTT_BROKER -t homeassistant/cover/switchbot-curtain/aa:bb:cc:dd:ee:ff/set -m CLOSE\n```\n\nOr a position in percent (0 fully closed, 100 fully opened) to topic\n`homeassistant/cover/switchbot-curtain/aa:bb:cc:dd:ee:ff/position/set-percent`:\n\n```sh\n$ mosquitto_pub -h MQTT_BROKER -t homeassistant/cover/switchbot-curtain/aa:bb:cc:dd:ee:ff/position/set-percent -m 42\n```\n\nThe command-line option `--fetch-device-info` enables position reports on topic\n`homeassistant/cover/switchbot-curtain/MAC_ADDRESS/position` after `STOP` commands\nand battery level reports on topic `homeassistant/cover/switchbot-curtain/MAC_ADDRESS/battery-percentage`\nafter every command.\nThese reports may be requested manually by sending a MQTT message to the topic\n`homeassistant/cover/switchbot-curtain/MAC_ADDRESS/request-device-info` (requires `--fetch-device-info`)\n\n### Device Passwords\n\nIn case some of your Switchbot devices are password-protected,\ncreate a JSON file mapping MAC addresses to passwords\nand provide its path via the `--device-password-file` option:\n```json\n{\n \"11:22:33:44:55:66\": \"password\",\n \"aa:bb:cc:dd:ee:ff\": \"secret\",\n \"00:00:00:0f:f1:ce\": \"random string\"\n}\n```\n```sh\n$ switchbot-mqtt --device-password-file /some/where/switchbot-passwords.json \u2026\n```\n\n### MQTT Authentication\n\n```sh\nswitchbot-mqtt --mqtt-username me --mqtt-password secret \u2026\n# or\nswitchbot-mqtt --mqtt-username me --mqtt-password-file /var/lib/secrets/mqtt/password \u2026\n```\n\n\u26a0\ufe0f `--mqtt-password` leaks the password to other users on the same machine,\nif `/proc` is mounted with `hidepid=0` (default).\n\n### MQTT Topic\n\nBy default, `switchbot-mqtt` prepends `homeassistant/` to all MQTT topics.\nThis common prefix can be changed via `--mqtt-topic-prefix`:\n```sh\n# listens on living-room/switch/switchbot/aa:bb:cc:dd:ee:ff/set\nswitchbot-mqtt --mqtt-topic-prefix living-room/ \u2026\n# listens on switch/switchbot/aa:bb:cc:dd:ee:ff/set\nswitchbot-mqtt --mqtt-topic-prefix '' \u2026\n```\n\n### Service Status Report\n\nAfter connecting to the MQTT broker, `switchbot-mqtt` will report `online` on topic `homeassistant/switchbot-mqtt/status`.\nWhen disconnecting (graceful shutdown or unexpected loss of connection), `offline` will be reported on the same topic.\n\n## Home Assistant \ud83c\udfe1\n\n### Rationale\n\nWhy not use the official [SwitchBot integration](https://www.home-assistant.io/integrations/switchbot/)?\n\nI prefer not to share the host's **network stack** with home assistant\n(more complicated network setup\nand additional [netfilter](https://en.wikipedia.org/wiki/Netfilter) rules required for isolation).\n\nSadly, `docker run --network host` even requires `--userns host`:\n> docker: Error response from daemon: cannot share the host's network namespace when user namespaces are enabled.\n\nThe docker image built from this repository works around this limitation\nby explicitly running as an **unprivileged user**.\n\nThe [official home assistant image](https://hub.docker.com/r/homeassistant/home-assistant)\nruns as `root`.\nThis imposes an unnecessary security risk, especially when disabling user namespace remapping\n(`--userns host`).\nSee https://github.com/fphammerle/docker-home-assistant for an alternative.\n\n### Setup\n\n```yaml\n# https://www.home-assistant.io/docs/mqtt/broker/#configuration-variables\nmqtt:\n broker: BROKER_HOSTNAME_OR_IP_ADDRESS\n # credentials, additional options\u2026\n\n# https://www.home-assistant.io/integrations/switch.mqtt/#configuration-variables\nswitch:\n- platform: mqtt\n name: switchbot_button\n command_topic: homeassistant/switch/switchbot/aa:bb:cc:dd:ee:ff/set\n state_topic: homeassistant/switch/switchbot/aa:bb:cc:dd:ee:ff/state\n # http://materialdesignicons.com/\n icon: mdi:light-switch\n\ncover:\n- platform: mqtt\n name: switchbot_curtains\n command_topic: homeassistant/cover/switchbot-curtain/11:22:33:44:55:66/set\n set_position_topic: homeassistant/cover/switchbot-curtain/aa:bb:cc:dd:ee:ff/position/set-percent\n state_topic: homeassistant/cover/switchbot-curtain/11:22:33:44:55:66/state\n```\n\n## Docker \ud83d\udc33\n\nPre-built docker images are available at https://hub.docker.com/r/fphammerle/switchbot-mqtt/tags\n\nAnnotation of signed tags `docker/*` contains docker image digests: https://github.com/fphammerle/switchbot-mqtt/tags\n\n```sh\n$ docker build -t switchbot-mqtt .\n$ docker run --name spelunca_switchbot \\\n --userns host --network host \\\n switchbot-mqtt:latest \\\n switchbot-mqtt --mqtt-host HOSTNAME_OR_IP_ADDRESS\n```\n\nAlternatively, you can use `docker-compose`:\n```yaml\nversion: '3.8'\n\nservices:\n switchbot-mqtt:\n image: switchbot-mqtt\n container_name: switchbot-mqtt\n network_mode: host\n userns_mode: host\n environment:\n - MQTT_HOST=localhost\n - MQTT_PORT=1883\n #- MQTT_USERNAME=username\n #- MQTT_PASSWORD=password\n #- FETCH_DEVICE_INFO=yes\n restart: unless-stopped\n```\n\n## Alternatives\n\n* https://github.com/binsentsu/switchbot-ctrl\n* https://github.com/OpenWonderLabs/python-host/blob/master/switchbot_py3.py\n* https://gist.github.com/aerialist/163a5794e95ccd28dc023161324009ed\n* https://gist.github.com/mugifly/a29f34df7de8960d72245fcb124513c7\n\n\n",
"bugtrack_url": null,
"license": "GPLv3+",
"summary": "MQTT client controlling SwitchBot button & curtain automators, compatible with home-assistant.io's MQTT Switch & Cover platform",
"version": "3.3.1",
"project_urls": {
"Changelog": "https://github.com/fphammerle/switchbot-mqtt/blob/master/CHANGELOG.md",
"Homepage": "https://github.com/fphammerle/switchbot-mqtt"
},
"split_keywords": [
"iot",
"automation",
"bluetooth",
"button",
"click",
"cover",
"curtain",
"home-assistant.io",
"home-automation",
"mqtt",
"press",
"push",
"switchbot"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "45458c3dccb32684b211dc6d61de418f602e8359dac7f16d59f508bc1db77673",
"md5": "3f39bd9bf9939f496bcaacb98573c707",
"sha256": "0bc46a6c56337e723d14e90258a6720617aa25eebc12ead93c8db2fce4d6ffea"
},
"downloads": -1,
"filename": "switchbot_mqtt-3.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3f39bd9bf9939f496bcaacb98573c707",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 28953,
"upload_time": "2022-08-31T14:47:56",
"upload_time_iso_8601": "2022-08-31T14:47:56.199443Z",
"url": "https://files.pythonhosted.org/packages/45/45/8c3dccb32684b211dc6d61de418f602e8359dac7f16d59f508bc1db77673/switchbot_mqtt-3.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8e505a0a3f4978929583cb4e06679e56eb80989a7ee87356bce50b2a7be69471",
"md5": "c5e12003be36fa795b6b96e09288f477",
"sha256": "e00f4b40afd980ac5ca84b7ea9868116d9c6f6c4f9f353be77a8082990ee3a70"
},
"downloads": -1,
"filename": "switchbot-mqtt-3.3.1.tar.gz",
"has_sig": false,
"md5_digest": "c5e12003be36fa795b6b96e09288f477",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 60481,
"upload_time": "2022-08-31T14:47:59",
"upload_time_iso_8601": "2022-08-31T14:47:59.663282Z",
"url": "https://files.pythonhosted.org/packages/8e/50/5a0a3f4978929583cb4e06679e56eb80989a7ee87356bce50b2a7be69471/switchbot-mqtt-3.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-08-31 14:47:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fphammerle",
"github_project": "switchbot-mqtt",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "switchbot-mqtt"
}
JSON
