snappy-hwe-snaps

Merge ~kzapalowicz/snappy-hwe-snaps/+git/bluez:feature/docs into ~snappy-hwe-team/snappy-hwe-snaps/+git/bluez:master

  1. Git
  2. lp:~kzapalowicz/snappy-hwe-snaps/+git/bluez
  3. feature/docs
  4. Merge into master
Proposed by Konrad Zapałowicz
Status: Merged
Approved by: Jim Hodapp
Approved revision: a77dfb5e55591f25479b7a75fc9f75797e5d4487
Merged at revision: 38900317e8978030702a05ea8cc00d49285a7abc
Proposed branch: ~kzapalowicz/snappy-hwe-snaps/+git/bluez:feature/docs
Merge into: ~snappy-hwe-team/snappy-hwe-snaps/+git/bluez:master
Diff against target: 1758 lines (+1312/-310)
22 files modified
dev/null (+0/-308)
docs/bluetooth-on-ubuntu-core.md (+42/-0)
docs/index.md (+34/-0)
docs/install-bluez.md (+46/-0)
docs/metadata.yaml (+60/-0)
docs/reference/available-commands.md (+45/-0)
docs/reference/dbus-api.md (+9/-0)
docs/reference/enablement/introduction.md (+21/-0)
docs/reference/enablement/kernel-configuration-options.md (+109/-0)
docs/reference/enablement/snapping-bluetooth-enabled-application.md (+52/-0)
docs/reference/enablement/supported-kernels.md (+36/-0)
docs/reference/gatt-services.md (+95/-0)
docs/reference/introduction.md (+33/-0)
docs/reference/pairing/inbound.md (+56/-0)
docs/reference/pairing/introduction.md (+59/-0)
docs/reference/pairing/outbound.md (+142/-0)
docs/reference/sending-files.md (+200/-0)
docs/reference/using-prerequisites.md (+95/-0)
docs/release-notes.md (+13/-0)
docs/report-bug.md (+72/-0)
docs/troubleshoot/faq.md (+93/-0)
snapcraft.yaml (+0/-2)
Reviewer Review Type Date Requested Status
Jim Hodapp (community) Approve
System Enablement Bot continuous-integration Approve
Konrad Zapałowicz (community) just-a-test-2 Needs Fixing
Simon Fels Needs Fixing
Review via email: mp+319770@code.launchpad.net

Description of the change

Add documentation for bluez to docs.ubuntu.com.

To post a comment you must log in.
Revision history for this message
System Enablement Bot (system-enablement-ci-bot) wrote :

FAILED: Continuous integration, rev:14cd8d94fea34e18bc36caa390ecec29ab6b31fc
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/1294/
Executed test runs:
    FAILURE: https://jenkins.canonical.com/system-enablement/job/generic-build-snap-worker/463/console
    None: https://jenkins.canonical.com/system-enablement/job/generic-update-snap-mp/1202/console
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/generic-cleanup-snap/125

Click here to trigger a rebuild:
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/1294/rebuild

review: Needs Fixing (continuous-integration)
Revision history for this message
System Enablement Bot (system-enablement-ci-bot) wrote :

FAILED: Continuous integration, rev:352c3b090dbb04dacfa308ad721a6a4d12fa91c0
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/1295/
Executed test runs:
    FAILURE: https://jenkins.canonical.com/system-enablement/job/generic-build-snap-worker/464/console
    None: https://jenkins.canonical.com/system-enablement/job/generic-update-snap-mp/1203/console
    None: https://jenkins.canonical.com/system-enablement/job/generic-cleanup-snap/126/console

Click here to trigger a rebuild:
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/1295/rebuild

review: Needs Fixing (continuous-integration)
Revision history for this message
Simon Fels (morphis) wrote :

LGTM

review: Approve
Revision history for this message
Simon Fels (morphis) wrote :

Sorry, this was for the wrong MP :-)

review: Needs Information
Revision history for this message
Konrad Zapałowicz (kzapalowicz) wrote :

> Sorry, this was for the wrong MP :-)

haha, my first thought was: wow this guy reads fast :-)

Revision history for this message
Matteo Croce (teknoraver) :
Revision history for this message
Simon Fels (morphis) :
review: Needs Fixing
Revision history for this message
Jim Hodapp (jhodapp) wrote :

Several changes inline below. I only got about half way through this and need to jump on to another high priority task. I would still like to finish proof-reading this though, so please don't merge this yet.

review: Needs Fixing
Revision history for this message
System Enablement Bot (system-enablement-ci-bot) wrote :

FAILED: Continuous integration, rev:6b067925dec3e45f18b36e747237bad1af0c64c0
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/1316/
Executed test runs:
    FAILURE: https://jenkins.canonical.com/system-enablement/job/generic-build-snap-worker/495/console
    None: https://jenkins.canonical.com/system-enablement/job/generic-update-snap-mp/1224/console
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/generic-cleanup-snap/154

Click here to trigger a rebuild:
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/1316/rebuild

review: Needs Fixing (continuous-integration)
Revision history for this message
System Enablement Bot (system-enablement-ci-bot) wrote :

FAILED: Continuous integration, rev:33943fa9cc6507405530f5299cbe666760348b3c
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/1317/
Executed test runs:
    FAILURE: https://jenkins.canonical.com/system-enablement/job/generic-build-snap-worker/496/console
    None: https://jenkins.canonical.com/system-enablement/job/generic-update-snap-mp/1225/console
    None: https://jenkins.canonical.com/system-enablement/job/generic-cleanup-snap/155/console

Click here to trigger a rebuild:
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/1317/rebuild

review: Needs Fixing (continuous-integration)
Revision history for this message
System Enablement Bot (system-enablement-ci-bot) wrote :

FAILED: Continuous integration, rev:81024f1bb17ab44ab14757c8f8a551f6e5e8045a
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/1318/
Executed test runs:
    FAILURE: https://jenkins.canonical.com/system-enablement/job/generic-build-snap-worker/497/console
    None: https://jenkins.canonical.com/system-enablement/job/generic-update-snap-mp/1226/console
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/generic-cleanup-snap/156

Click here to trigger a rebuild:
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/1318/rebuild

review: Needs Fixing (continuous-integration)
Revision history for this message
System Enablement Bot (system-enablement-ci-bot) wrote :

FAILED: Continuous integration, rev:4222901dcd45f106e169ceb4a34f68deb9dfd6b5
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/1326/
Executed test runs:
    FAILURE: https://jenkins.canonical.com/system-enablement/job/generic-build-snap-worker/515/console
    None: https://jenkins.canonical.com/system-enablement/job/generic-update-snap-mp/1233/console
    None: https://jenkins.canonical.com/system-enablement/job/generic-cleanup-snap/171/console

Click here to trigger a rebuild:
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/1326/rebuild

review: Needs Fixing (continuous-integration)
Revision history for this message
System Enablement Bot (system-enablement-ci-bot) wrote :

FAILED: Continuous integration, rev:053d2a2ff424850bb80fb66430355b3b1f380905
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/1328/
Executed test runs:
    FAILURE: https://jenkins.canonical.com/system-enablement/job/generic-build-snap-worker/517/console
    None: https://jenkins.canonical.com/system-enablement/job/generic-update-snap-mp/1236/console
    None: https://jenkins.canonical.com/system-enablement/job/generic-cleanup-snap/174/console

Click here to trigger a rebuild:
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/1328/rebuild

review: Needs Fixing (continuous-integration)
Revision history for this message
System Enablement Bot (system-enablement-ci-bot) wrote :

FAILED: Continuous integration, rev:3f5a6fa18099b17235768a8075d026cb7f6079e6
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/1332/
Executed test runs:
    FAILURE: https://jenkins.canonical.com/system-enablement/job/generic-build-snap-worker/521/console
    None: https://jenkins.canonical.com/system-enablement/job/generic-update-snap-mp/1239/console
    None: https://jenkins.canonical.com/system-enablement/job/generic-cleanup-snap/177/console

Click here to trigger a rebuild:
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/1332/rebuild

review: Needs Fixing (continuous-integration)
Revision history for this message
System Enablement Bot (system-enablement-ci-bot) wrote :

FAILED: Continuous integration, rev:7a9ff68dc48d295a96854822e14cfbb9fc25d505
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/1334/
Executed test runs:
    FAILURE: https://jenkins.canonical.com/system-enablement/job/generic-build-snap-worker/523/console
    None: https://jenkins.canonical.com/system-enablement/job/generic-update-snap-mp/1242/console
    None: https://jenkins.canonical.com/system-enablement/job/generic-cleanup-snap/180/console

Click here to trigger a rebuild:
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/1334/rebuild

review: Needs Fixing (continuous-integration)
Revision history for this message
System Enablement Bot (system-enablement-ci-bot) wrote :

PASSED: Continuous integration, rev:11cbfd12ffb5587fb5c07fc5afda7e9218b9cca1
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/1342/
Executed test runs:
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/generic-build-snap-worker/541
    None: https://jenkins.canonical.com/system-enablement/job/generic-update-snap-mp/1250/console
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/generic-test-snap/1176
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/generic-cleanup-snap/197

Click here to trigger a rebuild:
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/1342/rebuild

review: Approve (continuous-integration)
Revision history for this message
Konrad Zapałowicz (kzapalowicz) :
review: Needs Fixing (just-a-test)
Revision history for this message
Konrad Zapałowicz (kzapalowicz) :
review: Needs Fixing (just-a-test-2)
Revision history for this message
Simon Fels (morphis) :
Revision history for this message
Jim Hodapp (jhodapp) wrote :

Some more changes needed. I didn't quite get through the entire thing, probably 3/4. There's a lot here to review. Looking good, we'll get this into great shape soon enough.

review: Needs Fixing
Revision history for this message
Jim Hodapp (jhodapp) :
review: Needs Fixing
Revision history for this message
Jim Hodapp (jhodapp) wrote :

Ok, finally got through the entire thing. Several comments inline below.

review: Needs Fixing
Revision history for this message
System Enablement Bot (system-enablement-ci-bot) wrote :

PASSED: Continuous integration, rev:b07cfa31b20dbbc150bc7107da0a90f3089da062
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/1400/
Executed test runs:
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/generic-build-snap-worker/769
    None: https://jenkins.canonical.com/system-enablement/job/generic-update-snap-mp/1307/console
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/generic-test-snap/1396
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/generic-cleanup-snap/412

Click here to trigger a rebuild:
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/1400/rebuild

review: Approve (continuous-integration)
Revision history for this message
Jim Hodapp (jhodapp) wrote :

One final fix needed from me.

review: Needs Fixing
Revision history for this message
System Enablement Bot (system-enablement-ci-bot) wrote :

PASSED: Continuous integration, rev:a77dfb5e55591f25479b7a75fc9f75797e5d4487
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/1409/
Executed test runs:
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/generic-build-snap-worker/788
    None: https://jenkins.canonical.com/system-enablement/job/generic-update-snap-mp/1317/console
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/generic-test-snap/1418
    None: https://jenkins.canonical.com/system-enablement/job/generic-cleanup-snap/432/console

Click here to trigger a rebuild:
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/1409/rebuild

review: Approve (continuous-integration)
Revision history for this message
Jim Hodapp (jhodapp) wrote :

LGTM

review: Approve

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1diff --git a/doc/overview.md b/doc/overview.md
2deleted file mode 100644
3index 47cd50b..0000000
4--- a/doc/overview.md
5+++ /dev/null
6@@ -1,308 +0,0 @@
7-Overview
8-========
9-
10-This document gives a short overview of what is possible with the
11-bluetooth snap at the moment.
12-
13-It is based on the BlueZ bluetooth stack and we're based on the 5.37
14-release. For more details about BlueZ itself see its homepage at
15-http://www.bluez.org
16-
17-To easily interact with the BlueZ service the snap provides a small
18-utility called bluetoothctl which can be started from the command
19-line. The use in different scenarios will be explained in the
20-following sections.
21-
22-NOTE: The bluetoothctl utility used on the examples below just uses
23-the DBus APIs provided by the BlueZ service. It does nothing else.
24-The DBus APIs of the BlueZ service are available at
25-
26- https://git.kernel.org/cgit/bluetooth/bluez.git/tree/doc
27-
28-There are also various small python script examples to play with the
29-DBus API at
30-
31- https://git.kernel.org/cgit/bluetooth/bluez.git/tree/test
32-
33-# Power management and device discovery
34-
35-1. Start up bluetoothctl
36-
37-```
38-$ bluetoothctl
39-[NEW] Controller 1C:C3:E4:79:43:4C localhost.localdomain [default]
40-[bluetooth]#
41-```
42-
43-2. Power on the found blutooth controller
44-
45-```
46-[bluetooth]# power on
47-[CHG] Controller 5C:C5:D4:39:40:4E Powered: yes
48-```
49-
50-3. Start scanning for other Bluetooth devices
51-
52-```
53-[bluetooth]# scan on
54-Discovery started
55-[CHG] Controller 5C:C5:D4:39:40:4E Discovering: yes
56-[NEW] Device 5C:31:3E:71:0C:E7 5C-31-3E-71-0C-E7
57-```
58-Here we've found one device. It's MAC address is revevant in the next
59-steps.
60-
61-4. We can now show various information about the device we've found
62-
63-```
64-[bluetooth]# info 5C:31:3E:71:0C:E7
65-Device 5C:31:3E:71:0C:E7
66- Alias: 5C-31-3E-71-0C-E7
67- Paired: no
68- Trusted: no
69- Blocked: no
70- Connected: no
71- LegacyPairing: no
72- UUID: Vendor specific (0d27ffff-f0d4-469d-afd3-605a6ebbdb13)
73- ManufacturerData Key: 0xd0d1
74- ManufacturerData Value: 0x01
75- ManufacturerData Value: 0x00
76- ManufacturerData Value: 0x00
77- ManufacturerData Value: 0x00
78- ManufacturerData Value: 0x08
79- ManufacturerData Value: 0x00
80- RSSI: -52
81-```
82-
83-NOTE: This doesn't tell us which type of device (BR/EDR or LE) we've
84-found. All devices are considered equal in BlueZ. However the available
85-information and profiles will differ. In the example above we have a LE
86-device with a vendor specific profile. Also as we never connected yet
87-we don't know fully which profiles the device provide.
88-
89-# Pairing with other devices
90-
91-To pair with other devices BlueZ uses an agent-style dbus API. See the
92-following links for more details on this:
93-
94- * https://git.kernel.org/cgit/bluetooth/bluez.git/tree/doc/agent-api.txt
95- * https://git.kernel.org/cgit/bluetooth/bluez.git/tree/doc/device-api.txt
96-
97-Within the bluetoothctl utility we can register such an agent with a
98-specific IO capability with the BlueZ service and then process any
99-further pairing operation.
100-
101-If no agent is registered with BlueZ and a pairing operation happens
102-BlueZ will consider the IO capability as NoInputNoOutput and try to
103-pair with the remove device without further user interaction.
104-
105-NOTE: If using NoInputNoOutput this results in an unauthenticated
106-communication link with the remote device and will always use the
107-JustWorks method.
108-
109-In the following example we will register an agent with the IO
110-capability DisplayYesNo.
111-
112-1. Make sure the device you want to pair with is available and
113- turned on. You can with the following command if the snappy
114- devices has found that device:
115-
116-```
117-[bluetooth]# devices
118-Device AC:73:13:74:03:E6 Aquaris E4.5
119-```
120-
121-2. Register our agent with the BlueZ service (we're using the
122- DisplayYesNo capability here but you can use any other
123- capability too)
124-
125-```
126-[bluetooth]# agent DisplayYesNo
127-Agent registered
128-```
129-
130-3. Initiate the pairing process with the remote device
131-
132-```
133-[bluetooth]# pair AC:73:13:74:03:E6
134-Attempting to pair with AC:73:13:74:03:E6
135-```
136-
137-In the simplest case both devices choose the JustWorks pairing method
138-and no further user interaction is required. If further user
139-interaction is need the bluetootctl utility will prompt you for that.
140-
141-For the JustWorks case the further output looks like
142-
143-```
144-[CHG] Device AC:73:13:74:03:E6 Connected: yes
145-[CHG] Device AC:73:13:74:03:E6 UUIDs: 00001104-0000-1000-8000-00805f9b34fb
146-[CHG] Device AC:73:13:74:03:E6 UUIDs: 00001105-0000-1000-8000-00805f9b34fb
147-[CHG] Device AC:73:13:74:03:E6 UUIDs: 00001106-0000-1000-8000-00805f9b34fb
148-[CHG] Device AC:73:13:74:03:E6 UUIDs: 0000110a-0000-1000-8000-00805f9b34fb
149-[CHG] Device AC:73:13:74:03:E6 UUIDs: 0000110b-0000-1000-8000-00805f9b34fb
150-[CHG] Device AC:73:13:74:03:E6 UUIDs: 0000110c-0000-1000-8000-00805f9b34fb
151-[CHG] Device AC:73:13:74:03:E6 UUIDs: 0000110e-0000-1000-8000-00805f9b34fb
152-[CHG] Device AC:73:13:74:03:E6 UUIDs: 0000111e-0000-1000-8000-00805f9b34fb
153-[CHG] Device AC:73:13:74:03:E6 UUIDs: 0000112f-0000-1000-8000-00805f9b34fb
154-[CHG] Device AC:73:13:74:03:E6 UUIDs: 00001132-0000-1000-8000-00805f9b34fb
155-[CHG] Device AC:73:13:74:03:E6 UUIDs: 00001133-0000-1000-8000-00805f9b34fb
156-[CHG] Device AC:73:13:74:03:E6 UUIDs: 00001200-0000-1000-8000-00805f9b34fb
157-[CHG] Device AC:73:13:74:03:E6 UUIDs: 00001800-0000-1000-8000-00805f9b34fb
158-[CHG] Device AC:73:13:74:03:E6 UUIDs: 00001801-0000-1000-8000-00805f9b34fb
159-[CHG] Device AC:73:13:74:03:E6 UUIDs: 00005005-0000-1000-8000-0002ee000001
160-[CHG] Device AC:73:13:74:03:E6 Paired: yes
161-Pairing successful
162-[CHG] Device AC:73:13:74:03:E6 Connected: no
163-[CHG] Device AC:73:13:74:03:E6 RSSI: -65
164-```
165-
166-The device is now marked as paired. The switch from connected to not
167-connected happens cause BlueZ creates a L2CAP connection to perform
168-further SDP requests to find out about all the profiles the remote
169-device supports. It will not try to automatically connect any of the
170-profiles. However it is possible that the remote device starts to
171-initiate a connection.
172-
173-4. As we're now paired with the remote device we can look at its
174- provided profiles again which is now extended.
175-
176-```
177-[bluetooth]# info AC:73:13:74:03:E6
178-Device AC:73:13:74:03:E6
179- Name: Aquaris E4.5
180- Alias: Aquaris E4.5
181- Class: 0x3c0000
182- Paired: yes
183- Trusted: no
184- Blockcked: no
185- Connected: no
186- LegacyPairing: no
187- UUID: IrMC Sync (00001104-0000-1000-8000-00805f9b34fb)
188- UUID: OBEX Object Push (00001105-0000-1000-8000-00805f9b34fb)
189- UUID: OBEX File Transfer (00001106-0000-1000-8000-00805f9b34fb)
190- UUID: Audio Source (0000110a-0000-1000-8000-00805f9b34fb)
191- UUID: Audio Sink (0000110b-0000-1000-8000-00805f9b34fb)
192- UUID: A/V Remote Controllerol Target (0000110c-0000-1000-8000-00805f9b34fb)
193- UUID: A/V Remote Controllerolrol (0000110e-0000-1000-8000-00805f9b34fb)
194- UUID: Handsfree (0000111e-0000-1000-8000-00805f9b34fb)
195- UUID: Phonebook Acceptess Server (0000112f-0000-1000-8000-00805f9b34fb)
196- UUID: Message Acceptessss Server (00001132-0000-1000-8000-00805f9b34fb)
197- UUID: Message Notifyification Se.. (00001133-0000-1000-8000-00805f9b34fb)
198- UUID: PnP Information (00001200-0000-1000-8000-00805f9b34fb)
199- UUID: Generic Acceptessssccess Profile (00001800-0000-1000-8000-00805f9b34fb)
200- UUID: Generic Attribute Profile (00001801-0000-1000-8000-00805f9b34fb)
201- UUID: Vendor specific (00005005-0000-1000-8000-0002ee000001)
202- Modalias: userb:v1D6Bp0246d0522
203- RSSI: -65
204- TxPower: 24
205-
206-# Connect with HID Keyboard
207-
208-NOTE - this has only been tested on a RiPi2.
209-
210-In this example we want to connect a traditional BT keyboard. To do
211-so follow the instructions from the previous example for pairing.
212-
213-Once the keyboard has been successfully paired:
214-
215-1. Setup the keyboard as trusted
216-
217-```
218-[bluetooth]# connect 5C:31:3E:71:0C:E7
219-Attempting to connect to 5C:31:3E:71:0C:E7
220-[CHG] Device 5C:31:3E:71:0C:E7 Connected: yes
221-Connection successful
222-```
223-
224-At this point, you should be able to use the BT device for console input.
225-
226-# Connect with LE devices
227-
228-In this example we want to connect with a LE device and explore its
229-provided GATT services. The uses LE device in this example provides
230-a number of vendor specific GATT services but also the standard
231-battery GATT service.
232-
233-1. Connect with the discovered LE device
234-
235-```
236-[bluetooth]# connect 5C:31:3E:71:0C:E7
237-Attempting to connect to 5C:31:3E:71:0C:E7
238-[CHG] Device 5C:31:3E:71:0C:E7 Connected: yes
239-Connection successful
240-```
241-
242-2. As soon as BlueZ has discovered which GATT services are available
243- the bluetoothctl utility will print out these
244-
245-```
246-[CHG] Device 5C:31:3E:71:0C:E7 UUIDs: 00001800-0000-1000-8000-00805f9b34fb
247-[CHG] Device 5C:31:3E:71:0C:E7 UUIDs: 00001801-0000-1000-8000-00805f9b34fb
248-[CHG] Device 5C:31:3E:71:0C:E7 UUIDs: 0000180f-0000-1000-8000-00805f9b34fb
249-[CHG] Device 5C:31:3E:71:0C:E7 UUIDs: 0d271100-f0d4-469d-afd3-605a6ebbdb13
250-[CHG] Device 5C:31:3E:71:0C:E7 UUIDs: 0d27fa01-f0d4-469d-afd3-605a6ebbdb13
251-[CHG] Device 5C:31:3E:71:0C:E7 UUIDs: 0d27fa60-f0d4-469d-afd3-605a6ebbdb13
252-[CHG] Device 5C:31:3E:71:0C:E7 UUIDs: 0d27ffc0-f0d4-469d-afd3-605a6ebbdb13
253-[NEW] Service /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0010 Vendor specific (Primary)
254-[NEW] Characteristic /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0010/char0011 Vendor specific
255-[NEW] Characteristic /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0010/char0013 Vendor specific
256-[NEW] Characteristic /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0010/char0015 Vendor specific
257-[NEW] Characteristic /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0010/char0017 Vendor specific
258-[NEW] Characteristic /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0010/char0019 Vendor specific
259-[NEW] Characteristic /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0010/char001b Vendor specific
260-[NEW] Characteristic /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0010/char001d Vendor specific
261-[NEW] Service /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service001f Vendor specific (Primary)
262-[NEW] Characteristic /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service001f/char0020 Vendor specific
263-[NEW] Characteristic /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service001f/char0022 Vendor specific
264-[NEW] Characteristic /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service001f/char0024 Vendor specific
265-[NEW] Characteristic /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service001f/char0026 Vendor specific
266-[NEW] Descriptor /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service001f/char0026/desc0028 Client Characteristic Configuration
267-[NEW] Service /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0029 Battery Service (Primary)
268-[NEW] Characteristic /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0029/char002a Battery Level
269-[NEW] Descriptor /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0029/char002a/desc002c Client Characteristic Configuration
270-[NEW] Service /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service002d Vendor specific (Primary)
271-[NEW] Characteristic /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service002d/char002e Vendor specific
272-[NEW] Descriptor /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service002d/char002e/desc0030 Client Characteristic Configuration
273-[NEW] Descriptor /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service002d/char002e/desc0031 Characteristic User Description
274-[NEW] Service /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0032 Vendor specific (Primary)
275-[NEW] Characteristic /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0032/char0033 Vendor specific
276-[NEW] Descriptor /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0032/char0033/desc0035 Client Characteristic Configuration
277-[NEW] Descriptor /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0032/char0033/desc0036 Characteristic User Description
278-[NEW] Characteristic /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0032/char0037 Vendor specific
279-[NEW] Descriptor /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0032/char0037/desc0039 Client Characteristic Configuration
280-[NEW] Descriptor /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0032/char0037/desc003a Characteristic User Description
281-[NEW] Characteristic /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0032/char003b Vendor specific
282-[NEW] Descriptor /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0032/char003b/desc003d Client Characteristic Configuration
283-[NEW] Descriptor /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0032/char003b/desc003e Characteristic User Description
284-[CHG] Device 5C:31:3E:71:0C:E7 GattServices: /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0010
285-[CHG] Device 5C:31:3E:71:0C:E7 GattServices: /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service001f
286-[CHG] Device 5C:31:3E:71:0C:E7 GattServices: /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0029
287-[CHG] Device 5C:31:3E:71:0C:E7 GattServices: /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service002d
288-[CHG] Device 5C:31:3E:71:0C:E7 GattServices: /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0032
289-[CHG] Device 5C:31:3E:71:0C:E7 Name: X4-LIFE Xmarty 2.0
290-[CHG] Device 5C:31:3E:71:0C:E7 Alias: X4-LIFE Xmarty 2.0
291-```
292-
293-3. We can now select specific characteristics and read their values
294- or if possible also write them. In this example we select the
295- battery level characteristic from the battery GATT service.
296-
297-```
298-[5C-31-3E-71-0C-E7]# select-attribute /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0029/char002a
299-[X4-LIFE Xmarty 2.0:/service0029/char002a]# read
300-Attempting to read /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0029/char002a
301-[CHG] Attribute /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0029/char002a Value: 0x49
302- 49
303-```
304-
305-4. We can also register us to receive notifications when the value
306- of a characteristic changes
307-
308-```
309-[X4-LIFE Xmarty 2.0:/service0029/char002a]# notify on
310-[CHG] Attribute /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0029/char002a Notifying: yes
311-Notify started
312-```
313-This will now notify us whenever the value of the selected
314-characteristic changes.
315diff --git a/docs/bluetooth-on-ubuntu-core.md b/docs/bluetooth-on-ubuntu-core.md
316new file mode 100644
317index 0000000..4f43999
318--- /dev/null
319+++ b/docs/bluetooth-on-ubuntu-core.md
320@@ -0,0 +1,42 @@
321+---
322+title: "Bluetooth on Ubuntu Core"
323+table_of_contents: True
324+---
325+
326+# Ubuntu Core Bluetooth Interfaces
327+
328+Bluetooth on Ubuntu Core is provided by the BlueZ stack which is an official
329+Linux Bluetooth protocol stack. The lower-level part of it comes with the kernel
330+snap while the user-space portion can be installed as a separate snap.
331+
332+## The Bluetooth interfaces on Ubuntu Core
333+
334+On Ubuntu Core there are two interfaces which define the communication of the
335+Bluetooth stack:
336+
337+ * bluetooth-control
338+ * bluez
339+
340+You can learn more on the [interfaces
341+documentation](https://docs.ubuntu.com/core/en/reference/interfaces/index)
342+
343+Note that unlike the *bluetooth-control* interface the *bluez* interface is not
344+installed by the *core* snap, neither the *gadget* nor *kernel*. It shall be
345+installed by the application snap.
346+
347+### Putting it all together
348+
349+As you know now there are two Bluetooth related interfaces on Ubuntu Core, the:
350+*bluetooth-control* and *bluez*. One of them is provided by the *core* snap
351+while the another is provided by the application snap.
352+
353+On a system without *bluez* snap installed, type:
354+
355+```
356+$ snap interfaces | grep blue
357+:bluetooth-control -
358+```
359+
360+Observe that there is a *bluetooth-control* slot provided by the core snap. This
361+is unlike to *bluez* because no snap exists which provides a slot based on the
362+*bluez* interface. You need an application snap to reveal it.
363diff --git a/docs/index.md b/docs/index.md
364new file mode 100644
365index 0000000..2c3ad49
366--- /dev/null
367+++ b/docs/index.md
368@@ -0,0 +1,34 @@
369+---
370+title: "About BlueZ"
371+table_of_contents: False
372+---
373+
374+# About Bluetooth
375+
376+Bluetooth is a standard for wireless communication on short distances. It
377+standarized multiple profiles for different use-cases such as music streaming,
378+serial connections, message exchange, phone calls, and many others. It has been
379+first published in 1994 and since then has been updated several times. The
380+recent version called Bluetooth 5 is a major update and step forward towards
381+the IoT market and it's needs.
382+
383+Bluetooth is developed and published by the [Bluetooth Special Interest
384+Group](http://www.bluetooth.com/)
385+
386+# About BlueZ
387+
388+BlueZ is the official Linux Bluetooth stack. It provides, in it's modular way,
389+support for the core Bluetooth layers and protocols.
390+
391+Currently BlueZ consists of many separate modules:
392+
393+* Bluetooth kernel subsystem core
394+* L2CAP and SCO audio kernel layers
395+* RFCOMM, BNEP, CMTP and HIDP kernel implementations
396+* HCI UART, USB, PCMCIA and virtual device drivers
397+* General Bluetooth and SDP libraries and daemons
398+* Configuration and testing utilities
399+* Protocol decoding and analysis tools
400+
401+You can find more information about this on the BlueZ upstream homepage
402+[here](http://www.bluez.org/)
403diff --git a/docs/install-bluez.md b/docs/install-bluez.md
404new file mode 100644
405index 0000000..0f2a47a
406--- /dev/null
407+++ b/docs/install-bluez.md
408@@ -0,0 +1,46 @@
409+---
410+title: "Install bluez"
411+table_of_contents: True
412+---
413+
414+# Install bluez
415+
416+Install the *bluez* snap via:
417+
418+```
419+$ snap install bluez
420+```
421+
422+The snap is being downloaded and installed. Observe that the snap has been
423+installed like follows:
424+
425+```
426+$ snap install bluez
427+bluez 5.37-2 from 'canonical' installed
428+```
429+
430+The naming scheme for the *bluez* snap includes the current BlueZ version being
431+packaged in the snap (5.37 in this case) and the revision of the snap itself
432+(2nd in this case). Whenever the snap is updated but still provides BlueZ
433+version 5.37 the last digit will be incremented.
434+
435+The above output informs that BlueZ 5.37 has been installed on the system. This
436+effect is equivalent to typing
437+
438+```
439+$ sudo apt install bluez
440+```
441+
442+on a classic Ubuntu flavor that you run on your desktop or laptop computer.
443+
444+Again, let's list the interfaces:
445+
446+```
447+$ snap interfaces | grep blue
448+bluez:service bluez:client
449+:bluetooth-control -
450+$
451+```
452+
453+This time it lists the bluez:service slot and the bluez:client plug that are
454+provided by the *bluez* snap itself.
455diff --git a/docs/metadata.yaml b/docs/metadata.yaml
456new file mode 100644
457index 0000000..73dacac
458--- /dev/null
459+++ b/docs/metadata.yaml
460@@ -0,0 +1,60 @@
461+site_title: Bluetooth documentation
462+site_logo_url: https://assets.ubuntu.com/v1/c5cb0f8e-picto-ubuntu.svg
463+
464+navigation:
465+ - title: Introduction
466+ children:
467+ - title: About BlueZ
468+ location: index.md
469+ - title: Bluetooth on Ubuntu Core
470+ location: bluetooth-on-ubuntu-core.md
471+
472+ - title: Install & Configure
473+ children:
474+ - title: Install BlueZ
475+ location: install-bluez.md
476+
477+ - title: Reference
478+ children:
479+ - title: Introduction
480+ location: reference/introduction.md
481+ - title: Prerequisites
482+ location: reference/using-prerequisites.md
483+ - title: Commands
484+ location: reference/available-commands.md
485+ - title: DBus API
486+ location: reference/dbus-api.md
487+ - title: Pairing
488+ children:
489+ - title: Introduction
490+ location: reference/pairing/introduction.md
491+ - title: Outbound Pairing
492+ location: reference/pairing/outbound.md
493+ - title: Inbound Pairing
494+ location: reference/pairing/inbound.md
495+ - title: Sending Files
496+ location: reference/sending-files.md
497+ - title: Accessing GATT Services
498+ location: reference/gatt-services.md
499+ - title: Device Enablement
500+ children:
501+ - title: Introduction
502+ location: reference/enablement/introduction.md
503+ - title: Supported Linux Kernels
504+ location: reference/enablement/supported-kernels.md
505+ - title: Linux kernel configuration options
506+ location: reference/enablement/kernel-configuration-options.md
507+ - title: Snapping a Bluetooth Application
508+ location: reference/enablement/snapping-bluetooth-enabled-application.md
509+
510+ - title: Troubleshoot
511+ children:
512+ - title: FAQ
513+ location: troubleshoot/faq.md
514+
515+ - title: Release Notes
516+ location: release-notes.md
517+
518+ - title: Report a Bug
519+ location: report-bug.md
520+
521diff --git a/docs/reference/available-commands.md b/docs/reference/available-commands.md
522new file mode 100644
523index 0000000..d29dece
524--- /dev/null
525+++ b/docs/reference/available-commands.md
526@@ -0,0 +1,45 @@
527+---
528+title: "Available commands"
529+table_of_contents: True
530+---
531+
532+# Available Commands
533+
534+This section will describe which commands are provided by the *bluez* snap.
535+
536+## Commands
537+
538+The purpose of the *bluez* snap is to provide the BlueZ Bluetooth stack. Apart
539+from this it contains various tools shipped with BlueZ itself. The following
540+table lists the commands that are provided by the *bluez* snap:
541+
542+| Command | Short description |
543+|--------------|---------------------------------------------------------------|
544+| bluez | The *bluetoothd* Bluetooth daemon |
545+| obex | The *obexd* OBEX daemon |
546+| bluetoothctl | A command-line interface to the BlueZ |
547+| obexctl | A command-line interface to the BlueZ for file transfers |
548+| hciconfig | HCI device configuration utility |
549+| hcidump | Reads raw HCI data and prints it on screen |
550+| hciattach | Attach a serial UART to the BT stack as a transport interface |
551+| hcitool | Tool used to configure Bluetooth connections |
552+| sdptool | A tool to perform SDP queries on Bluetooth devices |
553+
554+There is a quick way of checking what a snap provides. To do this you can use
555+the snap scheme for exposing commands which is *snap_name.command*. To see
556+all the commands provided by the *bluez* snap type:
557+
558+```
559+$ bluez.<TAB><TAB>
560+```
561+
562+The double **TAB** indicates that you should hit the tab key twice for bash
563+auto-completion to kick in. Immediately you will see a list of
564+available commands:
565+
566+```
567+$ bluez.
568+bluez.bluetoothctl bluez.hciattach bluez.hciconfig bluez.hcidump
569+bluez.hcitool bluez.obexctl bluez.sdptool
570+$ bluez.
571+```
572diff --git a/docs/reference/dbus-api.md b/docs/reference/dbus-api.md
573new file mode 100644
574index 0000000..9efb36d
575--- /dev/null
576+++ b/docs/reference/dbus-api.md
577@@ -0,0 +1,9 @@
578+---
579+title: "DBus API"
580+table_of_contents: False
581+---
582+
583+# DBus API
584+
585+Documentation of the DBus API is provided by the BlueZ upstream project
586+[here](https://git.kernel.org/cgit/bluetooth/bluez.git/tree/doc)
587diff --git a/docs/reference/enablement/introduction.md b/docs/reference/enablement/introduction.md
588new file mode 100644
589index 0000000..5569bbc
590--- /dev/null
591+++ b/docs/reference/enablement/introduction.md
592@@ -0,0 +1,21 @@
593+---
594+title: "Introduction to Device Enablement with Bluetooth"
595+table_of_contents: True
596+---
597+
598+## Device Enablement with Bluetooth
599+
600+This page provides information about what are the requirements for an Ubuntu
601+Core system to support Bluetooth.
602+
603+The Linux kernel section will tell about the Linux kernel requirements for
604+having BlueZ up and running on Ubuntu Core based systems.
605+
606+The application development section will show what are the necessary bits in
607+the *snapcraft.yaml* to successfully snap an application that uses Bluetooth.
608+
609+You can quickly jump to the chapters using the list below:
610+
611+ - [Linux kernel supported versions](supported-kernels.html)
612+ - [Linux kernel configuration options](kernel-configuration-options.html)
613+ - [Snapping a Bluetooth application](snapping-bluetooth-enabled-application.html)
614diff --git a/docs/reference/enablement/kernel-configuration-options.md b/docs/reference/enablement/kernel-configuration-options.md
615new file mode 100644
616index 0000000..61cfff0
617--- /dev/null
618+++ b/docs/reference/enablement/kernel-configuration-options.md
619@@ -0,0 +1,109 @@
620+---
621+title: "Linux kernel configuration options"
622+table_of_contents: True
623+---
624+
625+# Linux Kernel Configuration Options
626+
627+This section lists the Linux kernel configuration options related to the
628+Bluetooth support. It is based on the Linux kernel v4.4.
629+
630+Note that the default Linux kernel for Ubuntu Core has al the necessary bits
631+enabled by default.
632+
633+Most of the Bluetooth systems will support *Classic* mode therefore you need
634+to make sure that the following options are selected.
635+
636+```
637+ [*] Networking support
638+ <M> Bluetooth subsystem support
639+ [*] Bluetooth Classic (BR/EDR) features
640+ <M> RFCOMM protocol support
641+ [*] RFCOMM TTY support
642+ <M> BNEP protocol support
643+ [*] Multicast filter
644+ [*] Protocol filter support
645+ <M> CMTP protocol support
646+ <M> HIDP protocol support
647+ [*] Bluetooth High Speed (HS) features
648+ [*] Bluetooth Low Energy (LE) features
649+ <M> Bluetooth 6LoWPAN support
650+ [ ] Bluetooth self testing support
651+ [*] Export Bluetooth internals in debugf
652+```
653+
654+Note that this is a general set and it might be further tweaked to match your
655+device use-cases and capabilities. For example, on devices that will not offer
656+networking over Bluetooth, a *BNEP* can be disabled.
657+
658+Note that if your Bluetooth controller (chip) supports Bluetooth Low Energy,
659+then leave the BLE related options selected or disable otherwise:
660+
661+```
662+ [*] Networking support
663+ <M> Bluetooth subsystem support
664+ [*] Bluetooth Low Energy (LE) features
665+ <M> Bluetooth 6LoWPAN support
666+```
667+
668+It is also important to remember about the [UHID
669+driver](https://lwn.net/Articles/508083/). It is needed for
670+Bluetooth Low Energy (a.k.a. Smart) keyboards and mice.
671+
672+```
673+Device Drivers
674+ HID support
675+ {M} HID bus support
676+ [*] Battery level reporting for HID devices
677+ [*] /dev/hidraw raw HID device support
678+ <M> User-space I/O driver support for HID subsystem
679+ <M> Generic HID driver
680+```
681+
682+Below are the Linux kenrel config options for reference. They are based on the
683+*Linux core16 4.4.0-1040-raspi2* kernel which is the official Ubuntu Core Linux
684+kernel for Raspberry Pi 2/3.
685+
686+```
687+CONFIG_NET=y
688+CONFIG_BT=m
689+CONFIG_BT_BREDR=y
690+CONFIG_BT_RFCOMM=m
691+CONFIG_BT_RFCOMM_TTY=y
692+CONFIG_BT_BNEP=m
693+CONFIG_BT_BNEP_MC_FILTER=y
694+CONFIG_BT_BNEP_PROTO_FILTER=y
695+CONFIG_BT_CMTP=m
696+CONFIG_BT_HIDP=m
697+CONFIG_BT_HS=y
698+CONFIG_BT_LE=y
699+CONFIG_BT_6LOWPAN=m
700+CONFIG_BT_DEBUGFS=y
701+
702+CONFIG_BT_HCIBCM203X=m
703+CONFIG_BT_HCIBFUSB=m
704+CONFIG_BT_HCIBPA10X=m
705+CONFIG_BT_HCIBTSDIO=m
706+CONFIG_BT_HCIBTUSB=m
707+CONFIG_BT_HCIBTUSB_BCM=y
708+CONFIG_BT_HCIBTUSB_RTL=y
709+CONFIG_BT_HCIUART=m
710+CONFIG_BT_HCIUART_3WIRE=y
711+CONFIG_BT_HCIUART_ATH3K=y
712+CONFIG_BT_HCIUART_BCM=y
713+CONFIG_BT_HCIUART_BCSP=y
714+CONFIG_BT_HCIUART_H4=y
715+CONFIG_BT_HCIUART_INTEL=y
716+CONFIG_BT_HCIUART_LL=y
717+CONFIG_BT_HCIUART_QCA=y
718+CONFIG_BT_HCIVHCI=m
719+
720+CONFIG_BT_ATH3K=m
721+CONFIG_BT_BCM=m
722+CONFIG_BT_INTEL=m
723+CONFIG_BT_MRVL=m
724+CONFIG_BT_MRVL_SDIO=m
725+CONFIG_BT_QCA=m
726+CONFIG_BT_RTL=m
727+CONFIG_BT_WILINK=m
728+```
729diff --git a/docs/reference/enablement/snapping-bluetooth-enabled-application.md b/docs/reference/enablement/snapping-bluetooth-enabled-application.md
730new file mode 100644
731index 0000000..460996f
732--- /dev/null
733+++ b/docs/reference/enablement/snapping-bluetooth-enabled-application.md
734@@ -0,0 +1,52 @@
735+---
736+title: "Snapping Bluetooth-enabled Application"
737+table_of_contents: True
738+---
739+
740+# Snapping Bluetooth-enabled Application
741+
742+This section will show what are the necessary bits in the *snapcraft.yaml* while
743+snapping an application that uses Bluetooth.
744+
745+## Bluetooth Interfaces
746+
747+There are two Bluetooth related interfaces available on Ubuntu Core.
748+
749+**bluez** interface that allows accessing the Bluetooth service through D-Bus
750+API
751+
752+**bluetooth-control** that can be used to talk to the kernel-side of the
753+Bluetooth stack directly.
754+
755+## Contents of snapcraft.yaml
756+
757+This section presents a *snapcraft.yaml* template for applications that use
758+Bluetooth.
759+
760+The *bluez* snap discussed previously is a somewhat complex thing because it
761+includes both the Bluetooth service (*bluetoothd* and *obexd*) and the client
762+applications (*bluetoothctl* and *obexctl*). Because of this it defines the
763+slots and plugs.
764+
765+The standalone Bluetooth application that could be used in place of
766+*bluetoothctl* needs to take care only of the client side. In fact all it has to
767+do is to define a *bluez* plug.
768+
769+In the example below the *foo* application defines a *client* plug that is
770+nothing more than a plug side of the *bluez* interface.
771+
772+```
773+plugs:
774+ client:
775+ interface: bluez
776+
777+apps:
778+ foo:
779+ command: "bin/foo-command"
780+ plugs: [client]
781+
782+```
783+
784+Note that if by any chance your application needs to talk directly to the chip,
785+then the *bluetooth-control* interface will suit these needs better than the
786+*bluez* one.
787diff --git a/docs/reference/enablement/supported-kernels.md b/docs/reference/enablement/supported-kernels.md
788new file mode 100644
789index 0000000..fea5b94
790--- /dev/null
791+++ b/docs/reference/enablement/supported-kernels.md
792@@ -0,0 +1,36 @@
793+---
794+title: "Linux Kernel Supported Versions"
795+table_of_contents: False
796+---
797+
798+# Linux Kernel Supported Versions
799+
800+The Ubuntu Core officially supports Linux kernel version 4.4 therefore any new
801+IoT device that is Ubuntu Core based should consider using it if possible.
802+Moreover this is a long term supported kernel by the Linux kernel community.
803+
804+Also, you could use an older version of the Linux kernel. Keep in mind however
805+that some features might not be available. For example you need at least Linux
806+kernel v3.13 to have the Bluetooth Low Energy functioning.
807+
808+Using an older kernel yet having good interoperability will most probably
809+require you to backport the Bluetooth part of the kernel from the newer release.
810+This can be easily done using
811+[Kernel Backports
812+Project](https://backports.wiki.kernel.org/index.php/Main_Page)
813+
814+In short:
815+
816+| Kernel version | Support Status |
817+|:--------------:|-----------------------------------------------------------|
818+| >= 4.4 | Will work out of the box |
819+| >= 3.13 | Ok for Bluetooth Classic and LE however consider backporting |
820+| >= 3.10 | Ok for Bluetooth Classic however consider backporting |
821+
822+The heart of Ubuntu Core is *snapd* which has some constraints on the kernel
823+version used. In particular it requires the newest AppArmor patches. Therefore,
824+when choosing a kernel please take a look at [sample
825+kernels](https://github.com/snapcore/sample-kernels) that have all the bits
826+necessary for *snapd* to run included. Also make sure to read the [Board
827+enablement
828+overview](https://docs.ubuntu.com/core/en/guides/build-device/board-enablement).
829diff --git a/docs/reference/gatt-services.md b/docs/reference/gatt-services.md
830new file mode 100644
831index 0000000..4737b9c
832--- /dev/null
833+++ b/docs/reference/gatt-services.md
834@@ -0,0 +1,95 @@
835+---
836+title: "Accessing GATT Services"
837+table_of_contents: True
838+---
839+
840+# Accessing GATT Services
841+
842+In this example we want to connect with a LE device and explore its
843+provided GATT services. The used LE device in this example provides
844+a number of vendor specific GATT services but also the standard
845+battery GATT service.
846+
847+First, connect with the discovered LE device by using the bluetoothctl command
848+
849+```
850+$ sudo bluetoothctl
851+[bluetooth]# connect 5C:31:3E:71:0C:E7
852+Attempting to connect to 5C:31:3E:71:0C:E7
853+[CHG] Device 5C:31:3E:71:0C:E7 Connected: yes
854+Connection successful
855+```
856+
857+As soon as BlueZ has discovered which GATT services are available the
858+bluetoothctl utility will print out the following:
859+
860+```
861+[CHG] Device 5C:31:3E:71:0C:E7 UUIDs: 00001800-0000-1000-8000-00805f9b34fb
862+[CHG] Device 5C:31:3E:71:0C:E7 UUIDs: 00001801-0000-1000-8000-00805f9b34fb
863+[CHG] Device 5C:31:3E:71:0C:E7 UUIDs: 0000180f-0000-1000-8000-00805f9b34fb
864+[CHG] Device 5C:31:3E:71:0C:E7 UUIDs: 0d271100-f0d4-469d-afd3-605a6ebbdb13
865+[CHG] Device 5C:31:3E:71:0C:E7 UUIDs: 0d27fa01-f0d4-469d-afd3-605a6ebbdb13
866+[CHG] Device 5C:31:3E:71:0C:E7 UUIDs: 0d27fa60-f0d4-469d-afd3-605a6ebbdb13
867+[CHG] Device 5C:31:3E:71:0C:E7 UUIDs: 0d27ffc0-f0d4-469d-afd3-605a6ebbdb13
868+[NEW] Service /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0010 Vendor specific (Primary)
869+[NEW] Characteristic /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0010/char0011 Vendor specific
870+[NEW] Characteristic /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0010/char0013 Vendor specific
871+[NEW] Characteristic /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0010/char0015 Vendor specific
872+[NEW] Characteristic /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0010/char0017 Vendor specific
873+[NEW] Characteristic /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0010/char0019 Vendor specific
874+[NEW] Characteristic /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0010/char001b Vendor specific
875+[NEW] Characteristic /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0010/char001d Vendor specific
876+[NEW] Service /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service001f Vendor specific (Primary)
877+[NEW] Characteristic /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service001f/char0020 Vendor specific
878+[NEW] Characteristic /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service001f/char0022 Vendor specific
879+[NEW] Characteristic /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service001f/char0024 Vendor specific
880+[NEW] Characteristic /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service001f/char0026 Vendor specific
881+[NEW] Descriptor /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service001f/char0026/desc0028 Client Characteristic Configuration
882+[NEW] Service /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0029 Battery Service (Primary)
883+[NEW] Characteristic /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0029/char002a Battery Level
884+[NEW] Descriptor /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0029/char002a/desc002c Client Characteristic Configuration
885+[NEW] Service /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service002d Vendor specific (Primary)
886+[NEW] Characteristic /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service002d/char002e Vendor specific
887+[NEW] Descriptor /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service002d/char002e/desc0030 Client Characteristic Configuration
888+[NEW] Descriptor /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service002d/char002e/desc0031 Characteristic User Description
889+[NEW] Service /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0032 Vendor specific (Primary)
890+[NEW] Characteristic /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0032/char0033 Vendor specific
891+[NEW] Descriptor /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0032/char0033/desc0035 Client Characteristic Configuration
892+[NEW] Descriptor /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0032/char0033/desc0036 Characteristic User Description
893+[NEW] Characteristic /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0032/char0037 Vendor specific
894+[NEW] Descriptor /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0032/char0037/desc0039 Client Characteristic Configuration
895+[NEW] Descriptor /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0032/char0037/desc003a Characteristic User Description
896+[NEW] Characteristic /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0032/char003b Vendor specific
897+[NEW] Descriptor /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0032/char003b/desc003d Client Characteristic Configuration
898+[NEW] Descriptor /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0032/char003b/desc003e Characteristic User Description
899+[CHG] Device 5C:31:3E:71:0C:E7 GattServices: /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0010
900+[CHG] Device 5C:31:3E:71:0C:E7 GattServices: /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service001f
901+[CHG] Device 5C:31:3E:71:0C:E7 GattServices: /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0029
902+[CHG] Device 5C:31:3E:71:0C:E7 GattServices: /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service002d
903+[CHG] Device 5C:31:3E:71:0C:E7 GattServices: /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0032
904+[CHG] Device 5C:31:3E:71:0C:E7 Name: X4-LIFE Xmarty 2.0
905+[CHG] Device 5C:31:3E:71:0C:E7 Alias: X4-LIFE Xmarty 2.0
906+```
907+
908+It is now possible to select specific characteristics and read their values or,
909+if possible, also write them. This example focuses on the battery level
910+characteristic from the battery GATT service.
911+
912+```
913+[5C-31-3E-71-0C-E7]# select-attribute /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0029/char002a
914+[X4-LIFE Xmarty 2.0:/service0029/char002a]# read
915+Attempting to read /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0029/char002a
916+[CHG] Attribute /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0029/char002a Value: 0x49
917+ 49
918+```
919+
920+It is also possible to receive notifications when the value of a characteristic
921+changes.
922+
923+```
924+[X4-LIFE Xmarty 2.0:/service0029/char002a]# notify on
925+[CHG] Attribute /org/bluez/hci0/dev_5C_31_3E_71_0C_E7/service0029/char002a Notifying: yes
926+Notify started
927+```
928+
929+This will now notify whenever the value of the selected characteristic changes.
930diff --git a/docs/reference/introduction.md b/docs/reference/introduction.md
931new file mode 100644
932index 0000000..aaa4119
933--- /dev/null
934+++ b/docs/reference/introduction.md
935@@ -0,0 +1,33 @@
936+---
937+title: "Introduction"
938+table_of_contents: False
939+---
940+
941+# Introduction
942+
943+This section gives a short overview of what is possible with the bluez snap
944+at the moment. It is not, however, Ubuntu Core specific and the steps described
945+here will work on any other Linux system with BlueZ installed on it regardless
946+if it is snap or classic (that is .deb, .rpm, .ebuild, or etc... based)
947+
948+To easily interact with the BlueZ service the snap provides a small
949+utility called bluetoothctl which can be started from the command
950+line. The use in different scenarios will be explained in the
951+following sections.
952+
953+**NOTE:** The bluetoothctl utility used on the examples below just uses
954+the DBus APIs provided by the BlueZ service.
955+
956+There are also various small python script examples to play with the
957+DBus API at
958+
959+[Test scripts](https://git.kernel.org/cgit/bluetooth/bluez.git/tree/test)
960+
961+In particular this section will discuss:
962+
963+* [Prerequisites](using-prerequisites.html)
964+* [Available commands](available-commands.md)
965+* [How to pair with remote devices](pairing/introduction.md)
966+* [How to send files using OPP](sending-files.md)
967+* [Accessing the GATT services](gatt-services.md)
968+* [Device Enablement with Bluetooth](enablement/introduction.md)
969diff --git a/docs/reference/pairing/inbound.md b/docs/reference/pairing/inbound.md
970new file mode 100644
971index 0000000..c3da3ef
972--- /dev/null
973+++ b/docs/reference/pairing/inbound.md
974@@ -0,0 +1,56 @@
975+---
976+title: "Inbound Pairing"
977+table_of_contents: True
978+---
979+
980+# Pairing From Remote Device
981+
982+In this scenario it is the remote device that is active in the pairing
983+procedure. It will search, discover and initiate pairing. The only thing that an
984+Ubuntu Core device has to make sure of is to be discoverable and pairable, as
985+this will allow the remote device to discover and initiate a connection with it.
986+
987+```
988+$ bluetoothctl
989+[bluetooth]# discoverable on
990+Changing discoverable on succeeded
991+[bluetooth]# pairable on
992+Changing pairable on succeeded
993+```
994+
995+At this stage the Ubuntu Core device is ready to be discovered.
996+It is important to register the pairing agent so that the authentication process
997+can be completed. Type:
998+
999+```
1000+$ bluetoothctl
1001+[bluetooth]# agent on
1002+Agent registered
1003+[bluetooth]# default-agent
1004+Default agent request successful
1005+```
1006+
1007+At this stage the Ubuntu Core device is ready to be discovered. Take your remote
1008+Bluetooth device and start the discovering process. After a short while you
1009+should see the Ubuntu Core device on the list of found devices. Initiate the
1010+pairing.
1011+
1012+Notice that bluetoothctl will display the pairing confirmation coming from
1013+the agent:
1014+
1015+```
1016+[CHG] Device 00:1A:7D:DA:71:08 Connected: yes
1017+Request confirmation
1018+[agent] Confirm passkey 687331 (yes/no):
1019+```
1020+
1021+The agent will require you to type yes or no depending on if you like to allow
1022+the devices to connect or not. Type yes here
1023+
1024+```
1025+[agent] Confirm passkey 687331 (yes/no): yes
1026+[CHG] Device 00:1A:7D:DA:71:08 Connected: no
1027+```
1028+
1029+At this stage the devices are paired and can be connected.
1030+
1031diff --git a/docs/reference/pairing/introduction.md b/docs/reference/pairing/introduction.md
1032new file mode 100644
1033index 0000000..43f9677
1034--- /dev/null
1035+++ b/docs/reference/pairing/introduction.md
1036@@ -0,0 +1,59 @@
1037+---
1038+title: "Introduction to Pairing"
1039+table_of_contents: True
1040+---
1041+
1042+# Introduction to Pairing
1043+
1044+This section teaches how to pair two Bluetooth devices using *bluetoothctl* -
1045+the command-line interface to BlueZ.
1046+
1047+## What is Pairing
1048+
1049+In Bluetooth terminology pairing is the process of making two devices know about
1050+each other. The key concept is about exchanging so called *link-keys* that are used to
1051+secure the communication. The pairing process involves authentication however
1052+due to the nature and variety of Bluetooth devices there will be different ways
1053+of confirming the pairing attempt:
1054+
1055+* Devices such as keyboards or car-kits will require authentication by PIN/passkey code
1056+* Other devices will provide a yes/no choice to the pairing attempt
1057+* Devices without an input interface such as headsets or speakers will not
1058+ require the user to confirm the pairing attempt at all
1059+
1060+Pairing with a remote device can be done in two ways due to the fact that it can
1061+be initiated from both endpoints. Both ways are described further in this
1062+section.
1063+
1064+* [Inbound pairing](inbound.html)
1065+* [Outbound pairing](outbound.html)
1066+
1067+## Handling Authentication Requests by BlueZ
1068+
1069+The pairing procedure includes an authentication that requires confirmation by
1070+the user. If you have ever used Bluetooth previously you probably remeber
1071+entering a pin code or answering a "would you like to connect yes/no" question.
1072+
1073+To pair with other devices BlueZ uses an agent-style DBus API. See the
1074+following links for more details on this:
1075+
1076+ * [Agent API](https://git.kernel.org/cgit/bluetooth/bluez.git/tree/doc/agent-api.txt)
1077+ * [Device API](https://git.kernel.org/cgit/bluetooth/bluez.git/tree/doc/device-api.txt)
1078+
1079+Within the bluetoothctl utility we can register such an agent with a
1080+specific IO capability with the BlueZ service and then process any
1081+further pairing operation.
1082+
1083+If no agent is registered with BlueZ and a pairing operation happens,
1084+BlueZ will try to pair with the remote device without further user interaction.
1085+
1086+The agent has to be registered explicitly by typing:
1087+
1088+```
1089+$ sudo bluetoothctl
1090+[bluetooth]# agent on
1091+Agent registered
1092+```
1093+
1094+The pairing section will walk you through the pairing procedure with a
1095+keyboard. It will require passcode authentication.
1096diff --git a/docs/reference/pairing/outbound.md b/docs/reference/pairing/outbound.md
1097new file mode 100644
1098index 0000000..4bca8ff
1099--- /dev/null
1100+++ b/docs/reference/pairing/outbound.md
1101@@ -0,0 +1,142 @@
1102+---
1103+title: "Outbound Pairing"
1104+table_of_contents: True
1105+---
1106+
1107+# Pairing from Ubuntu Core
1108+
1109+Having the *bluez* snap installed start the *bluetoothctl* tool which is a
1110+command-line interface to BlueZ.
1111+
1112+
1113+```
1114+$ sudo bluetoothctl
1115+```
1116+
1117+You should see the output similar to the following:
1118+
1119+
1120+```
1121+$ sudo bluez.bluetoothctl
1122+[NEW] Controller 00:1A:7D:DA:71:08 core16 [default]
1123+[NEW] Device 00:25:56:D1:36:6B ubuntu-0
1124+[bluetooth]#
1125+```
1126+
1127+The "[NEW] Controller" line displays the information about your Bluetooth chip.
1128+The "[NEW] Device" line displays the information about already known devices such
1129+as previously paired ones. Note that there might be multiple or no lines
1130+starting with [NEW] Device, as it depends on what happened prior. The
1131+last line is the *bluetoothctl* prompt.
1132+
1133+Since the pairing procedure will involve authentication by PIN, it is required
1134+to register with an authentication agent. The agent handles the PIN prompt. In
1135+order to do it type:
1136+
1137+
1138+```
1139+[bluetooth]# agent on
1140+```
1141+
1142+You should see the output like below that indicates that the agent has been
1143+successfully registered.
1144+
1145+
1146+```
1147+Agent registered
1148+[bluetooth]# default-agent
1149+Default agent request successful
1150+[bluetooth]#
1151+```
1152+
1153+Note that having the agent registered while performing pairing with a device
1154+that does not require user confirmation to the pairing attempt will have no
1155+negative impact and is safe to do so.
1156+
1157+At this point, you can proceed with scanning for remote Bluetooth devices. To
1158+do this type:
1159+
1160+```
1161+[bluetooth]# scan on
1162+```
1163+
1164+First you will see the confirmation that the discovery has been started
1165+
1166+```
1167+Discovery started
1168+[CHG] Controller 00:1A:7D:DA:71:08 Discovering: yes
1169+```
1170+
1171+Which is then followed with found device events that look like:
1172+
1173+```
1174+[NEW] Device 08:3E:8E:E6:79:47 annapurna
1175+[NEW] Device 00:25:56:D1:36:6B ubuntu-0
1176+....
1177+[NEW] Device <bluetooth address> <name>
1178+```
1179+
1180+The device discovery process will be stopped automatically the moment a pairing
1181+attempt is started.
1182+
1183+At this stage, the remote device has been discovered and is known, therefore it
1184+is now possible to pair with it. The target device is identified by its address,
1185+so make sure that you specify the correct one.
1186+
1187+Note that after a certain amount of time the device discovery results are
1188+invalidated. When this happens you see output like the following:
1189+
1190+```
1191+[DEL] Device 00:25:56:D1:36:6B ubuntu-0
1192+```
1193+
1194+If you still want to pair with this device then simply redo the
1195+device discovery step. Do *scan on* once again.
1196+
1197+Now do the device pairing:
1198+
1199+```
1200+[bluetooth]# pair 00:25:56:D1:36:6B
1201+```
1202+
1203+Both of the devices will try to establish a link and as it has been already
1204+described it might require authentication. This guide walks you through pairing
1205+with a keyboard, therefore, there will be PIN prompt unless you have skipped the
1206+agent registration. In that case the pairing will fail.
1207+
1208+You should see output like the following:
1209+
1210+```
1211+Attempting to pair with 00:25:56:D1:36:6B
1212+[CHG] Device 00:25:56:D1:36:6B Connected: yes
1213+Request confirmation
1214+[agent] Confirm passkey 687331 (yes/no):
1215+```
1216+
1217+Type *yes* or *no* depending on if you want the link to be established. Type
1218+*yes* here
1219+
1220+```
1221+[agent] Confirm passkey 687331 (yes/no): yes
1222+[CHG] Device 00:25:56:D1:36:6B UUIDs: 00001104-0000-1000-8000-00805f9b34fb
1223+[CHG] Device 00:25:56:D1:36:6B UUIDs: 00001105-0000-1000-8000-00805f9b34fb
1224+[CHG] Device 00:25:56:D1:36:6B UUIDs: 00001106-0000-1000-8000-00805f9b34fb
1225+[CHG] Device 00:25:56:D1:36:6B UUIDs: 0000110a-0000-1000-8000-00805f9b34fb
1226+[CHG] Device 00:25:56:D1:36:6B UUIDs: 0000110b-0000-1000-8000-00805f9b34fb
1227+[CHG] Device 00:25:56:D1:36:6B UUIDs: 0000110c-0000-1000-8000-00805f9b34fb
1228+[CHG] Device 00:25:56:D1:36:6B UUIDs: 0000110e-0000-1000-8000-00805f9b34fb
1229+[CHG] Device 00:25:56:D1:36:6B UUIDs: 00001112-0000-1000-8000-00805f9b34fb
1230+[CHG] Device 00:25:56:D1:36:6B UUIDs: 0000112f-0000-1000-8000-00805f9b34fb
1231+[CHG] Device 00:25:56:D1:36:6B UUIDs: 00001132-0000-1000-8000-00805f9b34fb
1232+[CHG] Device 00:25:56:D1:36:6B UUIDs: 00001133-0000-1000-8000-00805f9b34fb
1233+[CHG] Device 00:25:56:D1:36:6B UUIDs: 00001200-0000-1000-8000-00805f9b34fb
1234+[CHG] Device 00:25:56:D1:36:6B UUIDs: 00001800-0000-1000-8000-00805f9b34fb
1235+[CHG] Device 00:25:56:D1:36:6B UUIDs: 00001801-0000-1000-8000-00805f9b34fb
1236+[CHG] Device 00:25:56:D1:36:6B UUIDs: 00005005-0000-1000-8000-0002ee000001
1237+[CHG] Device 00:25:56:D1:36:6B Paired: yes
1238+Pairing successful
1239+[CHG] Device 00:25:56:D1:36:6B Connected: no
1240+```
1241+
1242+At this stage the devices are in a paired state and can be connected.
1243+
1244diff --git a/docs/reference/sending-files.md b/docs/reference/sending-files.md
1245new file mode 100644
1246index 0000000..85284ac
1247--- /dev/null
1248+++ b/docs/reference/sending-files.md
1249@@ -0,0 +1,200 @@
1250+---
1251+title: "Sending Files Using OPP"
1252+table_of_contents: True
1253+---
1254+
1255+# Using Bluetooth to Send Files on Ubuntu Core
1256+
1257+This section describes the required steps to be able to send files over
1258+Bluetooth using an Ubuntu Core device. It will focus on the [OBEX Object
1259+Push](https://www.bluetooth.org/docman/handlers/downloaddoc.ashx?doc_id=309007&amp;vId=346844)
1260+profile which is a standard Bluetooth profile for such a use case.
1261+
1262+## Prerequisites
1263+
1264+Make sure that:
1265+
1266+* The bluez snap is installed.
1267+* Service is up and running.
1268+* Both devices are paired.
1269+
1270+Refer to the previous sections in order to learn how to do it.
1271+
1272+The files will be sent to the server which is a Bluetooth-enabled device with
1273+the Object Push profile enabled. If this is not fulfilled then Ubuntu Core will
1274+fail to connect.
1275+
1276+The minimal set of the Bluetooth profiles that must be available on the server
1277+device is:
1278+
1279+| Profile | UUID |
1280+|------------------|:------:|
1281+| GAP Service | 0x1800 |
1282+| GATT Server | 0x1801 |
1283+| OBEX Object Push | 0x1105 |
1284+
1285+If you are unsure about which profiles are enabled, then check this using the
1286+*sdptool* utility:
1287+
1288+```
1289+% sdptool browse 00:1A:7D:DA:71:0F
1290+Browsing 00:1A:7D:DA:71:0F ...
1291+Service Name: GAP Service
1292+Service RecHandle: 0x10001
1293+Service Class ID List:
1294+  "Generic Access" (0x1800)
1295+Protocol Descriptor List:
1296+  "L2CAP" (0x0100)
1297+    PSM: 31
1298+  "ATT" (0x0007)
1299+    uint16: 0x0001
1300+    uint16: 0x0007
1301+Language Base Attr List:
1302+  code_ISO639: 0x656e
1303+  encoding:    0x6a
1304+  base_offset: 0x100
1305+
1306+Service Name: GATT Server
1307+Service RecHandle: 0x10002
1308+Service Class ID List:
1309+  "Generic Attribute" (0x1801)
1310+Protocol Descriptor List:
1311+  "L2CAP" (0x0100)
1312+    PSM: 31
1313+  "ATT" (0x0007)
1314+    uint16: 0x000c
1315+    uint16: 0x000f
1316+Language Base Attr List:
1317+  code_ISO639: 0x656e
1318+  encoding:    0x6a
1319+  base_offset: 0x100
1320+
1321+Failed to connect to SDP server on 00:1A:7D:DA:71:0F: Connection refused
1322+Service Name: OBEX Object Push
1323+Service RecHandle: 0x10004
1324+Service Class ID List:
1325+  "OBEX Object Push" (0x1105)
1326+Protocol Descriptor List:
1327+  "L2CAP" (0x0100)
1328+  "RFCOMM" (0x0003)
1329+    Channel: 1
1330+  "OBEX" (0x0008)
1331+Language Base Attr List:
1332+  code_ISO639: 0x656e
1333+  encoding:    0x6a
1334+  base_offset: 0x100
1335+Profile Descriptor List:
1336+  "OBEX Object Push" (0x1105)
1337+    Version: 0x0102
1338+```
1339+
1340+## Connect OPP Profile
1341+
1342+Make sure that the pairing is successfully completed. You can learn how to do it
1343+on the [Pairing page](pairing/introduction.html)
1344+
1345+Once the pairing is successfully completed, it is time to connect the OBEX
1346+Object Push profile. To interact with OBEX, the obexctl tool is used. Open
1347+another terminal and type
1348+
1349+```
1350+$ sudo bluez.obexctl
1351+```
1352+
1353+You will see output like this:
1354+
1355+```
1356+$ sudo obexctl
1357+[NEW] Client /org/bluez/obex
1358+[obex]#
1359+```
1360+
1361+This indicates that the OBEX client has been properly initialized and is
1362+awaiting interactive commands. The first thing to do is to get it connected to
1363+the remote server which is the device that has been paired in the previous
1364+step. Type:
1365+
1366+```
1367+[obex]# connect 00:25:56:D1:36:6B
1368+```
1369+
1370+You will see output like:
1371+
1372+```
1373+Attempting to connect to 00:25:56:D1:36:6B
1374+[NEW] Session /org/bluez/obex/client/session4 [default]
1375+[NEW] ObjectPush /org/bluez/obex/client/session4
1376+Connection successful
1377+[00:25:56:D1:36:6B]#
1378+```
1379+
1380+The above indicates that the connection has been established. Check the address
1381+of the remote device in the prompt. It is now possible to send files.
1382+
1383+## Sending Files
1384+
1385+In order to send files use the *send* command while connected to the OBEX Object
1386+Push profile. For sending a file type:
1387+
1388+```
1389+[00:25:56:D1:36:6B]# send <path to file>
1390+```
1391+
1392+Note that the file you are about to send should be accessible to the snap,
1393+therefore it must be placed in a readable location. For example:
1394+/var/snap/bluez/current.
1395+
1396+Also keep in mind that the regular use of the OPP shall be accomplished through
1397+the [D-Bus OBEX
1398+API](https://git.kernel.org/pub/scm/bluetooth/bluez.git/tree/doc/obex-api.txt)
1399+therefore the bluez snap itself does not need access to other snaps data.
1400+
1401+Below is example output of sending a file:
1402+
1403+```
1404+[00:25:56:D1:36:6B]# send /var/snap/bluez/current/f.txt
1405+Attempting to send /var/snap/bluez/current/f.txt to /org/bluez/obex/client/session5
1406+[NEW] Transfer /org/bluez/obex/client/session5/transfer10
1407+Transfer /org/bluez/obex/client/session5/transfer10
1408+        Status: queued
1409+        Name: f.txt
1410+        Size: 4
1411+        Filename: /var/snap/bluez/current/f.txt
1412+        Session: /org/bluez/obex/client/session5
1413+[CHG] Transfer /org/bluez/obex/client/session5/transfer10 Status: complete
1414+[DEL] Transfer /org/bluez/obex/client/session5/transfer10
1415+```
1416+
1417+## Receiving Files
1418+
1419+By default there is no way to receive a file using Bluetooth on Ubuntu Core
1420+unless the application snap implements the receiving side. This is because the
1421+incoming transfer has to be allowed and the obexctl tool does not provide
1422+such an agent. It is assumed that the application will implement this. For
1423+reference, here is the [OBEX D-Bus Agent
1424+API](https://git.kernel.org/cgit/bluetooth/bluez.git/tree/doc/obex-agent-api.txt)
1425+description.
1426+
1427+For convenience, there is a bluez-tests snap that packages the
1428+[simple-obex-agent](https://git.kernel.org/cgit/bluetooth/bluez.git/tree/test/simple-obex-agent)
1429+Python script that implements the mentioned API. It can be used to allow
1430+incoming file transfers through OBEX. The script itself has small
1431+modifications to make it compatible with Ubuntu Core specifics (Ubuntu Core uses
1432+the system, not session bus).
1433+
1434+Install the bluez-tests snap
1435+
1436+```
1437+$ sudo snap install bluez-tests
1438+```
1439+
1440+When the above operation successfully finishes, you are able to use the
1441+simple-obex-agent and experiment with receiving file transfers. Open another
1442+shell on the device and start the simple-obex-agent by typing:
1443+
1444+```
1445+$ sudo bluez-tests.simple-obex-agent
1446+```
1447+
1448+From now on it will listen for incoming OBEX transfers and when such transfers
1449+happen, it will prompt for a decision: accept or deny.
1450diff --git a/docs/reference/using-prerequisites.md b/docs/reference/using-prerequisites.md
1451new file mode 100644
1452index 0000000..da7ae59
1453--- /dev/null
1454+++ b/docs/reference/using-prerequisites.md
1455@@ -0,0 +1,95 @@
1456+---
1457+title: "Prerequisites"
1458+table_of_contents: True
1459+---
1460+
1461+# Prerequisites
1462+
1463+This section describes the requirements that must be satisfied in order to use
1464+Bluetooth on an Ubuntu Core device.
1465+
1466+In short you have to make sure that:
1467+
1468+ * The BlueZ snap is installed
1469+ * The Bluetooth daemons are running
1470+ * The plugs and slots are connected
1471+
1472+## The Bluez Snap is Installed
1473+
1474+Make sure that the latest *bluez* snap is installed. You can check this by using
1475+*snap list* command:
1476+
1477+```
1478+$ snap list
1479+Name Version Rev Developer Notes
1480+bluez 5.37-2 27 canonical -
1481+$
1482+```
1483+
1484+If *bluez* is not listed by the above command you can install it with:
1485+
1486+```
1487+$ sudo snap install bluez
1488+```
1489+
1490+## The Bluetooth Daemons are Running
1491+
1492+Normally, once the snap is installed, the Bluetooth daemon is up and running.
1493+Nevertheless it is still good to verify this.
1494+
1495+For *bluetoothd* type:
1496+
1497+```
1498+$ systemctl status snap.bluez.bluez.service
1499+```
1500+
1501+The expected output should look like:
1502+
1503+```
1504+● snap.bluez.bluez.service - Service for snap application bluez.bluez
1505+ Loaded: loaded (/etc/systemd/system/snap.bluez.bluez.service; enabled; vendor preset: enabled)
1506+ Active: active (running) since Wed 2016-11-02 15:15:31 UTC; 4 months 11 days ago
1507+ Main PID: 1580 (bluetoothd)
1508+ CGroup: /system.slice/snap.bluez.bluez.service
1509+ └─1580 /snap/bluez/x2/usr/lib/bluetooth/bluetoothd -E
1510+```
1511+
1512+For *obexd* type:
1513+
1514+```
1515+$ systemctl status snap.bluez.obex.service
1516+```
1517+
1518+The expected output should look like:
1519+
1520+```
1521+● snap.bluez.obex.service - Service for snap application bluez.obex
1522+ Loaded: loaded (/etc/systemd/system/snap.bluez.obex.service; enabled; vendor preset: enabled)
1523+ Active: active (running) since Wed 2016-11-02 15:15:31 UTC; 4 months 11 days ago
1524+ Main PID: 1584 (obexd)
1525+ CGroup: /system.slice/snap.bluez.obex.service
1526+ └─1584 /snap/bluez/x2/usr/lib/bluetooth/obexd
1527+```
1528+
1529+Note that you need *bluetoothd* for the regular Bluetooth usage, however it is
1530+not enough for exchanging files over Bluetooth. For this to work you need the
1531+*obexd* daemon. It is mentioned here because, for example, on Ubuntu Desktop the
1532+*obexd* is not started by default.
1533+
1534+## The Plugs and Slots are Connected
1535+
1536+Checking for the Bluetooth plug and slot being auto-connected is one of the snap
1537+verification criteria therefore in 99.9% cases it will be as expected. For the
1538+sake of exercise it is good to verify
1539+
1540+
1541+```
1542+$ snap interfaces bluez
1543+bluez:service bluez:client
1544+- bluez:bluetooth-control
1545+$
1546+```
1547+
1548+You should expect the output like the above, that is the *bluez:service* slot is
1549+connected with the *bluez:client* plug.
1550+
1551diff --git a/docs/release-notes.md b/docs/release-notes.md
1552new file mode 100644
1553index 0000000..1fe4e39
1554--- /dev/null
1555+++ b/docs/release-notes.md
1556@@ -0,0 +1,13 @@
1557+---
1558+title: "Release Notes"
1559+table_of_contents: False
1560+---
1561+
1562+# Release Notes
1563+
1564+The version numbers mentioned on this page correspond to those released in the
1565+Ubuntu snap store.
1566+
1567+## 5.37-2
1568+
1569+ * Initial release, based on BlueZ 5.37
1570diff --git a/docs/report-bug.md b/docs/report-bug.md
1571new file mode 100644
1572index 0000000..3707c77
1573--- /dev/null
1574+++ b/docs/report-bug.md
1575@@ -0,0 +1,72 @@
1576+---
1577+title: "Report a Bug"
1578+table_of_contents: False
1579+---
1580+
1581+# Report a Bug
1582+
1583+Bugs can be reported [here](https://bugs.launchpad.net/snappy-hwe-snaps/+filebug).
1584+
1585+## Information Required to Include in a Bug Report
1586+
1587+When submitting a bug report, please attach:
1588+
1589+ * */var/log/syslog*
1590+ * Bluetooth adapter information
1591+ * List of paired devices
1592+ * State of the Bluetooth kill-switch
1593+ * The HCI trace
1594+
1595+### Bluetooth Adapter Information
1596+
1597+```
1598+$ sudo hciconfig -a
1599+```
1600+
1601+### List of Paired Devices
1602+
1603+```
1604+$ bluetoothctl
1605+[bluetooth]# show
1606+[bluetooth]# devices
1607+[bluetooth]# info <mac addr of any device you have problems with>
1608+```
1609+
1610+### State of the Bluetooth kill-switch
1611+
1612+```
1613+$ snap install wireless-tools
1614+$ sudo wireless-tools.rfkill list
1615+```
1616+
1617+Note that the *rfkill* command is a part of *wireless-tools* snap.
1618+
1619+### The HCI Trace
1620+
1621+The HCI trace is a snapshot of the communication between the Bluetooth host
1622+(software stack) and the Bluetooth controller (the chip). The *btmon* tool can
1623+be used to capture such for both live debugging and saving it for later. Note
1624+that the HCI trace needs to be captured at the same time the Bluetooth issue
1625+occurs.
1626+
1627+When *btmon* is executed without any parameters, it will offer live debugging
1628+which will print in a ‘tail -f’ fashion an ongoing exchange of the commands and
1629+events between the stack and the chip. It is possible however to make it save
1630+the data in the [snoop format](https://tools.ietf.org/html/rfc1761) which can
1631+later be viewed using for example [Wireshark](https://www.wireshark.org).
1632+
1633+Now, for live debugging:
1634+
1635+```
1636+$ sudo btmon
1637+```
1638+
1639+For saving it later in a .snoop format:
1640+
1641+```
1642+$ sudo btmon --write ~/hcitrace.snoop
1643+```
1644+
1645+The nice thing about btmon and how it works is that it is possible to have
1646+several versions of it executed simultaneously. This allows capturing logs as
1647+in the last example in one shell and viewing it live in another.
1648diff --git a/docs/troubleshoot/faq.md b/docs/troubleshoot/faq.md
1649new file mode 100644
1650index 0000000..cfc1bf8
1651--- /dev/null
1652+++ b/docs/troubleshoot/faq.md
1653@@ -0,0 +1,93 @@
1654+---
1655+title: "FAQ"
1656+table_of_contents: False
1657+---
1658+
1659+# FAQ
1660+
1661+This section covers some of the most commonly encountered problems and attempts
1662+to provide solutions for them.
1663+
1664+## I'm Seeing org.bluez.Error.NotReady
1665+
1666+The *NotReady* error code indicates that the stack is not ready to fulfill the
1667+request. One of the reasons might be that the Bluetooth hardware is unpowered.
1668+
1669+Whenever you see something like:
1670+
1671+```
1672+$ sudo bluez.bluetoothctl
1673+[NEW] Controller 00:1A:7D:DA:71:08 core16 [default]
1674+[bluetooth]# scan on
1675+Failed to start discovery: org.bluez.Error.NotReady
1676+[bluetooth]#
1677+```
1678+
1679+Power the chip on explicitly, type:
1680+
1681+```
1682+[bluetooth]# power on
1683+[CHG] Controller 00:1A:7D:DA:71:08 Class: 0x500000
1684+Changing power on succeeded
1685+[CHG] Controller 00:1A:7D:DA:71:08 Powered: yes
1686+[bluetooth]#
1687+```
1688+
1689+## Pairing Fails With a Device That Requires Confirmation
1690+
1691+The common mistake when using *bluetoothctl* to access BlueZ is to forget about
1692+registering an agent. The agent entity is responsible for handling the
1693+authentication requests that are a part of the pairing procedure.
1694+
1695+If the agent is not registered then the pairing fails.
1696+
1697+Make sure that the agent is registered by typing:
1698+
1699+```
1700+[bluetooth]# agent on
1701+Agent registered
1702+[bluetooth]#
1703+```
1704+
1705+It is safe to do it multiple times
1706+
1707+```
1708+[bluetooth]# agent on
1709+Agent registered
1710+[bluetooth]# agent on
1711+Agent is already registered
1712+[bluetooth]#
1713+```
1714+
1715+## I cannot connect to an already paired device after reboot or long idle time
1716+
1717+The Bluetooth devices that required user-confirmation during the pairing
1718+procedure will require the pairing agent to reconnect after they have been
1719+disconnected.
1720+
1721+Note that the reason for disconnection might be power-cycling the Ubuntu Core
1722+device or idle-timeout on the remote device side when left idle for a longer
1723+period of time. It will, therefore, happen aside from explicit disconnection.
1724+
1725+When this happens use *bluetoothctl* to reconnect to the given device as you
1726+would do it for the first time. Note that you do not have to pair the devices
1727+again (unless you know that one of them has lost the pairing information) but
1728+you will need to connect them.
1729+
1730+In order to do this, type:
1731+
1732+```
1733+$ sudo bluez.bluetoothctl
1734+[bluetooth]# agent on
1735+Agent registered
1736+[bluetooth]# connect 90:7F:61:11:44:C8
1737+```
1738+
1739+And you shall see the devices connecting again
1740+
1741+```
1742+Attempting to connect to 90:7F:61:11:44:C8
1743+[CHG] Device 90:7F:61:11:44:C8 Connected: yes
1744+Connection successful
1745+[ThinkPad Compact Bluetooth Keyboard with TrackPoint]#
1746+```
1747diff --git a/snapcraft.yaml b/snapcraft.yaml
1748index fca7888..d0c3fd3 100644
1749--- a/snapcraft.yaml
1750+++ b/snapcraft.yaml
1751@@ -119,7 +119,5 @@ parts:
1752 plugin: dump
1753 organize:
1754 copyright: usr/share/doc/bluez/copyright
1755- doc/overview.md: usr/share/doc/bluez/overview.md
1756 prime:
1757 - usr/share/doc/bluez/copyright
1758- - usr/share/doc/bluez/overview.md

Subscribers

People subscribed via source and target branches