docs: Rename BLE to Bluetooth (LE) where applicable

Zephyr Write Tx Power Level (per Role/Connection) Command

=========================================================

This command dynamically modifies BLE Tx power level given a handle and a

This command dynamically modifies Bluetooth Tx power level given a handle and a

handle type (advertiser, scanner, connection).

+--------------------------+-------+--------------------+--------------------+

|                          |       |                    | Selected_Tx_Power  |

+--------------------------+-------+--------------------+--------------------+

The Tx power of the BLE radio interface is modified for any low-level link by

the controller with a high degree of flexibility. The BLE link whose power is

The Tx power of the Bluetooth radio interface is modified for any low-level link by

the controller with a high degree of flexibility. The Bluetooth link whose power is

set is identified based on a handle type (advertiser, scanner, connection) and

handle pair.

Zephyr Read Tx Power Level (per Role/Connection) Command

========================================================

This command reads the BLE Tx power level. In contrast to the standardized HCI

This command reads the Bluetooth Tx power level. In contrast to the standardized HCI

command, i.e. Read_Transmit_Power_Level, which returns the transmitted power

level only for a specified connection handle, this command operates for both

connected and unconnected states. It gets the BLE Tx power level for any given

connected and unconnected states. It gets the Bluetooth Tx power level for any given

handle type (advertiser, scanner, connection) and handle.

+--------------------------+-------+--------------------+--------------------+

|                          |       |                    | Tx_Power_Level     |

+--------------------------+-------+--------------------+--------------------+

The Tx power of the BLE radio interface used for a low-level link identified

The Tx power of the Bluetooth radio interface used for a low-level link identified

by a pair of Handle_Type and Handle is retrieved from the controller.

The role/state defining input parameter is the Handle_Type, whereas its

stack.

.. note::

   Zephyr supports mainly Bluetooth Low Energy (BLE), the low-power

   Zephyr supports mainly Bluetooth Low Energy (LE), the low-power

   version of the Bluetooth specification. Zephyr also has limited support

   for portions of the BR/EDR Host. Throughout this architecture document we

   use BLE interchangeably for Bluetooth except when noted.

   for portions of the BR/EDR Host.

.. _bluetooth-layers:

BLE Layers

==========

Bluetooth LE Layers

===================

There are 3 main layers that together constitute a full Bluetooth Low Energy

protocol stack:

* **Single-chip configuration**: In this configuration, a single microcontroller

  implements all three layers and the application itself. This can also be called a

  system-on-chip (SoC) implementation. In this case the BLE Host and the BLE

  system-on-chip (SoC) implementation. In this case the Bluetooth Host and the Bluetooth

  Controller communicate directly through function calls and queues in RAM. The

  Bluetooth specification does not specify how HCI is implemented in this

  single-chip configuration and so how HCI commands, events, and data flows between

  configuration. This configuration allows for a wider variety of combinations of

  Hosts when using the Zephyr OS as a Controller. Since HCI ensures

  interoperability among Host and Controller implementations, including of course

  Zephyr's very own BLE Host and Controller, users of the Zephyr Controller can

  Zephyr's very own Bluetooth Host and Controller, users of the Zephyr Controller can

  choose to use whatever Host running on any platform they prefer. For example,

  the host can be the Linux BLE Host stack (BlueZ) running on any processor

  the host can be the Linux Bluetooth Host stack (BlueZ) running on any processor

  capable of supporting Linux. The Host processor may of course also run Zephyr

  and the Zephyr OS BLE Host. Conversely, combining an IC running the Zephyr

  and the Zephyr OS Bluetooth Host. Conversely, combining an IC running the Zephyr

  Host with an external Controller that does not run Zephyr is also supported.

.. _bluetooth-build-types:

===========

The Zephyr software stack as an RTOS is highly configurable, and in particular,

the BLE subsystem can be configured in multiple ways during the build process to

the Bluetooth subsystem can be configured in multiple ways during the build process to

include only the features and layers that are required to reduce RAM and ROM

footprint as well as power consumption. Here's a short list of the different

BLE-enabled builds that can be produced from the Zephyr project codebase:

Bluetooth-enabled builds that can be produced from the Zephyr project codebase:

* **Controller-only build**: When built as a BLE Controller, Zephyr includes

* **Controller-only build**: When built as a Bluetooth Controller, Zephyr includes

  the Link Layer and a special application. This application is different

  depending on the physical transport chosen for HCI:

  corresponding device tree node is enabled.

* **Host-only build**: A Zephyr OS Host build will contain the Application and

  the BLE Host, along with an HCI driver (UART or SPI) to interface with an

  the Bluetooth Host, along with an HCI driver (UART or SPI) to interface with an

  external Controller chip.

  A build of this type sets the following Kconfig option values:

  used for Controller-only builds can be built as Combined

The picture below shows the SoC or single-chip configuration when using a Zephyr

combined build (a build that includes both a BLE Host and a Controller in the

combined build (a build that includes both a Bluetooth Host and a Controller in the

same firmware image that is programmed onto the chip):

.. figure:: img/ble_cfg_single.png

   :align: center

   :alt: BLE Combined build on a single chip

   :alt: Bluetooth Combined build on a single chip

   A Combined build on a Single-Chip configuration

.. figure:: img/ble_cfg_dual.png

   :align: center

   :alt: BLE dual-chip configuration builds

   :alt: Bluetooth dual-chip configuration builds

   Host-only and Controller-only builds on dual-chip configurations

When using a Zephyr Host (left side of image), two instances of Zephyr OS

must be built with different configurations, yielding two separate images that

must be programmed into each of the chips respectively. The Host build image

contains the application, the BLE Host and the selected HCI driver (UART or

contains the application, the Bluetooth Host and the selected HCI driver (UART or

SPI), while the Controller build runs either the

:zephyr:code-sample:`bluetooth_hci_uart`, or the

:zephyr:code-sample:`bluetooth_hci_spi` app to provide an interface to

the BLE Controller.

the Bluetooth Controller.

This configuration is not limited to using a Zephyr OS Host, as the right side

of the image shows. One can indeed take one of the many existing GNU/Linux

distributions, most of which include Linux's own BLE Host (BlueZ), to connect it

distributions, most of which include Linux's own Bluetooth Host (BlueZ), to connect it

via UART or USB to one or more instances of the Zephyr OS Controller build.

BlueZ as a Host supports multiple Controllers simultaneously for applications

that require more than one BLE radio operating at the same time but sharing the

that require more than one Bluetooth radio operating at the same time but sharing the

same Host stack.

Source tree layout

The :ref:`nrf52_bsim <nrf52_bsim>` and :ref:`nrf5340bsim <nrf5340bsim>` boards,

are simulated target boards

which emulate the necessary peripherals of a nRF52/53 SOC to be able to develop

and test BLE applications.

and test Bluetooth LE applications.

These boards, use:

   * `BabbleSim`_ to simulate the nRF5x modem and the radio environment.

Perhaps the most important block above the HCI handling is the Generic

Access Profile (GAP). GAP simplifies Bluetooth LE access by defining

four distinct roles of BLE usage:

four distinct roles of Bluetooth usage:

* Connection-oriented roles

* Connection-less roles

  * Broadcaster (sending out BLE advertisements, e.g. a smart beacon)

  * Broadcaster (sending out Bluetooth LE advertisements, e.g. a smart beacon)

  * Observer (scanning for BLE advertisements)

  * Observer (scanning for Bluetooth LE advertisements)

Each role comes with its own build-time configuration option:

:kconfig:option:`CONFIG_BT_PERIPHERAL`, :kconfig:option:`CONFIG_BT_CENTRAL`,

Peripheral role

===============

Most Zephyr-based BLE devices will most likely be peripheral-role

Most Zephyr-based Bluetooth LE devices will most likely be peripheral-role

devices. This means that they perform connectable advertising and expose

one or more GATT services. After registering services using the

:c:func:`bt_gatt_service_register` API the application will typically

***********************

The Linux Bluetooth Protocol Stack, BlueZ, comes with a very useful set of

tools that can be used to debug and interact with Zephyr's BLE Host and

tools that can be used to debug and interact with Zephyr's Bluetooth Host and

Controller. In order to benefit from these tools you will need to make sure

that you are running a recent version of the Linux Kernel and BlueZ:

:file:`tools/` folder and :file:`btmon` in the :file:`monitor/` folder.

You'll need to enable BlueZ's experimental features so you can access its

most recent BLE functionality. Do this by editing the file

most recent Bluetooth functionality. Do this by editing the file

:file:`/lib/systemd/system/bluetooth.service`

and making sure to include the :literal:`-E` option in the daemon's execution

start line:

     $ sudo ./build/zephyr/zephyr.exe --bt-dev=hci0

Using a Zephyr-based BLE Controller

===================================

Using a Zephyr-based Bluetooth Controller

=========================================

Depending on which hardware you have available, you can choose between two

transports when building a single-mode, Zephyr-based BLE Controller:

transports when building a single-mode, Zephyr-based Bluetooth Controller:

* UART: Use the :zephyr:code-sample:`bluetooth_hci_uart` sample and follow

  the instructions in :ref:`bluetooth-hci-uart-qemu-posix`.

Using Zephyr-based Controllers with BlueZ

*****************************************

If you want to test a Zephyr-powered BLE Controller using BlueZ's Bluetooth

If you want to test a Zephyr-powered Bluetooth Controller using BlueZ's Bluetooth

Host, you will need a few tools described in the :ref:`bluetooth_bluez` section.

Once you have installed the tools you can then use them to interact with your

Zephyr-based controller: