path: root/bluez-architecture.tex
diff options
Diffstat (limited to 'bluez-architecture.tex')
1 files changed, 425 insertions, 0 deletions
diff --git a/bluez-architecture.tex b/bluez-architecture.tex
new file mode 100644
index 0000000..dad4ab2
--- /dev/null
+++ b/bluez-architecture.tex
@@ -0,0 +1,425 @@
+\fancyfoot[C] {This document is confidential}
+\fancyfoot[R] {\thepage}
+\fancyhead[C] {BlueZ Architecture}
+\fancyhead[R] {\thepage}
+\title{BlueZ Architecture}
+ \author{João Paulo Rechi Vita \\
+ \and
+ Claudio Takahasi \\
+This document describes the BlueZ architecture. BlueZ is the official Linux
+Bluetooth protocol stack. It is an Open Source project distributed under GNU
+General Public License (GPL).
+\caption{BlueZ Architecture}
+BlueZ has three major components: kernel-level routines, bluetoothd daemon
+and user-level tools. The kernel is responsible for managing the Bluetooth
+hardware resources attached to the system handling manufacturer hooks, and
+providing an interface to the userspace. bluetoothd is a root level daemon
+responsible for providing a D-Bus interface to allow user applications to
+manage adapters, devices, and services.
+An overview of how these pieces fit together is depicted on Figure
+\section{Linux Bluetooth kernel architecture}
+Linux Bluetooth kernel subsystem consist of several layers:
+\item Bluetooth Core
+\subitem HCI device and connection manager, scheduler
+\subitem SCO audio links
+\subitem L2CAP (Logical Link Control and Adaptation Protocol)
+\subitem SMP (Security Manager Protocol) on LE (Low Energy) links
+\item HCI Device drivers (Interface to the hardware)
+\item RFCOMM Module (RFCOMM Protocol)
+\item BNEP Module (Bluetooth Network Encapsulation Protocol)
+\item CMTP Module (CAPI Message Transport Protocol)
+\item HIDP Module (Human Interface Device Protocol)
+Low Energy support changed the Bluetooth Core layer only. SMP and Signaling
+L2CAP fixed channels are not exposed to the userspace.
+Connection Parameter Update Procedure is handled completely inside the kernel.
+Acting as a master, BlueZ kernel accepts all valid parameters. At the moment,
+there isn't API to allow the userspace to initiate or reject the procedure.
+Security Manager is exposed to the userspace through the Management Interface.
+Pairing procedure can be triggered from the userspace by changing socket
+security level, sending HCI commands, or sending Pair Management Command.
+However, the exchanged keys are available through the Management events only,
+making this new Bluetooth kernel interface mandatory if security is required.
+\section{Linux Bluetooth userspace architecture}
+BlueZ userspace is composed by {\em bluetoothd}, libbluetooth, and command
+line tools. {\em bluetoothd} is the daemon responsible for the configuration
+of the Bluetooth modules in the kernel, and for providing user level APIs to
+manage local adapters and control device creation procedure.
+BlueZ core provides the abstraction to manage adapters, devices, services
+discovery, and security. Service (Profiles) plugins are implemented on the
+top of it. The major entities of the core are: adapter, device, sdp, agent
+for authorization and pairing, and GAttrib.
+In BlueZ, create a device means to get from the remote the services
+information, and to pair with it (CreatePairedDevice). BR/EDR and Bluetooth Low
+Energy uses the same API to discover devices and to manage pairing, the user
+does not need to know the adapters capabilities. The abstraction is implemented
+in the kernel and {\em bluetoothd} daemon.
+Service plugins are in general device driver(s) for a specific Bluetooth
+service. The design is based on the kernel device drivers: when the device
+is created, plugins are probed based on the supported UUIDs. It is analogous
+to kernel device driver ids. When a remote device exposes more than one
+service, each plugin gets a reference to the device {\em object}.
+Standard device discovery takes 10.12 seconds (defined in the Bluetooth GAP
+specification). For dual mode controllers, the GAP specification recomends
+a Interleaved Discovery Procedure: 5.12s inquiring followed by 5.12s scanning.
+In BlueZ, the discovery procedure works over both interfaces: Management, and
+standard HCI command interface. The abstraction is implemented by the
+{\em adapter\_ops} plugin, which hides from the {\em bluetoothd} upper layer
+the kernel interface in use. Management Interface has higer priority: if it is
+enabled in the kernel the default interface will be set to Management.
+Name resolution is part of the device discovery procedure for BlueZ. Since
+there aren't restrictions prohibiting to switch the order of the Interleave
+Discovery, BlueZ executes LE scanning before inquiry to reduce the discovery
+state machine complexity.
+Bonding for BLE works only over Management Interface. Pairing can be started
+increasing the socket security level, however the link keys, and authentication
+method setup requires Management Interface.
+BlueZ libs (a.k.a libbluetooth) is a development library which provides
+common functions and structures that can be used by Linux C programmers.
+libbluetooth usage is not encouraged, nowadays bluetoothd exposes friendly
+IPC methods (over D-Bus) which covers the most common operations. Usage of
+libbluetooth can be also introduce potential race conditions with bluetoothd
+The common functions declarations related to adapter setup, device and service
+discovery can be found in BlueZ headers: {\em lib} directory of the userspace
+source code repository.
+%\subsection{Standard Bluetooth Services}
+\subsection{Management Interface}
+The Management Interface ({\em mgmtops} plugin) is a new interface for the
+userspace to communicate with the kernel. Its purpose is to remove the raw
+HCI sockets from userspace and replace the deprecated {\em hciops} plugin (old
+Some advantages of {\em mgmtops} plugin in comparison with {\em hciops} plugin:
+\item Command queues and synchronization: All HCI traffic is handled by the kernel,
+ so the risk of conflicts between kernel and userspace is avoided.
+\item Blocking operations: No need to use the blocking ioctl interface to e.g.
+ power on/off adapters. Asynchronous messages are used, so blocking issues are
+ solved as well.
+\item Distributed security policy and logic: user interaction and link key storage
+ is handled in userpace and kernel handles link key requests.
+\item Early-tracing capability: special tracing socket will permit userspace catch
+ all HCI traffic since first moment which adapter is plugged.
+There is a layer called {\em adapter operations} (\verb|src/adapter.c|) that
+describes how to communicate with kernel side. For the management interface,
+this layer is implemented in \verb|plugins/mgmtops.c|.
+The MGMT interface is enabled by default on recent Linux kernel tree. It is
+still necessary to enable the LE support, so it can be used with LE devices.
+There are two ways to enable LE support:
+\item If the Bluetooth subsystem is compiled as module, it can be enabled while
+ loading the {\em bluetooth} module:
+$ sudo modprobe bluetooth enable_le
+\item Otherwise, if it is built-in, or the module is already loaded, enable it at
+ runtime with:
+$ echo 1 | sudo tee /sys/module/bluetooth/parameters/enable_le
+To verify that LE support is enabled, use:
+$ cat /sys/module/bluetooth/parameters/enable_le
+It will show \verb|Y| if LE support is enabled.
+BlueZ will use mgmtops automatically instead of hciops if it detects that the
+kernel has support for mgmt.
+Note that all LE development is being implemented only for the management
+interface. No support or updates to hciops will be provided.
+Detailed information regarding management interface is available at {\em
+doc/mgmt-api.txt}. For a technical introduction and rationale, see at BlueZ
+homepage \cite{bzhp}.
+\subsection{Security Manager}
+The Security Manager (SM) defines the protocol and behavior to manage pairing
+and key distribution, authentication and encryption between LE devices.
+The device in the master role shall initiate the Security procedures and the
+device in the slave role shall respond. The slave will send to the master a
+Security Request command and it may encrypt the link or reject de request.
+In the BlueZ, only the minimum from Security Manager was implemented.
+Currently, only the method {\em Just Works} is supported (method provides no
+protection against eavesdroppers or man in the middle attacks during the
+pairing process).
+In BlueZ API, there are two methods to connect and/or pair with devices,
+{\em CreateDevice} and {\em CreatePairedDevice}.
+{\em CreateDevice} creates a new object path for a remote device and
+connects to the device. It will retrieve all SDP records. Note that this
+method will fail if a path for the remote device already exists.
+{\em CreatePairedDevice} shares some characteristics with {\em CreateDevice}.
+It creates object path (if not exists), connects to the remote device and then
+initiates the pairing. It will fail if the pairing already exists.
+Consequently there is the option of create a device connection with
+{\em CreateDevice} and pair after with {\em CreatePairedDevice}.
+Additionally, we can increase the connection security with the \verb|bt_io_set()| function,
+setting the level to \verb|BT_IO_OPT_SEC_LEVEL|. After that, a
+security request is sent to the master and the security process is initiated.
+\subsection{Services over GATT}
+The Generic Attribute Profile (GATT) defines a service framework for
+discovering services, and reading and writing characteristics using Attribute
+A service is composed by service declaration and characteristic definitions.
+Attribute is the basic element used to describe services and characteristics.
+Currently, the adopted GATT based services run over Low Energy transport only.
+However, BlueZ architecture supports to run GATT services over both transports:
+BR/EDR and Low Energy.
+For BR/EDR, L2CAP PSM 0x001F is reserved for ATT. For Low Energy, the fixed
+L2CAP channel ID 0x0004 is reserved for ATT protocol.
+ATT is a sequential request-response protocol. A client shall not send a second
+request before receiving the response of the first request. In order to manage
+the restrictions imposed by the protocol, an abstraction called GAttrib has
+been created, allowing to share the same socket between multiple services.
+Roughly speaking, GAttrib is a command/response queue shared between multiple
+local GATT profiles (server and/or client roles).
+BlueZ exposes a Generic Attribute API \footnote{doc/attribute-api.txt} and
+Profile specific APIs. Generic Attribute API is suitable for proprietary
+services and services that doesn't require to access low level platform
+services. Proximity Path Loss is an example, RSSI needs to be monitored
+on regular intervals to calculate the path loss. It is not related to
+GATT/ATT and read the RSSI requires permission to send a HCI command.
+The reason behind GATT Profile specific API hide from the user GATT/ATT
+internals and move the qualification for the stack instead of the upper
+layer GATT applications.
+\subsubsection{GAttrib and ATT connection callbacks}
+Usually, there is only one GAttrib instance for each device connection, which
+is destroyed when the connection is terminated. In order to support a multiple
+profile scenario, GAttrib instances are reference counted. Therefore, profiles
+need to hold at least one reference to a GAttrib for as long as the connection
+is necessary, and drop this reference when the connection is no longer needed.
+It is possible to run custom code when a connection is established or
+terminated by using {\em ATT connection callbacks} (or attio callbacks, for short).
+These callbacks should be registered whenever the GATT profile has intent to
+communicate with a remote device. When implementing attio callbacks, it is
+important to make sure there is a valid reference to the current GAttrib as
+long as there is a need to use the active connection.
+\subsubsection{Generic Attribute API}
+Generic Attribute is a GATT client API based on concept of characteristics.
+At the moment BlueZ supports dual mode adapters only, due the GAP restrictions
+dual mode controllers should not send connectable advertise events. Meaning
+the LE connection should be always started by the BlueZ host.
+ATT channel is shared between several modules in BlueZ. Upper layer applications
+using this API should register a watcher to control connections, and to receive
+The Proximity profile specification defines the behavior related to the spatial
+relationship between devices (how the device will act when the connection is
+lost or the path loss increases, etc.).
+It includes two roles: the Proximity Reporter (GATT server) and the Proximity
+Monitor (GATT client).
+A device that supports the Proximity Reporter role shall implement the Link
+Loss service \cite{lls}, and optionally the Immediate Alert \cite{ias} and TX
+Power \cite{txp} services.
+A device that supports the Proximity Monitor role should contain an application
+that interacts with the Link Loss service and optionally the Immediate Alert
+and TX Power services. This application should allow the user to set the alert
+This profile is implemented in BlueZ and has a specific D-Bus API (described in
+{\em doc/proximity-api.txt} located on BlueZ source code) for both roles.
+For Monitor role there is:
+\item Methods: GetProperties(), SetProperty()
+\item Signals: PropertyChanged()
+\item Properties: SignalLevel, LinkLossAlertLevel, ImmediateAlertLevel
+For Reporter role:
+\item Methods: GetProperties()
+\item Signals: PropertyChanged()
+\item Properties: ImmediateAlertLevel, LinkLossAlertLevel
+The upper layer application defines business logic. In the case of the Monitor
+{\em ImmediateAlertLevel} property is exported to allow the application to
+select the alert level for a given device. For Proximity Reporter, this API
+design allows to trigger actions or play distinct alerts/sound per device.
+\subsubsection{Find Me}
+The Find Me profile \cite{fdmp} defines the behavior related to pressing a button on
+one device causing an alert or similar behavior on the peer device.
+It includes two roles: Find Me target role (GATT server) and the Find Me
+Locator role (GATT client).
+The Find Me Target shall have only one instance of the Immediate Alert Service
+(IAS). In BlueZ, the service implementation is shared with the Proximity
+profile (Reporter role), because it also uses the same IAS instance. The same
+applies to the client side: Find Me Locator and Proximity Monitor share the
+same D-Bus interface.
+Note that even if a peer device only supports one profile (either Proximity or
+Find Me), the API will still work at least for the shared {\em Immediate Alert}
+This profile is used to interact with data gathered from temperature sensors.
+There are two roles in this profile: {\em Thermometer} and {\em Collector}.
+For devices that support {\em Thermometer Role}, thermal data is stored and
+exposed to {\em Collector}. It is mandatory to have {\em Device Information}
+\cite{dis} service (general device characteristics) and {\em Health
+Thermometer} \cite{hts} service (temperature measurements).
+The {\em Collector Role} connects to {\em Thermometer} to obtain health
+temperatures. {\em Device Information} \cite{dis} service is optional, but
+{\em Health Thermometer} \cite{hts} service is mandatory.
+{\em Thermometer} \cite{htp} profile is implemented in BlueZ and accessible via
+D-Bus (described in {\em doc/thermometer-api.txt}).
+Under \verb|org.bluez.Thermometer| interface, there is:
+\item Methods: SetProperty(), GetProperties(), RegisterWatcher(),
+UnregisterWatcher(), EnableIntermediateMeasurement(),
+\item Signals: PropertyChanged()
+\item Properties: Intermediate, Interval, Maximum, Minimum
+The method \verb|RegisterWatcher| receives a Watcher. That object should
+implement the \verb|MeasurementReceived| method with a dict parameter:
+ "Exponent" : int8,
+ "Mantissa" : int32,
+ "Unit" : ("Celsius" or "Fahrenheit"),
+ "Time" : uint64,
+ "Type" : ("Armpit", "Body", "Ear", "Finger", "Intestines",
+ "Mouth", "Rectum", "Toe", "Tympanum"),
+ "Measurement" : ("Final" or "Intermediate")
+The \verb|Time| value is expressed in seconds since epoch.
+The temperature value is represented by \verb|(mantissa) x (10**exponent)|.
+\section{Contact channels}
+\bibitem{bzhp}The upcoming Management Interface. \url{}
+\bibitem{lls}Link Loss service. \url{}
+\bibitem{ias}Immediate Alert service. \url{}
+\bibitem{txp}TX Power service. \url{}
+\bibitem{fdmp}Find Me profile. \url{}
+\bibitem{htp}Health Thermometer profile. \url{}
+\bibitem{hts}Health Thermometer service. \url{}
+\bibitem{dis}Device Information service. \url{}