Add information about events in README.md

Add information about events in README.md :
- Add information about existing 'internal' hal events.
- Add information about events to provide for an 'external' hal.

BUG-AGL: SPEC-2683

Change-Id: I46e43fab026f850fd67852a19442ef6987872b61
Signed-off-by: Jonathan Aillet <jonathan.aillet@iot.bzh>

1 files changed, 213 insertions, 6 deletions

diff --git a/README.md b/README.md
index c6a2c9d..83b25c5 100644
--- a/README.md
+++ b/README.md
@@ -611,6 +611,113 @@ N.B. :
 * Values are normalized to a 0-100 range.
 * The number of values in the reponse depends on the number of values of the ALSA control.
 
+#### Subscribe / Unsubscribe to 'internal' hal events
+
+It is possible to register to hal events in order to be notified when an action is performed.\
+Muliple events are provided by an 'internal' hal, such as events when a stream volume is set
+or events when a halmap alsa control is set.
+
+In order to subscribe / unsubscribe to events, you need to call `subscribe` / `unsubscribe` verbs on the hal
+with a json to specify which event(s) you want to subscribe to.\
+Here is the json format :
+
+```json
+{
+  "events " : "$STREAM_TO_SUBSCRIBE"
+}
+```
+
+You can also subscribe / unsubscribe to multiple events in one call using this json format :
+
+```json
+{
+  "events " : [
+    "$STREAM1_TO_SUBSCRIBE",
+    "$STREAM2_TO_SUBSCRIBE",
+    "$CONTROL1_TO_SUBSCRIBE",
+    "$CONTROL2_TO_SUBSCRIBE"
+  ]
+}
+```
+
+Subscribe example :
+
+```json
+4a-hal-csl-cm106-8ch-usb subscribe { "events" : [ "multimedia", "agl-master-playback-volume" ] }
+
+ON-REPLY 1:4a-hal-csl-cm106-8ch-usb/subscribe: OK
+{
+  "response":2,
+  "jtype":"afb-reply",
+  "request":{
+    "status":"success",
+    "info":"Subscription succeed for all the 2 events requested"
+  }
+}
+```
+
+Received events examples :
+
+```json
+ON-EVENT 4a-hal-csl-cm106-8ch-usb/multimedia:
+{
+  "event":"4a-hal-csl-cm106-8ch-usb/multimedia",
+  "data":{
+    "volnew":70,
+    "volold":60
+  },
+  "jtype":"afb-event"
+}
+```
+
+```json
+ON-EVENT 4a-hal-csl-cm106-8ch-usb/agl-master-playback-volume:
+{
+  "event":"4a-hal-csl-cm106-8ch-usb/agl-master-playback-volume",
+  "data":[
+    90,
+    90,
+    90,
+    90,
+    90,
+    90,
+    90,
+    90
+  ],
+  "jtype":"afb-event"
+}
+```
+
+Unsubscribe example :
+
+```json
+4a-hal-csl-cm106-8ch-usb unsubscribe { "events" : [ "multimedia", "agl-master-playback-volume" ] }
+
+ON-REPLY 4:4a-hal-csl-cm106-8ch-usb/unsubscribe: OK
+{
+  "response":2,
+  "jtype":"afb-reply",
+  "request":{
+    "status":"success",
+    "info":"Unsubscription succeed for all the 2 events requested"
+  }
+}
+```
+
+### Provided 'internal' hal events
+
+Here is the list of events provided by an internal hal :
+
+* Each stream listed by `info` verb provides an event.
+  * Looking at 'Get hal information' section, we can see that 'multimedia', 'navigation',
+  'emergency', 'legacy', 'radio_stream' stream events are provided.
+  * These events are generated when an event volume set is done using hals.
+* Each halmap listed by `info` verb provides an event.
+  * Looking at 'Get hal information' section, we can see that 'agl-master-capture-volume',
+  'agl-master-playback-volume', 'hal-ping' halmap events are provided.
+  * These events are generated when an halmap value set is done from anywhere (using alsa control commands, hals, etc.).
+* A 'stream-updates' event to be notified when a stream is added/removed (e.g. for bluetooth streams) to/from the hal.
+
 ### Load an 'external' hal
 
 #### Register your external hal
@@ -630,12 +737,34 @@ Within this call you must provide a json description of your api, corresponding
 }
 ```
 
-#### Provide an event to share you hal status
+#### Verbs to provide and json response formats recognized by `4a-hal-manager`
 
-Your hal must also have a `subscribe` verb available and event named `status`.
+##### `subscribe`/`unsubscribe` verb (mandatory)
 
-At external hal loading, the `4a-hal-manager` will subscribe to this event.\
-Within your hal, you must generate an event each time the status of your hal changes.
+Verbs used to subscribe to your 'external' hal events
+
+Input Json formats :
+
+```json
+{
+  "events " : "$EVENT_TO_SUBSCRIBE"
+}
+```
+
+```json
+{
+  "events " : [
+    "$EVENT1_TO_SUBSCRIBE",
+    "$EVENT2_TO_SUBSCRIBE"
+  ]
+}
+```
+
+##### `get-status` verb (mandatory)
+
+Verb to get your 'external' hal status.
+
+At external hal loading, the `4a-hal-manager` will call this verb to get you hal current status.
 
 Here are the possible status (integer value) :
 
@@ -643,9 +772,52 @@ Here are the possible status (integer value) :
 * Available = 1
 * Ready = 2
 
+Response format :
+
+```json
+{
+  "response":2,
+  "jtype":"afb-reply",
+  "request":{
+    "status":"success"
+  }
+}
+```
+
+#### Events to provide and json formats recognized by `4a-hal-manager`
+
+##### Provide a `status` event to share you hal status
+
+Using you hal `subscribe` verb, `4a-hal-manager` will subscribe to a `status` event
+to be notified each time you hal status changes.\
+Within your hal, you must generate an event each time the status of your hal changes.
+
+See '`get-status` verb (mandatory)' section for more information about 'external' hal `status` event.
+
 #### Verbs to provide and json response formats recognized by `4a-hl-api`
 
-Be aware that only `info`/`streams` verbs are mandatory, `controls` can also be implemented but they are optional.
+Be aware that only `subscribe`/`unsubscribe`/`info`/`streams` verbs are mandatory, `controls` verbs can also be implemented but they are optional.
+
+##### `subscribe`/`unsubscribe` verb (mandatory)
+
+Verbs used to subscribe to your 'external' hal events
+
+Input Json formats :
+
+```json
+{
+  "events " : "$EVENT_TO_SUBSCRIBE"
+}
+```
+
+```json
+{
+  "events " : [
+    "$EVENT1_TO_SUBSCRIBE",
+    "$EVENT2_TO_SUBSCRIBE"
+  ]
+}
+```
 
 ##### `info` verb (mandatory)
 
@@ -801,6 +973,42 @@ Response format :
 },
 ```
 
+N.B. : The number of values sent back by verb depends on the number of ALSA control values.
+
+#### Events to provide and json response formats recognized by `4a-hl-api`
+
+##### `streams` events (mandatory)
+
+E.g. in some standard hals, available streams events can be `multimedia`, `navigation`, or `emergency`.
+
+Event data format :
+
+```json
+"data": {
+  "volnew":70,
+  "volold":60
+}
+```
+
+##### `controls` events (optional)
+
+Event data format :
+
+```json
+"data":[
+  90,
+  90,
+  90,
+  90,
+  90,
+  90,
+  90,
+  90
+],
+```
+
+N.B. : The number of values sent back by event depends on the number of ALSA control values.
+
 ### Known issues
 
 #### Fail to find json configuration files
@@ -825,4 +1033,3 @@ export CONTROL_CONFIG_PATH=/home/root/4a/smixer/etc:/home/root/4a/4a-hal/etc
 * Handling external hal status events.
 * Generation of a '4a-hal-manager' events when a hal status changes.
 * Dynamic handling of USB devices.
-* Documentation about hal events (subscribe/unsubscribe to events, available events, response formats ofr `4a-hl-api`).