Theme based Haptic, Visual and Audio Feedback

feedbackd provides a DBus daemon (feedbackd) to act on events to provide haptic, visual and audio feedback. It offers a library (libfeedback) and GObject introspection bindings to ease using it from applications.

License

feedbackd is licensed under the GPLv3+ while the libfeedback library is licensed under LGPL 2.1+.

Getting the source

git clone https://gitlab.freedesktop.org/agx/feedbackd
cd feedbackd

The main branch has the current development version.

Dependencies

On a Debian based system run

sudo apt-get -y install build-essential
sudo apt-get -y build-dep .

to install the needed build dependencies.

For an explicit list of dependencies check the Build-Depends entry in the debian/control file.

Building

We use the meson (and thereby Ninja) build system for feedbackd. The quickest way to get going is to do the following:

meson setup _build
meson compile -C _build
meson test -C _build

Installing

To install the files to /usr/local you can use

meson install -C _build

however for testing and development this is usually not necessary as you can things out of the built source tree.

Running

Running from the source tree

To run the daemon use

_build/run _build/src/feedbackd

To run under gdb use

FBD_GDB=1 _build/run _build/src/feedbackd

You can introspect and get the current profile with

gdbus introspect --session --dest org.sigxcpu.Feedback --object-path /org/sigxcpu/Feedback

To run feedback for an event, use fbcli

See examples/ for a simple python example using GObject introspection.

How it works

Whenever an event is submitted to the daemon by a client via the DBus API feedbackd looks up the corresponding feedbacks according to the current profile in the currently active feedback theme (taking per application profile settings into account).

Any feedback triggered by a client via an event will be stopped latest when the client disconnects from DBus. This makes sure all feedbacks get canceled if the app that triggered them crashes.

Feedback theme

As devices have varying capabilities and users different needs, events are mapped to feedbacks (sound, LED, vibra) via a configurable theme.

There are two types of themes: custom themes and device themes. They both use the same format but have different purpose. Custom themes are meant to tweak feedbackd's output to the users needs while device themes are meant to cater for hardware differences.

Custom themes

Feedbackd is shipped with a default theme default.json. You can replace this by your own, custom theme in multiple ways:

1. By exporting an environment variable FEEDBACK_THEME with a path to a valid theme file. This is not recommended, use it for testing only.

2. By creating a theme file under $XDG_CONFIG_HOME/feedbackd/themes/default.json. If XDG_CONFIG_HOME environment variable is not set or empty, it will default to $HOME/.config

3. By creating a theme file under $XDG_CONFIG_HOME/feedbackd/themes/custom.json and telling feedbackd to use that theme. In this custom theme you only specify the events you want to change. Also add a parent-name entry to chain up to the default theme:

   {
      "name: "custom"
      "parent-name": "default"
      "profiles" : [
       ...(events you want to change go here)...
      ]
   }
   

   This has the upside that your theme stays minimal and that new entries added to the default theme will automatically be used by your theme too. See here for an example.

   Once you have the file in place, tell feedbackd to use this theme instead of the default one:

   gsettings set org.sigxcpu.feedbackd theme custom
   

   When you want to go back to the default theme just do:

   gsettings reset org.sigxcpu.feedbackd theme
   

   Note that you can name your theme as you wish but avoid theme names starting with __ or $ as this namespace is reserved.

   This is the preferred way to specify a custom theme.

For available feedback types see the feedback-themes(5) manpage.

Upon reception of SIGHUP signal, the daemon process will proceed to retrigger the above logic to find the themes, and reload the corresponding one. This can be used to avoid having to restart the daemon in case of configuration changes.

Device themes

Feedbackd has support to pick up device specific themes automatically. This allows us to handle device differences like varying strength of haptic motors or different LED colors in an automatic way.

Which theme is selected for a device is determined by the device's device tree compatible as supplied by the kernel. To see the list of compatibles of a device use:

cat /sys/firmware/devicetree/base/compatible | tr '\0' "\n"

Check out the companion feedbackd-device-themes repository for the current list of device-specific themes we ship by default.

Device specific themes have the same format as custom themes. They also use the parent-name property to chain up to the default theme and only override the events that need adjustment. However the rules for finding the device theme in the file system differ.

If multiple device theme files exist, the selection logic follows these steps:

1. It picks an identifier from the devicetree, until none are left
2. It searches through the folders in XDG_DATA_DIRS in order of appearance, until none are left
3. If a theme file is found in the current location with the current name, it will be chosen and other themes are ignored.

Example for a Pine64 PinePhone:

$ cat /sys/firmware/devicetree/base/compatible | tr '\0' "\n"
pine64,pinephone-1.2
pine64,pinephone
allwinner,sun50i-a64

$ echo $XDG_DATA_DIRS
/usr/local/share/:/usr/share/

The selection logic would follow these steps:

• /usr/local/share/feedbackd/themes/pine64,pinephone-1.2.json takes precedence over /usr/local/share/feedbackd/themes/pine64-pinephone.json
• /usr/local/share/feedbackd/themes/pine64-pinephone.json takes precedence over /usr/share/feedbackd/themes/pine64-pinephone-1.2.json
• etc...

if you create or adjust a device theme and consider the changes generally useful, please submit them as merge request in the feedbackd-device-themes repository.

Stability guarantees

Note that the feedback theme API, including the theme file format, is not stable but considered internal to the daemon.

Profiles

The profile determines which parts of the theme are in use:

• full: Use configured events from the full, quiet and silent parts of the feedback them.
• quiet: Use quiet and silent part from of the feedback theme. This usually means no audio feedback.
• silent: Only use the silent part from the feedback theme. This usually means to not use audio or vibra.

It can be set via a GSetting

  gsettings set org.sigxcpu.feedbackd profile full

fbcli

fbcli can be used to trigger feedback for different events. Here are some examples:

Phone call

Run feedbacks for event phone-incoming-call until explicitly stopped:

_build/cli/fbcli -t 0 -E phone-incoming-call

New instant message

Run feedbacks for event message-new-instant just once:

_build/cli/fbcli -t -1 -E message-new-instant

Alarm clock

Run feedbacks for event message-new-instant for 10 seconds:

_build/cli/fbcli -t 10 -E alarm-clock-elapsed

Examples

Here's some examples that show how to use libfeedback in your application:

C

The command line tool fbcli can be used as example on how to use libfeedback from C.

Python

There's an example.py script demonstrating how to use the introspection bindings and how to trigger feedback via an event.

Rust

The libfeedback-rs Rust bindings ship an example to demo the usage.

Per app profiles

One can set the feedback profile of an individual application via GSettings. E.g. for an app with app id sm.puri.Phosh to set the profile to quiet do:

# If you don't have feedbackd installed, run this from the built source tree:
export GSETTINGS_SCHEMA_DIR=_build/data/
gsettings set org.sigxcpu.feedbackd.application:/org/sigxcpu/feedbackd/application/sm-puri-phosh/ profile quiet

Haptic API

In order to give applications like browsers and games more control over the haptic motor Feebackd implements an interface that allows to set vibra patterns. The vibration pattern is given as a sequence of rumble magnitude and duration pairs like:

busctl call --user org.sigxcpu.Feedback /org/sigxcpu/Feedback org.sigxcpu.Feedback.Haptic Vibrate 'sa(du)' org.foo.app 3 1.0 200  0.0 50  0.5 300

Vibration can be ended by submitting an empty array:

busctl call --user org.sigxcpu.Feedback /org/sigxcpu/Feedback org.sigxcpu.Feedback.Haptic Vibrate 'sa(du)' org.foo.app 0

The API is exported as a separate interface org.sigxcpu.Feedback.Haptic which is only available when a haptic device is found.

Getting in Touch

• Issue tracker: https://gitlab.freedesktop.org/agx/feedbackd/-/issues
• Matrix: https://matrix.to/#/#phosh:phosh.mobi

Code of Conduct

Note that as a project hosted on freedesktop.org, feedbackd follows its Code of Conduct, based on the Contributor Covenant. Please conduct yourself in a respectful and civilized manner when communicating with community members on IRC and bug tracker.

Documentation

• Libfeedback API
• Event naming spec draft
• Feedback-theme-spec draft
• W3's vibration API draft