binding: bluetooth: initial commit of binding rewrite

Bug-AGL: SPEC-1630
Change-Id: I33cfec70283fa29f47b76f9e6be3e8e6cd6a2f54
Signed-off-by: Matt Ranostay <matt.ranostay@konsulko.com>

1 files changed, 217 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..ed9deeb
--- /dev/null
+++ b/README.md
@@ -0,0 +1,217 @@
+# Bluetooth Service
+
+## Overview
+
+Bluetooth service uses the respective BlueZ package to connect to bluetooth devices
+
+## Verbs
+
+| Name               | Description                                             | JSON Response                                                           |
+|--------------------|---------------------------------------------------------|-------------------------------------------------------------------------|
+| subscribe          | subscribe to bluetooth events                           | *Request:* {"value": "device_changes"}                                  |
+| unsubscribe        | unsubscribe to bluetooth events                         | *Request:* {"value": "device_changes"}                                  |
+| managed_objects    | retrieve managed bluetooth devices                      | see managed_objects verb section                                        |
+| adapter_state      | retrieve or change adapter scan settings                | see adapter_state verb section                                          |
+| connect            | connect to already paired device                        | see connect/disconnect verb section                                     |
+| disconnect         | disconnect to already connected device                  | see connect/disconnect verb section                                     |
+| pair               | initialize a pairing request                            | *Request:* {"device":"/org/bluez/hci0/dev_88_0F_10_96_D3_20"}           |
+| cancel_pairing     | cancel an outgoing pair request                         |                                                                         |
+| confirm_pairing    | confirm incoming/outgoing bluetooth pairing pincode     | *Request:* {"pincode": 31415}                                           |
+| remove_device      | remove already paired device                            | *Request:* {"device": "/org/bluez/hci0/dev/dev_88_0F_10_96_D3_20"}      |
+
+
+### managed_objects verb
+
+This verb allows an client to get initial paired devices, and discovered unpaired devices before subscriptio to *devices_changed* event.
+
+<pre>
+{
+  "response": {
+    "adapters": [
+      {
+        "path": "/org/bluez/hci0",
+        "properties": {
+          "address": "00:1A:7D:DA:71:0F",
+          "powered": true,
+          "discoverable": true,
+          "discoverabletimeout": 180,
+          "pairable": true,
+          "pairabletimeout": 0,
+          "discovering": true,
+          "uuids": [
+            "00001112-0000-1000-8000-00805f9b34fb",
+            "00001801-0000-1000-8000-00805f9b34fb",
+            "0000110e-0000-1000-8000-00805f9b34fb",
+            "00001800-0000-1000-8000-00805f9b34fb",
+            "00001200-0000-1000-8000-00805f9b34fb",
+            "0000110c-0000-1000-8000-00805f9b34fb",
+            "0000110b-0000-1000-8000-00805f9b34fb",
+            "0000110a-0000-1000-8000-00805f9b34fb",
+            "0000111e-0000-1000-8000-00805f9b34fb",
+            "0000111f-0000-1000-8000-00805f9b34fb",
+            "00001108-0000-1000-8000-00805f9b34fb"
+          ]
+        }
+      }
+    ],
+    "devices": [
+      {
+        "path": "/org/bluez/hci0/dev_F8_34_41_DA_BA_46",
+        "properties": {
+          "address": "F8:34:41:DA:BA:46",
+          "name": "roguebox",
+          "alias": "roguebox",
+          "class": 1835276,
+          "icon": "computer",
+          "paired": false,
+          "trusted": false,
+          "blocked": false,
+          "legacypairing": false,
+          "rssi": -63,
+          "connected": false,
+          "uuids": [
+            "0000110e-0000-1000-8000-00805f9b34fb",
+            "0000110c-0000-1000-8000-00805f9b34fb",
+            "00001112-0000-1000-8000-00805f9b34fb",
+            "00001108-0000-1000-8000-00805f9b34fb",
+            "00001133-0000-1000-8000-00805f9b34fb",
+            "00001132-0000-1000-8000-00805f9b34fb",
+            "0000112f-0000-1000-8000-00805f9b34fb",
+            "00001104-0000-1000-8000-00805f9b34fb",
+            "00001106-0000-1000-8000-00805f9b34fb",
+            "00001105-0000-1000-8000-00805f9b34fb",
+            "0000110a-0000-1000-8000-00805f9b34fb",
+            "0000110b-0000-1000-8000-00805f9b34fb",
+            "00005005-0000-1000-8000-0002ee000001"
+          ],
+          "modalias": "usb:v1D6Bp0246d0530",
+          "adapter": "/org/bluez/hci0",
+          "txpower": 12,
+          "servicesresolved": false
+        }
+      },
+      {
+        "path": "/org/bluez/hci0/dev_67_13_E2_57_29_0F",
+        "properties": {
+          "address": "68:13:E2:57:29:0F",
+          "alias": "67-13-E2-57-29-0F",
+          "paired": false,
+          "trusted": false,
+          "blocked": false,
+          "legacypairing": false,
+          "rssi": -69,
+          "connected": false,
+          "uuids": [],
+          "adapter": "/org/bluez/hci0",
+          "servicesresolved": false
+        }
+      },
+...
+</pre>
+
+
+### adapter_state verb
+
+adapter_state verb allows setting and retrieving of requested adapter settings:
+
+| Name            | Description                                                      |
+|-----------------|------------------------------------------------------------------|
+| adapter         | Must be the bluez path to the adapter (i.e. /org/bluez/hci0)     |
+| discovery       | Discover nearby broadcasting devices                             |
+| discoverable    | Allow other devices to detect this device                        |
+| powered         | Adapter power state (optional, rfkill should be disabled already |
+
+
+### connect/disconnect verbs
+
+NOTE: uuid in this respect is not related to the afb framework but the Bluetooth profile UUID
+
+To connect/disconnect using the respective verb with all known and authenticated profiles:
+
+<pre>
+  {"device": "/org/bluez/hci0/dev_88_0F_10_96_D3_20"}
+</pre>
+
+To do the same for the respective device, verb, and for singular profile
+
+<pre>
+  {"device": "/org/bluez/hci0/dev_88_0F_10_96_D3_20", "uuid": "0000110e-0000-1000-8000-00805f9b34fb"}
+</pre>
+
+## Events
+
+| Name              | Description                              | JSON Event Data                           |
+|-------------------|------------------------------------------|-------------------------------------------|
+| device_changes    | report on bluetooth devices              | see device_changes event section          |
+| agent             | PIN from BlueZ agent for confirmation    | see agent event section                   |
+
+
+### device_changes event
+
+Sample of discovering a new device event:
+
+<pre>
+{
+  "device": "/org/bluez/hci0/dev_88_0F_10_96_D3_20",
+  "action": "added",
+  "properties": {
+    "address": "88:0F:10:96:D3:20",
+    "name": "MI_SCALE",
+    "alias": "MI_SCALE",
+    "class": 7995916,
+    "icon": "phone",
+    "paired": false,
+    "trusted": false,
+    "blocked": false,
+    "legacypairing": false,
+    "rssi": -55,
+    "connected": false,
+    "uuids": [
+      "00001200-0000-1000-8000-00805f9b34fb",
+      "0000111f-0000-1000-8000-00805f9b34fb",
+      "0000112f-0000-1000-8000-00805f9b34fb",
+      "0000110a-0000-1000-8000-00805f9b34fb",
+      "0000110c-0000-1000-8000-00805f9b34fb",
+      "00001116-0000-1000-8000-00805f9b34fb",
+      "00001132-0000-1000-8000-00805f9b34fb",
+      "00000000-deca-fade-deca-deafdecacafe",
+      "02030302-1d19-415f-86f2-22a2106a0a77",
+      "2d8d2466-e14d-451c-88bc-7301abea291a"
+    ],
+    "adapter": "/org/bluez/hci0",
+    "servicesresolved": false
+  }
+}
+</pre>
+
+Changed status events for a deivce:
+
+<pre>
+{
+  "path": "/org/bluez/hci0/dev_88_0F_10_96_D3_20",
+  "action": "changed",
+  "properties": {
+    "connected": true
+  }
+}
+</pre>
+
+### agent event
+
+After pairing request agent will send event for a pincode that must be confirmed on both sides:
+
+<pre>
+{
+  "action": "request_confirmation",
+  "device": "/org/bluez/hci0/dev_88_OF_10_96_D3_20",
+  "pincode": 327142
+}
+</pre>
+
+If pairing is canceled or fails:
+
+<pre>
+{
+  "action": "canceled_pairing"
+}
+</pre>