1Haptic/visual/audio feedback for GNOME 2====================================== 3[](https://source.puri.sm/guido.gunther/feedbackd/commits/master) 4 5feedbackd provides a DBus daemon (feedbackd) to act on events to provide 6haptic, visual and audio feedback. It offers a library (libfeedback) and 7GObject introspection bindings to ease using it from applications. 8 9## License 10 11feedbackd is licensed under the GPLv3+ while the libfeedback library is 12licensed under LGPL 2.1+. 13 14## Getting the source 15 16```sh 17git clone https://source.puri.sm/Librem5/feedbackd 18cd feedbackd 19``` 20 21The master branch has the current development version. 22 23## Dependencies 24On a Debian based system run 25 26```sh 27sudo apt-get -y install build-essential 28sudo apt-get -y build-dep . 29``` 30 31For an explicit list of dependencies check the `Build-Depends` entry in the 32[debian/control][] file. 33 34## Building 35 36We use the meson (and thereby Ninja) build system for feedbackd. The quickest 37way to get going is to do the following: 38 39 meson . _build 40 ninja -C _build 41 ninja -C _build test 42 ninja -C _build install 43 44## Running 45### Running from the source tree 46To run the daemon use 47 48```sh 49_build/run 50``` 51You can introspect and get the current theme with 52 53```sh 54gdbus introspect --session --dest org.sigxcpu.Feedback --object-path /org/sigxcpu/Feedback 55``` 56 57To run feedback for an event, use [fbcli](#fbcli) 58 59See `examples/` for a simple python example using GObject introspection. 60 61# How it works 62 63We're using a [event naming spec](./Event-naming-spec-0.0.0.md) 64similar to http://0pointer.de/public/sound-naming-spec.html to name 65events. This will allow us to act as a system sound library so 66applications only need to call into this library and things like 67the quiet and silent profile work out of the box. 68 69## Feedback theme 70Events are then mapped to a specific type of feedback (sound, led, vibra) via a 71device specific theme (since devices have different capabilities). 72 73Feedbackd is shipped with a default theme `default.json`. 74You can add your own themes in one of two ways: 75 761. By exporting an environment variable `FEEDBACK_THEME` with a path to a 77 valid theme file (not recommended, use for testing only), or 782. By creating a theme file under `$XDG_CONFIG_HOME/feedbackd/themes/default.json`. 79 If `XDG_CONFIG_HOME` environment variable is not set or empty, it will 80 default to `$HOME/.config`, or 813. By adding your theme file to one of the folders in the `XDG_DATA_DIRS` 82 environment variable, appended with `feedbackd/themes/`. This folder isn't 83 created automatically, so you have to create it yourself. Here's an example: 84 ```bash 85 # Check which folders are "valid" 86 $ echo $XDG_DATA_DIRS 87 [ ... ]:/usr/local/share:/usr/share 88 89 # Pick a folder that suits you. Note that you shouldn't place themes in 90 # /usr/share, because they would be overwritten by updates! 91 # Create missing directories 92 $ sudo mkdir -p /usr/local/share/feedbackd/themes 93 94 # Add your theme file! 95 $ sudo cp my_awesome_theme.json /usr/local/share/feedbackd/themes/ 96 ``` 97 98Upon reception of `SIGHUP` signal, the daemon process will proceed to retrigger 99the above logic to find the themes, and reload the corresponding one. This can 100be used to avoid having to restart the daemon in case of configuration changes. 101 102Check out the companion [feedbackd-device-themes][1] repository for a 103selection of device-specific themes. In order for your theme to be recognized 104it must be named properly. Currently, theme names are based on the `compatible` 105device-tree attribute. You can run the following command to get a list of valid 106filenames for your custom theme (**Note**: You must run this command on the 107device you want to create the theme for!): 108 109```bash 110$ cat /sys/firmware/devicetree/base/compatible | tr '\0' "\n" 111``` 112 113Example output (for a Pine64 PinePhone): 114 115```bash 116$ cat /sys/firmware/devicetree/base/compatible | tr '\0' "\n" 117pine64,pinephone-1.2 118pine64,pinephone 119allwinner,sun50i-a64 120``` 121 122Thus you could create a custom feedbackd theme for the Pinephone by placing a 123modified theme file in 124`/usr/local/share/feedbackd/themes/pine64,pinephone.json` 125 126If multiple theme files exist, the selection logic follows these steps: 127 1281. It picks an identifier from the devicetree, until none are left 1292. It searches through the folders in `XDG_DATA_DIRS` in order of appearence, 130 until none are left 1313. If a theme file is found in the current location with the current name, 132 **it will be chosen** and other themes are ignored. 133 134If no theme file can be found this way (i.e. there are no identifiers and 135folders left to check), `default.json` is chosen instead. Given the above 136examples: 137 138- `/usr/local/share/feedbackd/themes/pine64,pinephone-1.2.json` takes 139 precedence over `/usr/local/share/feedbackd/themes/pine64-pinephone.json` 140- `/usr/local/share/feedbackd/themes/pine64-pinephone.json` takes precedence 141 over `/usr/share/feedbackd/themes/pine64-pinephone-1.2.json` 142- etc... 143 144The currently available feedback types are: 145 146- Sound (an audible sound from the sound naming spec) 147- VibraRumble: haptic motor rumbling 148- VibraPeriodic: periodic feedback from the haptic motor 149- Led: Feedback via blinking LEDs 150 151You can check the feedback theme and the classes (prefixed with Fbd) 152for available properties. Note that the feedback theme API (including 153the theme file format) is not stable but considered internal to the 154daemon. 155 156## Profiles 157The profile determines which parts of the theme are in use: 158 159- `full`: Use configured events from the `full`, `quiet` and `silent` parts of 160 the feedback them. 161- `quiet`: Use `quiet` and `silent` part from of the feedback theme. This usually 162 means no audio feedback. 163- `silent`: Only use the `silent` part from the feedback theme. This usually means 164 to not use audio or vibra. 165 166It can be set via a GSetting 167 168```sh 169 gsettings set org.sigxcpu.feedbackd profile full 170``` 171## fbcli 172 173`fbcli` can be used to trigger feedback for different events. Here are some examples: 174 175### Phone call 176Run feedbacks for event `phone-incoming-call` until explicitly stopped: 177 178``` 179_build/cli/fbcli -t 0 -E phone-incoming-call 180``` 181 182### New instant message 183Run feedbacks for event `message-new-instant` just once: 184 185``` 186_build/cli/fbcli -t -1 -E message-new-instant 187``` 188 189### Alarm clock 190Run feedbacks for event `message-new-instant` for 10 seconds: 191 192``` 193_build/cli/fbcli -t 10 -E alarm-clock-elapsed 194``` 195 196## Per app profiles 197One can set the feedback profile of an individual application 198via `GSettings`. E.g. for an app with app id `sm.puri.Phosh` 199to set the profile to `quiet` do: 200 201``` 202GSETTINGS_SCHEMA_DIR=_build/data/ gsettings set org.sigxcpu.feedbackd.application:/org/sigxcpu/feedbackd/application/sm-puri-phosh/ profile quiet 203``` 204 205# Documentation 206 207- [Libfeedback API](https://honk.sigxcpu.org/projects/feedbackd/doc/) 208- [Event naming spec draft](./Event-naming-spec-0.0.0.md) 209- [Feedback-theme-spec draft](./Feedback-theme-spec-0.0.0.md) 210 211[debian/control]: ./debian/control#L5 212[1]: https://source.puri.sm/Librem5/feedbackd-device-themes) 213
){kind=link}