Backport of audio documentation from masterflounder_6.0.3flounder/6.0.36.0.3

Documentation was available only on master. New documentation website is
now by branch, so documentation should be available on both branches.

Bug: SPEC-1993

Change-Id: I55484d5c1f28ae1e7fa927533b3dd862a03ed207
Signed-off-by: Loïc Collignon <loic.collignon@iot.bzh>

12 files changed, 512 insertions, 0 deletions

diff --git a/docs/high-level-api/README.md b/docs/high-level-api/README.md
new file mode 100644
index 0000000..0120216
--- /dev/null
+++ b/docs/high-level-api/README.md
@@ -0,0 +1,80 @@
+# 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 <loic.collignon@iot.bzh>",
+        "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, 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.
+
+A higher value means a higher priority. 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
+
+Policy engine is provided as a controller plugin for the high level API.
+Currently, the sample policy engine only support the **ramp** interruption.
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..1edddb3
--- /dev/null
+++ b/docs/high-level-api/TipsAndTricks/4aTools.md
@@ -0,0 +1,198 @@
+# 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 bindings 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 lets 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 means that no HAL is loaded and ready. In
+such a case you won't be able to use 4a-framework because this means that there
+is no device to play audio on.
+
+To get more information about a HAL, you can call its **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 bound to which stream.
+Please note these are stream names, not roles names.
+In addition, multiples HALs can provide the same stream.
+In the current implementation, it results in a race condition: 4a-framework
+will be using the first HAL providing the stream.
+
+### List roles
+
+This lets you get the list of available audio roles.
+Only roles with a bound device are listed here, because roles without a device
+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 lets you play some audio file on a specified device, with an optional
+audio role.
+
+```bash
+4a-play <file> [<device> [<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 bound 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 versions
+>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 matches "multimedia" is "hw:0,0,2" (for more details
+>please read the [HALs](HALs.md) section).
+
+>**NOTE**: Some media files (WAV, MP3 and OGG) are provided with 4a-tools for
+>testing purpose and can be used as reference assets.
diff --git a/docs/high-level-api/TipsAndTricks/AdjustVolumes.md b/docs/high-level-api/TipsAndTricks/AdjustVolumes.md
new file mode 100644
index 0000000..2d8fca2
--- /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..9e1c0cd
--- /dev/null
+++ b/docs/high-level-api/TipsAndTricks/Devices.md
@@ -0,0 +1,32 @@
+# List available devices
+
+To list the 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..4c2ead6
--- /dev/null
+++ b/docs/high-level-api/TipsAndTricks/HALs.md
@@ -0,0 +1,46 @@
+# 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-ensoniq.json          hal-4a-jabra.json
+hal-4a-intel-minnow.json     hal-4a-rcar-m3.json
+hal-4a-intel-qemu.json       hal-4a-rcar-m3kf.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-ensoniq.json            hal-4a-jabra.json
+hal-4a-intel-minnow.json       hal-4a-rcar-m3.json
+hal-4a-intel-qemu.json         hal-4a-rcar-m3kf.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..6ae5ff6
--- /dev/null
+++ b/docs/high-level-api/TipsAndTricks/SUMMARY.md
@@ -0,0 +1,9 @@
+# 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
--- /dev/null
+++ b/docs/high-level-api/TipsAndTricks/images/MixerBaseMenu.png
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
--- /dev/null
+++ b/docs/high-level-api/TipsAndTricks/images/changeSound.png
diff --git a/docs/high-level-api/book.json b/docs/high-level-api/book.json
new file mode 100644
index 0000000..7f8bb85
--- /dev/null
+++ b/docs/high-level-api/book.json
@@ -0,0 +1,11 @@
+{
+    "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",
+    "pdf_filename": "AGL_4A_HighLevelAPI"
+}
\ 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..15e1874
--- /dev/null
+++ b/docs/high-level-api/kickstart.md
@@ -0,0 +1,22 @@
+# Kickstart
+
+As an application developer, 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..ed58705
--- /dev/null
+++ b/docs/high-level-api/reference.md
@@ -0,0 +1,95 @@
+# Reference
+
+## Verbs
+
+### ahl-4a/get_roles
+
+Get the list of available audio roles. By default it returns the list of roles
+that are bound 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 example **ahl-4a/multimedia**.
+
+This verb allows the control of the audio role. The action executed depends 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, if any, of the policy
+engine.
+
+The policy engine executes 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 before.
+An error will occur if you try to close a role that an other application has
+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