Add guide to testing Bluetooth pairing with another device

Development_Environment/Boards/HowTo.rst

@@ -9,6 +9,7 @@ how to perform routine tasks.
 .. toctree::
    :maxdepth: 2
 
+   HowTo/Bluetooth_Connections
    HowTo/Data_Connections
    HowTo/Location_Services
    HowTo/SSH_Access

Development_Environment/Boards/HowTo/Bluetooth_Connections.rst

+.. _devkit_howto_bluetooth:
+
+Bluetooth Connections
+=====================
+
+Once you have :ref:`configured Bluetooth <imx8_devkit_configure_bluetooth>` for
+the development board, you can check that it can be paired with other devices
+and used for data transfer with the following instructions.
+
+.. contents::
+   :local:
+
+Finding Another Device
+----------------------
+
+From a workstation, log in to the development board using either ``ssh`` or
+``picocom``. Ensure that the Bluetooth module is enabled then enter the
+following command::
+
+   purism@pureos:~$ sudo bluetoothctl
+
+You should see output like this::
+
+   Agent registered
+   [bluetooth]
+
+At the prompt, enter this command to start scanning for devices::
+
+   [bluetooth]# scan on
+
+You should see a ``Discovery started`` message and a list of devices should
+begin to appear. When the device you want to connect to, stop the scan with
+this command::
+
+   [bluetooth]# scan off
+
+Make a note of the address of the device you want to access. This takes the
+form of six comma-separated hexadecimal numbers, such as ``88:DA:1A:9E:BA:95``.
+
+Pairing with a Device
+---------------------
+
+At the prompt, initiate a pairing request with the device, replacing
+``88:DA:1A:9E:BA:95`` with the address you want to use::
+
+   [bluetooth]# pair 88:DA:1A:9E:BA:95
+
+You should see output like this::
+
+   Attempting to pair with 88:DA:1A:9E:BA:95
+   [CHG] Device 88:DA:1A:9E:BA:95 Connected: yes
+   Request confirmation
+   [agent] Confirm passkey 936222 (yes/no):
+
+The last line is a question that requires you to type ``yes`` or ``no`` to
+verify that the passkey shown has been presented to you by the other device.
+This passkey will be different to the one you see. The other device will also
+expect you to confirm the pairing request, typically using the notification it
+used to present the passkey.
+
+If the passkey is the same then confirm the pairing request on the other device
+and enter ``yes`` at the prompt. Otherwise enter ``no``.
+
+If you completed the pairing request, you should see this output::
+
+   Pairing successful
+
+You can test this by using the ``paired-devices`` command at the prompt.
+
+It should now be possible to use the device for data transfers without needing
+to enter a passkey again for the current session. You can exit the tool by
+entering this command::
+
+   [bluetooth]# quit
+
+When you have finished with the data connection, start ``bluetoothctl`` again
+and unpair the device::
+
+   [bluetooth]# remove 88:DA:1A:9E:BA:95
+
+You should see the following output::
+
+   Device has been removed
+
+If you want to access the device again you will need to perform another pairing
+request.

Development_Environment/Boards/imx8.rst

@@ -365,6 +365,8 @@ directly::
    nmcli device wifi list
    nmcli device wifi connect SSID-Name password wireless-password
 
+.. _imx8_devkit_configure_bluetooth:
+
 Configure Bluetooth
 -------------------
 
@@ -384,4 +386,5 @@ This should produce output like this::
    Devices:
            hci0    88:DA:1A:9E:BA:95
 
-The exact device address will be different for your board.
+The exact device address will be different for your board. See :ref:`devkit_howto_bluetooth`
+for further ways to test and use the Bluetooth module.