Templating

dbus2mqtt leverages Jinja to allow formatting of MQTT messages, D-Bus responses and other configuration aspects of dbus2mqtt. If you are not familiar with Jinja based expressions, have a look at Jinjas own Template Designer Documentation.

Templating is used in these areas of dbus2mqtt:

Besides the filters and functions that Jinja provides out of the box, additional extensions are available.

All filters from jinja2-ansible-filters are included as well as the following global functions, variables and filters:

Name	Type	Description
`dbus2mqtt.version`	string	The current version of the `dbus2mqtt` package.
`now`	function	Returns the current date and time as a `datetime` object.
`urldecode`	function	Decodes a URL-encoded string.
`dbus_list`	function	Returns a list of active subscribed bus_names, documentation below
`dbus_call`	function	D-Bus method invocation, documentation below

now()

Returns new datetime object representing current time.

Parameters:

Name	Type	Description	Default
`tz`	`optional`	If no tz is specified, uses local timezone.	`None`

Returns:

Type	Description
`datetime`	Current datetime object.

urldecode()

Decode a url-encoded URL string by replacing %xx escapes with their single-character equivalent.

Parameters:

Name	Type	Description	Default
`string`	`str`	The string to decode.	required

Returns:

Type	Description
`str`	A decoded URL string.

Example

>>> urldecode('abc%20def')
'abc def'
>>> urldecode('El%20Ni%C3%B1o')
'El Niño'

dbus_list()

This function is used to access active bus_names which dbus2mqtt is subscribed to.

Parameters:

Name	Type	Description	Default
`bus_name_pattern`	`str`	Glob pattern to filter on, e.g. '' or 'org.mpris.MediaPlayer2.'	required

Returns:

Type	Description
`list[str]`	List of matching bus names found in current subscriptions

Example

Template

all_subscibed_bus_names: "{{ dbus_list('*') }}"
subscribed_mpris_bus_names: "{{ dbus_list('org.mpris.MediaPlayer2.*') }}"

Result

all_subscibed_bus_names: ['org.bluez', 'org.mpris.MediaPlayer2.firefox']
subscribed_mpris_bus_names: ['org.mpris.MediaPlayer2.firefox']

dbus_call()

Call a method on a active dbus object that dbus2mqtt is subscribed to.

This function looks up an active subscribed dbus object for the given bus name and object path and invokes the specified method on the given interface with the provided positional arguments.

Parameters:

Name	Type	Description	Default
`bus_name`	`str`	The unique bus name (e.g. "org.mpris.MediaPlayer2.firefox") on which the subscribed object exists.	required
`path`	`str`	The object path (e.g. "/org/mpris/MediaPlayer2") for the subscribed dbus object.	required
`interface`	`str`	The interface name (e.g. "org.freedesktop.DBus.Properties") on which to call the method.	required
`method`	`str`	The name of the method to call on the interface.	required
`method_args`	`list[Any]`	Positional arguments to pass to the D-Bus method. Must be a list.	`[]`

Returns:

Type	Description
`object`	The result returned by the underlying D-Bus method call,

Example

Template

player_properties: |
  {{ dbus_call(mpris_bus_name, mpris_path, 'org.freedesktop.DBus.Properties', 'GetAll', ['org.mpris.MediaPlayer2.Player']) }}

Result

player_properties:
    Metadata: {}
    Position: 0
    PlaybackStatus: Stopped
    Volume: 0.0

Notes

The function assumes the dbus object has been previously subscribed to. It will not create subscriptions.
dbus_call can invoke any dbus method on any interface. It's a powerful function that is meant for retrieving state and property values. Although it can be used call methods that change state, it's a bad practice todo so from a template rendering perspective.