Include specifications in the documentation
Now that we can use markdown easily add them as they provide help to the developer what events exist, etc.
This commit is contained in:
Guido Günther
@@ -0,0 +1,100 @@
|
||||
Title: Event Naming Specification
|
||||
Slug: Event Naming Specification
|
||||
|
||||
# Overview
|
||||
|
||||
This specification gives direction on how to name the Event types
|
||||
(triggering feedbacks such as running the haptic motor or blinking an
|
||||
LED) that are available for use by applications, when creating a
|
||||
feedback theme. It does so by laying out a standard naming scheme for
|
||||
Event creation, as well as providing a minimal list of must have
|
||||
Events, and a larger list with many more examples to help with the
|
||||
creation of extended Events for third party applications, with
|
||||
different event types and usage.
|
||||
|
||||
This is similar in spirit (and heavily based on) to the [Sound naming spec][].
|
||||
|
||||
# Context
|
||||
|
||||
The list of default contexts for the feedback theme are:
|
||||
|
||||
- Alerts: Events to alert the user of an action or event which may
|
||||
have a major impact on the system or their current use
|
||||
- Notifications: Events to trigger feedback to notify the user that
|
||||
the system, or their current use case has changed state in some way,
|
||||
e.g. new email arriving
|
||||
- Actions: Event that notify the user on their actions.
|
||||
- Input Event: This triggers feedbacks that give direct response to
|
||||
input events from the user, such as key presses on an on screen
|
||||
keyboard
|
||||
|
||||
# Event naming guides
|
||||
|
||||
Here we define some guidelines for when creating new Event names
|
||||
that extend the standardized list of Event names defined here, in
|
||||
order to provide Events for more specific events and usages.
|
||||
|
||||
Event names are in the en_US.US_ASCII locale. This means that the
|
||||
characters allowed in the Event names must fall within the US-ASCII
|
||||
character set. As a further restriction, all Event names may only
|
||||
contain lowercase letters, numbers, underscore, dash, or period
|
||||
characters. Spaces, colons, slashes, and backslashes are not
|
||||
allowed. Also, sound names must be spelled as they are in the en_US
|
||||
dictionary.
|
||||
|
||||
Events for branded applications should be named the same as the binary
|
||||
executable for the application, prefixed by the string “x-”, to avoid
|
||||
name space clashes with future standardized names. Example:
|
||||
“x-openoffice-foobar”.
|
||||
|
||||
## Standard Event names
|
||||
|
||||
This section describes the standard Event names that should be used
|
||||
by artists when creating themes, and by developers when writing
|
||||
applications which will use the Feedback Theme Specification.
|
||||
|
||||
### Alerts
|
||||
|
||||
- battery-low: The Event used when the battery is low (below 20%, for example).
|
||||
- power-unplug-battery-low: The power cable has been unplugged and the battery level is low.
|
||||
|
||||
### Notifications
|
||||
|
||||
- camera-focus: The event used when the camera got focus.
|
||||
- camera-shutter: The event used when a photo was taken.
|
||||
- message-new-instant: The event used when a new IM is received.
|
||||
- message-new-sms: The event used when a new sms is received.
|
||||
- message-new-email: The event used when a new email is received.
|
||||
- message-missed-email: The event used when an email was received but not seen by the user.
|
||||
- message-missed-instant: The event used when a instant message was received but not seen by the user.
|
||||
- message-missed-notification: The event used when a notification was shown but not seen by the user.
|
||||
- message-missed-sms: The event used when a sms message was received but not seen by the user.
|
||||
- phone-incoming-call: The event used when a phone/voip call is coming in.
|
||||
- phone-missed-call: The event used when a phone/voip call is was incoming but not answered.
|
||||
- phone-outgoing-busy: The event used when for outgoing phone/voip call when the responder is busy/not available.
|
||||
- phone-hangup: The event used when a phone/voip call is hung up.
|
||||
- phone-failure: The event used when a phone/voip call is terminated because of a failure.
|
||||
- battery-caution: The event used when the battery is nearing exhaustion (below 40%, for example).
|
||||
- battery-full: The event used when the battery is fully loaded up.
|
||||
- device-added: The event used when a device has become available to the desktop, i.e. due to USB plugging.
|
||||
- power-plug: The power cable has been plugged in.
|
||||
- power-unplug: The power cable has been unplugged.
|
||||
- alarm-clock-elapsed: A user configured alarm elapsed.
|
||||
- timeout-completed: A user configured timeout completed (e.g. a stop watch).
|
||||
|
||||
### Actions
|
||||
|
||||
- message-sent-instant: The sound used when a new IM is sent.
|
||||
- bell-terminal: The sound to use as a terminal bell.
|
||||
- theme-demo: A event that should be played for demoing this theme. Usually
|
||||
this should just be an alias for a very representative sound (such as
|
||||
a incoming phone call) of a theme that would work nicely as a demo event for
|
||||
a theme in the theme selector dialog.
|
||||
|
||||
### Input Event
|
||||
|
||||
- button-pressed: The event used when a button is pressed.
|
||||
- button-released: The event used when a button is released.
|
||||
- window-close: The sound used when an existing window is closed.
|
||||
|
||||
[Sound naming spec]: http://0pointer.de/public/sound-naming-spec.html
|
||||
@@ -0,0 +1,81 @@
|
||||
Title: Feedback Theme Specification
|
||||
Slug: Feedback Theme Specification
|
||||
|
||||
# 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 requests feedback for an event via the feedback daemon
|
||||
the daemon selects the provided feedback like this,
|
||||
capping the noisiness for each limit:
|
||||
|
||||
1. The currently selected profile provides the (global) upper limit for noisiness
|
||||
|
||||
2. Per application settings impose another upper limit
|
||||
|
||||
3. Per event noisiness is the last noisiness constraint
|
||||
|
||||
4. All feedback consistent with the resulting limit are selected
|
||||
and run to provide the 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-incoming-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](https://source.puri.sm/Librem5/feedbackd/-/blob/main/data/default.json)
|
||||
|
||||
|
||||
# Recommendations
|
||||
|
||||
- The silent theme should 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]: https://source.puri.sm/Librem5/feedbackd/-/blob/main/doc/Event-naming-spec-0.0.0.md
|
||||
+1
-1
@@ -52,7 +52,7 @@ print help and exit
|
||||
<para>
|
||||
Submit the given event to <command>feedbackd</command>. Valid events are
|
||||
listes in the event naming spec at
|
||||
<ulink url="https://source.puri.sm/Librem5/feedbackd/-/blob/main/Event-naming-spec-0.0.0.md"/>
|
||||
<ulink url="https://source.puri.sm/Librem5/feedbackd/-/blob/main/doc/Event-naming-spec-0.0.0.md"/>
|
||||
</para>
|
||||
</varlistentry>
|
||||
|
||||
|
||||
@@ -39,4 +39,6 @@ content_files = [
|
||||
"overview.md",
|
||||
"build-howto.md",
|
||||
"initialization.md",
|
||||
"Event-naming-spec-0.0.0.md",
|
||||
"Feedback-theme-spec-0.0.0.md",
|
||||
]
|
||||
|
||||
@@ -4,6 +4,8 @@ expand_content_md_files = [
|
||||
'overview.md',
|
||||
'build-howto.md',
|
||||
'initialization.md',
|
||||
'Event-naming-spec-0.0.0.md',
|
||||
'Feedback-theme-spec-0.0.0.md',
|
||||
]
|
||||
|
||||
toml_data = configuration_data()
|
||||
|
||||
Reference in New Issue
Block a user