Bluetooth: Move Bluetooth docs to rst

Change-Id: I36009f5acd4016ec47edb6dac29e81e58b1ba24f
Signed-off-by: Anas Nashif <anas.nashif@intel.com>

17 files changed, 355 insertions, 133 deletions

diff --git a/samples/bluetooth/README b/samples/bluetooth/README
deleted file mode 100644
index 964783fff..000000000
--- a/samples/bluetooth/README
+++ /dev/null
@@ -1,109 +0,0 @@
-Bluetooth subsystem
-
-= Building =
-
-Build samples
-
-$ make -C samples/bluetooth/<app>
-
-= Bluetooth Sample application =
-
-Host Bluetooth controller is connected to the second qemu serial line
-through a UNIX socket (qemu option -serial unix:/tmp/bt-server-bredr).
-This option is already added to qemu through QEMU_EXTRA_FLAGS in Makefile.
-
-On the host side BlueZ allows to "connect" Bluetooth controller through
-a so-called user channel. Use the btproxy tool for that:
-
-$ sudo tools/btproxy -u
-Listening on /tmp/bt-server-bredr
-
-Note that before calling btproxy make sure that Bluetooth controller is down.
-
-Now running qemu result connecting second serial line to 'bt-server-bredr'
-UNIX socket. When Bluetooth (CONFIG_BLUETOOTH) and Bluetooth HCI UART driver
-(CONFIG_BLUETOOTH_H4) are enabled, Bluetooth driver registers to the system.
-From now on Bluetooth might be used by the application. To run application in
-the qemu run:
-
-$ make run
-
-= Bluetooth sanity check =
-
-There is smoke test application in tests directory which gets run in sanity
-check script:
-
-$ scripts/sanitycheck [-P <platform>]
-
-To only run Bluetooth tests use the -t bluetooth switch:
-
-$ scripts/sanitycheck -t bluetooth
-
-= Summary of available applications =
-
-beacon:
-        A simple application demonstrating the BLE Broadcaster role
-        functionality by advertising an Eddystone URL (the Zephyr
-        website).
-
-central:
-        Application demonstrating very basic BLE Central role
-        functionality by scanning for other BLE devices and establishing
-        a connection to the first one with a strong enough signal.
-
-central_hr:
-        Similar to 'central', except that this application specifically
-        looks for heart-rate monitors and reports the heart-rate
-        readings once connected.
-
-eddystone:
-        Application demostrating Eddystone Configuration Service:
-        https://github.com/google/eddystone/tree/master/configuration-service
-
-gatt:
-        Not an application, but a set of reusable modules for common
-        GATT profiles & services.
-
-hci_uart:
-	Expose Zephyr Bluetooth Controller support over UART to another
-	device/CPU using the H:4 HCI transport protocol (requires HW
-	flow control from the UART).
-
-hci_usb:
-	Make a USB Bluetooth dongle out of Zephyr. Requires USB device
-	support from the board it runs on (e.g. Arduino 101 has this).
-
-ipsp:
-        Application demonstrating the IPSP (Internet Protocol Support
-        Profile) Node role. IPSP is the Bluetooth profile that
-        underneath utilizes 6LoWPAN, i.e. gives you IPv6 connectivity
-        over BLE.
-
-peripheral:
-        Application demonstrating the BLE Peripheral role. It has
-        several well-known and vendor-specific GATT services that it
-        exposes.
-
-peripheral_csc:
-        Similar to 'peripheral', except that this application
-        specifically exposes the CSC (Cycling Speed and Cadence)
-        GATT Service.
-
-peripheral_dis:
-        Similar to 'peripheral', except that this application
-        specifically exposes the DIS (Device Information) GATT Service.
-
-peripheral_esp:
-        Similar to 'peripheral', except that this application
-        specifically exposes the ESP (Environmental Sensing Profile)
-        GATT Service.
-
-peripheral_hr:
-        Similar to 'peripheral', except that this application
-        specifically exposes the HR (Heart Rate) GATT Service. Once a
-        device connects it will generate dummy heart-rate values.
-
-peripheral_hids:
-        Similar to 'peripheral', except that this application
-        specifically exposes the HID GATT Service. The report map used
-	is for a generic mouse.
diff --git a/samples/bluetooth/beacon/README.rst b/samples/bluetooth/beacon/README.rst
new file mode 100644
index 000000000..e9fdf0ba4
--- /dev/null
+++ b/samples/bluetooth/beacon/README.rst
@@ -0,0 +1,21 @@
+Bluetooth: Beacon
+#################
+
+Overview
+********
+
+A simple application demonstrating the BLE Broadcaster role functionality by
+advertising an Eddystone URL (the Zephyr website).
+
+
+
+Requirements
+************
+
+* BlueZ running on the host, or
+* A board with BLE support
+
+Building and Running
+********************
+
+See :ref:`bluetooth setup section <bluetooth_setup>` for details.
diff --git a/samples/bluetooth/bluetooth.rst b/samples/bluetooth/bluetooth.rst
new file mode 100644
index 000000000..752bdab9f
--- /dev/null
+++ b/samples/bluetooth/bluetooth.rst
@@ -0,0 +1,43 @@
+.. _bluetooth_setup:
+
+Bluetooth
+##########
+
+To build any of the Bluetooth samples, follow the instructions below:
+
+.. code-block:: console
+
+   $ make -C samples/bluetooth/<app>
+
+Host Bluetooth controller is connected to the second QEMU serial line through a
+Unix socket (QEMU option -serial unix:/tmp/bt-server-bredr).  This option is
+already added to Qemu through QEMU_EXTRA_FLAGS in Makefile.
+
+On the host side BlueZ allows to "connect" Bluetooth controller through a
+so-called user channel. Use the btproxy tool for that:
+
+Note that before calling ``btproxy`` make sure that Bluetooth controller is
+down.
+
+.. code-block:: console
+
+   $ sudo tools/btproxy -u
+   Listening on /tmp/bt-server-bredr
+
+Running the application in Qemu will connect the second serial line to
+``bt-server-bredr`` Unix socket. When Bluetooth (CONFIG_BLUETOOTH) and Bluetooth
+HCI UART driver (CONFIG_BLUETOOTH_H4) are enabled, the Bluetooth driver
+registers with the system.
+
+From now on Bluetooth may be used by the application. To run applications in
+the Qemu emulation environment, type:
+
+.. code-block:: console
+
+   $ make run
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   **/*
diff --git a/samples/bluetooth/central/README.rst b/samples/bluetooth/central/README.rst
new file mode 100644
index 000000000..80a137aa3
--- /dev/null
+++ b/samples/bluetooth/central/README.rst
@@ -0,0 +1,24 @@
+.. _bluetooth_central:
+
+Bluetooth: Central
+##################
+
+Overview
+********
+
+Application demonstrating very basic BLE Central role functionality by scanning
+for other BLE devices and establishing a connection to the first one with a
+strong enough signal.
+
+
+
+Requirements
+************
+
+* BlueZ running on the host, or
+* A board with BLE support
+
+Building and Running
+********************
+
+See :ref:`bluetooth setup section <bluetooth_setup>` for details.
diff --git a/samples/bluetooth/central_hr/README.rst b/samples/bluetooth/central_hr/README.rst
new file mode 100644
index 000000000..ef5ea2424
--- /dev/null
+++ b/samples/bluetooth/central_hr/README.rst
@@ -0,0 +1,22 @@
+.. _bluetooth_central_hr:
+
+Bluetooth: Central / Heart-rate Monitor
+#######################################
+
+Overview
+********
+
+Similar to the :ref:`Central <bluetooth_central>` sample, except that this
+application specifically looks for heart-rate monitors and reports the
+heart-rate readings once connected.
+
+Requirements
+************
+
+* BlueZ running on the host, or
+* A board with BLE support
+
+Building and Running
+********************
+
+See :ref:`bluetooth setup section <bluetooth_setup>` for details.
diff --git a/samples/bluetooth/eddystone/README.rst b/samples/bluetooth/eddystone/README.rst
new file mode 100644
index 000000000..c8ea02855
--- /dev/null
+++ b/samples/bluetooth/eddystone/README.rst
@@ -0,0 +1,26 @@
+Bluetooth: Eddystone
+####################
+
+Overview
+********
+Application demostrating `Eddystone Configuration Service`_
+
+The Eddystone Configuration Service runs as a GATT service on the beacon while
+it is connectable and allows configuration of the advertised data, the
+broadcast power levels, and the advertising intervals. It also forms part of
+the definition of how Eddystone-EID beacons are configured and registered with
+a trusted resolver.
+
+
+Requirements
+************
+
+* BlueZ running on the host, or
+* A board with BLE support
+
+Building and Running
+********************
+
+See :ref:`bluetooth setup section <bluetooth_setup>` for details.
+
+.. _Eddystone Configuration Service: https://github.com/google/eddystone/tree/master/configuration-service
diff --git a/samples/bluetooth/hci_uart/README.rst b/samples/bluetooth/hci_uart/README.rst
new file mode 100644
index 000000000..bbbf66e0f
--- /dev/null
+++ b/samples/bluetooth/hci_uart/README.rst
@@ -0,0 +1,21 @@
+Bluetooth: HCI UART
+####################
+
+Overview
+*********
+
+Expose Zephyr Bluetooth Controller support over UART to another device/CPU using
+the H:4 HCI transport protocol (requires HW flow control from the UART)
+
+
+
+Requirements
+************
+
+* BlueZ running on the host, or
+* A board with BLE support
+
+Building and Running
+********************
+
+See :ref:`bluetooth setup section <bluetooth_setup>` for details.
diff --git a/samples/bluetooth/hci_usb/README.rst b/samples/bluetooth/hci_usb/README.rst
new file mode 100644
index 000000000..b221af642
--- /dev/null
+++ b/samples/bluetooth/hci_usb/README.rst
@@ -0,0 +1,20 @@
+Bluetooth: HCI USB
+##################
+
+Overview
+********
+
+Make a USB Bluetooth dongle out of Zephyr. Requires USB device support from the
+board it runs on (e.g. :ref:`arduino_101` has this).
+
+
+Requirements
+************
+
+* BlueZ running on the host, or
+* A board with BLE support
+
+Building and Running
+********************
+
+See :ref:`bluetooth setup section <bluetooth_setup>` for details.
diff --git a/samples/bluetooth/ipsp/README b/samples/bluetooth/ipsp/README
deleted file mode 100644
index 6e06e0932..000000000
--- a/samples/bluetooth/ipsp/README
+++ /dev/null
@@ -1,24 +0,0 @@
-IPSP sample application
-
-== Supported Boards ==
-
-This application currently only works with HCI based firmware since it
-requires L2CAP channels support.
-
-== Testing with Linux host ==
-
-To test IPSP please take a look at samples/net/README, in addition to running
-echo-client it is necessary to enable 6LowPAN module in Linux with the
-following commands:
-
-$ modprobe bluetooth_6lowpan
-$ echo 1 > /sys/kernel/debug/bluetooth/6lowpan_enable
-
-Then to connect:
-
-echo "connect <bdaddr> <type>" > /sys/kernel/debug/bluetooth/6lowpan_control
-
-Once connected a dedicated interface will be created, usually bt0, which can
-then be used as following:
-
-$ echo-client -i bt0 <ip>
diff --git a/samples/bluetooth/ipsp/README.rst b/samples/bluetooth/ipsp/README.rst
new file mode 100644
index 000000000..370cb543c
--- /dev/null
+++ b/samples/bluetooth/ipsp/README.rst
@@ -0,0 +1,42 @@
+Bluetooth: IPSP Sample
+######################
+
+Overview
+********
+Application demonstrating the IPSP (Internet Protocol Support Profile) Node
+role. IPSP is the Bluetooth profile that underneath utilizes 6LoWPAN, i.e. gives
+you IPv6 connectivity over BLE.
+
+Requirements
+************
+
+This application currently only works with HCI based firmware since it
+requires L2CAP channels support.
+
+Building and Running
+********************
+
+Testing with a Linux host
+=========================
+
+To test IPSP please take a look at samples/net/README, in addition to running
+echo-client you must enable 6LowPAN module in Linux with the
+following commands:
+
+.. code-block:: console
+
+   $ modprobe bluetooth_6lowpan
+   $ echo 1 > /sys/kernel/debug/bluetooth/6lowpan_enable
+
+Then to connect:
+
+.. code-block:: console
+
+   $ echo "connect <bdaddr> <type>" > /sys/kernel/debug/bluetooth/6lowpan_control
+
+Once connected a dedicated interface will be created, usually bt0, which can
+then be used as following:
+
+.. code-block:: console
+
+   $ echo-client -i bt0 <ip>
diff --git a/samples/bluetooth/peripheral/README.rst b/samples/bluetooth/peripheral/README.rst
new file mode 100644
index 000000000..2138b55ae
--- /dev/null
+++ b/samples/bluetooth/peripheral/README.rst
@@ -0,0 +1,22 @@
+.. _ble_peripheral:
+
+Bluetooth: Peripheral
+#####################
+
+Overview
+********
+
+Application demonstrating the BLE Peripheral role. It has several well-known and
+vendor-specific GATT services that it exposes.
+
+
+Requirements
+************
+
+* BlueZ running on the host, or
+  * A board with BLE support
+
+Building and Running
+********************
+
+See :ref:`bluetooth setup section <bluetooth_setup>` for details.
diff --git a/samples/bluetooth/peripheral_csc/README.rst b/samples/bluetooth/peripheral_csc/README.rst
new file mode 100644
index 000000000..7e9177a2b
--- /dev/null
+++ b/samples/bluetooth/peripheral_csc/README.rst
@@ -0,0 +1,23 @@
+.. _peripheral_csc:
+
+Bluetooth: Peripheral CSC
+#########################
+
+Overview
+********
+
+Similar to the :ref:`Peripheral <ble_peripheral>` sample, except that this
+application specifically exposes the CSC (Cycling Speed and Cadence) GATT
+Service.
+
+
+Requirements
+************
+
+* BlueZ running on the host, or
+* A board with BLE support
+
+Building and Running
+********************
+
+See :ref:`bluetooth setup section <bluetooth_setup>` for details.
diff --git a/samples/bluetooth/peripheral_dis/README.rst b/samples/bluetooth/peripheral_dis/README.rst
new file mode 100644
index 000000000..ea4bea78f
--- /dev/null
+++ b/samples/bluetooth/peripheral_dis/README.rst
@@ -0,0 +1,22 @@
+.. _peripheral_dis:
+
+Bluetooth: Peripheral DIS
+#########################
+
+Overview
+********
+
+Similar to the :ref:`Peripheral <ble_peripheral>` sample, except that this
+application specifically exposes the DIS (Device Information) GATT Service.
+
+
+Requirements
+************
+
+* BlueZ running on the host, or
+* A board with BLE support
+
+Building and Running
+********************
+
+See :ref:`bluetooth setup section <bluetooth_setup>` for details.
diff --git a/samples/bluetooth/peripheral_esp/README.rst b/samples/bluetooth/peripheral_esp/README.rst
new file mode 100644
index 000000000..d1d87c1c7
--- /dev/null
+++ b/samples/bluetooth/peripheral_esp/README.rst
@@ -0,0 +1,22 @@
+.. _peripheral_esp:
+
+Bluetooth: Peripheral ESP
+#########################
+
+Overview
+********
+Similar to the :ref:`Peripheral <ble_peripheral>` sample, except that this
+application specifically exposes the ESP (Environmental Sensing Profile) GATT
+Service.
+
+
+Requirements
+************
+
+* BlueZ running on the host, or
+* A board with BLE support
+
+Building and Running
+********************
+
+See :ref:`bluetooth setup section <bluetooth_setup>` for details.
diff --git a/samples/bluetooth/peripheral_hids/README.rst b/samples/bluetooth/peripheral_hids/README.rst
new file mode 100644
index 000000000..aaa9ec24b
--- /dev/null
+++ b/samples/bluetooth/peripheral_hids/README.rst
@@ -0,0 +1,23 @@
+.. _peripheral_hids:
+
+Bluetooth: Peripheral HIDs
+##########################
+
+Overview
+********
+
+Similar to the :ref:`Peripheral <ble_peripheral>` sample, except that this
+application specifically exposes the HID GATT Service. The report map used is
+for a generic mouse.
+
+
+Requirements
+************
+
+* BlueZ running on the host, or
+* A board with BLE support
+
+Building and Running
+********************
+
+See :ref:`bluetooth setup section <bluetooth_setup>` for details.
diff --git a/samples/bluetooth/peripheral_hr/README.rst b/samples/bluetooth/peripheral_hr/README.rst
new file mode 100644
index 000000000..f9aff4ff8
--- /dev/null
+++ b/samples/bluetooth/peripheral_hr/README.rst
@@ -0,0 +1,23 @@
+.. _peripheral_hr:
+
+Bluetooth: Peripheral HR
+########################
+
+Overview
+********
+
+Similar to the :ref:`Peripheral <ble_peripheral>` sample, except that this
+application specifically exposes the HR (Heart Rate) GATT Service. Once a device
+connects it will generate dummy heart-rate values.
+
+
+Requirements
+************
+
+* BlueZ running on the host, or
+* A board with BLE support
+
+Building and Running
+********************
+
+See :ref:`bluetooth setup section <bluetooth_setup>` for details.
diff --git a/samples/samples.rst b/samples/samples.rst
index aaca35c65..d2667c33f 100644
--- a/samples/samples.rst
+++ b/samples/samples.rst
@@ -9,6 +9,7 @@ Samples and Demos
    kernel
    basic/*
    net/net.rst
+   bluetooth/bluetooth.rst
    sensor/*
    grove/*
    advanced