dbus

dbus#

Description#

Plugin to interact with DBus.

This plugin can be used for the following tasks:

  • It can expose a D-Bus interface that other applications can use to push messages to Platypush (either action requests or events) serialized in JSON format. You can disable this listener by setting service_name to null in your configuration. If the D-Bus Platypush interface is enabled then you can push Platypush events and requests in JSON format from another application or script by specifying:

    • The D-Bus service (default: org.platypush.Bus)

    • The D-Bus interface (default: org.platypush.Bus)

    • The D-Bus path (default: /)

    • The D-Bus method (Post)

    • The Platypush JSON payload (first argument of the request). Format: {"type": "request", "action": "module.action", "args": {...}}

  • It can subscribe to multiple D-Bus signals, and it triggers a DbusSignalEvent when an event is received (signal filters should be specified in the signals configuration).

  • It can be used to query and inspect D-Bus objects through the query() method.

  • It can be used to execute methods exponsed by D-Bus objects through the execute() method.

    [{
  # Possible values: ['system', 'session']
  "bus": ...,
  # The DBus interface that should be monitored (default: all)
  "interface": ...,
  # Path of the resource to be monitored (default: all)
  "path": ...,
  # Signal name filter (default: all signals)
  "signal": ...,
  # Signal sender filter (default: all senders)
  "sender": ...
}]

For example, to subscribe to all the messages on the session bus:

dbus:
    signals:
        - bus: session

Configuration#

dbus:
  # [Optional]
  # Specify this if you want to subscribe to specific DBus
  # signals. Structure:
  # signals:   # type=Optional[Iterable[dict]]

  # [Optional]
  # Name of the D-Bus service where Platypush will listen
  # for new messages (requests and events). Set to null if you want to disable
  # message execution over D-Bus for Platypush (default: ``org.platypush.Bus``).
  # service_name: org.platypush.Bus  # type=Optional[str]

  # [Optional]
  # The path of the D-Bus message listener. Set to null
  # if you want to disable message execution over D-Bus for Platypush
  # (default: ``/``).
  # service_path: /  # type=Optional[str]

  # [Optional]
  # How often the `RunnablePlugin.loop <https://docs.platypush.tech/platypush/plugins/.html#platypush.plugins.RunnablePlugin.loop>`_ function should be
  # executed (default: 15 seconds). *NOTE*: For back-compatibility
  # reasons, the `poll_seconds` argument is also supported, but it's
  # deprecated.
  # poll_interval: 15  # type=Optional[float]

  # [Optional]
  # How long we should wait for any running
  # threads/processes to stop before exiting (default: 5 seconds).
  # stop_timeout: 5  # type=Optional[float]

  # [Optional]
  # If set to True then the plugin will not monitor
  # for new events. This is useful if you want to run a plugin in
  # stateless mode and only leverage its actions, without triggering any
  # events. Defaults to False.
  # disable_monitor: False  # type=bool

Dependencies#

pip

pip install pydbus defusedxml

Alpine

apk add py3-pydbus py3-defusedxml

Debian

apt install python3-defusedxml python3-pydbus

Fedora

yum install python-defusedxml python-pydbus

Arch Linux

pacman -S python-defusedxml python-pydbus

Triggered events#

Actions#

Module reference#

class platypush.plugins.dbus.DbusPlugin(signals: Iterable[dict] | None = None, service_name: str | None = 'org.platypush.Bus', service_path: str | None = '/', **kwargs)[source]#

Bases: RunnablePlugin

Plugin to interact with DBus.

This plugin can be used for the following tasks:

  • It can expose a D-Bus interface that other applications can use to push messages to Platypush (either action requests or events) serialized in JSON format. You can disable this listener by setting service_name to null in your configuration. If the D-Bus Platypush interface is enabled then you can push Platypush events and requests in JSON format from another application or script by specifying:

    • The D-Bus service (default: org.platypush.Bus)

    • The D-Bus interface (default: org.platypush.Bus)

    • The D-Bus path (default: /)

    • The D-Bus method (Post)

    • The Platypush JSON payload (first argument of the request). Format: {"type": "request", "action": "module.action", "args": {...}}

  • It can subscribe to multiple D-Bus signals, and it triggers a DbusSignalEvent when an event is received (signal filters should be specified in the signals configuration).

  • It can be used to query and inspect D-Bus objects through the query() method.

  • It can be used to execute methods exponsed by D-Bus objects through the execute() method.

__init__(signals: Iterable[dict] | None = None, service_name: str | None = 'org.platypush.Bus', service_path: str | None = '/', **kwargs)[source]#
Parameters:

  • signals –

    Specify this if you want to subscribe to specific DBus signals. Structure:

    [
  {
    "bus": "string",
    "interface": "The DBus interface that should be monitored (default: all)",
    "path": "Path of the resource to be monitored (default: all)",
    "sender": "Signal sender filter (default: all senders)",
    "signal": "Signal name filter (default: all signals)"
  }
]

    For example, to subscribe to all the messages on the session bus:

    dbus:
    signals:
        - bus: session

  • service_name – Name of the D-Bus service where Platypush will listen for new messages (requests and events). Set to null if you want to disable message execution over D-Bus for Platypush (default: org.platypush.Bus).

  • service_path – The path of the D-Bus message listener. Set to null if you want to disable message execution over D-Bus for Platypush (default: /).

execute(service: str, interface: str, method_name: str, bus: str = 'session', path: str = '/', args: list | None = None)[source]#

Execute a method exposed on DBus.

Parameters:

  • service – D-Bus service name.

  • interface – D-Bus nterface name.

  • method_name – Method name.

  • bus – Bus type. Supported: system and session (default: session).

  • path – Object path.

  • args – Arguments to be passed to the method, depending on the method signature.

Returns:

Return value of the executed method.

query(service: str | None = None, bus=('system', 'session')) → Dict[str, dict][source]#

Query DBus for a specific service or for the full list of services.

Parameters:

  • service – Service name (default: None, query all services).

  • bus – Which bus(ses) should be queried (default: both system and session).

Returns:

A {service_name -> {properties}} mapping. Example:

"session": {
  "org.platypush.Bus": {
    "/": {
      "org.freedesktop.DBus.Properties": {
        "method": [
          {
            "name": "Get",
            "args": [
              {
                "type": "s",
                "name": "interface_name",
                "direction": "in"
              },
              {
                "type": "s",
                "name": "property_name",
                "direction": "in"
              },
              {
                "type": "v",
                "name": "value",
                "direction": "out"
              }
            ]
          },
          {
            "name": "GetAll",
            "args": [
              {
                "type": "s",
                "name": "interface_name",
                "direction": "in"
              },
              {
                "type": "a{sv}",
                "name": "properties",
                "direction": "out"
              }
            ]
          },
          {
            "name": "Set",
            "args": [
              {
                "type": "s",
                "name": "interface_name",
                "direction": "in"
              },
              {
                "type": "s",
                "name": "property_name",
                "direction": "in"
              },
              {
                "type": "v",
                "name": "value",
                "direction": "in"
              }
            ]
          }
        ],
        "signal": [
          {
            "name": "PropertiesChanged",
            "args": [
              {
                "type": "s",
                "name": "interface_name"
              },
              {
                "type": "a{sv}",
                "name": "changed_properties"
              },
              {
                "type": "as",
                "name": "invalidated_properties"
              }
            ]
          }
        ]
      },
      "org.freedesktop.DBus.Introspectable": {
        "method": [
          {
            "name": "Introspect",
            "args": [
              {
                "type": "s",
                "name": "xml_data",
                "direction": "out"
              }
            ]
          }
        ]
      },
      "org.freedesktop.DBus.Peer": {
        "method": [
          {
            "name": "Ping"
          },
          {
            "name": "GetMachineId",
            "args": [
              {
                "type": "s",
                "name": "machine_uuid",
                "direction": "out"
              }
            ]
          }
        ]
      },
      "org.platypush.Bus": {
        "method": [
          {
            "name": "Post",
            "args": [
              {
                "type": "s",
                "name": "msg",
                "direction": "in"
              },
              {
                "type": "s",
                "name": "response",
                "direction": "out"
              }
            ]
          }
        ]
      }
    }
  }
}

Platypush documentation