1.. _bluetooth-dev: 2 3Application Development 4####################### 5 6Bluetooth applications are developed using the common infrastructure and 7approach that is described in the :ref:`application` section of the 8documentation. 9 10Additional information that is only relevant to Bluetooth applications can be 11found on this page. 12 13.. contents:: 14 :local: 15 :depth: 2 16 17Thread safety 18************* 19 20Calling into the Bluetooth API is intended to be thread safe, unless otherwise 21noted in the documentation of the API function. The effort to ensure that this 22is the case for all API calls is an ongoing one, but the overall goal is 23formally stated in this paragraph. Bug reports and Pull Requests that move the 24subsystem in the direction of such goal are welcome. 25 26.. _bluetooth-hw-setup: 27 28Hardware setup 29************** 30 31This section describes the options you have when building and debugging Bluetooth 32applications with Zephyr. Depending on the hardware that is available to you, 33the requirements you have and the type of development you prefer you may pick 34one or another setup to match your needs. 35 36There are 3 possible setups: 37 38#. :ref:`Embedded <bluetooth-hw-setup-embedded>` 39#. :ref:`External controller <bluetooth-hw-setup-external-ll>` 40 41 - :ref:`QEMU host <bluetooth-hw-setup-qemu-host>` 42 - :ref:`native_sim host <bluetooth-hw-setup-native-sim-host>` 43 44#. :ref:`Simulated nRF5x with BabbleSim <bluetooth-hw-setup-bsim>` 45 46.. _bluetooth-hw-setup-embedded: 47 48Embedded 49======== 50 51This setup relies on all software running directly on the embedded platform(s) 52that the application is targeting. 53All the :ref:`bluetooth-configs` and :ref:`bluetooth-build-types` are supported 54but you might need to build Zephyr more than once if you are using a dual-chip 55configuration or if you have multiple cores in your SoC each running a different 56build type (e.g., one running the Host, the other the Controller). 57 58To start developing using this setup follow the :ref:`Getting Started Guide 59<getting_started>`, choose one (or more if you are using a dual-chip solution) 60boards that support Bluetooth and then :ref:`run the application 61<application_run_board>`). 62 63There is a way to access the :ref:`HCI <bluetooth-hci>` traffic between the Host 64and Controller, even if there is no physical transport. See :ref:`Embedded HCI 65tracing <bluetooth-embedded-hci-tracing>` for instructions. 66 67.. _bluetooth-hw-setup-external-ll: 68 69Host on Linux with an external Controller 70========================================= 71 72.. note:: 73 This is currently only available on GNU/Linux 74 75This setup relies on a "dual-chip" :ref:`configuration <bluetooth-configs>` 76which is comprised of the following devices: 77 78#. A :ref:`Host-only <bluetooth-build-types>` application running in the 79 :ref:`QEMU <application_run_qemu>` emulator or the :ref:`native_sim <native_sim>` native 80 port of Zephyr 81#. A Controller, which can be one of the following types: 82 83 * A commercially available Controller 84 * A :ref:`Controller-only <bluetooth-build-types>` build of Zephyr 85 * A :ref:`Virtual controller <bluetooth_virtual_posix>` 86 87.. warning:: 88 Certain external Controllers are either unable to accept the Host to 89 Controller flow control parameters that Zephyr sets by default (Qualcomm), or 90 do not transmit any data from the Controller to the Host (Realtek). If you 91 see a message similar to:: 92 93 <wrn> bt_hci_core: opcode 0x0c33 status 0x12 94 95 when booting your sample of choice (make sure you have enabled 96 :kconfig:option:`CONFIG_LOG` in your :file:`prj.conf` before running the 97 sample), or if there is no data flowing from the Controller to the Host, then 98 you need to disable Host to Controller flow control. To do so, set 99 ``CONFIG_BT_HCI_ACL_FLOW_CONTROL=n`` in your :file:`prj.conf`. 100 101.. _bluetooth-hw-setup-qemu-host: 102 103QEMU 104---- 105 106You can run the Zephyr Host on the :ref:`QEMU emulator<application_run_qemu>` 107and have it interact with a physical external Bluetooth Controller. 108 109Refer to :ref:`bluetooth_qemu_native` for full instructions on how to build and 110run an application in this setup. 111 112.. _bluetooth-hw-setup-native-sim-host: 113 114native_sim 115---------- 116 117.. note:: 118 This is currently only available on GNU/Linux 119 120The :ref:`native_sim <native_sim>` target builds your Zephyr application 121with the Zephyr kernel, and some minimal HW emulation as a native Linux 122executable. 123 124This executable is a normal Linux program, which can be debugged and 125instrumented like any other, and it communicates with a physical or virtual 126external Controller. Refer to: 127 128- :ref:`bluetooth_qemu_native` for the physical controller 129- :ref:`bluetooth_virtual_posix` for the virtual controller 130 131.. _bluetooth-hw-setup-bsim: 132 133Simulated nRF5x with BabbleSim 134============================== 135 136.. note:: 137 This is currently only available on GNU/Linux 138 139The :ref:`nrf52_bsim <nrf52_bsim>` and :ref:`nrf5340bsim <nrf5340bsim>` boards, 140are simulated target boards 141which emulate the necessary peripherals of a nRF52/53 SOC to be able to develop 142and test BLE applications. 143These boards, use: 144 145 * `BabbleSim`_ to simulate the nRF5x modem and the radio environment. 146 * The POSIX arch and native simulator to emulate the processor, and run natively on your host. 147 * `Models of the nrf5x HW <https://github.com/BabbleSim/ext_NRF_hw_models/>`_ 148 149Just like with the :ref:`native_sim <native_sim>` target, the build result is a normal Linux 150executable. 151You can find more information on how to run simulations with one or several 152devices in either of :ref:`these boards's documentation <nrf52bsim_build_and_run>`. 153 154With the :ref:`nrf52_bsim <nrf52_bsim>`, typically you do :ref:`Combined builds 155<bluetooth-build-types>`, but it is also possible to build the controller with one of the 156:zephyr:code-sample:`bluetooth_hci_uart` samples in one simulated device, and the host with 157the H4 driver instead of the integrated controller in another simulated device. 158 159With the :ref:`nrf5340bsim <nrf5340bsim>`, you can build with either, both controller and host 160on its network core, or, with the network core running only the controller, the application 161core running the host and your application, and the HCI transport over IPC. 162 163Initialization 164************** 165 166The Bluetooth subsystem is initialized using the :c:func:`bt_enable` 167function. The caller should ensure that function succeeds by checking 168the return code for errors. If a function pointer is passed to 169:c:func:`bt_enable`, the initialization happens asynchronously, and the 170completion is notified through the given function. 171 172Bluetooth Application Example 173***************************** 174 175A simple Bluetooth beacon application is shown below. The application 176initializes the Bluetooth Subsystem and enables non-connectable 177advertising, effectively acting as a Bluetooth Low Energy broadcaster. 178 179.. literalinclude:: ../../../samples/bluetooth/beacon/src/main.c 180 :language: c 181 :lines: 19- 182 :linenos: 183 184The key APIs employed by the beacon sample are :c:func:`bt_enable` 185that's used to initialize Bluetooth and then :c:func:`bt_le_adv_start` 186that's used to start advertising a specific combination of advertising 187and scan response data. 188 189More Examples 190************* 191 192More :zephyr:code-sample-category:`sample Bluetooth applications <bluetooth>` are available in 193``samples/bluetooth/``. 194 195.. _BabbleSim: https://babblesim.github.io/ 196
