No Description

Fabian Peter Hammerle 0e492e446b `BTLEManagementError`: added workaround instructions for docker-based setups 2 years ago
.github 80f88cb0eb build(deps): bump docker/build-push-action from 2.5.0 to 2.7.0 2 years ago
switchbot_mqtt 81ab4563c4 `BTLEManagementError`: added workaround instructions for docker-based setups 2 years ago
tests 22d3f7bc2c fix capturing of `BTLEManagementError` on pySwitchbot v0.10.1 2 years ago
.dockerignore 046e59cda6 docker: no longer require build arg SWITCHBOT_MQTT_VERSION 3 years ago
.gitignore 3b5ea00bf0 pipeline / pipenv: explicitly specify python version to workaround pipenv picking highest available 3 years ago
.pylintrc 5dc3fc3b75 added command-line param `--device-password-file` 2 years ago
CHANGELOG.md 90d274d00c added option `--fetch-device-info` to toggle reporting of curtain motor's position (can't enable by default due to `bluepy.btle.BTLEManagementError: Failed to execute management command 'le on'`) 2 years ago
COPYING cb2596d32e standard python project tech stack (pipenv, pytest, pylint etc.); mqtt connect; GPLv3+ 3 years ago
Dockerfile d7b875458d setup github action verifying docker build succeeds (to replace docker's autobuild service) 2 years ago
Makefile 870cac5cfc refactor makefile: rename variables (including removal of "DOCKER_" prefixes) 3 years ago
Pipfile cfa4f82e75 env: add upper version constraint for `click` to keep compatibility with python3.5 2 years ago
Pipfile.lock 22d3f7bc2c fix capturing of `BTLEManagementError` on pySwitchbot v0.10.1 2 years ago
README.md 90d274d00c added option `--fetch-device-info` to toggle reporting of curtain motor's position (can't enable by default due to `bluepy.btle.BTLEManagementError: Failed to execute management command 'le on'`) 2 years ago
mypy.ini cb2596d32e standard python project tech stack (pipenv, pytest, pylint etc.); mqtt connect; GPLv3+ 3 years ago
setup.py fadf3877c9 provide further information & workaround in exception msg when `le on` triggers `BTLEManagementError` 2 years ago

README.md

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.

Setup

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

Usage

$ 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

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.

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 🏡

Rationale

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 https://github.com/fphammerle/docker-home-assistant for an alternative.

Setup

# 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
  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

$ 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'

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
    restart: unless-stopped

Alternatives