Metadata-Version: 2.1
Name: switchbot-mqtt
Version: 2.1.0
Summary: MQTT client controlling SwitchBot button & curtain automators, compatible with home-assistant.io's MQTT Switch & Cover platform
Home-page: https://github.com/fphammerle/switchbot-mqtt
Author: Fabian Peter Hammerle
Author-email: fabian@hammerle.me
License: GPLv3+
Project-URL: Changelog, https://github.com/fphammerle/switchbot-mqtt/blob/master/CHANGELOG.md
Description: # SwitchBot MQTT client
        
        [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
        [![CI Pipeline Status](https://github.com/fphammerle/switchbot-mqtt/workflows/tests/badge.svg)](https://github.com/fphammerle/switchbot-mqtt/actions)
        [![Coverage Status](https://coveralls.io/repos/github/fphammerle/switchbot-mqtt/badge.svg?branch=master)](https://coveralls.io/github/fphammerle/switchbot-mqtt?branch=master)
        [![Last Release](https://img.shields.io/pypi/v/switchbot-mqtt.svg)](https://pypi.org/project/switchbot-mqtt/#history)
        [![Compatible Python Versions](https://img.shields.io/pypi/pyversions/switchbot-mqtt.svg)](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
        ```
        
        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.
        
        ### 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
        ```
        
        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.
        
        ### 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).
        
        ## 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
          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
        
Keywords: IoT,automation,bluetooth,button,click,cover,curtain,home-assistant.io,home-automation,mqtt,press,push,switchbot
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Home Automation
Requires-Python: >=3.6
Description-Content-Type: text/markdown
