Added webhook support + major improvements

domoticsduino · domoticsduino · commit 7b778eb86444 · 2025-08-05T11:53:34.000+02:00
diff --git a/.env.example b/.env.example
@@ -0,0 +1,15 @@
+MQTT_BROKER=192.168.1.50
+MQTT_PORT=1883
+MQTT_USERNAME=test
+MQTT_PASSWORD=xxxx
+MQTT_CLIENT_ID=switchbot_api2mqtt
+MQTT_SMARTLOCK_BASE_TOPIC=smarthome/smartlock/
+MQTT_GENERIC_BASE_TOPIC=switchbot/api/generic/
+SWITCHBOT_TOKEN=XXXXXXXXX
+SWITCHBOT_SECRET=YYYYYYYYYY
+API_BASEURL=https://api.switch-bot.com/v1.1/
+HTTP_PORT=5100
+SWITCHBOT_VALID_DEVICE_TYPES='["WoLockPro", "WoKeypadTouch", "WoHub2"]'
+SWITCHBOT_VALID_DEVICE_ID='["AAAAA", "BBBBB", "CCCCC"]'
+SWITCHBOT_SMARTLOCK_VALID_COMMAND='["lock", "unlock", "status"]'
+SWITCHBOT_POLLING_INTERVAL_SEC=3600
diff --git a/.env.template b/.env.template
@@ -3,10 +3,13 @@ MQTT_PORT=
 MQTT_USERNAME=
 MQTT_PASSWORD=
 MQTT_CLIENT_ID=
-MQTT_TOPIC_COMMAND=
-MQTT_TOPIC_STATUS=
-MQTT_TOPIC_RESPONSE=
+MQTT_SMARTLOCK_BASE_TOPIC=
+MQTT_GENERIC_BASE_TOPIC=
 SWITCHBOT_TOKEN=
 SWITCHBOT_SECRET=
-LOG_FILE=
-API_BASEURL=
+API_BASEURL=
+HTTP_PORT=
+SWITCHBOT_VALID_DEVICE_TYPES=
+SWITCHBOT_VALID_DEVICE_ID=
+SWITCHBOT_SMARTLOCK_VALID_COMMAND=
+SWITCHBOT_POLLING_INTERVAL_SEC=
diff --git a/Dockerfile b/Dockerfile
@@ -9,7 +9,9 @@ RUN pip install --no-cache-dir -r requirements.txt
 
 # Copy source code
 COPY switchbot_api2mqtt.py .
+COPY http_utils.py .
 COPY .env .
+COPY logging.json .
 
 # Default command
 CMD ["python", "switchbot_api2mqtt.py"]
diff --git a/README.md b/README.md
@@ -8,21 +8,86 @@ Designed for ease of deployment, this solution can be run natively or as a Docke
 
 By translating commands and status updates between SwitchBot's proprietary API and standard MQTT messages, this solution enables you to control and monitor your SwitchBot devices directly from your MQTT-enabled smart home platform. This eliminates the need for separate apps or complex workarounds, providing a unified and efficient control experience.
 
+Tested on Smart Lock Pro device
+
 ***Please, use version 0.1 if you would like to control your smart lock pro in a simple way***
 
+***Please, use version 0.2 if you would like to operate in a generic way***
+
 ## Usage
 
-- Copy *.env-template* in *.env* and populate config variables according to your setup
+- Copy *.env-template* in *.env* and populate config variables according to your setup (see .env.example for help)
+- Make the appropriate changes to the logging.json file for management of application log
 - Follow this guide to obtain your authentication secrets: https://github.com/OpenWonderLabs/SwitchBotAPI?tab=readme-ov-file#getting-started
 - Run switchbot_api2mqtt.py using your python environment OR run with docker compose
-- Send GET and POST call to Switchbot API to *MQTT_TOPIC_COMMAND* topic using an MQTT publisher
-- Get responses subscribing to *MQTT_TOPIC_RESPONSE* topic
-- Actually the *MQTT_TOPIC_STATUS* topic is not used
+- Send commands to *MQTT_SMARTLOCK_BASE_TOPIC/[deviceid]/cmnd* topic to interact with smartlock devices. Payload is a plain string with command name. Responses will be published on *MQTT_SMARTLOCK_BASE_TOPIC/[deviceid]/response* topic
+- Send generic GET and POST call to Switchbot API to *MQTT_GENERIC_BASE_TOPIC* topic using an MQTT publisher. Responses will be published on *MQTT_GENERIC_BASE_TOPIC/response* topic
+- Webhook events will be published on *MQTT_SMARTLOCK_BASE_TOPIC/[deviceid]/event* topic
+- It is possible to enable a polling thread to obtain state information periodically (this is mandatory to periodically update battery information not managed by webhooks)
 
-### Payload template
+### Payload template for generic GET/POST call
 
 {"method": "[get/post]", "service": "[path_url]", "payload": ["generic_payload_for_POST_call"]}
 
+### Environment configuration
+
+- *MQTT_BROKER*=**mqtt broker ip address**
+- *MQTT_PORT*=**mqtt broker port**
+- *MQTT_USERNAME*=**mqtt broker username (if needed)**
+- *MQTT_PASSWORD*=**mqtt broker password (if needed)**
+- *MQTT_CLIENT_ID*=**mqtt_client_id**
+- *MQTT_SMARTLOCK_BASE_TOPIC*=**base topic for smart lock pro interaction**
+- *MQTT_GENERIC_BASE_TOPIC*=**base topic for generic api interaction**
+- *SWITCHBOT_TOKEN*=**switchbot authentication token** see https://github.com/OpenWonderLabs/SwitchBotAPI?-tab=readme-ov-file#getting-started
+- *SWITCHBOT_SECRET*=**switchbot authentication secret** see https://github.com/OpenWonderLabs/SwitchBotAPI?-tab=readme-ov-file#getting-started
+- *API_BASEURL*=**switchbot api base url**
+- *HTTP_PORT*=**http port listening for webhook events**
+- *SWITCHBOT_VALID_DEVICE_TYPES*=**array of valid device types managed by bridge** see https://github.com/-OpenWonderLabs/SwitchBotAPI?tab=readme-ov-file
+- *SWITCHBOT_VALID_DEVICE_ID*=**array of valid device id managed by bridge**
+- *SWITCHBOT_SMARTLOCK_VALID_COMMAND*=**array of valid smartlock commands managed by bridge**
+- *SWITCHBOT_POLLING_INTERVAL_SEC*=**polling interval in seconds. 0 means no polling**
+
+### MQTT Topics
+
+- *MQTT_SMARTLOCK_BASE_TOPIC/[deviceid]/cmnd*=**to send command to smart lock pro device**
+- *MQTT_SMARTLOCK_BASE_TOPIC/[deviceid]/response*=**to receive command response from smart lock pro device**
+- *MQTT_SMARTLOCK_BASE_TOPIC/[deviceid]/event*=**to receive webhook events from smart lock pro device**
+- *MQTT_GENERIC_BASE_TOPIC/cmnd*=**to send generic get/post call to switchbot api**
+- *MQTT_GENERIC_BASE_TOPIC/response*=**to receive response from switchbot api generic get/post call**
+
+### WEBHOOK configuration
+
+A simple video about webhook: https://youtu.be/FxlmHL5eWR8
+
+To enable webhook integration you must configure webhook using API. See https://github.com/OpenWonderLabs/SwitchBotAPI?tab=readme-ov-file#webhook
+
+So that webhook can work you need to have a public url to receive events.
+
+This can be directly managed by this bridge or by a frontend http server which through Reverse Proxy forwards requests to this bridge.
+
+It is important to know and manage security aspects before exposing services on the internet.
+
+As an example, this is a valid setup:
+
+![Webhook setup](assets/webhook01.jpg)
+
+- *Reception of the Webhook (Cloud Server)*: Switchbot webhook calls are sent to the public url of your cloud server (for example, http://www.example.com/switchbot_webhook). Being the server publicly accessible, it is able to receive these requests from Switchbot.
+- *SSH tunnel*: the cloud server is connected to your local Raspberry Pi via an SSH tunnel. This tunnel creates a safe and persistent connection between the external server and your home network, allowing the cloud server to forward the traffic to the Raspberry Pi.
+- *Forwarding of the request (Raspberry PI)*: once the webhook arrives at the Cloud server, this forwards it through the SSH tunnel to the Raspberry Pi. The Raspberry Pi, which acts as "bridge" for the webhooks, receives the request and can therefore process it.
+- *Local processing*: the bridge running on the Raspberry PI performs the desired actions based on the content of the Webhook request, such as checking the status of switchbot devices or activating specific automations within your home network.
+
+This setup allows you to receive the Switchbot Webhooks while keeping your Raspberry Pi and your home network protected behind a firewall, exposing only an intermediate server.
+
+## *Version 1.0 beta*
+ - Added webhooks support using an internal http server (**flask**)
+ - Added full support for **Smart Lock Pro** devices
+ - Added polling thread for status information
+ - Removed *LOG_FILE*, *MQTT_TOPIC_COMMAND*, *MQTT_TOPIC_STATUS* and *MQTT_TOPIC_RESPONSE* configuration properties
+ - Added *MQTT_SMARTLOCK_BASE_TOPIC*, *MQTT_GENERIC_BASE_TOPIC*, *HTTP_PORT*, *SWITCHBOT_VALID_DEVICE_TYPES*, *SWITCHBOT_VALID_DEVICE_ID*, *SWITCHBOT_SMARTLOCK_VALID_COMMAND*, *SWITCHBOT_POLLING_INTERVAL_SEC* configuration properties
+ - Added external logger configuration using logging.json file
+ - Added .env.example file
+ - Code refactoring
+
 ## *Version 0.2*
  - Generic version to invoke all switcbot API services using GET and POST method
  - MQTT payload containts all the details related to API call
diff --git a/docker-compose.yml b/docker-compose.yml
@@ -2,7 +2,7 @@ services:
   switchbot-proxy:
     build: .
     container_name: switchbot_api2mqtt
-    restart: no
+    restart: always
     env_file:
       - .env
     network_mode: host
diff --git a/http_utils.py b/http_utils.py
@@ -0,0 +1,30 @@
+import logging
+import os
+import requests
+from dotenv import load_dotenv
+
+load_dotenv()
+logger = logging.getLogger("http_utils")
+
+def http_post(service_url, payload, headers):
+    logger.debug(f"Call POST {service_url}")
+    logger.debug(f"Payload {payload}")
+    logger.debug(f"headers {headers}")
+    try:
+        response = requests.post(service_url, headers=headers, json=payload)
+        logger.debug(f"Response {response}")
+        return response
+    except Exception as e:
+        logger.error(f"Error sending POST request: {e}")
+        return False
+
+def http_get(service_url, headers):
+    logger.debug(f"Call GET {service_url}")
+    logger.debug(f"headers {headers}")
+    try:
+        response = requests.get(service_url, headers=headers)
+        logger.debug(f"Response {response}")
+        return response
+    except Exception as e:
+        logger.error(f"Error sending GET request: {e}")
+        return False
diff --git a/logging.json b/logging.json
@@ -0,0 +1,37 @@
+{
+  "version": 1,
+  "formatters": {
+    "standard": {
+      "format": "%(asctime)s [%(levelname)s] %(name)s: %(message)s"
+    }
+  },
+  "handlers": {
+    "console": {
+      "class": "logging.StreamHandler",
+      "formatter": "standard",
+      "level": "DEBUG"
+    },
+    "file": {
+      "class": "logging.FileHandler",
+      "formatter": "standard",
+      "level": "DEBUG",
+      "filename": "/logs/switchbot_api2mqtt.log"
+    }
+  },
+  "loggers": {
+    "switchbot_api2mqtt": {
+      "handlers": ["console", "file"],
+      "level": "INFO",
+      "propagate": false
+    },
+    "http_utils": {
+      "handlers": ["console", "file"],
+      "level": "INFO",
+      "propagate": false
+    }
+  },
+  "root": {
+    "level": "INFO",
+    "handlers": ["console", "file"]
+  }
+}
diff --git a/requirements.txt b/requirements.txt
@@ -1,3 +1,4 @@
 paho-mqtt>=1.6.1
 requests
 python-dotenv
+flask
diff --git a/switchbot_api2mqtt.py b/switchbot_api2mqtt.py
