diff options
| -rw-r--r-- | README.md | 219 |
1 files changed, 213 insertions, 6 deletions
@@ -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`). |