1 files changed, 80 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.