From 038e2f272a00c28168ae39c1ecb6b26a55542875 Mon Sep 17 00:00:00 2001 From: Loïc Collignon Date: Mon, 10 Sep 2018 10:36:46 +0200 Subject: Updated documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Added documentation up to date and using the gitbook format. Change-Id: Ie5d6a3bb489b9a9a95e21f5edd05bdd77bff5816 Signed-off-by: Loïc Collignon --- .gitignore | 1 + README.md | 138 ----------------- docs/4a-framework/README.md | 23 +++ docs/4a-framework/SUMMARY.md | 5 + docs/4a-framework/book.json | 10 ++ docs/4a-framework/components.md | 31 ++++ docs/4a-framework/concepts.md | 16 ++ docs/4a-framework/images/4a-architecture.svg | 155 +++++++++++++++++++ docs/4a-framework/images/apps-architecture.svg | 119 +++++++++++++++ docs/high-level-api/README.md | 66 ++++++++ docs/high-level-api/SUMMARY.md | 10 ++ docs/high-level-api/TipsAndTricks/4aTools.md | 168 +++++++++++++++++++++ docs/high-level-api/TipsAndTricks/AdjustVolumes.md | 9 ++ docs/high-level-api/TipsAndTricks/Devices.md | 29 ++++ docs/high-level-api/TipsAndTricks/HALs.md | 40 +++++ docs/high-level-api/TipsAndTricks/SUMMARY.md | 7 + .../TipsAndTricks/images/MixerBaseMenu.png | Bin 0 -> 170421 bytes .../TipsAndTricks/images/changeSound.png | Bin 0 -> 123509 bytes docs/high-level-api/book.json | 10 ++ docs/high-level-api/kickstart.md | 12 ++ docs/high-level-api/reference.md | 71 +++++++++ 21 files changed, 782 insertions(+), 138 deletions(-) delete mode 100644 README.md create mode 100644 docs/4a-framework/README.md create mode 100644 docs/4a-framework/SUMMARY.md create mode 100644 docs/4a-framework/book.json create mode 100644 docs/4a-framework/components.md create mode 100644 docs/4a-framework/concepts.md create mode 100644 docs/4a-framework/images/4a-architecture.svg create mode 100644 docs/4a-framework/images/apps-architecture.svg create mode 100644 docs/high-level-api/README.md create mode 100644 docs/high-level-api/SUMMARY.md create mode 100644 docs/high-level-api/TipsAndTricks/4aTools.md create mode 100644 docs/high-level-api/TipsAndTricks/AdjustVolumes.md create mode 100644 docs/high-level-api/TipsAndTricks/Devices.md create mode 100644 docs/high-level-api/TipsAndTricks/HALs.md create mode 100644 docs/high-level-api/TipsAndTricks/SUMMARY.md create mode 100644 docs/high-level-api/TipsAndTricks/images/MixerBaseMenu.png create mode 100644 docs/high-level-api/TipsAndTricks/images/changeSound.png create mode 100644 docs/high-level-api/book.json create mode 100644 docs/high-level-api/kickstart.md create mode 100644 docs/high-level-api/reference.md diff --git a/.gitignore b/.gitignore index 6f399d6..e20b1ae 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ build/ +build.*/ CMakeCache.txt Makefile *.so diff --git a/README.md b/README.md deleted file mode 100644 index a19c38c..0000000 --- a/README.md +++ /dev/null @@ -1,138 +0,0 @@ ------------------------------------------------------------------------- - AGL Audio High Level Binding ------------------------------------------------------------------------- - -# Audio High Level Binding ------------------------------ -The Audio High Level Binding is the upper layer in the Audio 4A architecture. -The binding provide a simple, unified single entry point for all AGL audio applications. - -Here are the features provide by the binding: - -- Expose all audio device capabilities in uniform way to applications -- Provide display name for device to applications (e.g. for user selection) -- Provide target device URI (e.g. stream to selected endpoint) to applications -- Automatically retrieve associated volume control for ALSA softvol URI -- Allow fine grain security permissions control, policy enforcement and application audio stream control isolation -- Priority-based and audio role specific endpoint selection / stream routings (automatic or explicit) -- Aggregation of different audio domains (ALSA, Pulse) -- Audio stream controls (volume, mute, state, properties) - - -# Glossary ------------------------------ -The binding define the following term: - -- AHL : Audio High Level Binding -- Audio role : Specific set of audio policy rules applied to a group of audio stream -- Endpoint : Virtual audio sink or source device. -- Stream : Audio connection between an application and an endpoint (source or sink). -- Audio 4A Framework : AGL Audio Framework using a set of low level, HAL and HLB bindings. -- Policy Engine : Static library define in ahl-policy.c implementing audio policy. -- URI : Uniform Resource Identifier (e.g. ALSA PCM name) - - -# Policy Engine ------------------------------- - -The sample implementation of the policy engine is implemented as a static library. -The interface between the policy engine and the audio high level binding is a simple JSON interface. -This allows users to easily replace it with their own policy engine. - - -# Endpoint Selection ------------------------------- -The AHL JSON configuration file defines a number of possible endpoints per audio role. The endpoints are listed in order of priority, from highest to lowest priority. -At initialization time, the AHL will validate each endpoint and only keep a list of available endpoints per audio role. Inactive endpoints are discarded and are not accessible to applications. - -Applications can request a list of available endpoints for a specific audio role by calling the API/Verb get_endpoints. -Applications can decide to open a stream on a specific endpoint from the list by specifying an EndpointID or let AHL select automatically an endpoint based on it audio role endpoint priority list. -In the latter case, the endpoint selected will be the first available endpoint on the audio-role specific list. - -# Events -------------------------------- -AHL will generate 4 types of events, defined in ahl-interface.h: - -- **AHL_STREAM_STATE_EVENT** - - Applications are automatically susbcribed to this event and will only receive events for streams they have opened. -- **AHL_ENDPOINT_VOLUME_EVENT** - - Applications need to subscribe to this event to receive volume change notifications. -- **AHL_ENDPOINT_PROPERTY_EVENT** - - Applications need to subscribe to this event to receive property change notifications. -- **AHL_POST_ACTION_EVENT** - - Applications need to subscribe to this event to receive action notifications. Note: This is for future use cases, involving sound generation for example. - - -# AHL Configuration File and System Configuration ----------------------------------------------- -Please refer to README.md documentation inside subfolder: - -conf.d/project/README.md - - -# Cloning Audio High Level Binding from Git -------------------------------------------------------- - -``` -# Initial clone with submodules -git clone --recurse-submodules https://github.com/Audiokinetic-Automotive/afb-audiohighlevel.git -cd audio-binding -# Do not forget submodules with pulling -git pull --recurse-submodules https://github.com/Audiokinetic-Automotive/afb-audiohighlevel.git - -``` - -# System libraries Dependencies ------------------------------------------------------------------- -- libasound (version 1.1.2 or latest) -- libsystemd (version 222 or latest) -- libmicrohttpd (version 0.9.55 or latest) -- afb-daemon (version 2.0 or latest) -- json-c -- libafbwsc -- glib-2.0 - -# AGL Binding Dependencies -------------------------------------------------------------------- -AGL Audio High Level Binding is part of the AGL Audio 4A framework, -It requires the following AGL bindings: - -- **4a-alsa-core** - - Alsa Low Level Binding - - source: https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/4a-alsa-core -- **4a-hal-reference** - - Hardware Abstraction Layer Binding - - source: https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/4a-hal-reference - - -# Compile AGL Audio High Level Binding --------------------------------------- - -Set INSTALL_PREFIX variable to your local AGL binding install folder. - - -``` -export INSTALL_PREFIX=~/opt -mkdir -p build -cd build -cmake -DCMAKE_INSTALL_PREFIX=$INSTALL_PREFIX .. -make -make install - -``` - -# Launch command to test and usage (the actual list of HAL to use may be specific to each hardware setup, please adapt name and ldpath parameters to match with your system configuration) - - -``` -afb-daemon --name=audio4a --workdir=.--ldpaths=./lib:../agl-service-audio-4a/lib/afb-audiohighlevel.so:../4a-hal-reference/lib/afb-hal-intel-hda.so:../4a-alsa-core/lib/afb-alsa-4a.so --port=1234 --roothttp=./htdocs --token="" --verbose - -``` diff --git a/docs/4a-framework/README.md b/docs/4a-framework/README.md new file mode 100644 index 0000000..1cc2940 --- /dev/null +++ b/docs/4a-framework/README.md @@ -0,0 +1,23 @@ +# AGL Advanced Audio Architecture (4a) + +4a is an audio framework made to handle automotive use cases like stream priority and interruptions. It does **not** deal with the audio by itself but rather with the policies and signaling about it. This means that 4a must be used in conjunction with an other API that is in charge of the audio stuff, like **alsa** or **pulseaudio**. + +# Architecture + +## Global architecture +![applications architecture diagram](images/apps-architecture.svg) + +This diagram shows the global architecture that any application playing audio should follow. As a developper, when you want to play audio, you rely on APIs such as alsa, pulseaudio or higher level API(s). To play audio you usually have some kind of device URI that you have to open in order to write audio data to it. + +4a does **not** change anything about that. You still have to do all of this. 4a provides permissions, signals and policies. This means that all compliant applications have to ask 4a when they want to open an audio role. If 4a give them the permission, it return a device URI that applications have to open. + +Nothing prevent an application to directly open a device, but in this case no policies can be applied. + +## 4a Architecture +![4a's architecture diagram](images/4a-architecture.svg) + +Even if applications only deals with the high level API, 4a is made of multiple components that relies on each other. + +The high level API use the hal-manager to list enabled HALs then it use directly those HALs. + +HALs relies directly on drivers and/or softmixer. \ No newline at end of file diff --git a/docs/4a-framework/SUMMARY.md b/docs/4a-framework/SUMMARY.md new file mode 100644 index 0000000..413454c --- /dev/null +++ b/docs/4a-framework/SUMMARY.md @@ -0,0 +1,5 @@ +# Summary + +* [Architecture](README.md) +* [Concepts](concepts.md) +* [Components](components.md) \ No newline at end of file diff --git a/docs/4a-framework/book.json b/docs/4a-framework/book.json new file mode 100644 index 0000000..5916103 --- /dev/null +++ b/docs/4a-framework/book.json @@ -0,0 +1,10 @@ +{ + "title": "AGL Advanced Audio Architecture (4A)", + "subtitle": "4A Framework", + "description": "This is the 4A framework documentation", + "keywords": "Audio, 4a, AGL, Development, Iotbzh", + "author": "IoT.Bzh Team", + "website": "http://iot.bzh", + "published": "September 2018", + "version": "1.0" +} \ No newline at end of file diff --git a/docs/4a-framework/components.md b/docs/4a-framework/components.md new file mode 100644 index 0000000..e63fd52 --- /dev/null +++ b/docs/4a-framework/components.md @@ -0,0 +1,31 @@ +# Components + +4a framework is made of several components which provide features to each other. The High Level API component is the only one that exports a public API. This means that, as an application developper you only need to care about the High Level API. + +## High level API +This is the publicly exported API. It exposes one verb for each audio roles, plus **get_roles** to get the audio role list. + +This component manages audio roles and apply permissions, signaling and policies. Because each role is a unique verb, it means that each role can have its own smack label. + +It makes use of the **4a-hal-manager** to list all HALs and their configurations. Then it uses directly the enabled HALs. + +## 4a-hal-manager +This component is responsible for HALs detection, initialization and state management. + +## 4a-hal-* +This block represents all the differents HALs. You can load multiple HALs provided that they don't interfere with each other. +HALs can be provided by two means: +* Built directly by the **4a-hal-manager** using it's controller and json files. +* External HAL (like the unicens one), that have to register themselves to the **4a-hal-manager**. + +HALs manages audio streams and zones. The streams are bound to audio roles. + +## 4a-softmixer +This component abstracts the real devices to virtuals one and provide some basic mixing capabilities for devices that doesn't have this feature builtin. +It exposes streams named like the audio roles. + +This component can be used by HALs, but this is not mandatory. + +HALs can either : +* use 4a-softmixer (for example when hardware doesn't provide mixing feature), or +* take advantage from the hardware to provide the mixing capabilities. \ No newline at end of file diff --git a/docs/4a-framework/concepts.md b/docs/4a-framework/concepts.md new file mode 100644 index 0000000..c0f0f1d --- /dev/null +++ b/docs/4a-framework/concepts.md @@ -0,0 +1,16 @@ +# Concepts +A user application requests to open an audio role, which is bound to a stream, which is bound to a zone. This allows the application to only care about the audio role. + +For example, a navigation application can request the **navigation** role, which is bound to the **navigation** stream defined by the HAL. This stream is bound to the **driver** zone, which is the closest speaker to the driver. + +## Roles +The high level API allows applications to open roles such as **emergency**, **navigation** or **multimedia**. A role is bound to a stream, which is basically a device URI. When a role is opened, then the policy engine is notified and executes an interrupt on every other opened roles with a lower priority. An interrupt is a policy engine function that can change the volume, mute or unmute, change the stream's state. + +This behaviour allows the policy engine to take actions like lowering the radio volume when an application wants to play something on the emergency role. + +## Streams +A stream is basically a device URI that you can open to write audio data. For exemple, it can be "hw:2,0,1", which means that you have to use this as an alsa device URI. + +## Zones +Multiple speakers are spread arround inside a vehicule, they are named depending on their position, like **front-center**, **front-left**, **front-right**, **rear-left**, **rear-right**, etc... +Zones are an abstraction of positional audio. A zone is made of one or more speakers and describes logical audio areas like **driver**, **front**, **rear**, etc. diff --git a/docs/4a-framework/images/4a-architecture.svg b/docs/4a-framework/images/4a-architecture.svg new file mode 100644 index 0000000..1554e8e --- /dev/null +++ b/docs/4a-framework/images/4a-architecture.svg @@ -0,0 +1,155 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 4a-hal-* + + + 4a-hal-* + + + + + + + + HARDWARE + + + + + + + + Drivers + + + + + + + + APPLICATIONS + + + + + + + + 4a-softmixer + + + + + + + + 4a-high-level + + + + + + + + 4a-hal-manager + + + + + + + + \ No newline at end of file diff --git a/docs/4a-framework/images/apps-architecture.svg b/docs/4a-framework/images/apps-architecture.svg new file mode 100644 index 0000000..4dca8b5 --- /dev/null +++ b/docs/4a-framework/images/apps-architecture.svg @@ -0,0 +1,119 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + HARDWARE + + + + + + + + APPLICATIONS + + + + + + + + Audio lib + + + + + + + + 4a + + + + + + + + \ No newline at end of file diff --git a/docs/high-level-api/README.md b/docs/high-level-api/README.md new file mode 100644 index 0000000..2f5d1f3 --- /dev/null +++ b/docs/high-level-api/README.md @@ -0,0 +1,66 @@ +# High Level API + +The High Level API provides an abstraction of audio roles. + +## Configuration + +Here is a sample configuration. + +```json +{ + "$schema": "http://iot.bzh/download/public/schema/json/ctl-schema.json", + "metadata": { + "uid": "4a-policy", + "version": "0.1", + "api": "4a-policy", + "require": [], + "info": "Basic Audio Policy Control for Audio-4a - Sample 1", + "author": "Loïc Collignon ", + "date": "2018-05-25" + }, + "onload": [], + "controls": [], + "events": [], + "roles":[ + { + "uid": "radio", + "description": "Radio (tuner)", + "priority": 0, + "stream": "radio_stream" + }, + { + "uid": "multimedia", + "description": "Multimedia content (e.g. media player, etc.)", + "priority": 0, + "stream": "multimedia" + }, + { + "uid": "emergency", + "description": "Safety-relevant or critical alerts/alarms", + "priority": 100, + "stream": "emergency", + "interrupts":[ + {"type": "ramp", "args": { "uid": "ramp-slow", "volume": 30} } + ] + }, + { + "uid": "navigation", + "name": "navigation", + "description": "Navigation instructions (GPS, turn directions, etc...)", + "priority": 25, + "stream": "navigation", + "interrupts":[ + {"type": "ramp", "args": { "uid": "ramp-slow", "volume": 30} } + ] + } + ] +} +``` + +Each defined roles should have a stream associated. This stream will be provided by HALs. If no HAL provides the stream, then the audio role will have no device URI. If multiple HALs provide the same stream, a race condition occurs, the first HAL found will be used, the next will be ignored. + +The higher priority value is, the higher priority is. In this sample, the **emergency** role has a higher priority than the **navigation**. + +>**NOTE:** In this sample there is only one stream per role and it's named after the corresponding role, but none of this is mandatory. + +## Policy engine diff --git a/docs/high-level-api/SUMMARY.md b/docs/high-level-api/SUMMARY.md new file mode 100644 index 0000000..ff21d0b --- /dev/null +++ b/docs/high-level-api/SUMMARY.md @@ -0,0 +1,10 @@ +# Summary + +* [Abstract](README.md) +* [Kickstart](kickstart.md) +* [Reference](reference.md) +* [Tips & Tricks](TipsAndTricks/SUMMARY.md) + * [Adjust Volumes](TipsAndTricks/AdjustVolumes.md) + * [4a-tools](TipsAndTricks/4aTools.md) + * [Devices](TipsAndTricks/Devices.md) + * [HALs](TipsAndTricks/HALs.md) diff --git a/docs/high-level-api/TipsAndTricks/4aTools.md b/docs/high-level-api/TipsAndTricks/4aTools.md new file mode 100644 index 0000000..6e13790 --- /dev/null +++ b/docs/high-level-api/TipsAndTricks/4aTools.md @@ -0,0 +1,168 @@ +# 4a-tools + +4a-tools is a set of simple scripts that can be used to test and troubleshoot 4a framework. + +## 4a-status +4a-status gives a diagnostic whether 4a-framework is supposed to be working or not. + +```bash +user@machine$ 4a-status +---- Audio cards detected ---- +card 0: Loopback +card 1: Intel + +---- snd-aloop driver availability ---- +SUCCESS: Built into the kernel + +---- 4a service status ---- +SUCCESS: Service is currently running! +``` + +If any error is shown then there is no way that 4a-framework can work. +Not running services do trigger only a warning because you may have started the service's binding manually and the script cannot detect this. +If you don't, this must be considered as an error, because 4a-framework obviously cannot work when binding are not running. + +```bash +---- Audio cards detected ---- +card 0: Loopback +card 1: Intel + +---- snd-aloop driver availability ---- +SUCCESS: Built into the kernel + +---- 4a service status ---- +WARNING: Service is not currently running! +It can be started using the following command: +systemctl restart *agl-service-audio-4a*.service +``` + +## 4a-api + +This script let you call 4a's APIs to test bindings and get some infos. + +### Ping API +Pinging an API let you know that the binding providing this API is running and ready. +```bash +user@machine$ 4a-api api smixer ping +Detected systemd unit file! +Port detected: 1025 +ON-REPLY 1:smixer/ping: OK +{ + "response":3, + "jtype":"afb-reply", + "request":{ + "status":"success" + } +} +``` + +### List HALs +You can list availables HALs using the following command: +```bash +user@machine$ 4a-api hals +Detected systemd unit file! +Port detected: 1025 +ON-REPLY 1:4a-hal-manager/loaded: OK +{ + "response":[ + "4a-hal-intel-qemu" + ], + "jtype":"afb-reply", + "request":{ + "status":"success", + "info":"Requested data" + } +} +``` +If the returned list is empty, this mean that no HAL is loaded and ready. In such a case you won't be able to use 4a-framework because this mean that there is no device to play audio on. + +To get more information about a HAL, you can call it's **info** verb: +```bash +user@machine$ 4a-api api 4a-hal-intel-qemu info +Detected systemd unit file! +Port detected: 1025 +ON-REPLY 1:4a-hal-intel-qemu/info: OK +{ + "response":{ + "streams":[ + { + "name":"multimedia", + "cardId":"hw:0,0,2" + }, + { + "name":"navigation", + "cardId":"hw:0,0,3" + }, + { + "name":"emergency", + "cardId":"hw:0,0,4" + } + ], + "playbacks":[ + { + "name":"playback", + "mixer-name":"INTEL-QEMU:playback" + } + ], + "captures":[ + { + "name":"capture", + "mixer-name":"INTEL-QEMU:capture" + } + ] + }, + "jtype":"afb-reply", + "request":{ + "status":"success", + "info":"Requested data" + } +} +``` + +This allows you to get which device is bounded to which stream. +Please note these are stream names, not roles name. +In addition, multiples HALs can provide the same stream. +Nowadays, it result in a race condition: 4a-framework using the first HAL providing the stream. + +### List roles +This let you get the list of available audio roles. +Only roles with a bounded device are listed here, because roles without a devices are pretty much unusable. + +```bash +user@machine$ 4a-api roles +Detected systemd unit file! +Port detected: 1025 +ON-REPLY 1:ahl-4a/get_roles: OK +{ + "response":[ + "radio", + "multimedia", + "emergency", + "navigation" + ], + "jtype":"afb-reply", + "request": { + "status":"success" + } +} +``` + +## 4a-play + +4a-play let you play some audio file on a specified device, with an optional audio role. + +```bash +4a-play [role] +``` + +Where *file* is the path to the file to play, *device* is the device to play on and and *role* is the 4a audio role to open (multimedia for example). + +The specified role should be the one that is bounded to the specified device, however the script is not able to detect it so there is no control about this. The role is opened before playing the audio file, and closed after playing is over. + +So for example: +```bash +4a-play Happy_MBB_75.ogg hw:2,0,0 multimedia +``` +>**NOTE**: For now you have to specify the device and the role. Future version of this script may detect devices and roles relations so that you will be able to omit either role or device. +> +>The device that usually match "multimedia" is "hw:0,0,2" (for more details please read the [HALs](HALs.md) section). diff --git a/docs/high-level-api/TipsAndTricks/AdjustVolumes.md b/docs/high-level-api/TipsAndTricks/AdjustVolumes.md new file mode 100644 index 0000000..fbbf279 --- /dev/null +++ b/docs/high-level-api/TipsAndTricks/AdjustVolumes.md @@ -0,0 +1,9 @@ +## **Adjust volumes** + +On the main menu, hit the "Mixer" icon. + +![Main Menu Interface](images/MixerBaseMenu.png) + +Then drag the cursor to change the sound volume of the corresponding role. + +![Mixer Interface](images/changeSound.png) diff --git a/docs/high-level-api/TipsAndTricks/Devices.md b/docs/high-level-api/TipsAndTricks/Devices.md new file mode 100644 index 0000000..a88f67d --- /dev/null +++ b/docs/high-level-api/TipsAndTricks/Devices.md @@ -0,0 +1,29 @@ +# List available devices +To list available devices, as well as their subdevices, you can use the **aplay** command. +```bash +user@machine$ aplay -l +**** List of PLAYBACK Hardware Devices **** +card 0: Loopback [Loopback], device 0: Loopback PCM [Loopback PCM] + Subdevices: 8/8 + Subdevice #0: subdevice #0 + Subdevice #1: subdevice #1 + Subdevice #2: subdevice #2 + Subdevice #3: subdevice #3 + Subdevice #4: subdevice #4 + Subdevice #5: subdevice #5 + Subdevice #6: subdevice #6 + Subdevice #7: subdevice #7 +card 0: Loopback [Loopback], device 1: Loopback PCM [Loopback PCM] + Subdevices: 8/8 + Subdevice #0: subdevice #0 + Subdevice #1: subdevice #1 + Subdevice #2: subdevice #2 + Subdevice #3: subdevice #3 + Subdevice #4: subdevice #4 + Subdevice #5: subdevice #5 + Subdevice #6: subdevice #6 + Subdevice #7: subdevice #7 +card 1: Intel [HDA Intel], device 0: Generic Analog [Generic Analog] + Subdevices: 0/1 + Subdevice #0: subdevice #0 +``` diff --git a/docs/high-level-api/TipsAndTricks/HALs.md b/docs/high-level-api/TipsAndTricks/HALs.md new file mode 100644 index 0000000..70b29c2 --- /dev/null +++ b/docs/high-level-api/TipsAndTricks/HALs.md @@ -0,0 +1,40 @@ +# HALs +HALs are known as json files in 4a, they are stored in **/usr/libexec/agl/4a-hal**. + +Enabled HALs can be found in the **etc** subfolder, and disabled HALs in **etc.available**. + +You can enable and disable HALs just by moving the corresponding json file from one folder to the other. + +Example: + +```bash +user@machine$ ls etc etc.available/ +etc: +hal-4a-csl-cm106-8ch-usb.json + +etc.available/: +hal-4a-2ch-generic-usb.json hal-4a-intel.json hal-4a-rcar-m3.json +hal-4a-ensoniq.json hal-4a-jabra.json hal-4a-rcar-m3kf.json +hal-4a-intel-minnow.json hal-4a-m3ulcbkf-radio-to-2ch.json +hal-4a-intel-qemu.json hal-4a-raspberry-pi-3.json + +user@machine$ mv etc/hal-4a-csl-cm106-8ch-usb.json etc.available +user@machine$ mv etc.available/hal-4a-2ch-generic-usb.json etc + +user@machine$ ls etc etc.available/ +etc: +hal-4a-2ch-generic-usb.json + +etc.available/: +hal-4a-csl-cm106-8ch-usb.json hal-4a-intel.json hal-4a-rcar-m3.json +hal-4a-ensoniq.json hal-4a-jabra.json hal-4a-rcar-m3kf.json +hal-4a-intel-minnow.json hal-4a-m3ulcbkf-radio-to-2ch.json +hal-4a-intel-qemu.json hal-4a-raspberry-pi-3.json + +user@machine$ sync +user@machine$ reboot +``` + +>NOTE: Even if multiple HAL are allowed, you have to make sure that they don't provide the same streams, because it will cause a race condition in the high level API. The first HAL providing the stream is used, any other are ignored. +> +>Also, the hardware used by enabled HALs should be available. diff --git a/docs/high-level-api/TipsAndTricks/SUMMARY.md b/docs/high-level-api/TipsAndTricks/SUMMARY.md new file mode 100644 index 0000000..44f6901 --- /dev/null +++ b/docs/high-level-api/TipsAndTricks/SUMMARY.md @@ -0,0 +1,7 @@ +# Tips & Tricks + +In this section you'll find useful tips and tricks to help you in case of trouble. +* [Adjust Volumes](AdjustVolumes.md) +* [4a-tools](4aTools.md) +* [Devices](Devices.md) +* [HALs](HALs.md) \ No newline at end of file diff --git a/docs/high-level-api/TipsAndTricks/images/MixerBaseMenu.png b/docs/high-level-api/TipsAndTricks/images/MixerBaseMenu.png new file mode 100644 index 0000000..e2e6fe6 Binary files /dev/null and b/docs/high-level-api/TipsAndTricks/images/MixerBaseMenu.png differ diff --git a/docs/high-level-api/TipsAndTricks/images/changeSound.png b/docs/high-level-api/TipsAndTricks/images/changeSound.png new file mode 100644 index 0000000..504f8ce Binary files /dev/null and b/docs/high-level-api/TipsAndTricks/images/changeSound.png differ diff --git a/docs/high-level-api/book.json b/docs/high-level-api/book.json new file mode 100644 index 0000000..a338781 --- /dev/null +++ b/docs/high-level-api/book.json @@ -0,0 +1,10 @@ +{ + "title": "AGL Advanced Audio Architecture (4A)", + "subtitle": "High Level API", + "description": "This is the 4A High Level API documentation", + "keywords": "Audio, 4a, AGL, Development, Iotbzh", + "author": "IoT.Bzh Team", + "website": "http://iot.bzh", + "published": "September 2018", + "version": "1.0" +} \ No newline at end of file diff --git a/docs/high-level-api/kickstart.md b/docs/high-level-api/kickstart.md new file mode 100644 index 0000000..f708a1f --- /dev/null +++ b/docs/high-level-api/kickstart.md @@ -0,0 +1,12 @@ +# Kickstart + +As an application developper, when you play audio, you have to use a device URI. +Instead of using the default one, guessing one by listing them or even hardcoding it, you should call **ahl-4a/[role]** with **open** as action. + +The role to open should be defined in a configuration file or hardcoded. If you hardcode it, please consider to at least define it at one known place so that it can be easily changed. + +As opening a role may fail, you should test if it returns a success and a device URI. Both of them should be tested because it's perfectly fine to have a role without a device URI from 4a point of view (no device is bound to the role thus no audio can be played in this case). + +Once you have finished to play audio, you should call **ahl-4a/[role]** with **close** as action. This is important to allow other applications to use the role when you are not using it. + +You may also want to handle events of the window manager to know if you application is displayed or not, and open/close accordingly the role you are using. diff --git a/docs/high-level-api/reference.md b/docs/high-level-api/reference.md new file mode 100644 index 0000000..47e7b3f --- /dev/null +++ b/docs/high-level-api/reference.md @@ -0,0 +1,71 @@ +# Reference + +## Verbs + +### ahl-4a/get_roles +Get the list of available audio roles. By default it returns the list of roles that are bounded to a stream. To get a list of all defined roles, regardless if they are bound to a stream or not, you can pass the following parameter. +```json +{ + "verbose": true +} +``` + +### ahl-4a/[role] +Replace [role] by the role's name. For exemple **ahl-4a/multimedia**. + +This verb allow the control of the audio role. The action executed depend on the parameter. + +#### Open +```json +{ "action": "open" } +``` +Request to open the role. + +On success it returns the device URI to open. This action fails if the role is already opened. + +When a role is opened, it triggers the first interruption of the policy engine. + +The policy engine execute the interruption for each opened audio role with a lower priority. + +#### Close +```json +{ "action": "close" } +``` +Request to close the role. + +On success it closes the role. You can only close roles that you opened. An error will occurs if you try to close a role that an other application opened. + +#### Volume +```json +{ + "action": "volume", + "value": 80 +} +``` +Request to get or set the volume. + +Value can be absolute or relative. Use a string as value to use relative, like **"+10"** or **"-20"**. To get the volume you can use **"+0"** as value. + +#### Mute +```json +{ + "action": "mute" +} +``` +Mute the volume of this. + +#### Unmute +```json +{ + "action": "unmute" +} +``` +Unmute the volume of this role. + +#### Interrupt +```json +{ + "action": "interrupt" +} +``` +Ask the policy engine to execute an interruption. \ No newline at end of file -- cgit 1.2.3-korg