summaryrefslogtreecommitdiffstats
path: root/docs/high-level-api
diff options
context:
space:
mode:
authorLoïc Collignon <loic.collignon@iot.bzh>2018-11-29 15:29:54 +0100
committerLoïc Collignon <loic.collignon@iot.bzh>2018-11-29 15:29:54 +0100
commit2610bf62ef76f4120a5f76dd0e5eb1e51538b41b (patch)
tree5a54c544bdfbab30601ef4c9cf4ebf554bc232e6 /docs/high-level-api
parent04f89b1c4f49372aea2f9d1c7e0adad5fb8bd99b (diff)
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>
Diffstat (limited to 'docs/high-level-api')
-rw-r--r--docs/high-level-api/README.md80
-rw-r--r--docs/high-level-api/SUMMARY.md10
-rw-r--r--docs/high-level-api/TipsAndTricks/4aTools.md198
-rw-r--r--docs/high-level-api/TipsAndTricks/AdjustVolumes.md9
-rw-r--r--docs/high-level-api/TipsAndTricks/Devices.md32
-rw-r--r--docs/high-level-api/TipsAndTricks/HALs.md46
-rw-r--r--docs/high-level-api/TipsAndTricks/SUMMARY.md9
-rw-r--r--docs/high-level-api/TipsAndTricks/images/MixerBaseMenu.pngbin0 -> 170421 bytes
-rw-r--r--docs/high-level-api/TipsAndTricks/images/changeSound.pngbin0 -> 123509 bytes
-rw-r--r--docs/high-level-api/book.json11
-rw-r--r--docs/high-level-api/kickstart.md22
-rw-r--r--docs/high-level-api/reference.md95
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
Binary files 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
--- /dev/null
+++ b/docs/high-level-api/TipsAndTricks/images/changeSound.png
Binary files differ
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