summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJonathan Aillet <jonathan.aillet@iot.bzh>2019-08-12 12:22:10 +0200
committerJonathan Aillet <jonathan.aillet@iot.bzh>2019-08-12 12:22:10 +0200
commit660e714874277031d74ee81c802e4a948cbd0981 (patch)
tree36fcc6ad9eb05ee04e8d8ad4d381d5a4505223d9
parent017bf16645a40887e26586011f6e8cff15f14e37 (diff)
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>
-rw-r--r--README.md219
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`).