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.
It provides a reference implementation for the Feedback theme specification and Event naming specification.
feedbackd is licensed under the GPLv3+ while the libfeedback library is licensed under LGPL 2.1+.
git clone https://gitlab.freedesktop.org/feedbackd/feedbackd.git
cd feedbackdThe main branch has the current development version.
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.
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 _buildTo 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.
To run the daemon use
_build/run _build/src/feedbackdTo run under gdb use
FBD_GDB=1 _build/run _build/src/feedbackdYou can introspect and get the current maximum profile with
gdbus introspect --session --dest org.sigxcpu.Feedback --object-path /org/sigxcpu/FeedbackTo run feedback for an event, use fbcli
See examples/ for a simple python example using GObject introspection.
Whenever an event is submitted to the daemon by a client via the DBus API feedbackd looks up the corresponding feedbacks in the profiles of the currently active feedback theme. Which feedbacks are actually triggered depends on the daemon's current feedback level, per application settings and hints provided by the client with the event. A feedback can be a sound played, a vibra rumble or a LED blinking with a given pattern.
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.
Each theme consists of up to three profile sections named full,
quiet and silent containing event names and their associated
feedback. feedbackd's currently selected profile determines which
profiles of the current theme are being used for event lookup:
full: Use events from thefull,quietandsilentprofiles of the current feedback theme.quiet: Use events from thequietandsilentprofiles of the current feedback theme. This usually means haptic and LED but no sound feedback.silent: Only use thesilentprofile from the current feedback theme. This usually means LED but no sound or vibra feedback.
The daemon's current profile can be changed via a GSetting:
gsettings set org.sigxcpu.feedbackd profile fullAs the daemon's current profile value sets an upper limit of the used profiles of a theme it is called the feedback level. See the Theme spec for further details.
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.
feedbackd is shipped with a default theme default.json. You can
replace this by your own, custom theme in multiple ways:
-
By exporting an environment variable
FEEDBACK_THEMEwith a path to a valid theme file. This is not recommended, use it for testing only. -
By creating a theme file under
$XDG_CONFIG_HOME/feedbackd/themes/default.json. IfXDG_CONFIG_HOMEenvironment variable is not set or empty, it will default to$HOME/.config -
By creating a theme file under
$XDG_CONFIG_HOME/feedbackd/themes/custom.jsonand telling feedbackd to use that theme. In this custom theme you only specify the events you want to change. Also add aparent-nameentry 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 customWhen 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. See examples/strict.json for a minimal example that you can copy to
~/.config/feedbackd/themes/and enable viagsettings set org.sigxcpu.feedbackd theme strict
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.
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 and device
themes always have the name property set to $device. The simplest
device theme, doing nothing looks like:
{
"name" : "$device",
"parent-name": "default"
}If multiple device theme files exist, the selection logic follows these steps:
- It picks an identifier from the devicetree, until none are left
- It searches through the folders in
XDG_DATA_DIRSin order of appearance, until none are left - 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 above selection logic would look at these concrete locations:
/usr/local/share/feedbackd/themes/pine64,pinephone-1.2.jsontakes precedence over/usr/local/share/feedbackd/themes/pine64-pinephone.json/usr/local/share/feedbackd/themes/pine64-pinephone.jsontakes 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.
Note that the feedback theme API, including the theme file format, is not stable but considered internal to the daemon.
fbcli is a command line tool that can be used to trigger feedback
for different events. Here are some examples:
Run feedbacks for event phone-incoming-call until explicitly stopped:
_build/cli/fbcli -t 0 -E phone-incoming-callRun feedbacks for event message-new-instant just once:
_build/cli/fbcli -t -1 -E message-new-instantRun feedbacks for event message-new-instant for 10 seconds:
_build/cli/fbcli -t 10 -E alarm-clock-elapsedHere's some examples that show how to use libfeedback in your application:
The command line tool fbcli can be used as example
on how to use libfeedback from C.
There's an example.py script demonstrating
how to use the introspection bindings and how to trigger feedback via
an event.
The libfeedback-rs Rust bindings ship an example to demo the usage.
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 quietIn order to give applications like browsers and games more control
over the haptic motor Feedbackd 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 0The API is exported as a separate interface org.sigxcpu.Feedback.Haptic which is only available when
a haptic device is found.
- Issue tracker: https://gitlab.freedesktop.org/feedbackd/feedbackd/-/issues
- Chat via Matrix: https://matrix.to/#/#phosh:phosh.mobi
Note that since feedbackd is 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.