mirror/btstack
1
0
Fork 0
mirror of https://github.com/bluekitchen/btstack.git synced 2025-03-10 22:13:37 +00:00
Code Issues Packages Projects Releases Wiki Activity

work on supported profiles and protocols

Browse Source
This commit is contained in:
mila@ringwald.ch 2014-11-07 16:08:26 +00:00
parent e2b9f4ac0f
commit 302495ebce
4 changed files with 354 additions and 89 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

47
docs/manual/bluetooth_classic.tex Normal file
View File

@ -0,0 +1,47 @@
% !TEX root = btstack_gettingstarted.tex
\subsection{Classic Bluetooth}
\subsubsection{HCI - Host Controller Interface}
The HCI protocol provides a command interface to the Bluetooth chipset.
\subsubsection{L2CAP - Logical Link Control and Adaptation Protocol}
The L2CAP protocol supports higher level protocol multiplexing and packet fragmentation.
%\section{Security Levels and L2AP}
\subsubsection{RFCOMM - Radio Frequency Communication Protocol}
%\label{section:flowcontrol}
The Radio frequency communication (RFCOMM) protocol provides emulation of serial ports over the L2CAP protocol.
and reassembly.
\textbf{RFCOMM flow control.}
RFCOMM has a mandatory credit-based flow-control. This means that two devices that established RFCOMM connection, use credits to keep track of how many more RFCOMM data packets can be sent to each. If a device has no (outgoing) credits left, it cannot send another RFCOMM packet, the transmission must be paused. During the connection establishment, initial credits are provided. BTstack tracks the number of credits in both directions. If no outgoing credits are available, the RFCOMM send function will return an error, and you can try later. For incoming data, BTstack provides channels and services with and without automatic credit management via different functions to create/register them respectively. If the management of credits is automatic, the new credits are provided when needed relying on ACL flow control - this is only useful if there is not much data transmitted and/or only one physical connection is used. If the management of credits is manual, credits are provided by the application such that it can manage its receive buffers explicitly.
\todo{\textbf{RFCOMM port configuration for both local and remote}}\\
\todo{\textbf{RFCOMM modem and line status control/information}}\\
\todo{\textbf{RFCOMM\_AGGREGATE\_FLOW\_OFF example}}\\
\todo{\textbf{Security Levels and RFCOMM}}\\
\subsection{SDP - Service Discovery Protocol}
The SDP protocol allows to discover services provided by a Bluetooth device.
\subsubsection{SPP - Serial Port Profile}
The SPP profile defines how to set up virtual serial ports and connect two Bluetooth enabled devices. See Appendix \ref{appendix:api_} for the SPP API.
\subsubsection{BNEP - Bluetooth Network Encapsulation Protocol}
The BNEP protocol is built on top of L2CAP and it is used to transport control and data packets over standard network protocols such as TCP, IPv4 or IPv6. . BNEP specifies a minimum L2CAP MTU of 1691.
\subsubsection{PAN - Personal Area Networking Profile}
The PAN profile uses BNEP to provide on-demand networking capabilities between Bluetooth devices. The PAN profile defines the following roles:
\begin{itemize}
\item PAN User (PANU)
\item Network Access Point (NAP)
\item Group Ad-hoc Network (GN)
\end{itemize}
PANU is a Bluetooth device that communicates as a client with GN, or NAP, or with another PANU Bluetooth device, through a point-to-point connection. Either the PANU or the other Bluetooth device may terminate the connection at anytime.
NAP is a Bluetooth device that provides the service of routing network packets between PANU by using BNEP and the IP routing mechanism. A NAP can also act as a bridge between Bluetooth networks and other network technologies by using the Ethernet packets.
The GN role enables two or more PANUs to interact with each other through a wireless network without using additional networking hardware. The devices are connected in a piconet where the GN acts as a master and communicates either point-to-point or a point-to-multipoint with a maximum of seven PANU slaves by using BNEP.
Currently, BTstack supports only PANU.

49
docs/manual/bluetooth_low_energy.tex Normal file
View File

@ -0,0 +1,49 @@
% !TEX root = btstack_gettingstarted.tex
\subsection{Low Energy}
The focus is on two different device roles: devices that provide services and/or can be controlled and devices that consume services and/or control other devices. Devices are first going through the advertising process that is governed by the Generic Access Profile (GAP). Once the connection is established, the communication will be governed by the Generic Attribute Profile (GATT). Both profiles, GAP and GATT, have concepts that describe these two BLE roles: GAP defines Peripheral and Central, and GATT defines Server and Client role respectively. The GATT roles are not necessarily tied to specific GAP roles and may be specified by higher layer profiles. GATT is built on top of the Attribute Protocol (ATT), which defines how to discover, read, and write attributes on a peer device. In addition, BLE uses two more BT protocols: SMP for for pairing and transport specific key distribution and L2CAP LE variant optimized for connectionless data used by Bluetooth Low Energy devices.
\textbf{Private/random addresses.}
To better protect privacy, a LE device can choose use a private i.e. random Bluetooth address. This address changes at a user-specified rate. To allow for later reconnection, the central and peripheral devices exchange their Identity Resolving Keys (IRKs) during bonding. The IRK is used to verify if a new address belongs to a previously bonded device.
\subsubsection{L2CAP LE - L2CAP Low Energy Protocol}
The L2CAP LE variant is optimized for connectionless data used by Bluetooth Low Energy devices. It is the base for the Attribute Protocol (ATT) of Bluetooth LE, which defines how to discover, read, and write attributes on a peer device. % , and the conveying of quality of service information. - L2CAP _can_ do this, but BTstack does not
\subsubsection{SMP - Security Manager Protocol }
The SMP protocol allows to setup authenticated and encrypted connection.
\subsubsection{ATT - Attribute Protocol}
ATT is a wire application protocol, while GATT dictates how ATT is employed in service composition. Every Low Energy profile must be based on GATT. So, ultimately, every LE service uses ATT as the application protocol. An ATT server stores attributes. An ATT client stores nothing; it uses the ATT wire protocol to read and write values on server attributes. Most of the ATT protocol is pure client-server: client takes the initiative, server answers. But ATT has notification and indication capabilities, in which the server takes the initiative of notifying a client that an attribute value has changed, saving the client from having to poll the attribute.
\subsubsection{GAP - Generic Access Profile for Low Energy}
The GAP profile defines how to discover and how to connect to a Bluetooth device. There are several GAP roles that a Bluetooth device can take, but the most important ones are the Central and the Peripheral role. Peripheral devices are those that provide information or can be controlled and central devices are those that consume information or control the peripherals. Before the connection can be established, devices are first going through the advertising process. What happens with the peripheral device after the central device connect to a it, depends on the peripheral's Bluetooth controller. The peripheral will either stop advertising itself and other devices will no longer be able to see it or connect to it until the existing connection is broken, or it will be able to continue with advertising so that the parallel connections can be established.
\textbf{GAP BLE Roles.}
There are four GAP roles defined for a Bluetooth low energy device: Broadcaster, Observer, Peripheral and Central. A device may operate in multiple GAP roles concurrently.
\begin{itemize}
\item \emph{GAP Broadcaster Role} - A broadcast device only sends advertisements and cannot be connected. It can emit some useful data as part of the advertisement. The most prominent use for this is Apple's iBeacon technology which uses broadcast devices to emit a unique ID. Apple's iOS framework then help to map this ID onto a specific location, e.g., in a museum. Broadcasting is efficient as no connection and no ATT database are needed. To control energy consumption the broadcast interval can be configured. An advertisement can contain up to 31 bytes of information. In addition, another 31 bytes of information can be sent in the scan response.
\item \emph{GAP Observer Role} - An observer device only receives advertising events and cannot be connected.
\item \emph{GAP Central Role} - The role of the central device is to scan for peripherals, connect to them, and discover and receive data from them or sends data to control them. During scanning the central device can retrieve information on other device such are its name and unique number, as well as some broadcast data from its services. Upon connection, the central explores the device by discovering its primary and included services, characteristics, and characteristic descriptors.
\item \emph{GAP Peripheral Role} - The role of a peripheral device is to deliver information on their inputs, i.e. sensor values, battery level, current time, to the applications running on central devices. It can also receive a write request from a central device and control connected actors, e.g. turn on and set the color of the light. Peripherals can broadcast data, they can be discovered and connected to by a central device, they can stay also disconnected and then establish connection when needed.
\end{itemize}
\textbf{Advertising and Scan Response Data.}
There are two ways to send advertising out with GAP: The Advertising Data payload and the Scan Response payload. Both payloads are identical and can contain up to 31 bytes of data, but only the advertising data payload is mandatory. The scan response payload is an optional secondary payload that central devices can request.
\todo{\textbf{Dedicated bonding.}}
\subsubsection{GATT - Generic Attribute Profile}
The GATT profile uses the ATT for discovering services, and for reading and writing characteristic values on a peer device. GATT also specifies the format of data contained on the GATT server: it groups ATT attributes into Services and Characteristics, and defines set of queries the GATT Client can use to discover services, characteristics.
\textbf{GATT LE Roles.}
There are two GATT roles defined for a Bluetooth low energy device:
\begin{itemize}
\item \emph{GATT Server Role} - The GATT server stores the data and accepts GATT client requests, commands and confirmations. The GATT server sends responses to requests and when configured, sends indication and notifications asynchronously to the GATT client.
\item \emph{GATT Client Role} - The GATT Client is used to discover services, and their characteristics and descriptors on a peer device. It can also subscribe for notifications or indications that the characteristic on the GATT server has changed its value.
\end{itemize}
\textbf{Attribute Database - GATT-based Profile Hierarchy.}
Attributes, as transported by the Attribute Protocol, are formatted as services and characteristics. Services may contain a collection of characteristics. Characteristics contain a single value and any number of descriptors describing the characteristic value. The peripheral device server (ATT server) provides a set of attributes that are stored in a simple lookup database. GATT formats these attributes as services and characteristics. Services may contain a collection of characteristics. Characteristics contain a single value and any number of descriptors describing the characteristic value. A service starts with a service declaration attribute defining its type, i.e. primary or secondary. It is followed by the included services and characteristics. By means of including services, the service can incorporate more complex behavior, and still keep the definition small. A characteristic is assigned to a single value that can be accessed. It is composed of three basic elements: declaration, value and descriptors. The characteristic declaration defines how the data can be accessed. A characteristic descriptor is used to capture the additional properties, e.g., to configure if the characteristic value should be reported upon its change. Together, characteristic declaration and the descriptors define types of action that can be performed on characteristic value.
The security that is required to access a service or a characteristic is defined in ATT database along with service/characteristic declaration. The GATT Server usually does not initiate any security request, but it can.

230
docs/manual/example_spp_le_counter.tex Normal file
View File

@ -0,0 +1,230 @@
% !TEX root = btstack_gettingstarted.tex
\subsection{spp\_and\_le\_counter - Dual mode example}
\begin{lstlisting}[caption= SPP\&LE client setup., label=code:spp_le_setup]
#define RFCOMM_SERVER_CHANNEL 1
static uint16_t rfcomm_channel_id;
static uint8_t spp_service_buffer[150];
static int le_notification_enabled;
const uint8_t adv_data[] = {
// Flags general discoverable
0x02, 0x01, 0x02,
// Name
0x0b, 0x09, 'L', 'E', ' ', 'C', 'o', 'u', 'n', 't', 'e', 'r',
};
uint8_t adv_data_len = sizeof(adv_data);
static uint16_t todos = 0;
void setup(void){
...
l2cap_init();
l2cap_register_packet_handler(packet_handler);
rfcomm_init();
rfcomm_register_packet_handler(packet_handler);
rfcomm_register_service_internal(NULL, RFCOMM_SERVER_CHANNEL, 100); // reserved channel, mtu=100
// init SDP, create record for SPP and register with SDP
sdp_init();
memset(spp_service_buffer, 0, sizeof(spp_service_buffer));
sdp_create_spp_service( spp_service_buffer, RFCOMM_SERVER_CHANNEL, "SPP Counter");
printf("SDP service record size: %u\n", de_get_len(spp_service_buffer));
sdp_register_service_internal(NULL, spp_service_buffer);
hci_ssp_set_io_capability(SSP_IO_CAPABILITY_DISPLAY_YES_NO);
// setup central device db
central_device_db_init();
// setup SM: Display only
sm_init();
// setup ATT server
att_server_init(profile_data, att_read_callback, att_write_callback);
att_dump_attributes();
}
\end{lstlisting}
\begin{lstlisting}[caption= SPP\&LE client - heartbeat handler., label=code:spp_le_heartbeat_handler]
#define HEARTBEAT_PERIOD_MS 1000
// The Counter
static int counter = 0;
static char counter_string[30];
static int counter_string_len;
static void heartbeat_handler(struct timer *ts){
counter++;
counter_string_len = sprintf(counter_string, "BTstack counter %04u\n", counter);
if (rfcomm_channel_id){
if (rfcomm_can_send_packet_now(rfcomm_channel_id)) {
int err = rfcomm_send_internal(rfcomm_channel_id, (uint8_t*) counter_string, counter_string_len);
if (err) {
log_error("rfcomm_send_internal -> error 0X%02x", err);
} else {
printf("%s", counter_string);
}
}
}
if (le_notification_enabled) {
att_server_notify(ATT_CHARACTERISTIC_0000FF11_0000_1000_8000_00805F9B34FB_01_VALUE_HANDLE, (uint8_t*) counter_string, counter_string_len);
}
run_loop_set_timer(ts, HEARTBEAT_PERIOD_MS);
run_loop_add_timer(ts);
}
\end{lstlisting}
\begin{lstlisting}[caption= SPP\&LE client - ATT Client Read Callback for Dynamic Data., label=code:spp_le_read_callback]
// - if buffer == NULL, don't copy data, just return size of value
// - if buffer != NULL, copy data and return number bytes copied
// @param offset defines start of attribute value
static uint16_t att_read_callback(uint16_t con_handle, uint16_t att_handle, uint16_t offset, uint8_t * buffer, uint16_t buffer_size){
if (att_handle == ATT_CHARACTERISTIC_0000FF11_0000_1000_8000_00805F9B34FB_01_VALUE_HANDLE){
if (buffer){
memcpy(buffer, &counter_string[offset], counter_string_len - offset);
}
return counter_string_len - offset;
}
return 0;
}
\end{lstlisting}
\begin{lstlisting}[caption= SPP\&LE client - ATT Client Write Callback., label=code:spp_le_write_callback]
// write requests
static int att_write_callback(uint16_t con_handle, uint16_t att_handle, uint16_t transaction_mode, uint16_t offset, uint8_t *buffer, uint16_t buffer_size){
// printf("WRITE Callback, handle %04x, mode %u, offset %u, data: ", handle, transaction_mode, offset);
// printf_hexdump(buffer, buffer_size);
if (att_handle != ATT_CHARACTERISTIC_0000FF11_0000_1000_8000_00805F9B34FB_01_CLIENT_CONFIGURATION_HANDLE) return 0;
le_notification_enabled = READ_BT_16(buffer, 0) == GATT_CLIENT_CHARACTERISTICS_CONFIGURATION_NOTIFICATION;
return 0;
}
\end{lstlisting}
\begin{lstlisting}[caption= SPP\&LE client - GAP run., label=code:spp_le_gap_run]
enum {
SET_ADVERTISEMENT_PARAMS = 1 << 0,
SET_ADVERTISEMENT_DATA = 1 << 1,
ENABLE_ADVERTISEMENTS = 1 << 2,
};
static void gap_run(){
if (!hci_can_send_command_packet_now()) return;
if (todos & SET_ADVERTISEMENT_DATA){
printf("GAP_RUN: set advertisement data\n");
todos &= ~SET_ADVERTISEMENT_DATA;
hci_send_cmd(&hci_le_set_advertising_data, adv_data_len, adv_data);
return;
}
if (todos & SET_ADVERTISEMENT_PARAMS){
todos &= ~SET_ADVERTISEMENT_PARAMS;
uint8_t adv_type = 0; // default
bd_addr_t null_addr;
memset(null_addr, 0, 6);
uint16_t adv_int_min = 0x0030;
uint16_t adv_int_max = 0x0030;
hci_send_cmd(&hci_le_set_advertising_parameters, adv_int_min, adv_int_max, adv_type, 0, 0, &null_addr, 0x07, 0x00);
return;
}
if (todos & ENABLE_ADVERTISEMENTS){
printf("GAP_RUN: enable advertisements\n");
todos &= ~ENABLE_ADVERTISEMENTS;
hci_send_cmd(&hci_le_set_advertise_enable, 1);
return;
}
}
\end{lstlisting}
\begin{lstlisting}[caption= SPP\&LE client - packet handler., label=code:spp_le_gap_run]
static void packet_handler (void * connection, uint8_t packet_type, uint16_t channel, uint8_t *packet, uint16_t size){
bd_addr_t event_addr;
uint8_t rfcomm_channel_nr;
uint16_t mtu;
int i;
switch (packet_type) {
case HCI_EVENT_PACKET:
switch (packet[0]) {
case BTSTACK_EVENT_STATE:
// bt stack activated, get started - set local name
if (packet[2] == HCI_STATE_WORKING) {
todos = SET_ADVERTISEMENT_PARAMS | SET_ADVERTISEMENT_DATA | ENABLE_ADVERTISEMENTS;
gap_run();
}
break;
case HCI_EVENT_PIN_CODE_REQUEST:
// inform about pin code request
printf("Pin code request - using '0000'\n");
bt_flip_addr(event_addr, &packet[2]);
hci_send_cmd(&hci_pin_code_request_reply, &event_addr, 4, "0000");
break;
case HCI_EVENT_USER_CONFIRMATION_REQUEST:
// inform about user confirmation request
printf("SSP User Confirmation Request with numeric value '%06u'\n", READ_BT_32(packet, 8));
printf("SSP User Confirmation Auto accept\n");
break;
case HCI_EVENT_DISCONNECTION_COMPLETE:
todos = ENABLE_ADVERTISEMENTS;
le_notification_enabled = 0;
gap_run();
break;
case RFCOMM_EVENT_INCOMING_CONNECTION:
// data: event (8), len(8), address(48), channel (8), rfcomm_cid (16)
bt_flip_addr(event_addr, &packet[2]);
rfcomm_channel_nr = packet[8];
rfcomm_channel_id = READ_BT_16(packet, 9);
printf("RFCOMM channel %u requested for %s\n", rfcomm_channel_nr, bd_addr_to_str(event_addr));
rfcomm_accept_connection_internal(rfcomm_channel_id);
break;
case RFCOMM_EVENT_OPEN_CHANNEL_COMPLETE:
// data: event(8), len(8), status (8), address (48), server channel(8), rfcomm_cid(16), max frame size(16)
if (packet[2]) {
printf("RFCOMM channel open failed, status %u\n", packet[2]);
} else {
rfcomm_channel_id = READ_BT_16(packet, 12);
mtu = READ_BT_16(packet, 14);
printf("\nRFCOMM channel open succeeded. New RFCOMM Channel ID %u, max frame size %u\n", rfcomm_channel_id, mtu);
}
break;
case RFCOMM_EVENT_CHANNEL_CLOSED:
printf("RFCOMM channel closed\n");
rfcomm_channel_id = 0;
break;
default:
break;
}
break;
case RFCOMM_DATA_PACKET:
printf("RCV: '");
for (i=0;i<size;i++){
putchar(packet[i]);
}
printf("'\n");
break;
default:
break;
}
gap_run();
}
\end{lstlisting}

113
docs/manual/protocols_profiles.tex
View File

@ -1,108 +1,47 @@
% !TEX root = btstack_gettingstarted.tex
\section{Protocols and Profiles}
\label{section:protocols_profiles}
BTstack implements following Bluetooh protocols: HCI, L2CAP, L2CAP-LE, RFCOMM, SDP, SMP, and ATT, as well as three profiles: GATT, GAP and SPP, see Figure \ref{fig:BTstackProtocolArchitecture}.
\begin{figure}[htbp] % figure placement: here, top, bottom, or page
\centering
\includegraphics[width=0.7\textwidth]{picts/btstack-protocols.pdf}
\caption{BTstack Protocol Architecture}
\caption{\todo{BTstack Protocol Architecture - update}}
\label{fig:BTstackProtocolArchitecture}
\end{figure}
\subsection{HCI - Host Controller Interface}
The HCI protocol provides a command interface to the Bluetooth chipset.
\subsection{L2CAP - Logical Link Control and Adaptation Protocol}
The L2CAP protocol supports higher level protocol multiplexing and packet fragmentation.
%\section{Security Levels and L2AP}
\subsection{L2CAP LE - L2CAP Low Energy Protocol}
The L2CAP LE variant is optimized for connectionless data used by Bluetooth Low Energy devices. It is the base for the Attribute Protocol (ATT) of Bluetooth LE, which defines how to discover, read, and write attributes on a peer device. % , and the conveying of quality of service information. - L2CAP _can_ do this, but BTstack does not
\subsection{RFCOMM - Radio Frequency Communication Protocol}
The Radio frequency communication (RFCOMM) protocol provides emulation of serial ports over the L2CAP protocol.
and reassembly.
\subsubsection{RFCOMM flow control}
\label{section:flowcontrol}
RFCOMM has a mandatory credit-based flow-control. This means that two devices that established RFCOMM connection, use credits to keep track of how many more RFCOMM data packets can be sent to each. If a device has no (outgoing) credits left, it cannot send another RFCOMM packet, the transmission must be paused. During the connection establishment, initial credits are provided. BTstack tracks the number of credits in both directions. If no outgoing credits are available, the RFCOMM send function will return an error, and you can try later. For incoming data, BTstack provides channels and services with and without automatic credit management via different functions to create/register them respectively. If the management of credits is automatic, the new credits are provided when needed relying on ACL flow control - this is only useful if there is not much data transmitted and/or only one physical connection is used. If the management of credits is manual, credits are provided by the application such that it can manage its receive buffers explicitly.
\subsubsection{RFCOMM configuration - TODO}
\todo{rfcomm configuration}
%\subsection{add RFCOMM port configuration for both local and remote}
%\subsection{add RFCOMM modem and line status control/information}
%\subsection{add RFCOMM\_AGGREGATE\_FLOW\_OFF to recoverable RFCOMM send errors (example in tex, code)}
%\section{Security Levels and RFCOMM}
\subsection{SDP - Service Discovery Protocol}
The SDP protocol allows to discover services provided by a Bluetooth device.
\subsection{SMP - Security Manager Protocol }
The SMP protocol allows to setup authenticated and encrypted connection.
\subsection{ATT - Attribute Protocol}
ATT is a wire application protocol, while GATT dictates how ATT is employed in service composition. Every Low Energy profile must be based on GATT. So, ultimately, every LE service uses ATT as the application protocol. An ATT server stores attributes. An ATT client stores nothing; it uses the ATT wire protocol to read and write values on server attributes. Most of the ATT protocol is pure client-server: client takes the initiative, server answers. But ATT has notification and indication capabilities, in which the server takes the initiative of notifying a client that an attribute value has changed, saving the client from having to poll the attribute.
\subsection{SPP - Serial Port Profile}
The SPP profile defines how to set up virtual serial ports and connect two Bluetooth enabled devices. See Appendix \ref{appendix:api_} for the SPP API.
\subsection{GAP - Generic Access Profile for Low Energy}
The GAP profile defines how to discover and how to connect to a Bluetooth device. There are several GAP roles that a Bluetooth device can take, but the most important ones are the Central and the Peripheral role. Peripheral devices are those that provide information or can be controlled and central devices are those that consume information or control the peripherals. Before the connection can be established, devices are first going through the advertising process. What happens with the peripheral device after the central device connect to a it, depends on the peripheral's Bluetooth controller. The peripheral will either stop advertising itself and other devices will no longer be able to see it or connect to it until the existing connection is broken, or it will be able to continue with advertising so that the parallel connections can be established.
\subsubsection{GAP BLE Roles}
There are four GAP roles defined for a Bluetooth low energy device: Broadcaster, Observer, Peripheral and Central. A device may operate in multiple GAP roles concurrently.
\pagebreak
BTstack implements a subset of Bluetooth protocols and profiles that can be utilized in:
\begin{itemize}
\item \emph{GAP Broadcaster Role} - A broadcast device only sends advertisements and cannot be connected. It can emit some useful data as part of the advertisement. The most prominent use for this is Apple's iBeacon technology which uses broadcast devices to emit a unique ID. Apple's iOS framework then help to map this ID onto a specific location, e.g., in a museum. Broadcasting is efficient as no connection and no ATT database are needed. To control energy consumption the broadcast interval can be configured. An advertisement can contain up to 31 bytes of information. In addition, another 31 bytes of information can be sent in the scan response.
\item \emph{GAP Observer Role} - An observer device only receives advertising events and cannot be connected.
\item \emph{GAP Central Role} - The role of the central device is to scan for peripherals, connect to them, and discover and receive data from them or sends data to control them. During scanning the central device can retrieve information on other device such are its name and unique number, as well as some broadcast data from its services. Upon connection, the central explores the device by discovering its primary and included services, characteristics, and characteristic descriptors.
\item \emph{GAP Peripheral Role} - The role of a peripheral device is to deliver information on their inputs, i.e. sensor values, battery level, current time, to the applications running on central devices. It can also receive a write request from a central device and control connected actors, e.g. turn on and set the color of the light. Peripherals can broadcast data, they can be discovered and connected to by a central device, they can stay also disconnected and then establish connection when needed.
\end{itemize}
\subsubsection{Advertising and Scan Response Data}
There are two ways to send advertising out with GAP: The Advertising Data payload and the Scan Response payload. Both payloads are identical and can contain up to 31 bytes of data, but only the advertising data payload is mandatory. The scan response payload is an optional secondary payload that central devices can request.
\subsubsection{Dedicated bonding}
\subsection{GATT - Generic Attribute Profile}
The GATT profile uses the ATT for discovering services, and for reading and writing characteristic values on a peer device. GATT also specifies the format of data contained on the GATT server: it groups ATT attributes into Services and Characteristics, and defines set of queries the GATT Client can use to discover services, characteristics.
\subsubsection{GATT BLE Roles}
\begin{itemize}
\item \emph{GATT Server Role} - The GATT server stores the data and accepts GATT client requests, commands and confirmations. The GATT server sends responses to requests and when configured, sends indication and notifications asynchronously to the GATT client.
\item \emph{GATT Client Role} - The GATT Client is used to discover services, and their characteristics and descriptors on a peer device. It can also subscribe for notifications or indications that the characteristic on the GATT server has changed its value.
\item Classic Bluetooth applications
\item Low Energy (LE) Bluetooth applications
\item Dual-mode applications (using both Classic and LE technologies)
\item Made for iPhone applications (MFi)
\end{itemize}
\subsubsection{Attribute Database - GATT-based Profile Hierarchy}
Attributes, as transported by the Attribute Protocol, are formatted as services and characteristics. Services may contain a collection of characteristics. Characteristics contain a single value and any number of descriptors describing the characteristic value. The peripheral device server (ATT server) provides a set of attributes that are stored in a simple lookup database. GATT formats these attributes as services and characteristics. Services may contain a collection of characteristics. Characteristics contain a single value and any number of descriptors describing the characteristic value. A service starts with a service declaration attribute defining its type, i.e. primary or secondary. It is followed by the included services and characteristics. By means of including services, the service can incorporate more complex behavior, and still keep the definition small. A characteristic is assigned to a single value that can be accessed. It is composed of three basic elements: declaration, value and descriptors. The characteristic declaration defines how the data can be accessed. A characteristic descriptor is used to capture the additional properties, e.g., to configure if the characteristic value should be reported upon its change. Together, characteristic declaration and the descriptors define types of action that can be performed on characteristic value.
The Basic Rate/Extended Data Rate (BR/EDR) technology, also known as Classic Bluetooth, provides a robust wireless connection between devices designed for high data rate transfer. In addition, it is associated with high connection setup latency, and high power consumption. The applications range from headsets and cars to industrial controllers.
The security that is required to access a service or a characteristic is defined in ATT database along with service/characteristic declaration. The GATT Server usually does not initiate any security request, but it can.
The Low Energy (LE) is a very different then the Classic Bluetooth. This technology is used for discovering services and optimized for low power consumption - you don't get high data rates, and usually don't keep connection for long periods, but the connection setup is quick and the power consumption is low. It is aimed for the healthcare like heart rate monitor, various fitness trackers, security like location beacons, and home entertainment like light control.
\subsection{BNEP - Bluetooth Network Encapsulation Protocol}
The BNEP protocol is built on top of L2CAP and it is used to transport control and data packets over standard network protocols such as TCP, IPv4 or IPv6. . BNEP specifies a minimum L2CAP MTU of 1691.
The most popular BTstack's dual mode applications are accessories that want to talk to both iOS and Android devices. The Android OS offers decent API for SPP, but support for LE is not supported on all devices. The iOS has excellent LE API, and service similar to SPP can be used only after engaging into MFi program.
\subsection{PAN - Personal Area Networking Profile}
The PAN profile uses BNEP to provide on-demand networking capabilities between Bluetooth devices. The PAN profile defines the following roles:
As depicted in Figure \ref{fig:BTstackProtocolArchitecture}, BTstack implements following Bluetooth technologies:
\begin{itemize}
\item PAN User (PANU)
\item Network Access Point (NAP)
\item Group Ad-hoc Network (GN)
\item Classic Bluetooth:
\begin{itemize}
\item protocols: HCI, L2CAP, RFCOMM, SDP, BNEP
\item profiles: SPP, PAN (PAN User (PANU))
\end{itemize}
\item Bluetooth Low Energy:
\begin{itemize}
\item protocols: L2CAP-LE, SMP, ATT
\item profiles: GATT
\end{itemize}
\end{itemize}
PANU is a Bluetooth device that communicates as a client with GN, or NAP, or with another PANU Bluetooth device, through a point-to-point connection. Either the PANU or the other Bluetooth device may terminate the connection at anytime.
In the following, we provide an overview of the supported protocols and profiles.
NAP is a Bluetooth device that provides the service of routing network packets between PANU by using BNEP and the IP routing mechanism. A NAP can also act as a bridge between Bluetooth networks and other network technologies by using the Ethernet packets.
\include{bluetooth_classic}
\include{bluetooth_low_energy}
The GN role enables two or more PANUs to interact with each other through a wireless network without using additional networking hardware. The devices are connected in a piconet where the GN acts as a master and communicates either point-to-point or a point-to-multipoint with a maximum of seven PANU slaves by using BNEP.
\subsection{Dual Mode Support}
\subsection{Made For iPhone Support}
Currently, BTstack supports only PANU.
\section{Dual Mode Support}
\subsection{BR/EDR - Basic Rate/Extended Data Rate, or shortly Classic}
\subsection{LE - Low Energy}
Bluetooth Low Energy (BLE) is a Bluetooth technology used for discovering services and optimized for low power consumption - you don't get high data rates, and usually don't keep connection for long periods. The focus is on two different device roles: devices that provide services and/or can be controlled and devices that consume services and/or control other devices. Devices are first going through the advertising process that is governed by the Generic Access Profile (GAP). Once the connection is established, the communication will be governed by the Generic Attribute Profile (GATT). Both profiles, GAP and GATT, have concepts that describe these two BLE roles: GAP defines Peripheral and Central, and GATT defines Server and Client role respectively. The GATT roles are not necessarily tied to specific GAP roles and may be specified by higher layer profiles. GATT is built on top of the Attribute Protocol (ATT), which defines how to discover, read, and write attributes on a peer device. In addition, BLE uses two more BT protocols: SMP for for pairing and transport specific key distribution and L2CAP LE variant optimized for connectionless data used by Bluetooth Low Energy devices.
\subsubsection{Private/random addresses}
To better protect privacy, a LE device can choose use a private i.e. random Bluetooth address. This address changes at a user-specified rate. To allow for later reconnection, the central and peripheral devices exchange their Identity Resolving Keys (IRKs) during bonding. The IRK is used to verify if a new address belongs to a previously bonded device.
\subsubsection{Security manager}
\label{section:security_manager}