diff options
Diffstat (limited to 'docs/high-level-api')
| -rw-r--r-- | docs/high-level-api/README.md | 66 | ||||
| -rw-r--r-- | docs/high-level-api/SUMMARY.md | 10 | ||||
| -rw-r--r-- | docs/high-level-api/TipsAndTricks/4aTools.md | 168 | ||||
| -rw-r--r-- | docs/high-level-api/TipsAndTricks/AdjustVolumes.md | 9 | ||||
| -rw-r--r-- | docs/high-level-api/TipsAndTricks/Devices.md | 29 | ||||
| -rw-r--r-- | docs/high-level-api/TipsAndTricks/HALs.md | 40 | ||||
| -rw-r--r-- | docs/high-level-api/TipsAndTricks/SUMMARY.md | 7 | ||||
| -rw-r--r-- | docs/high-level-api/TipsAndTricks/images/MixerBaseMenu.png | bin | 0 -> 170421 bytes | |||
| -rw-r--r-- | docs/high-level-api/TipsAndTricks/images/changeSound.png | bin | 0 -> 123509 bytes | |||
| -rw-r--r-- | docs/high-level-api/book.json | 10 | ||||
| -rw-r--r-- | docs/high-level-api/kickstart.md | 12 | ||||
| -rw-r--r-- | docs/high-level-api/reference.md | 71 |
12 files changed, 422 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..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 <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, 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 <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 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. + + + +Then drag the cursor to change the sound volume of the corresponding role. + + 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 Binary files differnew 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 Binary files differnew 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..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 |
