diff options
| author |   Loïc Collignon <loic.collignon@iot.bzh> | 2018-09-10 10:36:46 +0200 |
|---|---|---|
| committer | Loïc Collignon <loic.collignon@iot.bzh> | 2018-10-01 15:46:43 +0200 |
| commit | 75e26b091f6aae38c9edb069c173bcb04ae3ffd1 (patch) | |
| tree | ac31716b5bdd2ad0236559d141cdcca8f9696332 /docs | |
| parent | fe834167fd205e9a38c986bfb9dfde4265e9cc45 (diff) | |
Updated documentation
Updated documentation up to date and using the gitbook format.
Change-Id: Ie5d6a3bb489b9a9a95e21f5edd05bdd77bff5816
Signed-off-by: Loïc Collignon <loic.collignon@iot.bzh>
Diffstat (limited to 'docs')
19 files changed, 930 insertions, 0 deletions
diff --git a/docs/4a-framework/README.md b/docs/4a-framework/README.md new file mode 100644 index 0000000..90de65b --- /dev/null +++ b/docs/4a-framework/README.md @@ -0,0 +1,42 @@ +# AGL Advanced Audio Architecture (4a) + +## Abstract + +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 around 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 + + + +This diagram shows the global architecture that any application playing audio +should follow. As a developer, 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 for a 'role' when they want to play audio. If 4a +grants them the permission, it returns 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 and access permissions are handled by system policies. + +### 4a Architecture + + + +Even if applications only deal with the high level API, 4a is made of multiple +components that rely on each other. + +The high level API uses the hal-manager to list enabled HALs then it uses +directly those HALs. + +HALs rely directly on drivers and/or softmixer. 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..43eb2f0 --- /dev/null +++ b/docs/4a-framework/book.json @@ -0,0 +1,11 @@ +{ + "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", + "pdf_filename": "AGL_4A_Framework" +}
\ 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..2709d60 --- /dev/null +++ b/docs/4a-framework/components.md @@ -0,0 +1,49 @@ +# 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 developer 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 list of audio roles. + +This component manages audio roles and applies 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 different 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 manage audio streams and zones. The streams are bound to audio roles. + +## 4a-softmixer + +This component abstracts the real devices to virtual ones and provides some +basic mixing capabilities for devices that don'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. diff --git a/docs/4a-framework/concepts.md b/docs/4a-framework/concepts.md new file mode 100644 index 0000000..dba024d --- /dev/null +++ b/docs/4a-framework/concepts.md @@ -0,0 +1,37 @@ +# 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 role 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 +example, 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 around 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 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> +<svg version="1.2" width="82.13mm" height="140.01mm" viewBox="12000 2000 8213 14001" preserveAspectRatio="xMidYMid" fill-rule="evenodd" stroke-width="28.222" stroke-linejoin="round" xmlns="http://www.w3.org/2000/svg" xmlns:ooo="http://xml.openoffice.org/svg/export" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:presentation="http://sun.com/xmlns/staroffice/presentation" xmlns:smil="http://www.w3.org/2001/SMIL20/" xmlns:anim="urn:oasis:names:tc:opendocument:xmlns:animation:1.0" xml:space="preserve"> + <defs class="ClipPathGroup"> + <clipPath id="presentation_clip_path" clipPathUnits="userSpaceOnUse"> + <rect x="12000" y="2000" width="8213" height="14001"/> + </clipPath> + <clipPath id="presentation_clip_path_shrink" clipPathUnits="userSpaceOnUse"> + <rect x="12008" y="2014" width="8197" height="13973"/> + </clipPath> + </defs> + <defs> + <font id="EmbeddedFont_1" horiz-adv-x="2048"> + <font-face font-family="Liberation Sans embedded" units-per-em="2048" font-weight="normal" font-style="normal" ascent="1852" descent="423"/> + <missing-glyph horiz-adv-x="2048" d="M 0,0 L 2047,0 2047,2047 0,2047 0,0 Z"/> + <glyph unicode="x" horiz-adv-x="1006" d="M 801,0 L 510,444 217,0 23,0 408,556 41,1082 240,1082 510,661 778,1082 979,1082 612,558 1002,0 801,0 Z"/> + <glyph unicode="v" horiz-adv-x="1033" d="M 613,0 L 400,0 7,1082 199,1082 437,378 C 446,351 469,272 506,141 L 541,258 580,376 826,1082 1017,1082 613,0 Z"/> + <glyph unicode="t" horiz-adv-x="531" d="M 554,8 C 495,-8 434,-16 372,-16 228,-16 156,66 156,229 L 156,951 31,951 31,1082 163,1082 216,1324 336,1324 336,1082 536,1082 536,951 336,951 336,268 C 336,216 345,180 362,159 379,138 408,127 450,127 474,127 509,132 554,141 L 554,8 Z"/> + <glyph unicode="s" horiz-adv-x="901" d="M 950,299 C 950,197 912,118 835,63 758,8 650,-20 511,-20 376,-20 273,2 200,47 127,91 79,160 57,254 L 216,285 C 231,227 263,185 311,158 359,131 426,117 511,117 602,117 669,131 712,159 754,187 775,229 775,285 775,328 760,362 731,389 702,416 654,438 589,455 L 460,489 C 357,516 283,542 240,568 196,593 162,624 137,661 112,698 100,743 100,796 100,895 135,970 206,1022 276,1073 378,1099 513,1099 632,1099 727,1078 798,1036 868,994 912,927 931,834 L 769,814 C 759,862 732,899 689,925 645,950 586,963 513,963 432,963 372,951 333,926 294,901 275,864 275,814 275,783 283,758 299,738 315,718 339,701 370,687 401,673 467,654 568,629 663,605 732,583 774,563 816,542 849,520 874,495 898,470 917,442 930,410 943,377 950,340 950,299 Z"/> + <glyph unicode="r" horiz-adv-x="530" d="M 142,0 L 142,830 C 142,906 140,990 136,1082 L 306,1082 C 311,959 314,886 314,861 L 318,861 C 347,954 380,1017 417,1051 454,1085 507,1102 575,1102 599,1102 623,1099 648,1092 L 648,927 C 624,934 592,937 552,937 477,937 420,905 381,841 342,776 322,684 322,564 L 322,0 142,0 Z"/> + <glyph unicode="o" horiz-adv-x="980" d="M 1053,542 C 1053,353 1011,212 928,119 845,26 724,-20 565,-20 407,-20 288,28 207,125 126,221 86,360 86,542 86,915 248,1102 571,1102 736,1102 858,1057 936,966 1014,875 1053,733 1053,542 Z M 864,542 C 864,691 842,800 798,868 753,935 679,969 574,969 469,969 393,935 346,866 299,797 275,689 275,542 275,399 298,292 345,221 391,149 464,113 563,113 671,113 748,148 795,217 841,286 864,395 864,542 Z"/> + <glyph unicode="n" horiz-adv-x="874" d="M 825,0 L 825,686 C 825,757 818,813 804,852 790,891 768,920 737,937 706,954 661,963 602,963 515,963 447,933 397,874 347,815 322,732 322,627 L 322,0 142,0 142,851 C 142,977 140,1054 136,1082 L 306,1082 C 307,1079 307,1070 308,1055 309,1040 310,1024 311,1005 312,986 313,950 314,897 L 317,897 C 358,972 406,1025 461,1056 515,1087 582,1102 663,1102 782,1102 869,1073 924,1014 979,955 1006,857 1006,721 L 1006,0 825,0 Z"/> + <glyph unicode="m" horiz-adv-x="1457" d="M 768,0 L 768,686 C 768,791 754,863 725,903 696,943 645,963 570,963 493,963 433,934 388,875 343,816 321,734 321,627 L 321,0 142,0 142,851 C 142,977 140,1054 136,1082 L 306,1082 C 307,1079 307,1070 308,1055 309,1040 310,1024 311,1005 312,986 313,950 314,897 L 317,897 C 356,974 400,1027 450,1057 500,1087 561,1102 633,1102 715,1102 780,1086 828,1053 875,1020 908,968 927,897 L 930,897 C 967,970 1013,1022 1066,1054 1119,1086 1183,1102 1258,1102 1367,1102 1447,1072 1497,1013 1546,954 1571,856 1571,721 L 1571,0 1393,0 1393,686 C 1393,791 1379,863 1350,903 1321,943 1270,963 1195,963 1116,963 1055,934 1012,876 968,817 946,734 946,627 L 946,0 768,0 Z"/> + <glyph unicode="l" horiz-adv-x="187" d="M 138,0 L 138,1484 318,1484 318,0 138,0 Z"/> + <glyph unicode="i" horiz-adv-x="187" d="M 137,1312 L 137,1484 317,1484 317,1312 137,1312 Z M 137,0 L 137,1082 317,1082 317,0 137,0 Z"/> + <glyph unicode="h" horiz-adv-x="874" d="M 317,897 C 356,968 402,1020 457,1053 511,1086 580,1102 663,1102 780,1102 867,1073 923,1015 978,956 1006,858 1006,721 L 1006,0 825,0 825,686 C 825,762 818,819 804,856 790,893 767,920 735,937 703,954 659,963 602,963 517,963 450,934 399,875 348,816 322,737 322,638 L 322,0 142,0 142,1484 322,1484 322,1098 C 322,1057 321,1015 319,972 316,929 315,904 314,897 L 317,897 Z"/> + <glyph unicode="g" horiz-adv-x="927" d="M 548,-425 C 430,-425 336,-402 266,-356 196,-309 151,-243 131,-158 L 312,-132 C 324,-182 351,-220 392,-248 433,-274 486,-288 553,-288 732,-288 822,-183 822,27 L 822,201 820,201 C 786,132 739,80 680,45 621,10 551,-8 472,-8 339,-8 242,36 180,124 117,212 86,350 86,539 86,730 120,872 187,963 254,1054 355,1099 492,1099 569,1099 635,1082 692,1047 748,1012 791,962 822,897 L 824,897 C 824,917 825,952 828,1001 831,1050 833,1077 836,1082 L 1007,1082 C 1003,1046 1001,971 1001,858 L 1001,31 C 1001,-273 850,-425 548,-425 Z M 822,541 C 822,629 810,705 786,769 762,832 728,881 685,915 641,948 591,965 536,965 444,965 377,932 335,865 293,798 272,690 272,541 272,393 292,287 331,222 370,157 438,125 533,125 590,125 640,142 684,175 728,208 762,256 786,319 810,381 822,455 822,541 Z"/> + <glyph unicode="f" horiz-adv-x="557" d="M 361,951 L 361,0 181,0 181,951 29,951 29,1082 181,1082 181,1204 C 181,1303 203,1374 246,1417 289,1460 356,1482 445,1482 495,1482 537,1478 572,1470 L 572,1333 C 542,1338 515,1341 492,1341 446,1341 413,1329 392,1306 371,1283 361,1240 361,1179 L 361,1082 572,1082 572,951 361,951 Z"/> + <glyph unicode="e" horiz-adv-x="980" d="M 276,503 C 276,379 302,283 353,216 404,149 479,115 578,115 656,115 719,131 766,162 813,193 844,233 861,281 L 1019,236 C 954,65 807,-20 578,-20 418,-20 296,28 213,123 129,218 87,360 87,548 87,727 129,864 213,959 296,1054 416,1102 571,1102 889,1102 1048,910 1048,527 L 1048,503 276,503 Z M 862,641 C 852,755 823,838 775,891 727,943 658,969 568,969 481,969 412,940 361,882 310,823 282,743 278,641 L 862,641 Z"/> + <glyph unicode="a" horiz-adv-x="1060" d="M 414,-20 C 305,-20 224,9 169,66 114,123 87,202 87,302 87,414 124,500 198,560 271,620 390,652 554,656 L 797,660 797,719 C 797,807 778,870 741,908 704,946 645,965 565,965 484,965 426,951 389,924 352,897 330,853 323,793 L 135,810 C 166,1005 310,1102 569,1102 705,1102 807,1071 876,1009 945,946 979,856 979,738 L 979,272 C 979,219 986,179 1000,152 1014,125 1041,111 1080,111 1097,111 1117,113 1139,118 L 1139,6 C 1094,-5 1047,-10 1000,-10 933,-10 885,8 855,43 824,78 807,132 803,207 L 797,207 C 751,124 698,66 637,32 576,-3 501,-20 414,-20 Z M 455,115 C 521,115 580,130 631,160 682,190 723,231 753,284 782,336 797,390 797,445 L 797,534 600,530 C 515,529 451,520 408,504 364,488 330,463 307,430 284,397 272,353 272,299 272,240 288,195 320,163 351,131 396,115 455,115 Z"/> + <glyph unicode="W" horiz-adv-x="1932" d="M 1511,0 L 1283,0 1039,895 C 1023,951 1000,1051 969,1196 952,1119 937,1054 925,1002 913,950 822,616 652,0 L 424,0 9,1409 208,1409 461,514 C 491,402 519,287 544,168 560,241 579,321 600,408 621,495 713,828 877,1409 L 1060,1409 1305,532 C 1342,389 1372,267 1393,168 L 1402,203 C 1420,280 1435,342 1446,391 1457,439 1551,778 1727,1409 L 1926,1409 1511,0 Z"/> + <glyph unicode="T" horiz-adv-x="1192" d="M 720,1253 L 720,0 530,0 530,1253 46,1253 46,1409 1204,1409 1204,1253 720,1253 Z"/> + <glyph unicode="S" horiz-adv-x="1192" d="M 1272,389 C 1272,259 1221,158 1120,87 1018,16 875,-20 690,-20 347,-20 148,99 93,338 L 278,375 C 299,290 345,228 414,189 483,149 578,129 697,129 820,129 916,150 983,193 1050,235 1083,297 1083,379 1083,425 1073,462 1052,491 1031,520 1001,543 963,562 925,581 880,596 827,609 774,622 716,635 652,650 541,675 456,699 399,724 341,749 295,776 262,807 229,837 203,872 186,913 168,954 159,1000 159,1053 159,1174 205,1267 298,1332 390,1397 522,1430 694,1430 854,1430 976,1406 1061,1357 1146,1308 1205,1224 1239,1106 L 1051,1073 C 1030,1148 991,1202 933,1236 875,1269 795,1286 692,1286 579,1286 493,1267 434,1230 375,1193 345,1137 345,1063 345,1020 357,984 380,956 403,927 436,903 479,884 522,864 609,840 738,811 781,801 825,791 868,781 911,770 952,758 991,744 1030,729 1067,712 1102,693 1136,674 1166,650 1191,622 1216,594 1236,561 1251,523 1265,485 1272,440 1272,389 Z"/> + <glyph unicode="R" horiz-adv-x="1244" d="M 1164,0 L 798,585 359,585 359,0 168,0 168,1409 831,1409 C 990,1409 1112,1374 1199,1303 1285,1232 1328,1133 1328,1006 1328,901 1298,813 1237,742 1176,671 1091,626 984,607 L 1384,0 1164,0 Z M 1136,1004 C 1136,1086 1108,1149 1053,1192 997,1235 917,1256 812,1256 L 359,1256 359,736 820,736 C 921,736 999,760 1054,807 1109,854 1136,919 1136,1004 Z"/> + <glyph unicode="P" horiz-adv-x="1112" d="M 1258,985 C 1258,852 1215,746 1128,667 1041,588 922,549 773,549 L 359,549 359,0 168,0 168,1409 761,1409 C 919,1409 1041,1372 1128,1298 1215,1224 1258,1120 1258,985 Z M 1066,983 C 1066,1165 957,1256 738,1256 L 359,1256 359,700 746,700 C 959,700 1066,794 1066,983 Z"/> + <glyph unicode="O" horiz-adv-x="1430" d="M 1495,711 C 1495,564 1467,435 1411,324 1354,213 1273,128 1168,69 1063,10 938,-20 795,-20 650,-20 526,9 421,68 316,127 235,212 180,323 125,434 97,563 97,711 97,936 159,1113 282,1240 405,1367 577,1430 797,1430 940,1430 1065,1402 1170,1345 1275,1288 1356,1205 1412,1096 1467,987 1495,859 1495,711 Z M 1300,711 C 1300,886 1256,1024 1169,1124 1081,1224 957,1274 797,1274 636,1274 511,1225 423,1126 335,1027 291,889 291,711 291,534 336,394 425,291 514,187 637,135 795,135 958,135 1083,185 1170,286 1257,386 1300,528 1300,711 Z"/> + <glyph unicode="N" horiz-adv-x="1165" d="M 1082,0 L 328,1200 333,1103 338,936 338,0 168,0 168,1409 390,1409 1152,201 C 1144,332 1140,426 1140,485 L 1140,1409 1312,1409 1312,0 1082,0 Z"/> + <glyph unicode="L" horiz-adv-x="927" d="M 168,0 L 168,1409 359,1409 359,156 1071,156 1071,0 168,0 Z"/> + <glyph unicode="I" horiz-adv-x="213" d="M 189,0 L 189,1409 380,1409 380,0 189,0 Z"/> + <glyph unicode="H" horiz-adv-x="1165" d="M 1121,0 L 1121,653 359,653 359,0 168,0 168,1409 359,1409 359,813 1121,813 1121,1409 1312,1409 1312,0 1121,0 Z"/> + <glyph unicode="E" horiz-adv-x="1138" d="M 168,0 L 168,1409 1237,1409 1237,1253 359,1253 359,801 1177,801 1177,647 359,647 359,156 1278,156 1278,0 168,0 Z"/> + <glyph unicode="D" horiz-adv-x="1218" d="M 1381,719 C 1381,574 1353,447 1296,338 1239,229 1159,145 1055,87 951,29 831,0 695,0 L 168,0 168,1409 634,1409 C 873,1409 1057,1349 1187,1230 1316,1110 1381,940 1381,719 Z M 1189,719 C 1189,894 1141,1027 1046,1119 950,1210 811,1256 630,1256 L 359,1256 359,153 673,153 C 776,153 867,176 946,221 1024,266 1084,332 1126,417 1168,502 1189,603 1189,719 Z"/> + <glyph unicode="C" horiz-adv-x="1324" d="M 792,1274 C 636,1274 515,1224 428,1124 341,1023 298,886 298,711 298,538 343,400 434,295 524,190 646,137 800,137 997,137 1146,235 1245,430 L 1401,352 C 1343,231 1262,138 1157,75 1052,12 930,-20 791,-20 649,-20 526,10 423,69 319,128 240,212 186,322 131,431 104,561 104,711 104,936 165,1112 286,1239 407,1366 575,1430 790,1430 940,1430 1065,1401 1166,1342 1267,1283 1341,1196 1388,1081 L 1207,1021 C 1174,1103 1122,1166 1050,1209 977,1252 891,1274 792,1274 Z"/> + <glyph unicode="A" horiz-adv-x="1377" d="M 1167,0 L 1006,412 364,412 202,0 4,0 579,1409 796,1409 1362,0 1167,0 Z M 685,1265 L 676,1237 C 659,1182 635,1111 602,1024 L 422,561 949,561 768,1026 C 749,1072 731,1124 712,1182 L 685,1265 Z"/> + <glyph unicode="4" horiz-adv-x="1060" d="M 881,319 L 881,0 711,0 711,319 47,319 47,459 692,1409 881,1409 881,461 1079,461 1079,319 881,319 Z M 711,1206 C 710,1202 700,1184 683,1153 666,1122 653,1100 644,1087 L 283,555 229,481 213,461 711,461 711,1206 Z"/> + <glyph unicode="-" horiz-adv-x="531" d="M 91,464 L 91,624 591,624 591,464 91,464 Z"/> + <glyph unicode="*" horiz-adv-x="742" d="M 456,1114 L 720,1217 765,1085 483,1012 668,762 549,690 399,948 243,692 124,764 313,1012 33,1085 78,1219 345,1112 333,1409 469,1409 456,1114 Z"/> + </font> + </defs> + <defs class="TextShapeIndex"> + <g ooo:slide="id1" ooo:id-list="id3 id4 id5 id6 id7 id8 id9"/> + </defs> + <defs class="EmbeddedBulletChars"> + <g id="bullet-char-template-57356" transform="scale(0.00048828125,-0.00048828125)"> + <path d="M 580,1141 L 1163,571 580,0 -4,571 580,1141 Z"/> + </g> + <g id="bullet-char-template-57354" transform="scale(0.00048828125,-0.00048828125)"> + <path d="M 8,1128 L 1137,1128 1137,0 8,0 8,1128 Z"/> + </g> + <g id="bullet-char-template-10146" transform="scale(0.00048828125,-0.00048828125)"> + <path d="M 174,0 L 602,739 174,1481 1456,739 174,0 Z M 1358,739 L 309,1346 659,739 1358,739 Z"/> + </g> + <g id="bullet-char-template-10132" transform="scale(0.00048828125,-0.00048828125)"> + <path d="M 2015,739 L 1276,0 717,0 1260,543 174,543 174,936 1260,936 717,1481 1274,1481 2015,739 Z"/> + </g> + <g id="bullet-char-template-10007" transform="scale(0.00048828125,-0.00048828125)"> + <path d="M 0,-2 C -7,14 -16,27 -25,37 L 356,567 C 262,823 215,952 215,954 215,979 228,992 255,992 264,992 276,990 289,987 310,991 331,999 354,1012 L 381,999 492,748 772,1049 836,1024 860,1049 C 881,1039 901,1025 922,1006 886,937 835,863 770,784 769,783 710,716 594,584 L 774,223 C 774,196 753,168 711,139 L 727,119 C 717,90 699,76 672,76 641,76 570,178 457,381 L 164,-76 C 142,-110 111,-127 72,-127 30,-127 9,-110 8,-76 1,-67 -2,-52 -2,-32 -2,-23 -1,-13 0,-2 Z"/> + </g> + <g id="bullet-char-template-10004" transform="scale(0.00048828125,-0.00048828125)"> + <path d="M 285,-33 C 182,-33 111,30 74,156 52,228 41,333 41,471 41,549 55,616 82,672 116,743 169,778 240,778 293,778 328,747 346,684 L 369,508 C 377,444 397,411 428,410 L 1163,1116 C 1174,1127 1196,1133 1229,1133 1271,1133 1292,1118 1292,1087 L 1292,965 C 1292,929 1282,901 1262,881 L 442,47 C 390,-6 338,-33 285,-33 Z"/> + </g> + <g id="bullet-char-template-9679" transform="scale(0.00048828125,-0.00048828125)"> + <path d="M 813,0 C 632,0 489,54 383,161 276,268 223,411 223,592 223,773 276,916 383,1023 489,1130 632,1184 813,1184 992,1184 1136,1130 1245,1023 1353,916 1407,772 1407,592 1407,412 1353,268 1245,161 1136,54 992,0 813,0 Z"/> + </g> + <g id="bullet-char-template-8226" transform="scale(0.00048828125,-0.00048828125)"> + <path d="M 346,457 C 273,457 209,483 155,535 101,586 74,649 74,723 74,796 101,859 155,911 209,963 273,989 346,989 419,989 480,963 531,910 582,859 608,796 608,723 608,648 583,586 532,535 482,483 420,457 346,457 Z"/> + </g> + <g id="bullet-char-template-8211" transform="scale(0.00048828125,-0.00048828125)"> + <path d="M -4,459 L 1135,459 1135,606 -4,606 -4,459 Z"/> + </g> + <g id="bullet-char-template-61548" transform="scale(0.00048828125,-0.00048828125)"> + <path d="M 173,740 C 173,903 231,1043 346,1159 462,1274 601,1332 765,1332 928,1332 1067,1274 1183,1159 1299,1043 1357,903 1357,740 1357,577 1299,437 1183,322 1067,206 928,148 765,148 601,148 462,206 346,322 231,437 173,577 173,740 Z"/> + </g> + </defs> + <defs class="TextEmbeddedBitmaps"/> + <g class="SlideGroup"> + <g> + <g id="container-id1"> + <g id="id1" class="Slide" clip-path="url(#presentation_clip_path)"> + <g class="Page"> + <g class="com.sun.star.drawing.PolyPolygonShape"> + <g id="id3"> + <rect class="BoundingBox" stroke="none" fill="none" x="11999" y="7787" width="8215" height="4215"/> + <path fill="rgb(114,159,207)" stroke="none" d="M 20212,7788 L 20212,9788 16212,9788 16212,11788 12212,11788 12212,7788 20212,7788 Z"/> + <path fill="none" stroke="rgb(114,159,207)" d="M 20212,7788 L 20212,9788 16212,9788 16212,11788 12212,11788 12212,7788 20212,7788 Z"/> + <text class="TextShape"><tspan class="TextParagraph" font-family="Liberation Sans, sans-serif" font-size="635px" font-weight="400"><tspan class="TextPosition" x="15105" y="9200"><tspan fill="rgb(114,159,207)" stroke="none">4a-hal-*</tspan></tspan></tspan></text> + <path fill="rgb(114,159,207)" stroke="none" d="M 20000,8000 L 20000,10000 16000,10000 16000,12000 12000,12000 12000,8000 20000,8000 Z"/> + <path fill="none" stroke="rgb(52,101,164)" d="M 20000,8000 L 20000,10000 16000,10000 16000,12000 12000,12000 12000,8000 20000,8000 Z"/> + <text class="TextShape"><tspan class="TextParagraph" font-family="Liberation Sans, sans-serif" font-size="635px" font-weight="400"><tspan class="TextPosition" x="14893" y="9412"><tspan fill="rgb(0,0,0)" stroke="none">4a-hal-*</tspan></tspan></tspan></text> + </g> + </g> + <g class="com.sun.star.drawing.CustomShape"> + <g id="id4"> + <rect class="BoundingBox" stroke="none" fill="none" x="11999" y="13999" width="8003" height="2003"/> + <path fill="rgb(255,166,166)" stroke="none" d="M 16000,16000 L 12000,16000 12000,14000 20000,14000 20000,16000 16000,16000 Z"/> + <path fill="none" stroke="rgb(52,101,164)" d="M 16000,16000 L 12000,16000 12000,14000 20000,14000 20000,16000 16000,16000 Z"/> + <text class="TextShape"><tspan class="TextParagraph" font-family="Liberation Sans, sans-serif" font-size="635px" font-weight="400"><tspan class="TextPosition" x="14163" y="15221"><tspan fill="rgb(0,0,0)" stroke="none">HARDWARE</tspan></tspan></tspan></text> + </g> + </g> + <g class="com.sun.star.drawing.CustomShape"> + <g id="id5"> + <rect class="BoundingBox" stroke="none" fill="none" x="11999" y="11999" width="8003" height="2003"/> + <path fill="rgb(255,170,149)" stroke="none" d="M 16000,14000 L 12000,14000 12000,12000 20000,12000 20000,14000 16000,14000 Z"/> + <path fill="none" stroke="rgb(52,101,164)" d="M 16000,14000 L 12000,14000 12000,12000 20000,12000 20000,14000 16000,14000 Z"/> + <text class="TextShape"><tspan class="TextParagraph" font-family="Liberation Sans, sans-serif" font-size="635px" font-weight="400"><tspan class="TextPosition" x="14997" y="13221"><tspan fill="rgb(0,0,0)" stroke="none">Drivers</tspan></tspan></tspan></text> + </g> + </g> + <g class="com.sun.star.drawing.CustomShape"> + <g id="id6"> + <rect class="BoundingBox" stroke="none" fill="none" x="11999" y="1999" width="8003" height="2003"/> + <path fill="rgb(255,255,166)" stroke="none" d="M 16000,4000 L 12000,4000 12000,2000 20000,2000 20000,4000 16000,4000 Z"/> + <path fill="none" stroke="rgb(52,101,164)" d="M 16000,4000 L 12000,4000 12000,2000 20000,2000 20000,4000 16000,4000 Z"/> + <text class="TextShape"><tspan class="TextParagraph" font-family="Liberation Sans, sans-serif" font-size="635px" font-weight="400"><tspan class="TextPosition" x="13712" y="3221"><tspan fill="rgb(0,0,0)" stroke="none">APPLICATIONS</tspan></tspan></tspan></text> + </g> + </g> + <g class="com.sun.star.drawing.CustomShape"> + <g id="id7"> + <rect class="BoundingBox" stroke="none" fill="none" x="15999" y="9999" width="4003" height="2003"/> + <path fill="rgb(180,199,220)" stroke="none" d="M 18000,12000 L 16000,12000 16000,10000 20000,10000 20000,12000 18000,12000 Z"/> + <path fill="none" stroke="rgb(52,101,164)" d="M 18000,12000 L 16000,12000 16000,10000 20000,10000 20000,12000 18000,12000 Z"/> + <text class="TextShape"><tspan class="TextParagraph" font-family="Liberation Sans, sans-serif" font-size="635px" font-weight="400"><tspan class="TextPosition" x="16256" y="11221"><tspan fill="rgb(0,0,0)" stroke="none">4a-softmixer</tspan></tspan></tspan></text> + </g> + </g> + <g class="com.sun.star.drawing.PolyPolygonShape"> + <g id="id8"> + <rect class="BoundingBox" stroke="none" fill="none" x="11999" y="3999" width="8003" height="4003"/> + <path fill="rgb(52,101,164)" stroke="none" d="M 20000,4000 L 20000,6000 16000,6000 16000,8000 12000,8000 12000,4000 20000,4000 Z"/> + <path fill="none" stroke="rgb(52,101,164)" d="M 20000,4000 L 20000,6000 16000,6000 16000,8000 12000,8000 12000,4000 20000,4000 Z"/> + <text class="TextShape"><tspan class="TextParagraph" font-family="Liberation Sans, sans-serif" font-size="635px" font-weight="400"><tspan class="TextPosition" x="14190" y="5412"><tspan fill="rgb(0,0,0)" stroke="none">4a-high-level</tspan></tspan></tspan></text> + </g> + </g> + <g class="com.sun.star.drawing.CustomShape"> + <g id="id9"> + <rect class="BoundingBox" stroke="none" fill="none" x="15999" y="5999" width="4003" height="2003"/> + <path fill="rgb(89,131,176)" stroke="none" d="M 18000,8000 L 16000,8000 16000,6000 20000,6000 20000,8000 18000,8000 Z"/> + <path fill="none" stroke="rgb(52,101,164)" d="M 18000,8000 L 16000,8000 16000,6000 20000,6000 20000,8000 18000,8000 Z"/> + <text class="TextShape"><tspan class="TextParagraph" font-family="Liberation Sans, sans-serif" font-size="494px" font-weight="400"><tspan class="TextPosition" x="16254" y="7172"><tspan fill="rgb(0,0,0)" stroke="none">4a-hal-manager</tspan></tspan></tspan></text> + </g> + </g> + </g> + </g> + </g> + </g> + </g> +</svg>
\ 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 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> +<svg version="1.2" width="80.01mm" height="60.01mm" viewBox="7000 5000 8001 6001" preserveAspectRatio="xMidYMid" fill-rule="evenodd" stroke-width="28.222" stroke-linejoin="round" xmlns="http://www.w3.org/2000/svg" xmlns:ooo="http://xml.openoffice.org/svg/export" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:presentation="http://sun.com/xmlns/staroffice/presentation" xmlns:smil="http://www.w3.org/2001/SMIL20/" xmlns:anim="urn:oasis:names:tc:opendocument:xmlns:animation:1.0" xml:space="preserve"> + <defs class="ClipPathGroup"> + <clipPath id="presentation_clip_path" clipPathUnits="userSpaceOnUse"> + <rect x="7000" y="5000" width="8001" height="6001"/> + </clipPath> + <clipPath id="presentation_clip_path_shrink" clipPathUnits="userSpaceOnUse"> + <rect x="7008" y="5006" width="7985" height="5989"/> + </clipPath> + </defs> + <defs> + <font id="EmbeddedFont_1" horiz-adv-x="2048"> + <font-face font-family="Liberation Sans embedded" units-per-em="2048" font-weight="normal" font-style="normal" ascent="1852" descent="423"/> + <missing-glyph horiz-adv-x="2048" d="M 0,0 L 2047,0 2047,2047 0,2047 0,0 Z"/> + <glyph unicode="u" horiz-adv-x="874" d="M 314,1082 L 314,396 C 314,325 321,269 335,230 349,191 371,162 402,145 433,128 478,119 537,119 624,119 692,149 742,208 792,267 817,350 817,455 L 817,1082 997,1082 997,231 C 997,105 999,28 1003,0 L 833,0 C 832,3 832,12 831,27 830,42 830,59 829,78 828,97 826,132 825,185 L 822,185 C 781,110 733,58 679,27 624,-4 557,-20 476,-20 357,-20 271,10 216,69 161,128 133,225 133,361 L 133,1082 314,1082 Z"/> + <glyph unicode="o" horiz-adv-x="980" d="M 1053,542 C 1053,353 1011,212 928,119 845,26 724,-20 565,-20 407,-20 288,28 207,125 126,221 86,360 86,542 86,915 248,1102 571,1102 736,1102 858,1057 936,966 1014,875 1053,733 1053,542 Z M 864,542 C 864,691 842,800 798,868 753,935 679,969 574,969 469,969 393,935 346,866 299,797 275,689 275,542 275,399 298,292 345,221 391,149 464,113 563,113 671,113 748,148 795,217 841,286 864,395 864,542 Z"/> + <glyph unicode="l" horiz-adv-x="187" d="M 138,0 L 138,1484 318,1484 318,0 138,0 Z"/> + <glyph unicode="i" horiz-adv-x="187" d="M 137,1312 L 137,1484 317,1484 317,1312 137,1312 Z M 137,0 L 137,1082 317,1082 317,0 137,0 Z"/> + <glyph unicode="d" horiz-adv-x="927" d="M 821,174 C 788,105 744,55 689,25 634,-5 565,-20 484,-20 347,-20 247,26 183,118 118,210 86,349 86,536 86,913 219,1102 484,1102 566,1102 634,1087 689,1057 744,1027 788,979 821,914 L 823,914 821,1035 821,1484 1001,1484 1001,223 C 1001,110 1003,36 1007,0 L 835,0 C 833,11 831,35 829,74 826,113 825,146 825,174 L 821,174 Z M 275,542 C 275,391 295,282 335,217 375,152 440,119 530,119 632,119 706,154 752,225 798,296 821,405 821,554 821,697 798,802 752,869 706,936 633,969 532,969 441,969 376,936 336,869 295,802 275,693 275,542 Z"/> + <glyph unicode="b" horiz-adv-x="953" d="M 1053,546 C 1053,169 920,-20 655,-20 573,-20 505,-5 451,25 396,54 352,102 318,168 L 316,168 C 316,147 315,116 312,74 309,31 307,7 306,0 L 132,0 C 136,36 138,110 138,223 L 138,1484 318,1484 318,1061 C 318,1018 317,967 314,908 L 318,908 C 351,977 396,1027 451,1057 506,1087 574,1102 655,1102 792,1102 892,1056 957,964 1021,872 1053,733 1053,546 Z M 864,540 C 864,691 844,800 804,865 764,930 699,963 609,963 508,963 434,928 388,859 341,790 318,680 318,529 318,387 341,282 386,215 431,147 505,113 607,113 698,113 763,147 804,214 844,281 864,389 864,540 Z"/> + <glyph unicode="a" horiz-adv-x="1060" d="M 414,-20 C 305,-20 224,9 169,66 114,123 87,202 87,302 87,414 124,500 198,560 271,620 390,652 554,656 L 797,660 797,719 C 797,807 778,870 741,908 704,946 645,965 565,965 484,965 426,951 389,924 352,897 330,853 323,793 L 135,810 C 166,1005 310,1102 569,1102 705,1102 807,1071 876,1009 945,946 979,856 979,738 L 979,272 C 979,219 986,179 1000,152 1014,125 1041,111 1080,111 1097,111 1117,113 1139,118 L 1139,6 C 1094,-5 1047,-10 1000,-10 933,-10 885,8 855,43 824,78 807,132 803,207 L 797,207 C 751,124 698,66 637,32 576,-3 501,-20 414,-20 Z M 455,115 C 521,115 580,130 631,160 682,190 723,231 753,284 782,336 797,390 797,445 L 797,534 600,530 C 515,529 451,520 408,504 364,488 330,463 307,430 284,397 272,353 272,299 272,240 288,195 320,163 351,131 396,115 455,115 Z"/> + <glyph unicode="W" horiz-adv-x="1932" d="M 1511,0 L 1283,0 1039,895 C 1023,951 1000,1051 969,1196 952,1119 937,1054 925,1002 913,950 822,616 652,0 L 424,0 9,1409 208,1409 461,514 C 491,402 519,287 544,168 560,241 579,321 600,408 621,495 713,828 877,1409 L 1060,1409 1305,532 C 1342,389 1372,267 1393,168 L 1402,203 C 1420,280 1435,342 1446,391 1457,439 1551,778 1727,1409 L 1926,1409 1511,0 Z"/> + <glyph unicode="T" horiz-adv-x="1192" d="M 720,1253 L 720,0 530,0 530,1253 46,1253 46,1409 1204,1409 1204,1253 720,1253 Z"/> + <glyph unicode="S" horiz-adv-x="1192" d="M 1272,389 C 1272,259 1221,158 1120,87 1018,16 875,-20 690,-20 347,-20 148,99 93,338 L 278,375 C 299,290 345,228 414,189 483,149 578,129 697,129 820,129 916,150 983,193 1050,235 1083,297 1083,379 1083,425 1073,462 1052,491 1031,520 1001,543 963,562 925,581 880,596 827,609 774,622 716,635 652,650 541,675 456,699 399,724 341,749 295,776 262,807 229,837 203,872 186,913 168,954 159,1000 159,1053 159,1174 205,1267 298,1332 390,1397 522,1430 694,1430 854,1430 976,1406 1061,1357 1146,1308 1205,1224 1239,1106 L 1051,1073 C 1030,1148 991,1202 933,1236 875,1269 795,1286 692,1286 579,1286 493,1267 434,1230 375,1193 345,1137 345,1063 345,1020 357,984 380,956 403,927 436,903 479,884 522,864 609,840 738,811 781,801 825,791 868,781 911,770 952,758 991,744 1030,729 1067,712 1102,693 1136,674 1166,650 1191,622 1216,594 1236,561 1251,523 1265,485 1272,440 1272,389 Z"/> + <glyph unicode="R" horiz-adv-x="1244" d="M 1164,0 L 798,585 359,585 359,0 168,0 168,1409 831,1409 C 990,1409 1112,1374 1199,1303 1285,1232 1328,1133 1328,1006 1328,901 1298,813 1237,742 1176,671 1091,626 984,607 L 1384,0 1164,0 Z M 1136,1004 C 1136,1086 1108,1149 1053,1192 997,1235 917,1256 812,1256 L 359,1256 359,736 820,736 C 921,736 999,760 1054,807 1109,854 1136,919 1136,1004 Z"/> + <glyph unicode="P" horiz-adv-x="1112" d="M 1258,985 C 1258,852 1215,746 1128,667 1041,588 922,549 773,549 L 359,549 359,0 168,0 168,1409 761,1409 C 919,1409 1041,1372 1128,1298 1215,1224 1258,1120 1258,985 Z M 1066,983 C 1066,1165 957,1256 738,1256 L 359,1256 359,700 746,700 C 959,700 1066,794 1066,983 Z"/> + <glyph unicode="O" horiz-adv-x="1430" d="M 1495,711 C 1495,564 1467,435 1411,324 1354,213 1273,128 1168,69 1063,10 938,-20 795,-20 650,-20 526,9 421,68 316,127 235,212 180,323 125,434 97,563 97,711 97,936 159,1113 282,1240 405,1367 577,1430 797,1430 940,1430 1065,1402 1170,1345 1275,1288 1356,1205 1412,1096 1467,987 1495,859 1495,711 Z M 1300,711 C 1300,886 1256,1024 1169,1124 1081,1224 957,1274 797,1274 636,1274 511,1225 423,1126 335,1027 291,889 291,711 291,534 336,394 425,291 514,187 637,135 795,135 958,135 1083,185 1170,286 1257,386 1300,528 1300,711 Z"/> + <glyph unicode="N" horiz-adv-x="1165" d="M 1082,0 L 328,1200 333,1103 338,936 338,0 168,0 168,1409 390,1409 1152,201 C 1144,332 1140,426 1140,485 L 1140,1409 1312,1409 1312,0 1082,0 Z"/> + <glyph unicode="L" horiz-adv-x="927" d="M 168,0 L 168,1409 359,1409 359,156 1071,156 1071,0 168,0 Z"/> + <glyph unicode="I" horiz-adv-x="213" d="M 189,0 L 189,1409 380,1409 380,0 189,0 Z"/> + <glyph unicode="H" horiz-adv-x="1165" d="M 1121,0 L 1121,653 359,653 359,0 168,0 168,1409 359,1409 359,813 1121,813 1121,1409 1312,1409 1312,0 1121,0 Z"/> + <glyph unicode="E" horiz-adv-x="1138" d="M 168,0 L 168,1409 1237,1409 1237,1253 359,1253 359,801 1177,801 1177,647 359,647 359,156 1278,156 1278,0 168,0 Z"/> + <glyph unicode="D" horiz-adv-x="1218" d="M 1381,719 C 1381,574 1353,447 1296,338 1239,229 1159,145 1055,87 951,29 831,0 695,0 L 168,0 168,1409 634,1409 C 873,1409 1057,1349 1187,1230 1316,1110 1381,940 1381,719 Z M 1189,719 C 1189,894 1141,1027 1046,1119 950,1210 811,1256 630,1256 L 359,1256 359,153 673,153 C 776,153 867,176 946,221 1024,266 1084,332 1126,417 1168,502 1189,603 1189,719 Z"/> + <glyph unicode="C" horiz-adv-x="1324" d="M 792,1274 C 636,1274 515,1224 428,1124 341,1023 298,886 298,711 298,538 343,400 434,295 524,190 646,137 800,137 997,137 1146,235 1245,430 L 1401,352 C 1343,231 1262,138 1157,75 1052,12 930,-20 791,-20 649,-20 526,10 423,69 319,128 240,212 186,322 131,431 104,561 104,711 104,936 165,1112 286,1239 407,1366 575,1430 790,1430 940,1430 1065,1401 1166,1342 1267,1283 1341,1196 1388,1081 L 1207,1021 C 1174,1103 1122,1166 1050,1209 977,1252 891,1274 792,1274 Z"/> + <glyph unicode="A" horiz-adv-x="1377" d="M 1167,0 L 1006,412 364,412 202,0 4,0 579,1409 796,1409 1362,0 1167,0 Z M 685,1265 L 676,1237 C 659,1182 635,1111 602,1024 L 422,561 949,561 768,1026 C 749,1072 731,1124 712,1182 L 685,1265 Z"/> + <glyph unicode="4" horiz-adv-x="1060" d="M 881,319 L 881,0 711,0 711,319 47,319 47,459 692,1409 881,1409 881,461 1079,461 1079,319 881,319 Z M 711,1206 C 710,1202 700,1184 683,1153 666,1122 653,1100 644,1087 L 283,555 229,481 213,461 711,461 711,1206 Z"/> + <glyph unicode=" " horiz-adv-x="556"/> + </font> + </defs> + <defs class="TextShapeIndex"> + <g ooo:slide="id1" ooo:id-list="id3 id4 id5 id6"/> + </defs> + <defs class="EmbeddedBulletChars"> + <g id="bullet-char-template-57356" transform="scale(0.00048828125,-0.00048828125)"> + <path d="M 580,1141 L 1163,571 580,0 -4,571 580,1141 Z"/> + </g> + <g id="bullet-char-template-57354" transform="scale(0.00048828125,-0.00048828125)"> + <path d="M 8,1128 L 1137,1128 1137,0 8,0 8,1128 Z"/> + </g> + <g id="bullet-char-template-10146" transform="scale(0.00048828125,-0.00048828125)"> + <path d="M 174,0 L 602,739 174,1481 1456,739 174,0 Z M 1358,739 L 309,1346 659,739 1358,739 Z"/> + </g> + <g id="bullet-char-template-10132" transform="scale(0.00048828125,-0.00048828125)"> + <path d="M 2015,739 L 1276,0 717,0 1260,543 174,543 174,936 1260,936 717,1481 1274,1481 2015,739 Z"/> + </g> + <g id="bullet-char-template-10007" transform="scale(0.00048828125,-0.00048828125)"> + <path d="M 0,-2 C -7,14 -16,27 -25,37 L 356,567 C 262,823 215,952 215,954 215,979 228,992 255,992 264,992 276,990 289,987 310,991 331,999 354,1012 L 381,999 492,748 772,1049 836,1024 860,1049 C 881,1039 901,1025 922,1006 886,937 835,863 770,784 769,783 710,716 594,584 L 774,223 C 774,196 753,168 711,139 L 727,119 C 717,90 699,76 672,76 641,76 570,178 457,381 L 164,-76 C 142,-110 111,-127 72,-127 30,-127 9,-110 8,-76 1,-67 -2,-52 -2,-32 -2,-23 -1,-13 0,-2 Z"/> + </g> + <g id="bullet-char-template-10004" transform="scale(0.00048828125,-0.00048828125)"> + <path d="M 285,-33 C 182,-33 111,30 74,156 52,228 41,333 41,471 41,549 55,616 82,672 116,743 169,778 240,778 293,778 328,747 346,684 L 369,508 C 377,444 397,411 428,410 L 1163,1116 C 1174,1127 1196,1133 1229,1133 1271,1133 1292,1118 1292,1087 L 1292,965 C 1292,929 1282,901 1262,881 L 442,47 C 390,-6 338,-33 285,-33 Z"/> + </g> + <g id="bullet-char-template-9679" transform="scale(0.00048828125,-0.00048828125)"> + <path d="M 813,0 C 632,0 489,54 383,161 276,268 223,411 223,592 223,773 276,916 383,1023 489,1130 632,1184 813,1184 992,1184 1136,1130 1245,1023 1353,916 1407,772 1407,592 1407,412 1353,268 1245,161 1136,54 992,0 813,0 Z"/> + </g> + <g id="bullet-char-template-8226" transform="scale(0.00048828125,-0.00048828125)"> + <path d="M 346,457 C 273,457 209,483 155,535 101,586 74,649 74,723 74,796 101,859 155,911 209,963 273,989 346,989 419,989 480,963 531,910 582,859 608,796 608,723 608,648 583,586 532,535 482,483 420,457 346,457 Z"/> + </g> + <g id="bullet-char-template-8211" transform="scale(0.00048828125,-0.00048828125)"> + <path d="M -4,459 L 1135,459 1135,606 -4,606 -4,459 Z"/> + </g> + <g id="bullet-char-template-61548" transform="scale(0.00048828125,-0.00048828125)"> + <path d="M 173,740 C 173,903 231,1043 346,1159 462,1274 601,1332 765,1332 928,1332 1067,1274 1183,1159 1299,1043 1357,903 1357,740 1357,577 1299,437 1183,322 1067,206 928,148 765,148 601,148 462,206 346,322 231,437 173,577 173,740 Z"/> + </g> + </defs> + <defs class="TextEmbeddedBitmaps"/> + <g class="SlideGroup"> + <g> + <g id="container-id1"> + <g id="id1" class="Slide" clip-path="url(#presentation_clip_path)"> + <g class="Page"> + <g class="com.sun.star.drawing.CustomShape"> + <g id="id3"> + <rect class="BoundingBox" stroke="none" fill="none" x="6999" y="8999" width="8003" height="2003"/> + <path fill="rgb(255,166,166)" stroke="none" d="M 11000,11000 L 7000,11000 7000,9000 15000,9000 15000,11000 11000,11000 Z"/> + <path fill="none" stroke="rgb(52,101,164)" d="M 11000,11000 L 7000,11000 7000,9000 15000,9000 15000,11000 11000,11000 Z"/> + <text class="TextShape"><tspan class="TextParagraph" font-family="Liberation Sans, sans-serif" font-size="635px" font-weight="400"><tspan class="TextPosition" x="9163" y="10221"><tspan fill="rgb(0,0,0)" stroke="none">HARDWARE</tspan></tspan></tspan></text> + </g> + </g> + <g class="com.sun.star.drawing.CustomShape"> + <g id="id4"> + <rect class="BoundingBox" stroke="none" fill="none" x="6999" y="4999" width="8003" height="2003"/> + <path fill="rgb(255,255,166)" stroke="none" d="M 11000,7000 L 7000,7000 7000,5000 15000,5000 15000,7000 11000,7000 Z"/> + <path fill="none" stroke="rgb(52,101,164)" d="M 11000,7000 L 7000,7000 7000,5000 15000,5000 15000,7000 11000,7000 Z"/> + <text class="TextShape"><tspan class="TextParagraph" font-family="Liberation Sans, sans-serif" font-size="635px" font-weight="400"><tspan class="TextPosition" x="8712" y="6221"><tspan fill="rgb(0,0,0)" stroke="none">APPLICATIONS</tspan></tspan></tspan></text> + </g> + </g> + <g class="com.sun.star.drawing.CustomShape"> + <g id="id5"> + <rect class="BoundingBox" stroke="none" fill="none" x="6999" y="6999" width="4003" height="2003"/> + <path fill="rgb(255,182,108)" stroke="none" d="M 9000,9000 L 7000,9000 7000,7000 11000,7000 11000,9000 9000,9000 Z"/> + <path fill="none" stroke="rgb(52,101,164)" d="M 9000,9000 L 7000,9000 7000,7000 11000,7000 11000,9000 9000,9000 Z"/> + <text class="TextShape"><tspan class="TextParagraph" font-family="Liberation Sans, sans-serif" font-size="635px" font-weight="400"><tspan class="TextPosition" x="7787" y="8221"><tspan fill="rgb(0,0,0)" stroke="none">Audio lib</tspan></tspan></tspan></text> + </g> + </g> + <g class="com.sun.star.drawing.CustomShape"> + <g id="id6"> + <rect class="BoundingBox" stroke="none" fill="none" x="10999" y="6999" width="4003" height="2003"/> + <path fill="rgb(114,159,207)" stroke="none" d="M 13000,9000 L 11000,9000 11000,7000 15000,7000 15000,9000 13000,9000 Z"/> + <path fill="none" stroke="rgb(52,101,164)" d="M 13000,9000 L 11000,9000 11000,7000 15000,7000 15000,9000 13000,9000 Z"/> + <text class="TextShape"><tspan class="TextParagraph" font-family="Liberation Sans, sans-serif" font-size="635px" font-weight="400"><tspan class="TextPosition" x="12649" y="8221"><tspan fill="rgb(0,0,0)" stroke="none">4a</tspan></tspan></tspan></text> + </g> + </g> + </g> + </g> + </g> + </g> + </g> +</svg>
\ 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..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..f1bff4b --- /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. + + + +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..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 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..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 |
