# **SwitchBot Actions: A YAML-based Automation Engine**
`switchbot-actions` is a lightweight, standalone automation engine that turns a single `config.yaml` file into a powerful local controller for your SwitchBot BLE devices. React to device states, create time-based triggers, and integrate with MQTT and Prometheus—all with a simple, configuration-driven approach.
At its core, `switchbot-actions` monitors various input sources and, based on your rules, triggers a wide range of actions.
Its efficiency makes it a great fit for resource-constrained hardware like a Raspberry Pi Zero, allowing you to build a sophisticated, private, and reliable home automation hub without needing a large, all-in-one platform.
## **Key Features**
- **Powerful Automation Rules**: Define complex automations with a unified `if`/`then` structure.
- **Inter-Device Communication**: Create rules where one device's state triggers an action based on the state of another device.
- **Direct Device Control**: A `switchbot_command` action allows you to directly control any SwitchBot device, enabling powerful, interconnected automations.
- **Event-Driven & Time-Based Triggers**: React to state changes instantly or trigger actions only when a condition has been met for a specific duration (e.g., "if a door has been open for 5 minutes").
- **Full MQTT Integration**: Use MQTT messages as triggers and publish messages as an action.
- **Prometheus Exporter**: Exposes device metrics at a configurable `/metrics` endpoint. It also provides a special `switchbot_device_info` metric, which allows you to use your custom device names in PromQL queries for improved readability. For technical details and query examples, please see the [Project Specification](https://github.com/hnw/switchbot-actions/blob/main/docs/specification.md).
- **`switchbot_device_info` metric**: This metric provides metadata about configured SwitchBot devices, including their `address`, user-defined `name` (alias), and `model`. Its value is always `1` and it's useful for joining with other metrics to make queries more readable.
**Example PromQL Query (to get temperature by device name):**
```promql
switchbot_temperature * on(address) group_left(name) switchbot_device_info{name="living_room_meter"}
```
## **Prerequisites**
- **Python**: Version 3.11 or newer is required.
- **Operating System**: The application is tested and supported on Linux. It is also expected to work on other platforms like macOS and Windows, but BLE functionality may vary depending on the system's Bluetooth support.
- **Permissions (Linux)**: The application needs permissions to access the Bluetooth adapter. This can typically be achieved by running with sudo or by setting the necessary capabilities (see the [Deployment Guide](https://github.com/hnw/switchbot-actions/blob/main/docs/deployment.md)).
## **Quick Start**
### **1. Installation**
We strongly recommend installing with `pipx` to keep your system clean and avoid dependency conflicts.
```
# Install pipx
pip install pipx
pipx ensurepath
# Install the application
pipx install switchbot-actions
```
### **2. Configuration**
Create a config.yaml file. Start with this example that showcases inter-device automation: it turns on a fan only if the room is hot **and** the window is closed.
```yaml
# config.yaml
# 1. Define aliases for your devices for easy reference.
devices:
office-meter:
address: "aa:bb:cc:dd:ee:ff" # Your temperature sensor's address
office-window:
address: "11:22:33:44:55:66" # Your contact sensor's address
automations:
- name: "Turn on Fan when Hot and Window is Closed"
if:
# This rule triggers when the temperature goes above 28 degrees.
source: "switchbot"
device: "office-meter"
conditions:
temperature: "> 28.0"
# And at that moment, check the state of the window sensor.
office-window.contact_open: false
then:
# In a real scenario, you would control a fan here.
# This example just logs a message.
type: "log"
level: "WARNING"
message: "Room is hot and window is closed. Turning on fan..."
```
### **3. Run**
Launch the application with your configuration. Use the --debug flag first to ensure your devices are discovered.
```
# Run with sudo if you encounter permission errors
switchbot-actions --debug -c config.yaml
```
## **What's Possible? (More Examples)**
switchbot-actions enables highly context-aware automations.
- **React to State Changes**: Trigger an action only when a state _changes_. This is perfect for detecting button presses.
```yaml
if:
source: "switchbot"
conditions:
# Triggers when the button_count is different from its previous value.
button_count: "!= {previous.button_count}"
```
- **Time-Based Alerts**: Send a notification if a door has been left open for more than 10 minutes.
```yaml
if:
source: "switchbot_timer"
duration: "10m"
conditions:
contact_open: True
```
- **Full MQTT Integration**: Control your devices with MQTT messages from other systems.
```yaml
if:
source: "mqtt"
topic: "home/living/light/set"
conditions:
payload: "ON" # React to a simple string payload
```
**For a complete reference of all configuration options, please see the [Project Specification](https://github.com/hnw/switchbot-actions/blob/main/docs/specification.md).**
## **Advanced Usage**
- **Running as a Service**: For continuous, 24/7 monitoring, we recommend running the application as a systemd service. View the [**Deployment Guide**](https://github.com/hnw/switchbot-actions/blob/main/docs/deployment.md)).
- **Command-Line Overrides**: You can temporarily override any setting in your config.yaml using command-line flags. Run switchbot-actions --help for a full list.
## **Robustness Features**
switchbot-actions is designed for reliability:
- **Fail-Fast Startup**: The application performs critical resource checks at startup and exits with a clear error if a resource (e.g., a port) is unavailable.
- **Configuration Reload with Rollback**: Send a SIGHUP signal (sudo systemctl kill -s HUP switchbot-actions.service) to reload your configuration without downtime. If the new configuration is invalid, the application automatically rolls back to the last known good state.
Raw data
{
"_id": null,
"home_page": null,
"name": "switchbot-actions",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "switchbot, automation, prometheus, ble, home-automation",
"author": null,
"author_email": "Yoshio HANAWA <y@hnw.jp>",
"download_url": "https://files.pythonhosted.org/packages/e0/73/8fc782df35f83af6e113516392e6ebd267aa2733a067b836eddc48649fd7/switchbot_actions-1.5.0.tar.gz",
"platform": null,
"description": "# **SwitchBot Actions: A YAML-based Automation Engine**\n\n`switchbot-actions` is a lightweight, standalone automation engine that turns a single `config.yaml` file into a powerful local controller for your SwitchBot BLE devices. React to device states, create time-based triggers, and integrate with MQTT and Prometheus\u2014all with a simple, configuration-driven approach.\n\nAt its core, `switchbot-actions` monitors various input sources and, based on your rules, triggers a wide range of actions.\n\n\n\nIts efficiency makes it a great fit for resource-constrained hardware like a Raspberry Pi Zero, allowing you to build a sophisticated, private, and reliable home automation hub without needing a large, all-in-one platform.\n\n## **Key Features**\n\n- **Powerful Automation Rules**: Define complex automations with a unified `if`/`then` structure.\n- **Inter-Device Communication**: Create rules where one device's state triggers an action based on the state of another device.\n- **Direct Device Control**: A `switchbot_command` action allows you to directly control any SwitchBot device, enabling powerful, interconnected automations.\n- **Event-Driven & Time-Based Triggers**: React to state changes instantly or trigger actions only when a condition has been met for a specific duration (e.g., \"if a door has been open for 5 minutes\").\n- **Full MQTT Integration**: Use MQTT messages as triggers and publish messages as an action.\n- **Prometheus Exporter**: Exposes device metrics at a configurable `/metrics` endpoint. It also provides a special `switchbot_device_info` metric, which allows you to use your custom device names in PromQL queries for improved readability. For technical details and query examples, please see the [Project Specification](https://github.com/hnw/switchbot-actions/blob/main/docs/specification.md).\n - **`switchbot_device_info` metric**: This metric provides metadata about configured SwitchBot devices, including their `address`, user-defined `name` (alias), and `model`. Its value is always `1` and it's useful for joining with other metrics to make queries more readable.\n\n **Example PromQL Query (to get temperature by device name):**\n\n ```promql\n switchbot_temperature * on(address) group_left(name) switchbot_device_info{name=\"living_room_meter\"}\n ```\n\n## **Prerequisites**\n\n- **Python**: Version 3.11 or newer is required.\n- **Operating System**: The application is tested and supported on Linux. It is also expected to work on other platforms like macOS and Windows, but BLE functionality may vary depending on the system's Bluetooth support.\n- **Permissions (Linux)**: The application needs permissions to access the Bluetooth adapter. This can typically be achieved by running with sudo or by setting the necessary capabilities (see the [Deployment Guide](https://github.com/hnw/switchbot-actions/blob/main/docs/deployment.md)).\n\n## **Quick Start**\n\n### **1. Installation**\n\nWe strongly recommend installing with `pipx` to keep your system clean and avoid dependency conflicts.\n\n```\n# Install pipx\npip install pipx\npipx ensurepath\n\n# Install the application\npipx install switchbot-actions\n```\n\n### **2. Configuration**\n\nCreate a config.yaml file. Start with this example that showcases inter-device automation: it turns on a fan only if the room is hot **and** the window is closed.\n\n```yaml\n# config.yaml\n\n# 1. Define aliases for your devices for easy reference.\ndevices:\n office-meter:\n address: \"aa:bb:cc:dd:ee:ff\" # Your temperature sensor's address\n office-window:\n address: \"11:22:33:44:55:66\" # Your contact sensor's address\n\nautomations:\n - name: \"Turn on Fan when Hot and Window is Closed\"\n if:\n # This rule triggers when the temperature goes above 28 degrees.\n source: \"switchbot\"\n device: \"office-meter\"\n conditions:\n temperature: \"> 28.0\"\n # And at that moment, check the state of the window sensor.\n office-window.contact_open: false\n then:\n # In a real scenario, you would control a fan here.\n # This example just logs a message.\n type: \"log\"\n level: \"WARNING\"\n message: \"Room is hot and window is closed. Turning on fan...\"\n```\n\n### **3. Run**\n\nLaunch the application with your configuration. Use the --debug flag first to ensure your devices are discovered.\n\n```\n# Run with sudo if you encounter permission errors\nswitchbot-actions --debug -c config.yaml\n```\n\n## **What's Possible? (More Examples)**\n\nswitchbot-actions enables highly context-aware automations.\n\n- **React to State Changes**: Trigger an action only when a state _changes_. This is perfect for detecting button presses.\n\n```yaml\nif:\n source: \"switchbot\"\n conditions:\n # Triggers when the button_count is different from its previous value.\n button_count: \"!= {previous.button_count}\"\n```\n\n- **Time-Based Alerts**: Send a notification if a door has been left open for more than 10 minutes.\n\n```yaml\nif:\n source: \"switchbot_timer\"\n duration: \"10m\"\n conditions:\n contact_open: True\n```\n\n- **Full MQTT Integration**: Control your devices with MQTT messages from other systems.\n\n```yaml\nif:\n source: \"mqtt\"\n topic: \"home/living/light/set\"\n conditions:\n payload: \"ON\" # React to a simple string payload\n```\n\n**For a complete reference of all configuration options, please see the [Project Specification](https://github.com/hnw/switchbot-actions/blob/main/docs/specification.md).**\n\n## **Advanced Usage**\n\n- **Running as a Service**: For continuous, 24/7 monitoring, we recommend running the application as a systemd service. View the [**Deployment Guide**](https://github.com/hnw/switchbot-actions/blob/main/docs/deployment.md)).\n- **Command-Line Overrides**: You can temporarily override any setting in your config.yaml using command-line flags. Run switchbot-actions --help for a full list.\n\n## **Robustness Features**\n\nswitchbot-actions is designed for reliability:\n\n- **Fail-Fast Startup**: The application performs critical resource checks at startup and exits with a clear error if a resource (e.g., a port) is unavailable.\n- **Configuration Reload with Rollback**: Send a SIGHUP signal (sudo systemctl kill -s HUP switchbot-actions.service) to reload your configuration without downtime. If the new configuration is invalid, the application automatically rolls back to the last known good state.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A YAML-based automation engine for SwitchBot BLE devices with a Prometheus exporter.",
"version": "1.5.0",
"project_urls": {
"Bug Tracker": "https://github.com/hnw/switchbot-actions/issues",
"Homepage": "https://github.com/hnw/switchbot-actions",
"Repository": "https://github.com/hnw/switchbot-actions"
},
"split_keywords": [
"switchbot",
" automation",
" prometheus",
" ble",
" home-automation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b685131d16df181df2ea0450f5bc7c492f4fb2a996178cbbbed489a22f690c42",
"md5": "281b78a08163a4facaaa3714be8783d4",
"sha256": "9ea7d975f02d7e33ac24338d8f3d6242c823ed741cbd8db4932dc8a5f16fb9bd"
},
"downloads": -1,
"filename": "switchbot_actions-1.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "281b78a08163a4facaaa3714be8783d4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 35198,
"upload_time": "2025-08-14T11:06:55",
"upload_time_iso_8601": "2025-08-14T11:06:55.939144Z",
"url": "https://files.pythonhosted.org/packages/b6/85/131d16df181df2ea0450f5bc7c492f4fb2a996178cbbbed489a22f690c42/switchbot_actions-1.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e0738fc782df35f83af6e113516392e6ebd267aa2733a067b836eddc48649fd7",
"md5": "c86bd00d8e9463a722511f820f23c029",
"sha256": "3265848434c75b9e4f39c1d03028b1bc9d79099afc3ef2841799a0f29bd2fcc3"
},
"downloads": -1,
"filename": "switchbot_actions-1.5.0.tar.gz",
"has_sig": false,
"md5_digest": "c86bd00d8e9463a722511f820f23c029",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 62269,
"upload_time": "2025-08-14T11:06:57",
"upload_time_iso_8601": "2025-08-14T11:06:57.519443Z",
"url": "https://files.pythonhosted.org/packages/e0/73/8fc782df35f83af6e113516392e6ebd267aa2733a067b836eddc48649fd7/switchbot_actions-1.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-14 11:06:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hnw",
"github_project": "switchbot-actions",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "switchbot-actions"
}
JSON
