Initial commit

Signed-off-by: Guido Günther <agx@sigxcpu.org>
2020-02-14 17:40:34 +01:00
commit 3663b7d149
83 changed files with 8059 additions and 0 deletions
@@ -0,0 +1,74 @@
+# Overview
+
+A feedback theme defines the kind of feedback that events (as
+described in the [Event naming spec][]) will trigger.
+
+The feedback daemon is responsible to select an appropriate feedback
+theme for a given device.
+
+# Definitions
+
+- Feedback: A feedback is something that notifies the user that
+  s.th. happened (e.g. a played sound, the vibration of a haptic
+  motor or led blinking).
+
+- Feedback theme: A feedback theme is a set of feedbacks grouped by
+  profiles. Each feedback is mapped to a single event.
+
+- Feedback Profile: A feedback profile groups feedbacks by
+  "noisiness". The currently defined profiles names are
+  *full*, *quiet* and *silent*. With *full* being the noisiest
+  profile.
+
+- Event: What the user should be notified about. The event
+  names are built according to the [Event naming spec][].
+
+# Implementation
+
+When an application triggers feedback for an event in the feedback
+daemon the daemon selects the provided feedback like this:
+
+1. feedbacks from a nosier profiles like the currently selected are
+   ignored
+
+2. All other feedbacks for this event are selected and run to provide
+   feedback to the user
+
+With the above a feedback theme in YAML format could look like:
+
+```yaml
+full:
+    - event-name: phone-incoming-call
+      type: Sound
+      effect: phone-incoing-call
+    - event-name: message-new-sms
+    ...
+quiet:
+    - event-name: phone-incoming-call
+      type: Vibra
+      duration: 0.5s
+    - event-name: message-new-sms
+    ...
+silent:
+    - event-name: phone-incoming-call
+      type: Led
+      location: Front
+      Color: Green
+      Interval: 0.2s
+    - event-name: message-new-sms
+    ...
+```
+
+At the time of writing the theme format is daemon dependent. E.g. feedbackd
+uses a format [similar to the above in JSON](./data/default.json).
+
+
+# Recommendations
+
+- The silent theme shoud not produce any audible feedback. This includes
+  the buzzing of haptic motors.
+- The quiet theme should not play any sounds. Haptic motors and LEDs can
+  be used.
+- The full feedback theme can use any available feedback mechanisms
+
+[Event naming spec]: ./Event-naming-spec-0.0.0.md