summaryrefslogtreecommitdiffstats
path: root/README.md
diff options
context:
space:
mode:
authorMatt Ranostay <matt.ranostay@konsulko.com>2018-10-30 19:41:53 -0700
committerMatt Ranostay <matt.ranostay@konsulko.com>2018-11-12 03:58:47 -0800
commit93f9937300ce2ae1f45d3362d6c1a3180e0743a8 (patch)
tree49983702697c8f0437b7fcff22b0255d3ced0e13 /README.md
parent45d4198af0c314cdcd3d489429953a5b93de988b (diff)
binding: bluetooth: initial commit of binding rewrite
Bug-AGL: SPEC-1630 Change-Id: I33cfec70283fa29f47b76f9e6be3e8e6cd6a2f54 Signed-off-by: Matt Ranostay <matt.ranostay@konsulko.com>
Diffstat (limited to 'README.md')
-rw-r--r--README.md217
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>