| Name | dbus2mqtt JSON |
| Version |
0.4.2
JSON |
| download |
| home_page | None |
| Summary | A Python tool to expose Linux D-Bus signals, methods and properties over MQTT - featuring templating, payload enrichment and Home Assistant-ready examples |
| upload_time | 2025-07-13 15:47:32 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | None |
| keywords |
dbus
home-assistant
mpris
mqtt
python
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# dbus2mqtt
**dbus2mqtt** is a Python application that bridges **DBus** with **MQTT**.
It lets you forward Linux D-Bus signals and properties to MQTT topics, call D-Bus methods via MQTT messages, and shape payloads using flexible **Jinja2 templating**.
This makes it easy to integrate Linux desktop services or system signals into MQTT-based workflows - including **Home Assistant**.
## ✨ Features
* 🔗 Forward **D-Bus signals** to MQTT topics.
* 🧠 Enrich or transform **MQTT payloads** using Jinja2 templates and additional D-Bus calls.
* ⚡ Trigger message publishing via **signals, timers, property changes, or startup events**.
* 📡 Expose **D-Bus methods** for remote control via MQTT messages.
* 🏠 Includes example configurations for **MPRIS** and **Home Assistant Media Player** integration.
## Project status
**dbus2mqtt** is considered stable for the use-cases it has been tested against, and is actively being developed. Documentation is continuously being improved.
Initial testing has focused on MPRIS integration. A table of tested MPRIS players and their supported methods can be found here: [home_assistant_media_player.md](https://github.com/jwnmulder/dbus2mqtt/blob/main/docs/examples/home_assistant_media_player.md)
## Getting started with dbus2mqtt
Create a `config.yaml` file with the contents shown below. This configuration will expose all bus properties from the `org.mpris.MediaPlayer2.Player` interface to MQTT on the `dbus2mqtt/org.mpris.MediaPlayer2/state` topic. Have a look at [docs/examples](https://github.com/jwnmulder/dbus2mqtt/blob/main/docs/examples.md) for more examples
```yaml
dbus:
subscriptions:
- bus_name: org.mpris.MediaPlayer2.*
path: /org/mpris/MediaPlayer2
interfaces:
- interface: org.freedesktop.DBus.Properties
methods:
- method: GetAll
flows:
- name: "Publish MPRIS state"
triggers:
- type: object_added
- type: schedule
interval: {seconds: 5}
actions:
- type: context_set
context:
mpris_bus_name: '{{ dbus_list("org.mpris.MediaPlayer2.*") | first }}'
path: /org/mpris/MediaPlayer2
- type: mqtt_publish
topic: dbus2mqtt/org.mpris.MediaPlayer2/state
payload_type: json
payload_template: |
{{ dbus_call(mpris_bus_name, path, 'org.freedesktop.DBus.Properties', 'GetAll', ['org.mpris.MediaPlayer2.Player']) }}
```
MQTT connection details can be configured in that same `config.yaml` file or via environment variables. For now create a `.env` file with the following contents.
```bash
MQTT__HOST=localhost
MQTT__PORT=1883
MQTT__USERNAME=
MQTT__PASSWORD=
```
### Install and run dbus2mqtt
```bash
python -m pip install dbus2mqtt
dbus2mqtt --config config.yaml
```
### Run using docker with auto start behavior
To build and run dbus2mqtt using Docker with the [home_assistant_media_player.yaml](https://github.com/jwnmulder/dbus2mqtt/blob/main/docs/examples/home_assistant_media_player.yaml) example from this repository.
```bash
# setup configuration
mkdir -p $HOME/.config/dbus2mqtt
cp docs/examples/home_assistant_media_player.yaml $HOME/.config/dbus2mqtt/config.yaml
cp .env.example $HOME/.config/dbus2mqtt/.env
# run image and automatically start on reboot
sudo docker pull jwnmulder/dbus2mqtt
sudo docker run --detach --name dbus2mqtt \
--volume "$HOME"/.config/dbus2mqtt:"$HOME"/.config/dbus2mqtt \
--volume /run/user:/run/user \
--env DBUS_SESSION_BUS_ADDRESS="$DBUS_SESSION_BUS_ADDRESS" \
--env-file "$HOME"/.config/dbus2mqtt/.env \
--user $(id -u):$(id -g) \
--privileged \
--restart unless-stopped \
jwnmulder/dbus2mqtt \
--config "$HOME"/.config/dbus2mqtt/config.yaml
# view logs
sudo docker logs dbus2mqtt -f
```
## Examples
This repository contains examples under [docs/examples](https://github.com/jwnmulder/dbus2mqtt/blob/main//docs/examples.md). The most complete one being [MPRIS to Home Assistant Media Player integration](https://github.com/jwnmulder/dbus2mqtt/blob/main/docs/examples/home_assistant_media_player.md)
## Configuration reference
dbus2mqtt leverages [jsonargparse](https://jsonargparse.readthedocs.io/en/stable/) which allows configuration via either yaml configuration, CLI or environment variables. Until this is fully documented have a look at the examples in this repository.
### MQTT and D-Bus connection details
```bash
# dbus_fast configuration
export DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus
# dbus2mqtt configuration
MQTT__HOST=localhost
MQTT__PORT=1883
MQTT__USERNAME=
MQTT__PASSWORD=
```
or
```yaml
mqtt:
host: localhost
port: 1883
subscription_topics:
- dbus2mqtt/#
```
### Exposing dbus methods
```yaml
dbus:
subscriptions:
- bus_name: org.mpris.MediaPlayer2.*
path: /org/mpris/MediaPlayer2
interfaces:
- interface: org.mpris.MediaPlayer2.Player
mqtt_command_topic: dbus2mqtt/org.mpris.MediaPlayer2/command
methods:
- method: Pause
- method: Play
```
This configuration will expose 2 methods. Triggering methods can be done by publishing json messages to the `dbus2mqtt/org.mpris.MediaPlayer2/command` MQTT topic. Arguments can be passed along in `args`.
Some examples that call methods on **all** bus_names matching the configured pattern
```json
{
"method": "Play",
}
```
```json
{
"method": "OpenUri",
"args": []
}
```
To specifically target objects the properties `bus_name` and/or `path` can be used. Both properties support wildcards
```json
{
"method": "Play",
"bus_name": "*.firefox",
"path": "/org/mpris/MediaPlayer2"
}
```
### Exposing dbus signals
Publishing signals to MQTT topics works by subscribing to the relevant signal and using flows for publishing
```yaml
dbus:
subscriptions:
- bus_name: org.mpris.MediaPlayer2.*
path: /org/mpris/MediaPlayer2
interfaces:
- interface: org.freedesktop.DBus.Properties
signals:
- signal: PropertiesChanged
flows:
- name: "Property Changed flow"
triggers:
- type: on_signal
actions:
- type: mqtt_publish
topic: dbus2mqtt/org.mpris.MediaPlayer2/signals/PropertiesChanged
payload_type: json
```
## Flows
A reference of all supported flow triggers and actions can be found on [Flows](https://github.com/jwnmulder/dbus2mqtt/blob/main/docs/flows.md)
## Jinja templating
TODO: Document Jinja templating, for now see the [MPRIS to Home Assistant Media Player integration](https://github.com/jwnmulder/dbus2mqtt/blob/main/docs/examples/home_assistant_media_player.md) example
Raw data
{
"_id": null,
"home_page": null,
"name": "dbus2mqtt",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "dbus, home-assistant, mpris, mqtt, python",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/b4/d6/34813e255ad020a1b13ba2fc364e4a2756f35ad87e37ef96ddd7f4d7d23a/dbus2mqtt-0.4.2.tar.gz",
"platform": null,
"description": "# dbus2mqtt\n\n**dbus2mqtt** is a Python application that bridges **DBus** with **MQTT**.\nIt lets you forward Linux D-Bus signals and properties to MQTT topics, call D-Bus methods via MQTT messages, and shape payloads using flexible **Jinja2 templating**.\n\nThis makes it easy to integrate Linux desktop services or system signals into MQTT-based workflows - including **Home Assistant**.\n\n## \u2728 Features\n\n* \ud83d\udd17 Forward **D-Bus signals** to MQTT topics.\n* \ud83e\udde0 Enrich or transform **MQTT payloads** using Jinja2 templates and additional D-Bus calls.\n* \u26a1 Trigger message publishing via **signals, timers, property changes, or startup events**.\n* \ud83d\udce1 Expose **D-Bus methods** for remote control via MQTT messages.\n* \ud83c\udfe0 Includes example configurations for **MPRIS** and **Home Assistant Media Player** integration.\n\n## Project status\n\n**dbus2mqtt** is considered stable for the use-cases it has been tested against, and is actively being developed. Documentation is continuously being improved.\n\nInitial testing has focused on MPRIS integration. A table of tested MPRIS players and their supported methods can be found here: [home_assistant_media_player.md](https://github.com/jwnmulder/dbus2mqtt/blob/main/docs/examples/home_assistant_media_player.md)\n\n## Getting started with dbus2mqtt\n\nCreate a `config.yaml` file with the contents shown below. This configuration will expose all bus properties from the `org.mpris.MediaPlayer2.Player` interface to MQTT on the `dbus2mqtt/org.mpris.MediaPlayer2/state` topic. Have a look at [docs/examples](https://github.com/jwnmulder/dbus2mqtt/blob/main/docs/examples.md) for more examples\n\n```yaml\ndbus:\n subscriptions:\n - bus_name: org.mpris.MediaPlayer2.*\n path: /org/mpris/MediaPlayer2\n interfaces:\n - interface: org.freedesktop.DBus.Properties\n methods:\n - method: GetAll\n\n flows:\n - name: \"Publish MPRIS state\"\n triggers:\n - type: object_added\n - type: schedule\n interval: {seconds: 5}\n actions:\n - type: context_set\n context:\n mpris_bus_name: '{{ dbus_list(\"org.mpris.MediaPlayer2.*\") | first }}'\n path: /org/mpris/MediaPlayer2\n - type: mqtt_publish\n topic: dbus2mqtt/org.mpris.MediaPlayer2/state\n payload_type: json\n payload_template: |\n {{ dbus_call(mpris_bus_name, path, 'org.freedesktop.DBus.Properties', 'GetAll', ['org.mpris.MediaPlayer2.Player']) }}\n```\n\nMQTT connection details can be configured in that same `config.yaml` file or via environment variables. For now create a `.env` file with the following contents.\n\n```bash\nMQTT__HOST=localhost\nMQTT__PORT=1883\nMQTT__USERNAME=\nMQTT__PASSWORD=\n```\n\n### Install and run dbus2mqtt\n\n```bash\npython -m pip install dbus2mqtt\ndbus2mqtt --config config.yaml\n```\n\n\n### Run using docker with auto start behavior\n\nTo build and run dbus2mqtt using Docker with the [home_assistant_media_player.yaml](https://github.com/jwnmulder/dbus2mqtt/blob/main/docs/examples/home_assistant_media_player.yaml) example from this repository.\n\n```bash\n# setup configuration\nmkdir -p $HOME/.config/dbus2mqtt\ncp docs/examples/home_assistant_media_player.yaml $HOME/.config/dbus2mqtt/config.yaml\ncp .env.example $HOME/.config/dbus2mqtt/.env\n\n# run image and automatically start on reboot\nsudo docker pull jwnmulder/dbus2mqtt\nsudo docker run --detach --name dbus2mqtt \\\n --volume \"$HOME\"/.config/dbus2mqtt:\"$HOME\"/.config/dbus2mqtt \\\n --volume /run/user:/run/user \\\n --env DBUS_SESSION_BUS_ADDRESS=\"$DBUS_SESSION_BUS_ADDRESS\" \\\n --env-file \"$HOME\"/.config/dbus2mqtt/.env \\\n --user $(id -u):$(id -g) \\\n --privileged \\\n --restart unless-stopped \\\n jwnmulder/dbus2mqtt \\\n --config \"$HOME\"/.config/dbus2mqtt/config.yaml\n\n# view logs\nsudo docker logs dbus2mqtt -f\n```\n\n## Examples\n\nThis repository contains examples under [docs/examples](https://github.com/jwnmulder/dbus2mqtt/blob/main//docs/examples.md). The most complete one being [MPRIS to Home Assistant Media Player integration](https://github.com/jwnmulder/dbus2mqtt/blob/main/docs/examples/home_assistant_media_player.md)\n\n## Configuration reference\n\ndbus2mqtt leverages [jsonargparse](https://jsonargparse.readthedocs.io/en/stable/) which allows configuration via either yaml configuration, CLI or environment variables. Until this is fully documented have a look at the examples in this repository.\n\n### MQTT and D-Bus connection details\n\n```bash\n# dbus_fast configuration\nexport DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus\n\n# dbus2mqtt configuration\nMQTT__HOST=localhost\nMQTT__PORT=1883\nMQTT__USERNAME=\nMQTT__PASSWORD=\n```\n\nor\n\n```yaml\nmqtt:\n host: localhost\n port: 1883\n subscription_topics:\n - dbus2mqtt/#\n```\n\n### Exposing dbus methods\n\n```yaml\ndbus:\n subscriptions:\n - bus_name: org.mpris.MediaPlayer2.*\n path: /org/mpris/MediaPlayer2\n interfaces:\n - interface: org.mpris.MediaPlayer2.Player\n mqtt_command_topic: dbus2mqtt/org.mpris.MediaPlayer2/command\n methods:\n - method: Pause\n - method: Play\n```\n\nThis configuration will expose 2 methods. Triggering methods can be done by publishing json messages to the `dbus2mqtt/org.mpris.MediaPlayer2/command` MQTT topic. Arguments can be passed along in `args`.\n\nSome examples that call methods on **all** bus_names matching the configured pattern\n\n```json\n{\n \"method\": \"Play\",\n}\n```\n\n```json\n{\n \"method\": \"OpenUri\",\n \"args\": []\n}\n```\n\nTo specifically target objects the properties `bus_name` and/or `path` can be used. Both properties support wildcards\n\n```json\n{\n \"method\": \"Play\",\n \"bus_name\": \"*.firefox\",\n \"path\": \"/org/mpris/MediaPlayer2\"\n}\n```\n\n### Exposing dbus signals\n\nPublishing signals to MQTT topics works by subscribing to the relevant signal and using flows for publishing\n\n```yaml\ndbus:\n subscriptions:\n - bus_name: org.mpris.MediaPlayer2.*\n path: /org/mpris/MediaPlayer2\n interfaces:\n - interface: org.freedesktop.DBus.Properties\n signals:\n - signal: PropertiesChanged\n\n flows:\n - name: \"Property Changed flow\"\n triggers:\n - type: on_signal\n actions:\n - type: mqtt_publish\n topic: dbus2mqtt/org.mpris.MediaPlayer2/signals/PropertiesChanged\n payload_type: json\n```\n\n## Flows\n\nA reference of all supported flow triggers and actions can be found on [Flows](https://github.com/jwnmulder/dbus2mqtt/blob/main/docs/flows.md)\n\n## Jinja templating\n\nTODO: Document Jinja templating, for now see the [MPRIS to Home Assistant Media Player integration](https://github.com/jwnmulder/dbus2mqtt/blob/main/docs/examples/home_assistant_media_player.md) example\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python tool to expose Linux D-Bus signals, methods and properties over MQTT - featuring templating, payload enrichment and Home Assistant-ready examples ",
"version": "0.4.2",
"project_urls": {
"Issues": "https://github.com/jwnmulder/dbus2mqtt/issues",
"Repository": "https://github.com/jwnmulder/dbus2mqtt.git"
},
"split_keywords": [
"dbus",
" home-assistant",
" mpris",
" mqtt",
" python"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ce80277d65b83e6dd1791a352d6b0309693086d4dcbf5a4e4a1d6a4908ba466b",
"md5": "5953588e6c699581bd49501bb62af94c",
"sha256": "08f9aa693b8b020e13a26e4a71ba8702f6000a6a15137f93d83264ecf2b89543"
},
"downloads": -1,
"filename": "dbus2mqtt-0.4.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5953588e6c699581bd49501bb62af94c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 30207,
"upload_time": "2025-07-13T15:47:30",
"upload_time_iso_8601": "2025-07-13T15:47:30.901522Z",
"url": "https://files.pythonhosted.org/packages/ce/80/277d65b83e6dd1791a352d6b0309693086d4dcbf5a4e4a1d6a4908ba466b/dbus2mqtt-0.4.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b4d634813e255ad020a1b13ba2fc364e4a2756f35ad87e37ef96ddd7f4d7d23a",
"md5": "21952174262c6c43f5fa3d2e689aeaf4",
"sha256": "dc86655e8d858da7b9b8e74f5171ec33cc8a0c91cac642b6569e38db9c31903b"
},
"downloads": -1,
"filename": "dbus2mqtt-0.4.2.tar.gz",
"has_sig": false,
"md5_digest": "21952174262c6c43f5fa3d2e689aeaf4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 76761,
"upload_time": "2025-07-13T15:47:32",
"upload_time_iso_8601": "2025-07-13T15:47:32.230816Z",
"url": "https://files.pythonhosted.org/packages/b4/d6/34813e255ad020a1b13ba2fc364e4a2756f35ad87e37ef96ddd7f4d7d23a/dbus2mqtt-0.4.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-13 15:47:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jwnmulder",
"github_project": "dbus2mqtt",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "dbus2mqtt"
}
