{"id":17222352,"url":"https://github.com/fphammerle/switchbot-mqtt","last_synced_at":"2025-04-06T02:07:50.702Z","repository":{"id":37083012,"uuid":"262254966","full_name":"fphammerle/switchbot-mqtt","owner":"fphammerle","description":"MQTT client controlling SwitchBot button automators \u0026 curtain motors, compatible with Home Assistant :house_with_garden: 🐳","archived":false,"fork":false,"pushed_at":"2025-03-28T16:19:04.000Z","size":1085,"stargazers_count":51,"open_issues_count":5,"forks_count":9,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-03T03:12:26.134Z","etag":null,"topics":["docker","home-assistant","home-automation","mqtt-client","python","switchbot"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/switchbot-mqtt/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fphammerle.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-05-08T07:22:18.000Z","updated_at":"2025-03-28T16:19:07.000Z","dependencies_parsed_at":"2022-08-01T08:09:44.612Z","dependency_job_id":"584889b8-b7f0-4fba-8196-4dd7c253e810","html_url":"https://github.com/fphammerle/switchbot-mqtt","commit_stats":{"total_commits":256,"total_committers":6,"mean_commits":"42.666666666666664","dds":0.421875,"last_synced_commit":"80af6c9875203e9a8717d0b03517daac750b7eb9"},"previous_names":[],"tags_count":85,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fphammerle%2Fswitchbot-mqtt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fphammerle%2Fswitchbot-mqtt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fphammerle%2Fswitchbot-mqtt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fphammerle%2Fswitchbot-mqtt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fphammerle","download_url":"https://codeload.github.com/fphammerle/switchbot-mqtt/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247423513,"owners_count":20936626,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","home-assistant","home-automation","mqtt-client","python","switchbot"],"created_at":"2024-10-15T04:04:57.146Z","updated_at":"2025-04-06T02:07:50.676Z","avatar_url":"https://github.com/fphammerle.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SwitchBot MQTT client\n\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n[![CI Pipeline Status](https://github.com/fphammerle/switchbot-mqtt/workflows/tests/badge.svg)](https://github.com/fphammerle/switchbot-mqtt/actions)\n![Coverage Status](https://ipfs.io/ipfs/QmP8k5H4MkfspFxQxdL2kEZ4QQWQjF8xwPYD35KvNH4CA6/20230429T090002+0200/s3.amazonaws.com/assets.coveralls.io/badges/coveralls_100.svg)\n[![Last Release](https://img.shields.io/pypi/v/switchbot-mqtt.svg)](https://pypi.org/project/switchbot-mqtt/#history)\n[![Compatible Python Versions](https://img.shields.io/pypi/pyversions/switchbot-mqtt.svg)](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\n# or\n$ switchbot-mqtt --mqtt-host HOSTNAME_OR_IP_ADDRESS --mqtt-disable-tls\n```\n\nUse `sudo hcitool lescan`\nor select device settings \u003e 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 …\n```\n\n### MQTT Authentication\n\n```sh\nswitchbot-mqtt --mqtt-username me --mqtt-password secret …\n# or\nswitchbot-mqtt --mqtt-username me --mqtt-password-file /var/lib/secrets/mqtt/password …\n```\n\n⚠️  `--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/ …\n# listens on switch/switchbot/aa:bb:cc:dd:ee:ff/set\nswitchbot-mqtt --mqtt-topic-prefix '' …\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 🏡\n\n### Rationale\n\nWhy not use the official [SwitchBot integration](https://www.home-assistant.io/integrations/switchbot/)?\n\nOlder versions of pySwitchbot (before bleak replaced bluepy) required access to the host's **network stack**.\nI prefer not to share the host's network stack with home assistant's container\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\u003e docker: Error response from daemon: cannot share the host's network namespace when user namespaces are enabled.\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`).\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…\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 🐳\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 \\\n    -v /var/run/dbus/system_bus_socket:/var/run/dbus/system_bus_socket \\\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    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    volumes:\n    - /var/run/dbus/system_bus_socket:/var/run/dbus/system_bus_socket\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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffphammerle%2Fswitchbot-mqtt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffphammerle%2Fswitchbot-mqtt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffphammerle%2Fswitchbot-mqtt/lists"}