Changes between Initial Version and Version 1 of wireless/bluetooth


Ignore:
Timestamp:
10/22/2017 05:28:45 AM (2 years ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • wireless/bluetooth

    v1 v1  
     1[[PageOutline]]
     2
     3[[Image(https://upload.wikimedia.org/wikipedia/commons/thumb/d/da/Bluetooth.svg/220px-Bluetooth.svg.png,120px)]]
     4
     5
     6= Goals =
     7The main objective of this page is to describe Bluetooth from a Linux perspective and provide some general notes for specific applications such as reading a Bluetooth serial device or connecting to a Bluetooth HID.
     8
     9= Bluetooth =
     10Bluetooth is a wireless protocol for short distances which encompasses the obvious benefit of low power. There is a concept of a Master device and a Slave device which is synonymous to infrastructure mode in 802.11a/b/g/n/ac (i.e. AP with several STA's). There can be a maximum of 7 active devices connected to the Master, but can have a total of 255 inactive connections. This Bluetooth network is called a Piconet. However, there are several options on how a Bluetooth network can be configured, several of which will be discussed below in the [wiki:bluetooth#Software software] section. There also exist several Bluetooth protocols which are defined by the Bluetooth SIG organization. [http://en.wikipedia.org/wiki/List_of_Bluetooth_protocols This Wikipedia entry has a complete list of protocols.] In order to fully appreciate the flexibility Bluetooth has to offer, the next few sections will be dedicated to these protocols and how to gain access to them.
     11
     12All Bluetooth devices (both controllers and endpoints), like Ethernet devices, have a unique 6-byte MAC address.
     13
     14Common Terminology:
     15- stack - Refers to the software that implements the Bluetooth protocols
     16- device - a Bluetooth end-point device
     17- controller - Refers to the host controller attached to the CPU that can talk to bluetooth devices
     18
     19== Bluetooth Versions ==
     20
     21Which version is used is dependent on the Hardware used as well as software. Be sure to check the specifications of the radio / device being used.
     22
     23 * Bluetooth 4.0
     24  * Standard
     25 * Bluetooth 5.0
     26  * 2x the datarate of 4.x, moving from 1Mbps to 2Mbps
     27  * Advertising packets move to 255 bytes
     28  * More advertising channels
     29
     30== Bluetooth Low Energy (BLE) ==
     31Also called Bluetooth LE, BLE, and Bluetooth Smart.
     32
     33This is primarily used for data sensing, and not for something like streaming audio.
     34
     35Bluetooth Low Energy is much lower power than classic Bluetooth, possibly lasting months on a coincell. BLE is also cheaper for each peripheral devices.
     36
     37BLE has many defined profiles, including specific profiles for the healthcare industry, sports and fitness and more. These are all based on the Generic Attribute Profile (GATT).
     38
     39
     40[=#bsp]
     41== Gateworks BSP Support ==
     42Gateworks supports multiple Board Support Packages. The following table shows details on bluetooth support for each:
     43||= BSP              =||= Product Families =||= Drivers    =||= Stack    =||
     44|| OpenWrt 14.08      || All                || btusb/btuart || bluez3     ||
     45|| [wiki:Yocto Yocto] || Ventana            || btusb/btuart || bluez4     ||
     46|| [wiki:Android] 5.1     || Ventana            || btusb        || bluez5     ||
     47
     48
     49[=#openwrt1408]
     50=== OpenWrt 14.08 ===
     51Gateworks OpenWrt 14.08 supports Bluetooth via BlueZ 3.36
     52
     53The following packages are installed by default on Gateworks firmware images:
     54 * btusb and bluetooth core kernel drivers
     55 * bluez-utils (bluetooth daemon and utils)
     56 * bluez-libs (bluetooth lib)
     57 * kmod-bluetooth (hci_uart, btusb, rfcomm, bnep, bluetooth, hidp, ath3k)
     58
     59By default dbus-daemon and bluetooth daemon (hcid) are running and the controller is powered up with ISCAN and PSCAN enabled (discovery enabled) and the name is configured as 'OpenWrt' (the system hostname).
     60
     61The {{{dbus-send}}} application is not installed by default (it is included in the dbus-util) package if you wish to install it, and no passkey agent is installed by default.
     62
     63OpenWrt 14.08 supports UCI configuration for the Bluetooth daemon storing its configs in {{{/etc/config/bluetooth}}}. The default configuration provides:
     64 - hcid: enabled by default (controller discoverable via 'iscan enable; pscan enable' in /etc/bluetooth/hcid.conf)
     65 - hciattach: disabled by default
     66 - rfcomm: disabled by default
     67 - dund: disabled by default
     68 - pand: disabled by default
     69
     70The Gateworks OpenWrt 14.08 BSP default firmware image provides support for the following:
     71 * most common USB based based BT controllers (via btusb, ath3k, btintel drivers)
     72 * HCI core protocol kernel support (HCI/L2CAP/SMP/SCO)
     73 * RFCOMM/BNPEP/HIDP kernel support
     74 * hciconfig/hcitool/sdptool/bluetoothd/rfcomm applications and daemones
     75 * scan/pair/discovery of bluetooth devices
     76 * Serial Port Profile (SP) via rfcomm app
     77 * Personal Area Network (PAN) Profile via pand app
     78
     79A patch is needed to add the {{{hidd}}} application in order to support Human Interface Device Profile (HID):
     80{{{
     81diff --git a/utils/bluez-utils/Makefile b/utils/bluez-utils/Makefile
     82index 4f3f787..80d626f 100644
     83--- a/utils/bluez-utils/Makefile
     84+++ b/utils/bluez-utils/Makefile
     85@@ -43,6 +43,8 @@ CONFIGURE_ARGS += \
     86        --enable-network \
     87        --enable-usb \
     88        --enable-input \
     89+       --enable-hidd \
     90        --disable-audio \
     91        --with-bluez="$(STAGING_DIR)/usr/include" \
     92        --with-usb=yes \
     93@@ -58,9 +60,19 @@ endef
     94
     95}}}
     96
     97
     98[=#yocto]
     99=== Yocto 1.8 ===
     100Gateworks Yocto 1.8 BSP supports Bluetooth via BlueZ 4.101. Note that Yocto 1.3 also supported BlueZ 4 but the Yocto 1.6 and 1.7 BSP's do not have bluetooth enabled in the kernel.
     101
     102The following packages are installed by default on Gateworks firmware images:
     103 * btusb and bluetooth core kernel drivers
     104 * bluez4 (bluetoothd daemon, libs, and utils)
     105 * bluez4-testtools
     106 * bluez-hcidump
     107 * gstreamer1.0-plugins-bad-bluze
     108 * libasound-module-bluez
     109
     110The Gateworks Yocto 1.8 BSP default firmware images provides support for the following:
     111 * most common USB based based BT controllers (via btusb, ath3k, btintel drivers)
     112 * HCI core protocol kernel support (HCI/L2CAP/SMP/SCO)
     113 * RFCOMM/BNPEP/HIDP kernel support
     114 * hciconfig/hcitool/sdptool/bluetoothd/rfcomm applications and daemones
     115 * scan/discovery of bluetooth devices
     116 * Serial Port Profile (SP) via rfcomm app
     117 * Human Interface Device (HID) Profile via hidd dbus-send
     118
     119By default the Bluetooth daemon (bluetoothd) is not running as there is no default init script. The {{{dbus-send}}} application exists and can be used for establishing HID connections. No passkey agent is installed by default for pairing (see how to install the pyton test tools for the bluez-simple-agent below).
     120
     121To run bluetoothd:
     122{{{#!bash
     123bluetoothd
     124}}}
     125
     126''' Installing Extra Bluetooth Packages '''
     127
     128Depending on your needs, you may also need to install the test tools that are missing from the Yocto bluez package (and patch them to use the version of python-object installed on Yocto). This will add support for:
     129 * Personal Area Network (PAN) Profile (test-nap & test-network)
     130 * Simple Pairing agent (simple-agent)
     131{{{#!bash
     132mkdir -p /usr/local/bin
     133for i in simple-agent simple-service test-adapter test-audio test-device test-discovery test-input test-manager test-nap test-network test-oob test-serial; do \
     134  wget "http://git.kernel.org/cgit/bluetooth/bluez.git/plain/test/${i}?h=4.101" -O /usr/local/bin/bluez-${i}; \
     135  sed -i 's/from gi.repository import GObject/import gobject/' /usr/local/bin/bluez-${i}; \
     136  sed -i 's/mainloop = GObject.MainLoop/mainloop = gobject.MainLoop/' /usr/local/bin/bluez-${i}; \
     137  chmod +x /usr/local/bin/bluez-${i}; \
     138done
     139}}}
     140 - On Ubuntu for example, these are packaged in the 'bluez' package already
     141
     142If you are interested in using OBEX/FTP/OPP for binary file transfers you may want to build and install the {{{obexftp}}} and/or {{{openobex}}} Yocto packages.
     143
     144
     145[=#trusty]
     146=== Ubuntu 14.04 ===
     147Ubuntu 14.04 uses the BlueZ 4.x stack and provides the following packages related to bluetooth:
     148 * bluez - core bluetooth daemon, utils and python test scripts (You will need to also install python-gobject and python-dbus if you wish to use the python test scripts)
     149 * bluez-compat - pand, hidd, dund for backwards compatibility with BlueZ 3 instructions and methods
     150 * bluez-btsco - Bluetooth SCO tool
     151 * bluez-cups - Bluetooth printer driver for CUPS
     152 * bluez-hcidump - Analyses Bluetooth HCI packets
     153 * [https://code.google.com/archive/p/bluez-tools/alternative bluez-tools] - An alternative set of tools to manage bluetooth devices for linux (not documented here)
     154 * bluez-alsa - ALSA plugin for A2DP profile
     155 * bluez-gstreamer - GStreamer plugin for A2DP profile
     156 * pulseaudio-module-bluetooth - Bluetooth module for !PulseAudio sound server (not documented here)
     157 * obexfs - mount filesystem of devices supporting OBEX FTP profile
     158 * obexftp - file transfer utility and daemon for devices supporting OBEX FTP profile
     159 * obexpushd - program for receiving files via OBEX OPP profile
     160
     161For example:
     162 * to install all bluetooth related packages (174MB on top of a base Ubuntu system as described in [wiki:ventana/ubuntu]):
     163{{{#!bash
     164apt-get install bluez bluez-compat bluez-alsa bluez-gstreamer bluez-utils bluez-tools python-gobject python-dbus
     165}}}
     166 * if you want the minimize you can just install bluez (which does depend on dbus, systemd, and python among some others) (14.9MB on top of a base Ubuntu system as described in [wiki:ventana/ubuntu]):
     167{{{#!bash
     168apt-get install bluez
     169}}}
     170
     171With the bluetooth packages above installed this allows for the following support:
     172 * most common USB based based BT controllers (via btusb, ath3k, btintel drivers)
     173 * HCI core protocol kernel support (HCI/L2CAP/SMP/SCO)
     174 * RFCOMM/BNPEP/HIDP kernel support
     175 * hciconfig/hcitool/sdptool/bluetoothd/rfcomm applications and daemones
     176 * scan/discovery of bluetooth devices
     177 * Serial Port Profile (SP) via rfcomm app
     178 * Human Interface Device (HID) Profile via hidd/dbus-send/bluez-test-input
     179 * Personal Area Network (PAN) Profile via pand app
     180 * File Transfer Protocol (FTP) Profile via obexftp and obxfs
     181 * Object Push Profile (OOP) via obexpushd
     182 * Advanced Audio Distribution Profile (A2DP) via bluez-alsa
     183
     184
     185
     186[=#android]
     187=== Android ===
     188The Gateworks Android BSP replaces the standard Android Bluetooth 'bluedroid' stack with BlueZ. Please see [wiki:Android#bluetooth Android Bluetooth] for details on Android Bluetooth support.
     189
     190
     191== Software (Linux) ==
     192A Bluetooth stack refers to the software that implements the protocol layers. This software can reside in the Linux kernel as well as userspace.
     193
     194[=#bluez]
     195=== BlueZ (Standard Linux) ===
     196[http://www.bluez.org/ BlueZ] is the Open Source Linux bluetooth protocol stack implemented in userspace using the Linux Bluetooth HCI core drivers. It also provides several tools for managing your Bluetooth connections, whether you're acting as a Slave (device) or Master (controller). BlueZ offers support for multiple Bluetooth devices, security, and several other features. It also provides several Protocols, or "Profiles", such as PAN, HID, and A2DP. The upcoming sections will discuss software generally compiled when building BlueZ
     197
     198BlueZ general features:
     199 * flexible, efficient, modular architecture
     200 * support for multiple Bluetooth devices
     201 * multithreaded
     202 * hardware abstraction
     203 * standard socket interface to all layers
     204
     205BlueZ consists of:
     206 * Linux kernel side:
     207  - Bluetooth Core:
     208   - HCI (Host Controller Interface) device and connection manager, schedule
     209   - SCO (Synchronous Connection Oriented) audio links
     210   - L2CAP (Logical Link Control and Adaptation Protocol)
     211   - SMP (Security Manager Protocol) on LE (Low Energy) links
     212  - HCI Device drivers (Interface to the hardware)
     213   - USB (btusb)
     214   - UART (btuart)
     215   - SDIO
     216  - RFCOMM (RFCOMM Protocol for serial communication) Module (creates /dev/rfcomm serial devices)
     217  - BNEP (Bluetooth Network Encapsulation Protocol) Module (creates /sys/class/net/bnep network interfaces)
     218  - CMTP (CAPI Message Transport Protocol) Module
     219  - HIDP (Human Interface Device Protocol) Module (creates /sys/class/input devices)
     220 * Userspace side:
     221  - config and test utilities
     222
     223Various linux distros will package BlueZ in a number of packages:
     224 * bluez - Bluetooth tools and daemons
     225 * bluez-alsa - Bluetooth ALSA support
     226 * bluez-btsco - Bluez Bluetooth SCO tool
     227 * bluez-cups - Bluetooth printder driver for CUPS
     228 * bluez-gstreamer - Bluetooth GStreamer support
     229 * bluez-hcidump - Analyze Bluetooth packets
     230 * bluez-tools - manage Bluetooth devices
     231
     232While Bluez5 is the current stable release many Linux distros including Ubuntu 14.04, Gateworks Yocto 1.8 BSP still use Bluez4. See [#bsp above] regarding which Gateworks BSP's have what version of BlueZ
     233
     234Recent BlueZ Version history:
     235 * [http://www.bluez.org/release-of-bluez-5-0/ BlueZ 5]: Dec 2012
     236  - use standard D-Bus Properties and !ObjectManager interfaces
     237  - different (and incompatible) D-Bus API (see the [http://www.bluez.org/bluez-5-api-introduction-and-porting-guide/ BlueZ 5 API porting-guide])
     238  - introduction of interface versions
     239  - simplification or removal of per-profile interfaces and the addition of a general org.bluez.Device1.Connect method
     240  - removal of org.bluez.Service interface
     241  - Dynamic device object creation during discovery
     242  - Introduction of an AgentManager1 interface
     243  - base path moved to "/org/bluez"
     244 * [http://www.bluez.org/bluez-40/ bluez-4.0]: Aug 2008:
     245  - merged bluez-libs and bluez-utils together
     246  - main daemon now called bluetoothd (instead of hcid)
     247  - main config file is /etc/bluetoth/main.conf following an INI-style syntax
     248  - GLib no longer optional (eglib support fully removed)
     249  - old D-Bus API from 3.x series fully removed
     250
     251
     252[=#kernel]
     253==== Linux Kernel Drivers ====
     254The Linux Kernel defines a Bluetooth Host Controller Interface (HCI) for communication between hardware kernel drivers and userspace applications.
     255
     256Several Linux kernel drivers implement a standard bluetooth HCI API in the form of a device node and ioctls. Each of these drivers implements support for a specific HCI presenting and a list of them can be found in /sys/class/bluetooth/hci*
     257
     258The more standard HCI device drivers can be broken down into the following:
     259 * USB based HCI's (typically added to a system by the user) - [http://lxr.missinglinkelectronics.com/linux/drivers/bluetooth/btusb.c linux/drivers/bluetooth/btusb.c] usually built as the '''btusb.ko''' kernel module
     260 * UART based HCI's (typically embedded onto a board) - [http://lxr.missinglinkelectronics.com/linux/drivers/bluetooth/btuart.c linux/drivers/bluetooth/btuart_cs.c] usually build as the '''btuart.ko''' kernel module
     261 * SDIO based HCI's (typically embedded onto a board) - [http://lxr.missinglinkelectronics.com/linux/drivers/bluetooth/btsdio.c drivers/bluetooth/btsdio.c] usually built as the '''btsdio.ko''' kernel module
     262 * addition drivers exist in drivers/bluetooth for specific hardware implmentaitons
     263
     264While Gateworks does not currently have bluetooth HCI's directly on its boards, our customers often add USB based HCI's in the form of miniPCIe combo cards (see [#hardware hardware] section below) or USB form-factor peripherals.
     265
     266You can see what Bluetooth controllers are registered with the kernel by looking at the {{{/sys/class/bluetooth}}} directory:
     267{{{#!bash
     268# ls /sys/class/bluetooth
     269hci0
     270}}}
     271
     272
     273[=#bluez5]
     274==== BlueZ 5.x ====
     275The Bluez5 bluetooth daemon (/usr/lib/bluez5/bluetooth/bluetoothd) runs in the background and the {{{bluetoothctl}}} application provides a Command Line Interface (CLI) to the daemon to perform all device and controller management.
     276
     277A typical session may look like this:
     2781. Use {{{list}}} to list available controllers, and {{{select <mac>}}} to select one
     2791. Turn the power on to a controller via {{{power on}}} (its off by default)
     2801. Enable device discovery mode for the selected controller with {{{scan on}}} (its off by default)
     281 - New devices will be presented as they are found
     282 - Periodic messages will appear for each device found along with its signal strength (RSSI)
     2831. You can list current devices with the {{{devices}}} command
     2841. Turn the pairing agent on with the {{{agent on}}} command
     2851. Pair a device via {{{pair <mac>}}}
     286 - If using a device without a PIN, you man need to manually trust the device before it can reconnect successfully. To do so use {{{trust <mac>}}}
     2871. Establish a connection to the device via {{{connect <mac>}}}
     288
     289Note that while in the CLI:
     290- Tab completion works
     291- Periodic asynchonous/unsolicited messages will appear for devices being scanned while scanning is on
     292
     293Examples:
     294 * Pairing and connecting an HID keyboard:
     295{{{#!bash
     296bluetoothctl
     297[NEW] Controller 00:06:C6:FF:AD:1A ventana-0 [default]
     298[bluetooth]# list
     299Controller 00:06:C6:FF:AD:1A ventana-0 [default]
     300[bluetooth]# show 00:06:C6:FF:AD:1A
     301Controller 00:06:C6:FF:AD:1A
     302        Name: BlueZ 5.28
     303        Alias: ventana-0
     304        Class: 0x000000
     305        Powered: yes
     306        Discoverable: no
     307        Pairable: yes
     308        UUID: PnP Information           (00001200-0000-1000-8000-00805f9b34fb)
     309        UUID: Generic Access Profile    (00001800-0000-1000-8000-00805f9b34fb)
     310        UUID: Generic Attribute Profile (00001801-0000-1000-8000-00805f9b34fb)
     311        UUID: A/V Remote Control        (0000110e-0000-1000-8000-00805f9b34fb)
     312        UUID: A/V Remote Control Target (0000110c-0000-1000-8000-00805f9b34fb)
     313        UUID: Handsfree                 (0000111e-0000-1000-8000-00805f9b34fb)
     314        Modalias: usb:v1D6Bp0246d051C
     315        Discovering: no
     316
     317[bluetooth]# select 00:06:C6:FF:AD:1A
     318[bluetooth]# scan on
     319Discovery started
     320[CHG] Controller 00:06:C6:FF:AD:1A Discovering: yes
     321[NEW] Device 54:46:6B:01:7B:2B 54-46-6B-01-7B-2B
     322[CHG] Device 54:46:6B:01:7B:2B LegacyPairing: no
     323[CHG] Device 54:46:6B:01:7B:2B Name: Bluetooth FAVI
     324[CHG] Device 54:46:6B:01:7B:2B Alias: Bluetooth FAVI
     325[bluetooth]# devices
     326Device 54:46:6B:01:7B:2B Bluetooth FAVI
     327[bluetooth]# pair 54:46:6B:01:7B:2B
     328Attempting to pair with 54:46:6B:01:7B:2B
     329Failed to pair: org.bluez.Error.ConnectionAttemptFailed
     330[bluetooth]# pair 54:46:6B:01:7B:2B
     331Attempting to pair with 54:46:6B:01:7B:2B
     332[CHG] Device 54:46:6B:01:7B:2B Connected: yes
     333[CHG] Device 54:46:6B:01:7B:2B Modalias: usb:v0A5Cp8502d011B
     334[CHG] Device 54:46:6B:01:7B:2B UUIDs:
     335        00001000-0000-1000-8000-00805f9b34fb
     336        00001124-0000-1000-8000-00805f9b34fb
     337        00001200-0000-1000-8000-00805f9b34fb
     338[CHG] Device 54:46:6B:01:7B:2B Paired: yes
     339Pairing successful
     340[CHG] Device 54:46:6B:01:7B:2B Connected: no
     341[bluetooth]# connect 54:46:6B:01:7B:2B
     342Attempting to connect to 54:46:6B:01:7B:2B
     343[ 2178.501028] Bluetooth: HIDP (Human Interface Emulation) ver 1.2
     344[ 2178.507023] Bluetooth: HIDP socket layer initialized
     345[CHG] Device 54:46:6B:01:7B:2B Connected: yes
     346Connection successful
     347}}}
     348 - If using a device without a PIN you can manually trust the device in order to connect:
     349{{{#!bash
     350[bluetooth]# trust 54:46:6B:01:7B:2B
     351}}}
     352
     353To bring up a bluetooth controller (HCI) on boot, you can use a udev rule such as:
     354- /etc/udev/rules.d/10-local.rules
     355{{{#!bash
     356# bring up bluetooth host controller
     357ACTION=="add", KERNEL=="hci0", RUN+="/usr/bin/hciconfig hci0 up"
     358}}}
     359
     360After a suspend/resume cycle you can use a systemd service to bring the controller back up:
     361- /etc/systemd/system/bluetooth-auto-power@.service
     362{{{#!bash
     363[Unit]
     364Description=Bluetooth auto power on
     365After=bluetooth.service sys-subsystem-bluetooth-devices-%i.device suspend.target
     366
     367[Service]
     368Type=oneshot
     369ExecStart=/usr/bin/hciconfig %i up
     370
     371[Install]
     372WantedBy=suspend.target
     373}}}
     374
     375Configuration:
     376 - bluetooth daemon configuruation is in /etc/bluetooth/main.conf:
     377  * !AutoEnable=true in [Policy] section will bring up HCI on startup
     378 - bluetooth dbus configuration is in /etc/dbus-1/system.d/bluetooth.conf (can specify group there, defaults to lp group)
     379
     380Notes:
     381- must turn power on to controller by entering 'power on' (off by default) or by using hciconfig up
     382- enter device desovery mode with 'scan on'
     383- tab completion works in CLI
     384- to pair, the bluetooth device must be in pairing mode (consult devices documentation). Typically this involves pressing or holding a button for a few seconds and results in a blinking blue LED to indicate the device is in pairing mode. Pairing typically stops after a minute or so depending on the device
     385
     386
     387References:
     388- https://wiki.archlinux.org/index.php/Bluetooth
     389
     390
     391[=#bluez4]
     392==== BlueZ 4.x ====
     393BlueZ 4.x was released in Aug 2008 with the following major changes over BlueZ 3.x:
     394 - Merged bluez-libs and bluez-utils together
     395 - Main daemon now called bluetoothd (instead of hcid)
     396 - Main config file is /etc/bluetooth/main.conf following an INI-style syntax
     397 - GLib no longer optional (eglib support fully removed)
     398 - Old D-Bus API from 3.x series fully removed
     399 - New D-Bus API is defined in [http://git.kernel.org/cgit/bluetooth/bluez.git/tree/doc/network-api.txt?id=4.101 doc/network-api.txt]
     400
     401The standard userpsace tools are:
     402 - bluetoothd - Bluetooth Daemon that manages all Bluetooth devices and configured via /etc/bluetooth/main.conf. Provides a number of services via D-Bus message bus system
     403 - hcitool
     404 - hciattach
     405 - hciconfig
     406 - l2ping
     407 - l2test
     408 - sdptool
     409
     410some distros (ie Ubuntu) will provide a set of bluetooth compatibility binaries in a {{{bluez-compat}}} package that provide the following tools which were removed from bluez4:
     411 - [http://linuxcommand.org/man_pages/pand1.html pand] - Personal Area Network (PAN) networking daemon
     412 - [http://linuxcommand.org/man_pages/dund1.html dund] - Dial-Up Networking daemon
     413 - [http://linuxcommand.org/man_pages/hidd1.html hidd] - Bluetooth HID daemon
     414
     415Configuration:
     416 - /etc/init/bluetooth.conf - bluetooth daemon init
     417 - /etc/bluetooth/main.conf - main bluetooth daemon config
     418  - name of device (when discoverable)
     419 - /etc/bluetooth/input.conf - configuration of the input service
     420 - /etc/bluetooth/audio.conf - configuration of the audio service (SCO routing: PCM or HCI)
     421 - /etc/bluetooth/network.conf - configuration of the network service (link encryption)
     422 - /etc/bluetooth/rfcomm.conf - configuration of rfcomm layer
     423 - /etc/bluetooth/serial.conf - configuration of serial (DUN tty, UID)
     424
     425
     426
     427
     428[=#bluez3]
     429==== BlueZ 3.x ====
     430BlueZ 3.x has the following features:
     431 - uses dbus and system.d configured via /etc/dbus-1/system.d/bluetooth.conf
     432 - D-Bus API is defined in [http://git.kernel.org/cgit/bluetooth/bluez.git/tree/doc/network-api.txt?id=utils-3.36 doc/network-api.txt]
     433
     434 - bluetooth daemon (hidc)
     435 - /etc/bluetooth/hcid.conf daemon configuration
     436
     437The standard userspace tools are:
     438 - hcid - Bluetooth Daemon that manages all Bluetooth devices and configured via /etc/bluetooth/hcid.conf. Provides a number of services via D-Bus message bus system
     439 - hciconfig/hcitool/hciattach - HCI configuration tools
     440 - l2ping - Layer2 ping utility
     441 - sdptool - SDP browser
     442 - hidd - Human Interface Devices (HID) daemon
     443 - pand - Personal Area Network (PAN) networking daemon
     444 - dund - Dial-up networking daemon
     445
     446
     447[=#dbus]
     448=== D-Bus Message Bus System ===
     449The BlueZ stack uses the [https://www.freedesktop.org/wiki/Software/dbus/ D-Bus message bus system] which is a simple way for applications to talk to one another.
     450
     451
     452==== BlueZ 4 D-Bus API ====
     453The BlueZ 4 D-Bus API is defined in [http://git.kernel.org/cgit/bluetooth/bluez.git/tree/doc/network-api.txt?id=4.101 doc/network-api.txt]. Some example usage using {{{dbus-send}}}:
     454  * First you need to get the path to the bluetooth controller you wish to use. We will assign it to a shell env variable and export it for future use:
     455{{{#!bash
     456export BTADAPTER=`dbus-send --system --dest=org.bluez --print-reply / org.bluez.Manager.DefaultAdapter | tail -1 | sed 's/^.*"\(.*\)".*$/\1/'`
     457}}}
     458  * To introspect with you can use something like:
     459{{{#!bash
     460# dbus-send --system --dest=org.bluez --print-reply $BTADAPTER org.freedesktop.DBus.Introspectable.Introspect
     461}}}
     462  * To make your controller discoverable:
     463{{{#!bash
     464# dbus-send --system --dest=org.bluez --print-reply $BTADAPTER org.bluez.Adapter.SetProperty string:Discoverable variant:boolean:true
     465}}}
     466 * To disable discovery:
     467{{{#!bash
     468# dbus-send --system --dest=org.bluez --print-reply $BTADAPTER org.bluez.Adapter.SetProperty string:Discoverable variant:boolean:false
     469}}}
     470 * To list paired devices:
     471{{{#!bash
     472# dbus-send --system --dest=org.bluez --print-reply $BTADAPTER org.bluez.Adapter.ListDevices
     473}}}
     474 * To trust a device:
     475{{{#!bash
     476dbus-send --system --dest=org.bluez --print-reply $BTADAPTER/dev_54_46_6B_01_7B_2B org.bluez.Device.SetProperty string:Trusted variant:boolean:true
     477}}}
     478 * To connect to an HID device (must pair first and can see the path above):
     479{{{#!bash
     480# dbus-send --system --dest=org.bluez --print-reply $BTADAPTER/dev_54_46_6B_01_7B_2B org.bluez.Input.Connect
     481[ 2710.946655] Bluetooth: HIDP (Human Interface Emulation) ver 1.2
     482[ 2710.952642] Bluetooth: HIDP socket layer initialized
     483method return sender=:1.3 -> dest=:1.13 reply_serial=2
     484root@ventana:~# [ 2711.352289] hid-generic 0005:0A5C:8502.0001: unknown main item tag 0x0
     485[ 2711.359234] input: Bluetooth FAVI as /devices/soc0/soc.0/2100000.aips-bus/2184000.usb/ci_hdrc.0/usb1/1-1/1-1:1.0/bluetooth/hci0/hci0:42/0005:0A5C:8502.0001/input/input1
     486[ 2711.374829] hid-generic 0005:0A5C:8502.0001: input: BLUETOOTH HID v1.1b Keyboard [Bluetooth FAVI] on 00:15:83:3d:0a:57
     487evtest /dev/input/event1
     488}}}
     489
     490
     491
     492[=#bluedroid]
     493=== !BlueDroid (Android) ===
     494While Android used to use the standard Linux BlueZ stack, in 4.2.2 it switched to its own native stack called !BlueDroid.
     495
     496For Android Bluetooth details please see the [w iki:ventana/Android Android wiki pages].
     497
     498
     499[=#profiles]
     500== Bluetooth Profiles ==
     501In order to use Bluetooth a device must be compatible with a subset of Bluetooth '''profiles''' for specific services. These profiles sit on top of the Bluetooth Core specification and protocols.
     502
     503The way a device uses Bluetooth technology depends on its profile capabilities. The profiles provide standards which manufacturers follow to allow devices to be compatible.
     504
     505A full list of profiles can be found [https://en.wikipedia.org/wiki/List_of_Bluetooth_profiles here] however here are some common ones are described in detail in the sections below
     506
     507[=#sp]
     508=== Serial Port Profile (SP) ===
     509The Serial Port Profile is based on ETSI 07.10 and the RFCOMM protocol. It emulates a serial cable to provide a simple substitude for existing RS-232 including control signals. This is the basis for DUN, FAX, HSP and AVRCP profiles. SPP maximum payload capacity is 128 bytes.
     510
     511An example of a device using this profile would be a Bluetooth GPS device.
     512
     513The Linux kernel has an RFCOMM driver that ties into the bluetooth stack and registers /dev/rfcomm<n> device nodes when necessary.
     514
     515Use the {{{rfcomm}}} utility from the bluez package to listen for or connect so bluetooth connections. It is not necessary to be paired or trusted in this case.
     516
     517For example, to create a serial link between two Linux systems:
     518 * Machine1: SP server
     519{{{#!bash
     520# hciconfig hci0 piscan # make us discoverable
     521# hciconfig hci0 -a
     522hci0:   Type: BR/EDR  Bus: USB
     523        BD Address: 00:02:72:C9:56:47  ACL MTU: 1021:8  SCO MTU: 64:1
     524        UP RUNNING PSCAN ISCAN
     525        RX bytes:7258 acl:121 sco:0 events:203 errors:0
     526        TX bytes:4561 acl:119 sco:0 commands:91 errors:0
     527        Features: 0xbf 0xfe 0xcf 0xfe 0xdb 0xff 0x7b 0x87
     528        Packet type: DM1 DM3 DM5 DH1 DH3 DH5 HV1 HV2 HV3
     529        Link policy: RSWITCH SNIFF
     530        Link mode: SLAVE ACCEPT
     531        Name: 'ventana-0'
     532        Class: 0x000100
     533        Service Classes: Unspecified
     534        Device Class: Computer, Uncategorized
     535        HCI Version: 4.0 (0x6)  Revision: 0x1000
     536        LMP Version: 4.0 (0x6)  Subversion: 0x220e
     537        Manufacturer: Broadcom Corporation (15)
     538
     539# sdptool add SP --channel=1 # advertise an SP service record for channel 1
     540# rfcomm listen hci0 1 # listen on hci0 for SP requests on channel 1 (cntl-C to exit)
     541Waiting for connection on channel 1
     542}}}
     543 * Machine2: SP client
     544{{{#!bash
     545# hciconfig hci0 up
     546# hcitool scan
     547Scanning ...
     548        00:02:72:C9:56:47       ventana-0
     549# sdptool search SP
     550Inquiring ...
     551Searching for SP on 00:02:72:C9:56:47 ...
     552Service Name: Serial Port
     553Service Description: COM Port
     554Service Provider: BlueZ
     555Service RecHandle: 0x10000
     556Service Class ID List:
     557  "Serial Port" (0x1101)
     558Protocol Descriptor List:
     559  "L2CAP" (0x0100)
     560  "RFCOMM" (0x0003)
     561    Channel: 1
     562Language Base Attr List:
     563  code_ISO639: 0x656e
     564  encoding:    0x6a
     565  base_offset: 0x100
     566Profile Descriptor List:
     567  "Serial Port" (0x1101)
     568    Version: 0x0100
     569
     570# rfcomm connect hci0 00:02:72:C9:56:47 1
     571Press CTRL-C for hangup
     572}}}
     573  - once a connection is established the {{{rfcomm}}} processes on both the client and server will display 'Press CTRL-C for hangup' at which point they will create a {{{/dev/rfcomm0}}} node that can be used with any terminal application. When you wish to close the connection kill the rfcomm process.
     574  - terminal characterists such as baudrate and line control have no effect on rfcomm devices
     575
     576You can configure the bluetooth daemon to bind to a device on startup via {{{/etc/bluetooth/rfcomm.conf}}}. For example:
     577For example:
     578{{{
     579rfcomm0 {
     580       # Automatically bind the device at startup
     581       bind no;
     582       # Bluetooth address of the device
     583       device 00:11:22:33:44:55;
     584       # RFCOMM channel for the connection (check your GPS docs for details)
     585       channel 1;
     586       # Description of the connection
     587       comment "Bluetooth GPS";
     588}
     589}}}
     590
     591Restart the Bluetooth daemon or services following this change:
     592{{{#!bash
     593# /etc/init.d/bluetoothd restart
     594}}}
     595
     596You should now be able to bind the GPS to /dev/rfcomm0 like this:
     597{{{#!bash
     598# rfcomm bind 0
     599}}}
     600
     601And you can confirm the connection:
     602{{{#!bash
     603# rfcomm
     604rfcomm0: 00:11:22:33:44:55 channel 1 clean
     605}}}
     606
     607Now you can use {{{/dev/rfcomm0}}} like any other serial device (ie 'stty', 'screen', etc):
     608{{{#!bash
     609# stty -F /dev/rfcomm0 115200 # set baudrate
     610# cat /dev/rfcomm0
     611$GPGGA,111748.000,5907.6964,N,01121.1787,E,1,06,1.2,57.7,M,40.1,M,,0000*6F
     612$GPRMC,111748.000,A,5907.6964,N,01121.1787,E,0.00,94.94,160807,,,A*50
     613$GPVTG,94.94,T,,M,0.00,N,0.0,K,A*3D
     614}}}
     615
     616References:
     617 * http://wiki.openmoko.org/wiki/Manually_using_Bluetooth#RFCOMM
     618
     619
     620[=#hsp]
     621=== Headset Profile (HSP) ===
     622The Headset Profile (HSP) was encoropred in the initial Bluetooth specification for mono headsets. If a microphone is present on a stereo headphone device, it uses HSP for the audio channel. HSP uses a RFCOMM channel for control based on standard AT commands with bluetooth specific extensions for volume control and accept/reject buttons. The transport for audio is an SCO channel which allows a single (mono) 8kHz PCM encoded using Continuous Variable Slope Delta (CVSD) modulation amounting to 64kbps. This audio transferred over SCO can be provided to the HCI hardware driver (typical) or in highly embedded applications directly to an audio codec chip via a PCM back-channel depending on the bluetooth chipset.
     623
     624[=#hfp]
     625=== Handsfree Profile (HFP) ===
     626The Handsfree profile (HFP) is a more advanced version of HSP but also designed for mono headsets. It adds support for additional remote functions such as dialing and later versions add optional support for better-quality mono audio using the SBC codec.
     627
     628[=#hid]
     629=== Human Interface Device Profile (HID) ===
     630The Human Interface Device Profile (HID) is implemented with a kernel module (hidp) that registers a Linux Input device upon request from the bluetooth daemon.
     631
     632Configuration of HID depends upon the version of BlueZ (see [#bsp BSP table above]). In general the HID device must be paired with (or trusted) and the bluetooth daemon must register it for use with the {{{hidp}}} kernel module which creates a Linux Input device that can be seen in {{{/sys/class/input}}}.
     633
     634Notes:
     635 * BT HID devices (ie keyboard or mouse) and controllers (HCI) need to be paired once. See [#pairing Pairing] for more details.
     636 * Once connected a {{{/dev/input/event<n>}}} device node will be registered and can be used for Linux Input events as long as the connection persists.
     637 * You can test the connection (if connected through a TTY session) by running a tool such as {{{evtest}}} or {{{event_test}}} which will show you events on Linux Input devices.
     638
     639BlueZ 5:
     640 * The {{{bluetoothctl}}} utility allows for HID's to connect to the Bluetooth adapter. This provides a Command Line Interface (CLI):
     641{{{#!bash
     642# bluetoothctl
     643[NEW] Controller 00:06:C6:FF:AD:1A ventana-0 [default]
     644[bluetooth]# power on
     645Changing power on succeeded
     646[CHG] Controller 00:06:C6:FF:AD:1A Powered: yes
     647[bluetooth]# scan on
     648Discovery started
     649[CHG] Controller 00:06:C6:FF:AD:1A Discovering: yes
     650[NEW] Device 54:46:6B:01:7B:2B 54-46-6B-01-7B-2B
     651[CHG] Device 54:46:6B:01:7B:2B LegacyPairing: no
     652[CHG] Device 54:46:6B:01:7B:2B Name: Bluetooth FAVI
     653[CHG] Device 54:46:6B:01:7B:2B Alias: Bluetooth FAVI
     654[bluetooth]# devices
     655Device 54:46:6B:01:7B:2B Bluetooth FAVI
     656[bluetooth]# pair 54:46:6B:01:7B:2B
     657Attempting to pair with 54:46:6B:01:7B:2B
     658[CHG] Device 54:46:6B:01:7B:2B Connected: yes
     659[CHG] Device 54:46:6B:01:7B:2B Modalias: usb:v0A5Cp8502d011B
     660[CHG] Device 54:46:6B:01:7B:2B UUIDs:
     661        00001000-0000-1000-8000-00805f9b34fb
     662        00001124-0000-1000-8000-00805f9b34fb
     663        00001200-0000-1000-8000-00805f9b34fb
     664[CHG] Device 54:46:6B:01:7B:2B Paired: yes
     665Pairing successful
     666[CHG] Device 54:46:6B:01:7B:2B Connected: no
     667[bluetooth]# connect 54:46:6B:01:7B:2B
     668Attempting to connect to 54:46:6B:01:7B:2B
     669[ 2178.501028] Bluetooth: HIDP (Human Interface Emulation) ver 1.2
     670[ 2178.507023] Bluetooth: HIDP socket layer initialized
     671[CHG] Device 54:46:6B:01:7B:2B Connected: yes
     672Connection successful
     673[bluetooth]# exit
     674}}}
     675
     676
     677BlueZ 4:
     678 * Using D-Bus via the {{{dbus-send}}} to interact with {{{bluetoothd}}} (requires [#pairing  pairing]):
     679{{{#!bash
     680# hciconfig hci0 up
     681# hcitool -i hci0 scan
     682Scanning ...
     683        54:46:6B:01:7B:2B       Bluetooth FAVI
     684# sdptool search HID # search for and show all discoverable devices advertising an HID service
     685Inquiring ...
     686Searching for HID on 54:46:6B:01:7B:2B ...
     687Service Name: Broadcom Bluetooth Wireless  Keyboard                       
     688Service Description: Keyboard
     689Service Provider: Broadcom Corp. 
     690Service RecHandle: 0x10000
     691Service Class ID List:
     692  "Human Interface Device" (0x1124)
     693Protocol Descriptor List:
     694  "L2CAP" (0x0100)
     695    PSM: 17
     696  "HIDP" (0x0011)
     697Language Base Attr List:
     698  code_ISO639: 0x656e
     699  encoding:    0x6a
     700  base_offset: 0x100
     701Profile Descriptor List:
     702  "Human Interface Device" (0x1124)
     703    Version: 0x0100
     704
     705# bluez-simple-agent hci0 54:46:6B:01:7B:2B  # request pairing (specify pin code when requested then enter this code followed by a Enter on the keyboard to pair)
     706RequestPinCode (/org/bluez/471/hci0/dev_54_46_6B_01_7B_2B)
     707Enter PIN Code: 0000
     708Release
     709New device (/org/bluez/471/hci0/dev_54_46_6B_01_7B_2B)
     710# export BTADAPTER=`dbus-send --system --dest=org.bluez --print-reply / org.bluez.Manager.DefaultAdapter | tail -1 | sed 's/^.*"\(.*\)".*$/\1/'` # get the adapter path
     711# dbus-send --system --dest=org.bluez --print-reply $BTADAPTER org.bluez.Adapter.ListDevices  # list paired adapters
     712# dbus-send --system --dest=org.bluez --print-reply $BTADAPTER/dev_54_46_6B_01_7B_2B org.bluez.Input.Connect # connect to an adapter
     713method return sender=:1.3 -> dest=:1.8 reply_serial=2
     714[ 2710.946655] Bluetooth: HIDP (Human Interface Emulation) ver 1.2
     715[ 2710.952642] Bluetooth: HIDP socket layer initialized
     716[ 2711.352289] hid-generic 0005:0A5C:8502.0001: unknown main item tag 0x0
     717[ 2711.359234] input: Bluetooth FAVI as /devices/soc0/soc.0/2100000.aips-bus/2184000.usb/ci_hdrc.0/usb1/1-1/1-1:1.0/bluetooth/hci0/hci0:42/0005:0A5C:8502.0001/input/input1
     718[ 2711.374829] hid-generic 0005:0A5C:8502.0001: input: BLUETOOTH HID v1.1b Keyboard [Bluetooth FAVI] on 00:15:83:3d:0a:57
     719evtest /dev/input/event1
     720}}}
     721 * Using D-Bus via {{{bluez-test-input}}} python script (requires [#pairing pairing]):
     722{{{#!bash
     723# hciconfig hci0 up
     724# hcitool -i hci0 scan
     725Scanning ...
     726        54:46:6B:01:7B:2B       Bluetooth FAVI
     727# bluez-simple-agent hci0 54:46:6B:01:7B:2B  # request pairing (specify pin code when requested then enter this code followed by a Enter on the keyboard to pair)
     728RequestPinCode (/org/bluez/471/hci0/dev_54_46_6B_01_7B_2B)
     729Enter PIN Code: 0000
     730Release
     731New device (/org/bluez/471/hci0/dev_54_46_6B_01_7B_2B)
     732# bluez-test-input connect 54:46:6B:01:7B:2B
     733[ 1654.853401] Bluetooth: HIDP (Human Interface Emulation) ver 1.2
     734[ 1654.859353] Bluetooth: HIDP socket layer initialized
     735[ 1655.633452] hid-generic 0005:0A5C:8502.0001: unknown main item tag 0x0
     736[ 1655.640391] input: Bluetooth FAVI as /devices/soc0/soc.0/2100000.aips-bus/2184000.usb/ci_hdrc.0/usb1/1-1/1-1:1.0/bluetooth/hci0/hci0:12/0005:0A5C:8502.0001/input/input1
     737[ 1655.655952] hid-generic 0005:0A5C:8502.0001: input: BLUETOOTH HID v1.1b Keyboard [Bluetooth FAVI] on 00:02:72:c9:56:47
     738}}}
     739 * Use {{{hidd}}} from the {{{bluez-compat}}} package to connect (see [#hidd below])
     740 * In all of the above cases the kernel has registered a new input device input1 (/sys/class/input/input1, /dev/input/event1)
     741
     742
     743[=#hidd]
     744BlueZ 3:
     745 * Use {{{hidd}}} from the {{{bluez}}} package to connect (does not require pairing, or more specifically performs automatic pairing for you):
     746{{{#!bash
     747# hciconfig hci0 up
     748# hcitool -i hci0 scan # show all discverable devices
     749Scanning ...
     750        54:46:6B:01:7B:2B       Bluetooth FAVI
     751# sdptool search HID # search for and show all discoverable devices advertising an HID service
     752Inquiring ...
     753Searching for HID on 54:46:6B:01:7B:2B ...
     754Service Name: Broadcom Bluetooth Wireless  Keyboard                       
     755Service Description: Keyboard
     756Service Provider: Broadcom Corp. 
     757Service RecHandle: 0x10000
     758Service Class ID List:
     759  "Human Interface Device" (0x1124)
     760Protocol Descriptor List:
     761  "L2CAP" (0x0100)
     762    PSM: 17
     763  "HIDP" (0x0011)
     764Language Base Attr List:
     765  code_ISO639: 0x656e
     766  encoding:    0x6a
     767  base_offset: 0x100
     768Profile Descriptor List:
     769  "Human Interface Device" (0x1124)
     770    Version: 0x0100
     771
     772# hidd --connect 54:46:6B:01:7B:2B
     773[28013.797391] Bluetooth: HIDP (Human Interface Emulation) ver 1.2
     774[28013.798954] Bluetooth: HIDP socket layer initialized
     775[28018.300685] hid-generic 0005:0A5C:8502.0001: unknown main item tag 0x0
     776[28018.309052] input: Broadcom Bluetooth Wireless  Keyboard                         as /devices/soc0/soc.0/2100000.aips-bus/2184200.usb/ci_hdrc.1/usb1/1-1/1-1.1/1-1.1:1.0/bluetooth/hci0/hci0:40/0005:0A5C:8502.0001/input/input5
     777[28018.309767] hid-generic 0005:0A5C:8502.0001: input: BLUETOOTH HID v1.1b Keyboard [Broadcom Bluetooth Wireless  Keyboard                        ] on 00:15:83:6b:e2:bd
     778}}}
     779  - use {{{hidd unplug <bdaddr>}}} to disconnect the HID connection
     780  - use {{{hidd kill <bdaddr>}}} to kill the HID connection
     781  - use {{{hidd show}}} to show all HID connections
     782  - use {{{hidd search}}} to search for HID devices in range and automatically connect to them
     783  - use {{{-i <hciX|bdaddr>}}} to specify the bluetooth controller
     784
     785
     786[=#pan]
     787=== Personal Area Network Device Profile (PAN) ===
     788The Personal Area Network Device Profile (PAN) allows encapsulating IP over bluetooth using the Bluetooth Network Encapsulation Protocol (BNEP). The kernel bnep module (CONFIG_BT_BNEP) is responsible for registering a bnep<n> network interface when requested by the Bluetooth daemon. You do not need to use paring for PAN connections. Once a PAN connection is active and you have a bnep<n> interface you can use standard networking tools to configure and/or bridge the interface.
     789
     790There are three PAN roles:
     791 * NAP - Network Access Point
     792 * PANU - PAN User (client to a PAN NAP)
     793 * GN - Group Network (adhoc based)
     794
     795Configuration of PAN depends upon the version of BlueZ (see [#bsp BSP table above]).
     796
     797BlueZ 5:
     798 * Using D-Bus via a [https://github.com/mk-fg/fgtk/blob/master/bt-pan bt-pan] python script and the {{{bluetoothctl}}} CLI (requires python, python-dbus):
     799  - Machine1: server / NAP
     800{{{#!bash
     801# bluetoothctl
     802[NEW] Controller 00:02:72:C9:56:47 BlueZ 5.37 [default]
     803[bluetooth]# power on
     804Changing power on succeeded
     805[CHG] Controller 00:02:72:C9:56:47 Powered: yes
     806[bluetooth]# discoverable on
     807Changing discoverable on succeeded
     808[CHG] Controller 00:02:72:C9:56:47 Discoverable: yes
     809[bluetooth]# agent on
     810Agent registered
     811[bluetooth]# default-agent
     812Default agent request successful
     813[NEW] Device 00:15:83:3D:0A:57 yocto18-0
     814Request PIN code
     815[agent] Enter PIN code: 0000
     816[CHG] Device 00:15:83:3D:0A:57 Paired: yes
     817[CHG] Device 00:15:83:3D:0A:57 Connected: no
     818[bluetooth]# paired-devices
     819Device 00:15:83:3D:0A:57 yocto18-0
     820[bluetooth]# trust 00:15:83:3D:0A:57
     821[CHG] Device 00:15:83:3D:0A:57 Trusted: yes
     822Changing 00:15:83:3D:0A:57 trust succeeded
     823[bluetooth]# exit
     824Agent unregistered
     825[DEL] Controller 00:02:72:C9:56:47 BlueZ 5.37 [default]
     826# sdptool add NAP # advertise NAP service
     827# brctl addbr br0
     828# wget https://raw.githubusercontent.com/mk-fg/fgtk/master/bt-pan
     829# chmod +x bt-pan
     830# ./bt-pan --debug server br0 &
     831DEBUG:root:Using local device (addr: 00:02:72:C9:56:47): /org/bluez/hci0
     832DEBUG:root:Registered uuid 'nap' with bridge/dev: br0 / 00:02:72:C9:56:47
     833# ifconfig br0
     834br0       Link encap:Ethernet  HWaddr 00:02:72:c9:56:47 
     835          BROADCAST MULTICAST  MTU:1500  Metric:1
     836          RX packets:0 errors:0 dropped:0 overruns:0 frame:0
     837          TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
     838          collisions:0 txqueuelen:0
     839          RX bytes:0 (0.0 B)  TX bytes:0 (0.0 B)
     840
     841# brctl show br0
     842bridge name     bridge id               STP enabled     interfaces
     843br0             8000.000272c95647       no              bnep0
     844}}}
     845   - first we used {{{bluetoothctl}}} to bring up the controller, make it discoverable, and pair with and trust the client. Next we created a bridge, fetched the bt-pan python script and used it to resiter a NAP server which registers a bnep0 network interface with Linux upon successful connection with a PANU client. The bnpeg0 network interface will be added to the bridge. Make sure you use standard networking tools to configure the bridge as desired.
     846  - Machine2: client / PANU
     847{{{#!bash
     848# bluetoothctl
     849[NEW] Controller 00:02:72:C9:56:47 BlueZ 5.37 [default]
     850[bluetooth]# power on
     851Changing power on succeeded
     852[bluetooth]# discoverable on
     853Changing discoverable on succeeded
     854[CHG] Controller 00:02:72:C9:56:47 Discoverable: yes
     855[bluetooth]# agent on
     856Agent registered
     857[bluetooth]# default-agent
     858Default agent request successful
     859[NEW] Device 00:15:83:6B:E2:BD ventana-trusty-0
     860Request confirmation
     861[agent] Confirm passkey 744563 (yes/no): yes
     862[CHG] Device 00:15:83:6B:E2:BD UUIDs: 0000110c-0000-1000-8000-00805f9b34fb
     863[CHG] Device 00:15:83:6B:E2:BD UUIDs: 0000110e-0000-1000-8000-00805f9b34fb
     864[CHG] Device 00:15:83:6B:E2:BD UUIDs: 00001112-0000-1000-8000-00805f9b34fb
     865[CHG] Device 00:15:83:6B:E2:BD UUIDs: 00001116-0000-1000-8000-00805f9b34fb
     866[CHG] Device 00:15:83:6B:E2:BD UUIDs: 0000111e-0000-1000-8000-00805f9b34fb
     867[CHG] Device 00:15:83:6B:E2:BD UUIDs: 0000111f-0000-1000-8000-00805f9b34fb
     868[CHG] Device 00:15:83:6B:E2:BD UUIDs: 0000112d-0000-1000-8000-00805f9b34fb
     869[CHG] Device 00:15:83:6B:E2:BD Paired: yes
     870[CHG] Device 00:15:83:6B:E2:BD Connected: no
     871[bluetooth]# trust 00:15:83:6B:E2:BD
     872[CHG] Device 00:15:83:6B:E2:BD Trusted: yes
     873Changing 00:15:83:6B:E2:BD trust succeeded
     874[bluetooth]# exit
     875Agent unregistered
     876[DEL] Controller 00:02:72:C9:56:47 BlueZ 5.37 [default]
     877root@xenial:~# bluetoothctl
     878[NEW] Controller 00:02:72:C9:56:47 BlueZ 5.37 [default]
     879[NEW] Device 00:15:83:6B:E2:BD ventana-trusty-0
     880[bluetooth]# paired-devices
     881Device 00:15:83:6B:E2:BD ventana-trusty-0
     882[bluetooth]# exit
     883[DEL] Controller 00:02:72:C9:56:47 BlueZ 5.37 [default]
     884# sdptool search NAP
     885Inquiring ...
     886Searching for NAP on 00:15:83:6B:E2:BD ...
     887Service Name: Network Access Point
     888Service Description: BlueZ PAN Service
     889Service Provider: BlueZ PAN
     890Service RecHandle: 0x10006
     891Service Class ID List:
     892  "Network Access Point" (0x1116)
     893Protocol Descriptor List:
     894  "L2CAP" (0x0100)
     895    PSM: 15
     896  "BNEP" (0x000f)
     897    Version: 0x0100
     898    SEQ16: 800 806
     899Language Base Attr List:
     900  code_ISO639: 0x656e
     901  encoding:    0x6a
     902  base_offset: 0x100
     903Profile Descriptor List:
     904  "Network Access Point" (0x1116)
     905    Version: 0x0100
     906
     907# wget https://raw.githubusercontent.com/mk-fg/fgtk/master/bt-pan
     908# chmod +x bt-pan
     909# ./bt-pan --debug client 00:15:83:6B:E2:BD
     910DEBUG:root:Using local device (addr: 00:02:72:C9:56:47): /org/bluez/hci0
     911DEBUG:root:Using remote device (addr: 00:15:83:6B:E2:BD): /org/bluez/hci0/dev_00_15_83_6B_E2_BD
     912DEBUG:root:Connected to network (dev_remote: /org/bluez/hci0/dev_00_15_83_6B_E2_BD, addr: 00:15:83:6B:E2:BD) uuid 'nap' with iface: bnep0
     913DEBUG:root:Finished
     914root@xenial:~# ifconfig bnep0
     915bnep0     Link encap:Ethernet  HWaddr 00:02:72:c9:56:47 
     916          inet6 addr: fe80::202:72ff:fec9:5647/64 Scope:Link
     917          UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
     918          RX packets:0 errors:0 dropped:0 overruns:0 frame:0
     919          TX packets:4 errors:0 dropped:0 overruns:0 carrier:0
     920          collisions:0 txqueuelen:1000
     921          RX bytes:16 (16.0 B)  TX bytes:148 (148.0 B)
     922
     923}}}
     924   - first we used {{{bluetoothctl}}} to pair with and trust the client. Next we fetched the bt-pan python script and used it to connect to the client which registers a bnep0 network interface with Linux upon successful connection with a NAP server. Make sure you use standard networking tools to configure the bridge as desired.
     925
     926
     927BlueZ 4:
     928 * Using the {{{pand}}} tool from the {{{bluez-compat}}} package (see [#pand below])
     929  - '''to use the {{{pand}}} application for BlueZ 4.x you must disable the internal network plugin in its bluetooth daemon. To do this add a '!DisablePlugins=network' to /etc/bluetooth/main.conf under the [General] section and restart the bluetooth daemon)'''
     930 * Using the {{{bt-network}}} application from the {{{bluez-tools}}} package (requires [#pairing pairing]):
     931  - Machine1: server / NAP:
     932{{{#!bash
     933# hciconfig hci0 up # bring up controller
     934# hciconfig hci0 piscan # make discoverable
     935# brctl addbr br0 # add a bridge
     936# bt-network --server nap br0 # run NAP service
     937NAP server registered
     938}}}
     939  - Machine2: client / PANU:
     940{{{
     941# hciconfig hci0 up # bring up controller
     942# hciconfig hci0 piscan # make discoverable
     943# sdptool search NAP # search for NAP service
     944# bt-network --connect 00:02:72:C9:56:47 nap &
     945}}}
     946
     947[=#pand]
     948BlueZ 3:
     949 * Using the {{{pand}}} tool from the {{{bluez}}} package:
     950  - '''to use the {{{pand}}} application for BlueZ 4.x you must disable the internal network plugin in its bluetooth daemon. To do this add a '!DisablePlugins=network' to /etc/bluetooth/main.conf under the [General] section and restart the bluetooth daemon)'''
     951  - Machine1: server / NAP:
     952{{{#!bash
     953# hciconfig hci0 up # bring up bluetooth controller
     954# hciconfig hci0 piscan # make discoverable
     955# pand --listen --role NAP --master
     956}}}
     957   * Once connected to a PANU you will see a message such as {{{pand[872]: New connection from 00:15:83:3D:0A:57 at bnep0}}}
     958  - Machine2: client / PANU:
     959{{{#!bash
     960# hciconfig hci0 up # bring up bluetooth controller
     961# hcitool -i hci0 scan # show all discoverable bluetooth devices
     962Scanning ...
     963        00:15:83:6B:E2:BD       ventana-trusty-0
     964# sdptool search NAP # show all discoverable bluetooth devices advertising NAP service
     965Inquiring ...
     966Searching for NAP on 00:15:83:6B:E2:BD ...
     967Service Name: Network Access Point
     968Service Description: BlueZ PAN Service
     969Service Provider: BlueZ PAN
     970Service RecHandle: 0x10008
     971Service Class ID List:
     972  "Network Access Point" (0x1116)
     973Protocol Descriptor List:
     974  "L2CAP" (0x0100)
     975    PSM: 15
     976  "BNEP" (0x000f)
     977    Version: 0x0100
     978    SEQ16: 800 806
     979Language Base Attr List:
     980  code_ISO639: 0x656e
     981  encoding:    0x6a
     982  base_offset: 0x100
     983Profile Descriptor List:
     984  "Network Access Point" (0x1116)
     985    Version: 0x0100
     986
     987# pand --connect 00:15:83:6B:E2:BD --service NAP --nodetach
     988pand[717]: Bluetooth PAN daemon version 4.101
     989pand[717]: Connecting to 00:15:83:6B:E2:BD
     990pand[717]: bnep0 connected
     991}}}
     992  - You can remove the {{{--nodetach}}} to run as a daemon (in which case you won't see the pand messages on the console indicating the connection status)
     993  - You can use {{{pand --role PANU --search}}} to search for and auto-connect to the first NAP server found:
     994{{{#!bash
     995# pand --role PANU --search --nodetach
     996pand[723]: Bluetooth PAN daemon version 4.101
     997pand[723]: Inquiring
     998pand[723]: Searching for NAP on 00:15:83:6B:E2:BD
     999pand[723]: Connecting to 00:15:83:6B:E2:BD
     1000pand[723]: bnep0 connected
     1001}}}
     1002
     1003 * Using D-Bus messages via {{{dbus-send}}}:
     1004  - Machine1: server / NAP:
     1005{{{#!bash
     1006export BTADAPTER=`dbus-send --system --dest=org.bluez --print-reply / org.bluez.Manager.DefaultAdapter | tail -1 | sed 's/^.*"\(.*\)".*$/\1/'` # get the adapter path
     1007
     1008dbus-send --system --dest=org.bluez --print-reply $BTADAPTER org.bluez.NetworkHub.SetProperty string:Enabled variant:boolean:true
     1009}}}
     1010
     1011
     1012[=#opp]
     1013=== Object Push Profile (OPP) ===
     1014The Object Push Profile (OPP) is used to send binary data objects. An OPP server is needed to receive files via OPP. OOP defines the roles of 'push server' and 'push client':
     1015 - Push Server - the device that provides an object exchange server.
     1016 - Push Client - the device that pushes and pulls objects to and from the Push Server.
     1017
     1018You can use the {{{obexpushd}}} tool to create an OPP Push Server and listen for incoming files. You can use the {{{obexftp}}} tool as a Push Client to send files to a Push Server.
     1019
     1020Devices do not need to be previously paired for the OPP profile. Note that the [#ftp FTP profile] is much more capable profile.
     1021
     1022Android devices:
     1023 * Several Android applications can use OPP to push files to a device with an OPP Push Server. For example, Google photos and the Google Camera app use this when you select the 'share icon' when viewing an image followed by the 'Bluetooth' icon (at which point it will show you all bluetooth devices that provide an OPP Push server)
     1024 * There are several applications in the Google Play Store that provide the ability to push files to an 'OBEX OPP' server such as 'Bluetooth File Transfer' by Medieval Software: Note that by default this application enables an OOP and an FTP server without authentication (but pairing is required) while the app is running.
     1025
     1026Examples:
     1027 * Discover devices providing a Push Server:
     1028{{{#!bash
     1029# sdptool search OPUSH
     1030}}}
     1031 * Receive a file via {{{obexpushd}}}:
     1032{{{#!bash
     1033# hciconfig hci0 piscan # make sure we are discoverable
     1034# obexpushd -B5 -o /tmp -n # start Push Server on bluetooth channel 9 using /tmp as a directory store
     1035obexpushd 0.11.2 Copyright (C) 2006-2010 Hendrik Sattler
     1036This software comes with ABSOLUTELY NO WARRANTY.
     1037This is free software, and you are welcome to redistribute it
     1038under certain conditions.
     1039Warning: local character set is not Unicode.
     1040Listening on bluetooth/[00:00:00:00:00:00]:5
     1041Creating file "/tmp/0001.patch"
     1042^C
     1043}}}
     1044  - remove the {{{-n}}} to run in the background
     1045  - above shows a file accepted called 00001.patch
     1046 * Binary file transfer to a device providing an OBEX OPP Push server using {{{obexftp}}}:
     1047{{{#!bash
     1048# sdptool search OPUSH
     1049Inquiring ...
     1050Searching for OPUSH on 00:15:83:6B:E2:BD ...
     1051Service Name: OBEX Object Push
     1052Service Description: a free OBEX server
     1053Service Provider: obexpushd
     1054Service RecHandle: 0x10006
     1055Service Class ID List:
     1056  "OBEX Object Push" (0x1105)
     1057Protocol Descriptor List:
     1058  "L2CAP" (0x0100)
     1059  "RFCOMM" (0x0003)
     1060    Channel: 5
     1061  "OBEX" (0x0008)
     1062Profile Descriptor List:
     1063  "OBEX Object Push" (0x1105)
     1064    Version: 0x0100
     1065
     1066# obexftp --bluetooth 00:15:83:6B:E2:BDE --channel 5 --put file.pdf
     1067Connecting..\done
     1068Tried to connect for 129ms
     1069Sending "file.pdf".../done
     1070Disconnecting..-done
     1071}}}
     1072
     1073
     1074[=#ftp]
     1075=== File Transfer Profile (FTP) ===
     1076Provides the capability to browse, manipulate and transfer objects (files and folders) in an object store (file system) of another system. This uses GOEP as a basis.
     1077
     1078You can use this with the {{{obexftp}}} and {{{obexfs}}} Linux tools when paired with the right service:
     1079 - obexftp - a file transfer protocol client using the OBEX FTP profile
     1080 - obexfs - a FUSE-based filesystem that uses the OBEX FTP profile to connect to an OBEX server
     1081
     1082Devices need to be previously paired (see [#pairing pairing]).
     1083
     1084Android devices:
     1085 * There are several applications in the Google Play Store that provide an 'OBEX FTP' server:
     1086  - 'Bluetooth File Transfer' by Medieval Software: Note that by default this application enables an OOP and an FTP server without authentication (but pairing is required) while the app is running.
     1087
     1088Examples:
     1089 * Discover devices providing a FTP service:
     1090{{{#!bash
     1091# sdptool search FTP
     1092}}}
     1093 * List available files on a device providing an OBEX FTP service using {{{obexftp}}}:
     1094{{{#!bash
     1095# sdptool search FTP # search for devices advertising FTP profile
     1096Inquiring ...
     1097Searching for FTP on 98:E7:F5:A1:A1:EE ...
     1098Service Name: OBEX FTP
     1099Service RecHandle: 0x1000d
     1100Service Class ID List:
     1101  UUID 128: 00001106-0000-1000-8000-00805f9b34fb
     1102Protocol Descriptor List:
     1103  "L2CAP" (0x0100)
     1104  "RFCOMM" (0x0003)
     1105    Channel: 6
     1106
     1107# obexftp --bluetooth 98:E7:F5:A1:A1:EE --channel 6 --list
     1108}}}
     1109 * Delete a file from a device providing an OBEX FTP service using {{{obexftp}}}:
     1110{{{#!bash
     1111# sdptool search FTP # search for devices advertising FTP profile
     1112Inquiring ...
     1113Searching for FTP on 98:E7:F5:A1:A1:EE ...
     1114Service Name: OBEX FTP
     1115Service RecHandle: 0x1000d
     1116Service Class ID List:
     1117  UUID 128: 00001106-0000-1000-8000-00805f9b34fb
     1118Protocol Descriptor List:
     1119  "L2CAP" (0x0100)
     1120  "RFCOMM" (0x0003)
     1121    Channel: 6
     1122
     1123# obexftp --bluetooth 98:E7:F5:A1:A1:EE --channel 6 --delete
     1124}}}
     1125 * Binary file transfer to a device providing an OBEX FTP service using {{{obexftp}}}:
     1126{{{#!bash
     1127# sdptool search FTP # search for devices advertising FTP profile
     1128Inquiring ...
     1129Searching for FTP on 98:E7:F5:A1:A1:EE ...
     1130Service Name: OBEX FTP
     1131Service RecHandle: 0x1000d
     1132Service Class ID List:
     1133  UUID 128: 00001106-0000-1000-8000-00805f9b34fb
     1134Protocol Descriptor List:
     1135  "L2CAP" (0x0100)
     1136  "RFCOMM" (0x0003)
     1137    Channel: 6
     1138
     1139# obexftp --bluetooth 98:E7:F5:A1:A1:EE --channel 6 --put file.pdf
     1140Connecting..\done
     1141Tried to connect for 129ms
     1142Sending "file.pdf".../done
     1143Disconnecting..-done
     1144}}}
     1145 * Binary file transfer from a device providing an OBEX FTP service using {{{obexftp}}}:
     1146{{{#!bash
     1147# sdptool search FTP # search for devices advertising FTP profile
     1148Inquiring ...
     1149Searching for FTP on 98:E7:F5:A1:A1:EE ...
     1150Service Name: OBEX FTP
     1151Service RecHandle: 0x1000d
     1152Service Class ID List:
     1153  UUID 128: 00001106-0000-1000-8000-00805f9b34fb
     1154Protocol Descriptor List:
     1155  "L2CAP" (0x0100)
     1156  "RFCOMM" (0x0003)
     1157    Channel: 6
     1158
     1159# obexftp --bluetooth 98:E7:F5:A1:A1:EE --channel 6 --get file.pdf
     1160Connecting..\done
     1161Tried to connect for 60ms
     1162Receiving "file.pdf".../done
     1163Disconnecting..-done
     1164}}}
     1165 * Run an OBEX FTP server using {{{obexftpd}}}:
     1166{{{#!bash
     1167# hciconfig hci0 piscan # make us discoverable
     1168# cd /tmp
     1169# obexftpd -b5 # start OBEX FTP server via bluetooth channel 5
     1170}}}
     1171 * Mount a filesystem from an 'OBEX FTP' service using {{{obexfs}}}:
     1172{{{#!bash
     1173# sdptool search FTP # search for devices advertising FTP profile
     1174Inquiring ...
     1175Searching for FTP on 98:E7:F5:A1:A1:EE ...
     1176Service Name: OBEX FTP
     1177Service RecHandle: 0x1000d
     1178Service Class ID List:
     1179  UUID 128: 00001106-0000-1000-8000-00805f9b34fb
     1180Protocol Descriptor List:
     1181  "L2CAP" (0x0100)
     1182  "RFCOMM" (0x0003)
     1183    Channel: 6
     1184
     1185# obexfs --bluetooth 98:E7:F5:A1:A1:EE --channel 6 /mnt
     1186# mount | grep obexfs
     1187obexfs on /mnt type fuse.obexfs (rw,nosuid,nodev)
     1188# ls /mnt
     1189Alarms    LinkLocalStorage  Notifications  UnityAdsVideoCache  file.pdf
     1190Android   Logs              Pictures       camera-p.jpg        games
     1191DCIM      Movies            Podcasts       docs                panoramas
     1192Download  Music             Ringtones      foo
     1193}}}
     1194
     1195Note that the {{{obexftp}}} application also supports pushing files to an OBEX OPP server (see [#opp above]).
     1196
     1197
     1198
     1199[=#a2dp]
     1200=== Advanced Audio Distribution Profile (A2DP) ===
     1201The Advanced Audio Distribution Profile (A2DP) is a bluetooth profile that many devices support and is what is used for high fidelity headphone stereo audio. All stereo headphones support A2DP and AVRCP. The Logical Link Controller and Adaptation Protocol (L2CAP) is used in conjunction with the Audio/Video Distribution Transport Protocol (AVDTP) for control and streaming audio. This defines a binary protocol and binary streaming protocol based on RTP. A royalty free Subband-codec (SBC) is included i n the A2DP spec as a mandatory protocol but it is possible for BT devices to also optionally support MP3, AAC or other codecs.
     1202
     1203The quality of audio sent to a wireless headphone is determined by the codec. After the audio source (ie phone) selects the appropriate profile it chooses a codec which the audio sink (ie headhpone) the decodes for playback. Although it is theoretically possible to send mp3's or any other digital format straight to the headphones over Bluetooth instead the A2DP profile specifies its own set of audio codecs:
     1204 * SBC (Subband Coding) - the mandatory default codec for A2DP supported by all Bluetooth stereo devices. It was deisgned to provide reasonably good audio quality over the limited bandwidth of Bluetooth without heavy processing requirements. SBC is capable of bitrates up to about 328kbps at 44.1kHz sampling which is not far off from the maximum for mp3 encoding though mp3 is superior to SBC in terms of audio quality given similar bitrates. SBC is also capable of mid and low quality streams which sound quite compressed to the ears and are unacceptable for music streaming and sound quality varies widly between different SBC implementations.
     1205 * aptX is a proprietary audio codec developed for demanding audio applications designed to encode CD-quality (16bit 44.1kHz) or better (up to 24bit 96kHz) without loss of quality using a slightly higher data rate but more efficient compared to SBC. The aptX codec is not required by A2DP and currently aptX is only supported by CSR chipsets typically used in high-end Android devices. Both the headphone and the source must support aptX and if not the default SBC codec will be used instead. Currently aptX support is limited to mostly high-end Android smartphones and Hi-Fi wireless devices.
     1206 * AAC (Advanced Audio Coding) is a popular codec in general designed to achieve better sound quality than mp3 at similar bit rates. Unlike aptX it is supported by iOS devices (Apple implements AAC over bluetooth at about 250kbps) which should compete in fidelity. Support for AAC is not common in bluetooth devices.
     1207
     1208Requirements:
     1209 * userspace bluteooth-alsa libs (libasound_module_{pcm,ctl}_bluetooth.so) (Ubuntu: bluez-alsa, Yocto: libasound-module-bluez)
     1210
     1211The process to connect Bluetooth A2DP devices differs based on the version of the BlueZ stack you are using as well as the audio back-end that you are using:
     1212 - ALSA: bluez-alsa (Ubuntu) / libasound-module-bluez (Yocto) package providing libasound_module_{pcm,ctl}_bluetooth.so
     1213 - GStreamer: bluez-gstreamer (Ubuntu) providing libgstbluetooth.so / gstreamer1.0-plugins-bad-bluez (Yocto) providing libgstbluez.so
     1214 - !PulseAudio: pulseaudio-module-blueeooth (Ubuntu) providing module-bluetooth-{policy,device,discover,proximity}.so
     1215
     1216
     1217BlueZ 4.x / ALSA:
     1218 - Using Bluetooth headphones to playback audio from Linux device (Linux device is an A2DP Source and connecting to an A2DP Sink)
     1219 1. Identify (put headphones into pairing mode)
     1220{{{#!bash
     1221# hcitool scan
     1222Scanning ...
     1223        A4:15:66:5B:B9:79       Motorola Buds
     1224# sdptool search A2SNK
     1225Inquiring ...
     1226Searching for A2SNK on A4:15:66:5B:B9:79 ...
     1227Service Provider: AVExtension_Device
     1228Service RecHandle: 0x10002
     1229Service Class ID List:
     1230  "Audio Sink" (0x110b)
     1231Protocol Descriptor List:
     1232  "L2CAP" (0x0100)
     1233    PSM: 25
     1234  "AVDTP" (0x0019)
     1235    uint16: 0x0100
     1236Profile Descriptor List:
     1237  "Advanced Audio" (0x110d)
     1238    Version: 0x0100
     1239
     1240}}}
     1241 2. Pair
     1242{{{#!bash
     1243# bluez-simple-agent hci0 A4:15:66:5B:B9:79
     1244RequestPinCode (/org/bluez/506/hci0/dev_A4_15_66_5B_B9_79)
     1245Enter PIN Code: 0000
     1246Release
     1247New device (/org/bluez/391/hci0/dev_A4_15_66_5B_B9_79)
     1248}}}
     1249   - refer to your headset documentation for the correct PIN (0000 shown above or 1234 is typical)
     1250 3. Bluetooth audio configuration:
     1251   - Make sure you have 'Source' and 'Media' enabled under [General] in /etc/bluetooth/audio.conf:
     1252{{{#!bash
     1253# sed 's/#Disable=\(.*\)/Enable=Source,Sink,Headset,Gateway,Control,Socket,Media/' /etc/bluetooth/audio.conf -i # enable all modules
     1254}}}
     1255   - Restart the bluetooth daemon
     1256 4. bluetooth-alsa configuration: Configure a 'btheadset' audio device:
     1257{{{#!bash
     1258# cat <<EOT >/etc/asound.conf
     1259pcm.btheadset {
     1260   type plug
     1261   slave {
     1262       pcm {
     1263           type bluetooth
     1264           device A4:15:66:5B:B9:79
     1265           profile "auto"
     1266       } 
     1267   } 
     1268   hint {
     1269       show on
     1270       description "BT Headset"
     1271   } 
     1272}
     1273
     1274ctl.btheadset {
     1275  type bluetooth
     1276}
     1277EOT
     1278}}}
     1279 5. You should now be able to play audio to the paired headset via ALSA:
     1280  - For example with the {{{aplay}}} tool from the {{{alsa-utils}}} package:
     1281{{{#!bash
     1282# aplay -D btheadset /usr/share/sounds/alsa/Front_Center.wav # play
     1283}}}
     1284  - or mplayer:
     1285{{{#!bash
     1286# mplayer -ao alsa:device=btheadset /usr/share/sounds/alsa/Front_Center.wav
     1287}}}
     1288  - In order to get your headet's multimedia buttons (play,pause,next,previous) you need to create /etc/modules-load.d/uinput.conf containing uinput
     1289  - For !PulseAudio you need to have !PulseAudio installed (pulseaudio-module-blueeooth) and have the !PulseAudio sound server started: {{{pulseaudio --start}}} and do not need to have /etc/asound.conf configured
     1290
     1291References:
     1292 * https://www.kernel.org/doc/ols/2008/ols2008v1-pages-193-196.pdf
     1293 * http://theheadphonelist.com/wireless-fidelity-making-sense-bluetooth-headphone-technology/
     1294
     1295=== Generic Access Protocol GAP ===
     1296Protocol when devices are continuously advertising and there is no bonded connection. Example: temperature sensor advertising its value.
     1297
     1298Two device roles:
     1299
     1300 * Central - device such as Gateworks SBC
     1301 * Peripheral - device such as a temperature sensor
     1302
     1303Packets are 31 bytes.
     1304
     1305=== Generic Attribute Profile GATT ===
     1306Used in Bluetooth Low Energy. This for a dedicated connection between two devices after GAP has already been completed. A BLE peripheral can only be connected to on central device at a time.
     1307
     1308GATT has the following:
     1309 * Client - A device who initates a GATT command or request. Ex: Gateworks SBC
     1310 * Server - A device that receives GATT requests and then responds. Ex: Temperature Sensor
     1311 * Characteristic - A data value, such as a battery voltage
     1312 * Service - Collection of Characteristics
     1313 * Descriptor - Additional information for a characteristic.
     1314 * Identifiers - a UUID for services, descriptors, and characteristics.
     1315 * Notifications - Client can be notified when a characteristic changes on a server. Avoids the need for the client to poll the server
     1316 * Indication - The same as a notification, but the client must confirm to the server it received the message.
     1317
     1318
     1319
     1320== Common Commandline Tools and Operations ==
     1321Several command-line tools and operations are consistent among the various versions of the BlueZ stack.
     1322
     1323[=#hciconfig]
     1324=== Configuring Bluetooth Controller (hciconfig) ===
     1325The {{{hciconfig}}} tool will allow you to identify and configure Bluetooth controllers. It is very similar to ifconfig in that it shows Bluetooth devices, their TX/RX bytes, MAC and some other relevant information. A Bluetooth device generally shows up as hciX where X is a zero-based number. That is, if there is only one Bluetooth adapter on your system, it would usually show up as hci0.
     1326
     1327You can see the available Bluetooth controllers on a Linux system by looking in the {{{/sys/class/bluetooth}}} directory:
     1328{{{#!bash
     1329# ls /sys/class/bluetooth
     1330hci0
     1331}}}
     1332
     1333Example uses:
     1334 * show configuration for all controllers:
     1335{{{#!bash
     1336# hciconfig
     1337hci0:   Type: BR/EDR  Bus: USB
     1338        BD Address: 2C:3D:4F:04:12:55  ACL MTU: 339:6  SCO MTU: 180:1
     1339        DOWN
     1340        RX bytes:488 acl:0 sco:0 events:20 errors:0
     1341        TX bytes:82 acl:0 sco:0 commands:20 errors:0
     1342}}}
     1343  - The above shows a single controller named 'hci0' with unique MAC of 2C:3D:4F:04:12:55 currently in the power down state
     1344 * bring up controller (if you don't have a bluetooth daemon that automatically does this for you):
     1345{{{#!bash
     1346hciconfig hci0 up
     1347}}}
     1348  - If this fails with an error like {{{Operation not possible due to RF-kill}}} then you need to unblock it via a hardware button/gpio or use the {{{rfkill}}} utility to unblock it:
     1349{{{#!bash
     1350rfkill unblock all
     1351}}}
     1352
     1353The {{{hciconfig}}} command will show you the state of controllers as well (UP/DOWN, RUNNING, PSCAN, ISCAN). The Inquiry Scan (ISCAN) and Page Scan (PSCAN) settings determine device discover-ability ([#discovery see discovery below]).
     1354
     1355
     1356[=#hciattach]
     1357=== UART based HCI configuration (hciattach) ===
     1358The {{{hciattach}}} tool is used to attach serial devices via UART HCI to the BlueZ stack.
     1359
     1360This is useful for on-board Bluetooth controllers that are connected directly to a processor UART. Gateworks does not use any such controllers.
     1361
     1362
     1363[=#discoverable]
     1364=== Discoverability (hciconfig) ===
     1365Every Bluetooth end-point device and controller has a unique MAC address (also known as a BDADDR) and a name.
     1366
     1367A Bluetooth device needs to be in discovery mode to show up in a scan. Refer to the device documentation for details. Typically this involves holding a button down (often the power on button) for several seconds and results in a flashing blue LED indicating the device is in pairing or discovery mode.
     1368
     1369The {{{hciconfig}}} command can be used to configure the discover-ability and the name of a bluetooth controller. A Bluetooth controller may start off in hidden mode and needs to be in the 'Inquiry Scan' state to be discoverable.
     1370
     1371Examples:
     1372 * show state of 'Inquiry Scan' and 'Page Scan':
     1373{{{#!bash
     1374# hciconfig hci0
     1375}}}
     1376 * enable 'Inquiry Scan' state:
     1377{{{#!bash
     1378# hciconfig hci0 iscan
     1379}}}
     1380 * enable 'Page Scan' state:
     1381{{{#!bash
     1382# hciconfig hci0 pscan
     1383}}}
     1384 * enable both 'Page Scan' and 'Inquiry Scan' states:
     1385{{{#!bash
     1386# hciconfig hci0 piscan
     1387}}}
     1388 * disable discovery mode (be hidden):
     1389{{{#!bash
     1390# hciconfig hci0 noscan
     1391}}}
     1392
     1393The name that is shown with the MAC address of discovered nearby devices is configurable. For Linux Bluetooth controllers the {{{name}}} sub-command will configure the controllers name. You can also specify this in the Bluetooth daemon's configuration file.
     1394
     1395Examples:
     1396 * show the name of a controller:
     1397{{{#!bash
     1398# hciconfig hci0 name
     1399hci0:   Type: BR/EDR  Bus: SDIO
     1400        BD Address: 00:06:C6:FF:AD:1A  ACL MTU: 1021:7  SCO MTU: 120:6
     1401        Name: 'ventana-0'
     1402}}}
     1403 * use the name instead of the device name:
     1404{{{#!bash
     1405# hciconfig ventana-0
     1406hci0:   Type: BR/EDR  Bus: SDIO
     1407        BD Address: 00:06:C6:FF:AD:1A  ACL MTU: 1021:7  SCO MTU: 120:6
     1408        UP RUNNING PSCAN
     1409        RX bytes:18030 acl:121 sco:0 events:910 errors:0
     1410        TX bytes:7916 acl:76 sco:0 commands:448 errors:0
     1411}}}
     1412 * Set the name:
     1413{{{#!bash
     1414# hciconfig hci0 name "MyUCI"
     1415# hciconfig hci0 name
     1416hci0:   Type: BR/EDR  Bus: SDIO
     1417        BD Address: 00:06:C6:FF:AD:1A  ACL MTU: 1021:7  SCO MTU: 120:6
     1418        Name: 'MyUCI'
     1419# hciconfig MyUCI
     1420hci0:   Type: BR/EDR  Bus: SDIO
     1421        BD Address: 00:06:C6:FF:AD:1A  ACL MTU: 1021:7  SCO MTU: 120:6
     1422        UP RUNNING PSCAN
     1423        RX bytes:18393 acl:123 sco:0 events:917 errors:0
     1424        TX bytes:8238 acl:79 sco:0 commands:450 errors:0
     1425
     1426}}}
     1427
     1428References:
     1429 * file:///home/tharvey/Downloads/Discovery_WP_V10.pdf
     1430
     1431
     1432[=#scan]
     1433=== Scanning for Bluetooth devices available for pairing (hcitool) ===
     1434The {{{hcitool}}} app from the bluez package can also be used to scan for and connect to Bluetooth devices in the area as well as give you information as to their identity (user defined name) and signal quality.
     1435
     1436Examples:
     1437 * Scan for nearby discoverable Bluetooth devices:
     1438{{{#!bash
     1439# hciconfig hci0 up # make sure controller is powered on
     1440# hcitool -i hci0 scan # shows MAC and name of nearby devices which are configured as discoverable
     1441Scanning ..
     1442        09:40:A4:45:B1:4B       P6
     1443}}}
     1444  - The above shows a single device found named 'P6' with a unique MAC address of '09:40:A4:45:B1:4B'
     1445 * Connects to a specific Bluetooth device and show its link quality
     1446{{{#!bash
     1447# hcitool cc 09:40:A4:45:B1:4B; hcitool lq 09:40:A4:45:B1:4B; hcitool con
     1448Link quality: 255
     1449Connections:
     1450        < ACL 09:40:A4:45:B1:4B handle 256 state 7 lm MASTER
     1451# hcitool con
     1452Connections:
     1453#
     1454}}}
     1455  - The above connects to the device with the specified MAC address and shows the active connection link quality
     1456
     1457 * To scan for Bluetooth Low Energy devices, use the following command:
     1458{{{
     1459hcitool lescan
     1460}}}
     1461
     1462
     1463[=#l2ping]
     1464=== Pinging a device to test its connection (l2ping) ===
     1465When a device has been discovered you can use {{{l2ping}}} from the bluez package to test the connection. This requires you to know the unique MAC address of the device:
     1466{{{#!bash
     1467# l2ping 09:40:a4:45:b1:4b
     14680 bytes from 09:40:a4:45:b1:4b id 0 time 9.12ms
     14690 bytes from 09:40:a4:45:b1:4b id 1 time 52.33ms
     14700 bytes from 09:40:a4:45:b1:4b id 2 time 22.50ms
     14710 bytes from 09:40:a4:45:b1:4b id 3 time 25.92ms
     1472^C4 sent, 4 received, 0% loss
     1473}}}
     1474 * Use 'cntl-C' to stop the ping if you did not specify a -c parameter to limit the number of ping counts
     1475 * You can ping a device even if it is no longer responding to scanning (because its no longer in discovery mode) as long as the device is powered on
     1476
     1477
     1478[=#connect]
     1479=== Open A Connection (hcitool) ===
     1480Use {{{hcitool}}} to open a connection between an HCI and a bluetooth device:
     1481{{{#!bash
     1482# hcitool cc 54:46:6B:01:7B:2B
     1483}}}
     1484
     1485
     1486[=#linkqual]
     1487=== Link Quality (hcitool) ===
     1488Use {{{hcitool}}} to open a connection and determine hte link quality of a connection:
     1489{{{#!bash
     1490# hcitool cc 54:46:6B:01:7B:2B; hcitool lq 54:46:6B:01:7B:2B; hcitool con
     1491}}}
     1492
     1493
     1494[#sdptool]
     1495=== Bluetooth Service Discovery Protocol (SDP) (sdptool) ===
     1496The Bluetooth Service Discovery Protocol (SDP) provides a means by which service applications running on different Bluetooth enabled devices may discover each other's existence and exchange info to determine their characteristics.
     1497
     1498Use {{{sdptool}}} from the bluez package to perform SDP queries on Bluetooth devices and for administering a local SDP daemon, or {{{sdpd}}}.
     1499
     1500Example:
     1501 * Show characteristics of the Sound Intone Bluetooth headset by showing all possible service records:
     1502{{{#!bash
     1503# sdptool records 09:40:a4:45:b1:4b
     1504Service Name: JL_A2DP
     1505Service RecHandle: 0x10001
     1506Service Class ID List:
     1507  "Audio Sink" (0x110b)
     1508Protocol Descriptor List:
     1509  "L2CAP" (0x0100)
     1510    PSM: 25
     1511  "AVDTP" (0x0019)
     1512    uint16: 0x100
     1513Language Base Attr List:
     1514  code_ISO639: 0x656e
     1515  encoding:    0x6a
     1516  base_offset: 0x100
     1517Profile Descriptor List:
     1518  "Advanced Audio" (0x110d)
     1519    Version: 0x0100
     1520
     1521Service RecHandle: 0x10002
     1522Service Class ID List:
     1523  "AV Remote" (0x110e)
     1524Protocol Descriptor List:
     1525  "L2CAP" (0x0100)
     1526    PSM: 23
     1527  "AVCTP" (0x0017)
     1528    uint16: 0x100
     1529Profile Descriptor List:
     1530  "AV Remote" (0x110e)
     1531    Version: 0x0100
     1532
     1533Service Name: JL_HFP
     1534Service RecHandle: 0x10003
     1535Service Class ID List:
     1536  "Handsfree" (0x111e)
     1537  "Generic Audio" (0x1203)
     1538Protocol Descriptor List:
     1539  "L2CAP" (0x0100)
     1540  "RFCOMM" (0x0003)
     1541    Channel: 4
     1542Language Base Attr List:
     1543  code_ISO639: 0x656e
     1544  encoding:    0x6a
     1545  base_offset: 0x100
     1546Profile Descriptor List:
     1547  "Handsfree" (0x111e)
     1548    Version: 0x0105
     1549
     1550}}}
     1551 * Show records of a bluetooth keyboard:
     1552{{{#!bash
     1553# sdptool records 54:46:6B:01:7B:2B
     1554Service Name: Broadcom Bluetooth Wireless  Keyboard                       
     1555Service Description: Keyboard
     1556Service Provider: Broadcom Corp. 
     1557Service RecHandle: 0x10000
     1558Service Class ID List:
     1559  "Human Interface Device" (0x1124)
     1560Protocol Descriptor List:
     1561  "L2CAP" (0x0100)
     1562    PSM: 17
     1563  "HIDP" (0x0011)
     1564Language Base Attr List:
     1565  code_ISO639: 0x656e
     1566  encoding:    0x6a
     1567  base_offset: 0x100
     1568Profile Descriptor List:
     1569  "Human Interface Device" (0x1124)
     1570    Version: 0x0100
     1571
     1572Service Name: Broadcom Bluetooth Wireless Keyboard PnP Server
     1573Service Description: Keyboard
     1574Service RecHandle: 0x10001
     1575Service Class ID List:
     1576  "PnP Information" (0x1200)
     1577Protocol Descriptor List:
     1578  "L2CAP" (0x0100)
     1579    PSM: 1
     1580  "SDP" (0x0001)
     1581Language Base Attr List:
     1582  code_ISO639: 0x656e
     1583  encoding:    0x6a
     1584  base_offset: 0x100
     1585Profile Descriptor List:
     1586  "PnP Information" (0x1200)
     1587    Version: 0x0100
     1588
     1589}}}
     1590 * Show all devices advertising the A2DP Profile:
     1591{{{#!bash
     1592# sdptool search A2DP
     1593Service Name: JL_A2DP
     1594Service RecHandle: 0x10001
     1595Service Class ID List:
     1596  "Audio Sink" (0x110b)
     1597Protocol Descriptor List:
     1598  "L2CAP" (0x0100)
     1599    PSM: 25
     1600  "AVDTP" (0x0019)
     1601    uint16: 0x100
     1602Language Base Attr List:
     1603  code_ISO639: 0x656e
     1604  encoding:    0x6a
     1605  base_offset: 0x100
     1606Profile Descriptor List:
     1607  "Advanced Audio" (0x110d)
     1608    Version: 0x0100
     1609
     1610}}}
     1611
     1612Reference:
     1613 * https://developer.bluetooth.org/TechnologyOverview/Pages/SDAP.aspx
     1614 * http://linux.die.net/man/1/sdptool
     1615
     1616
     1617[=#pairing]
     1618=== Pairing and bonding (Setting up connections) ===
     1619Many of the bluetooth services can expose private data or allow control of a device, therefore for security reasons it is desired to securely pair devices in a fashion that doesn't make it too difficult to use conveniently.
     1620
     1621Bluetooth uses a process called '''bonding''' where a bond is generated through a process called '''pairing'''. Paring is triggered either by a specific request or triggered automatically when connecting to a service for the first time. There is usually some form of user interaction to confirm the identify of the devices but once pairing is complete a bond will have been formed between the two devices, enabling them to connect to each other in the future without requiring the pairing process again. If desired the bonding relationship can later be removed by the user which would force a pairing to be completed again.
     1622
     1623You can also tell your controller to specifically trust a device based on its MAC address which eliminates the need for pairing. It is the controller that decides to pair or trust a device, not the device itself.
     1624
     1625The configuration for paired devices is stored in {{{/var/lib/bluetooth/<hci_mac>/}}}.
     1626
     1627The method used for pairing a controller to a device differs depending on the version of the BlueZ stack being used:
     1628 * BlueZ 5:
     1629  * The BlueZ 5 bluetooth daemon stores its persistent pairing details in {{{/var/lib/bluetooth/<hci_MAC>/<device_MAC>/info}}} with the format of:
     1630{{{
     1631[LinkKey]
     1632Key       String  <key in hex format>
     1633Type      Integer <Type of link key>
     1634PINLength Integer <Length of PIN>
     1635}}}
     1636   - therefore you can remove all pairing history by removing that file and restarting bluetoothd
     1637  * You can request pairing with devices using the {{{bluetoothctl}}} CLI {{{pair <bdaddr>}}} command:
     1638{{{#!bash
     1639# bluetoothctl
     1640[NEW] Controller 00:15:83:6B:E2:BD BlueZ 5.37 [default]
     1641[bluetooth]# power on
     1642Changing power on succeeded
     1643[bluetooth]# scan on
     1644Discovery started
     1645[CHG] Controller 00:15:83:6B:E2:BD Discovering: yes
     1646[NEW] Device 54:46:6B:01:7B:2B 54-46-6B-01-7B-2B
     1647[CHG] Device 54:46:6B:01:7B:2B RSSI: -75
     1648[CHG] Device 54:46:6B:01:7B:2B LegacyPairing: no
     1649[CHG] Device 54:46:6B:01:7B:2B Name: Bluetooth FAVI
     1650[CHG] Device 54:46:6B:01:7B:2B Alias: Bluetooth FAVI
     1651[bluetooth]# pair 54:46:6B:01:7B:2B
     1652Attempting to pair with 54:46:6B:01:7B:2B
     1653[CHG] Device 54:46:6B:01:7B:2B Connected: yes
     1654[CHG] Device 54:46:6B:01:7B:2B Modalias: usb:v0A5Cp8502d011B
     1655[CHG] Device 54:46:6B:01:7B:2B UUIDs: 00001000-0000-1000-8000-00805f9b34fb
     1656[CHG] Device 54:46:6B:01:7B:2B UUIDs: 00001124-0000-1000-8000-00805f9b34fb
     1657[CHG] Device 54:46:6B:01:7B:2B UUIDs: 00001200-0000-1000-8000-00805f9b34fb
     1658[CHG] Device 54:46:6B:01:7B:2B Paired: yes
     1659Pairing successful
     1660[CHG] Device 54:46:6B:01:7B:2B Connected: no
     1661[CHG] Device 54:46:6B:01:7B:2B LegacyPairing: yes
     1662[CHG] Device 54:46:6B:01:7B:2B RSSI: -66
     1663[CHG] Device 54:46:6B:01:7B:2B RSSI: -66
     1664[bluetooth]# scan off
     1665[CHG] Controller 00:15:83:6B:E2:BD Discovering: no
     1666Discovery stopped
     1667[bluetooth]# paired-devices
     1668Device 54:46:6B:01:7B:2B Bluetooth FAVI
     1669Device 09:40:A4:45:B1:4B P6
     1670[bluetooth]#
     1671}}}
     1672   - above first we enable scanning, then we pair with a device, next we disable scanning (optional), and lastly we show paired devices
     1673  * You can respond to pairing requests using the bluetoothd internal agent using the {{{bluetoothctl}}} CLI:
     1674{{{#!bash
     1675# bluetoothctl
     1676[NEW] Controller 00:15:83:6B:E2:BD BlueZ 5.37 [default]
     1677[bluetooth]# power on
     1678Changing power on succeeded
     1679[bluetooth]# agent on
     1680Agent registered
     1681[bluetooth]# default-agent
     1682Default agent request successful
     1683[NEW] Device 00:15:83:3D:0A:57 yocto18-0
     1684Request PIN code
     1685[agent] Enter PIN code: 0000
     1686[CHG] Device 00:15:83:3D:0A:57 Paired: yes
     1687[CHG] Device 00:15:83:3D:0A:57 Connected: no
     1688[bluetooth]# paired-devices
     1689Device 00:15:83:3D:0A:57 yocto18-0
     1690}}}
     1691   - above we first enable the agent, then set it to the default agent and wait for pairing requests. A pairing request comes from a device with a bdaddr or 00:15:83:3D:0A:57 and a name of yocto18-0 and we enter in the PIN that the device is expecting and we pair with it
     1692 * BlueZ 4:
     1693  * The BlueZ 4.x bluetooth daemon stores persistent pairing details {{{/var/lib/bluetooth/<hci_MAC>/linkkeys}}} with the following format:
     1694{{{
     1695<bdaddr> <128bit_link_key> <key_type> <key_length>
     1696}}}
     1697   - therefore you can remove all pairing history by removing that file and restarting bluetoothd
     1698  * You can pair with a device using the python 'simple-agent' found in the bluez4 git tree [http://git.kernel.org/cgit/bluetooth/bluez.git/plain/test/simple-agent?h=4.101 here] (requires python, python-dbus and python-gobject)
     1699{{{#!bash
     1700# ./simple-agent hci0 54:46:6B:01:7B:2B
     1701RequestPinCode (/org/bluez/449/hci0/dev_54_46_6B_01_7B_2B)
     1702Enter PIN Code: 1234
     1703Release
     1704New device (/org/bluez/449/hci0/dev_54_46_6B_01_7B_2B)
     1705# ls /var/lib/bluetooth/00\:15\:83\:3D\:0A\:57/
     1706classes   did       linkkeys  profiles 
     1707config    lastused  names     sdp       
     1708# cat /var/lib/bluetooth/00\:15\:83\:3D\:0A\:57/linkkeys
     170954:46:6B:01:7B:2B E45EED6C956306606A306EA1A2E22B68 0 4
     1710}}}
     1711   - Depending on the version of python you have installed, you may need to patch simple-agent with the following changes:
     1712{{{#!bash
     1713--- simple-agent.orig
     1714+++ simple-agent
     1715@@ -2,8 +2,7 @@
     1716 
     1717 from __future__ import absolute_import, print_function, unicode_literals
     1718 
     1719-from gi.repository import GObject
     1720-
     1721+import gobject
     1722 import sys
     1723 import dbus
     1724 import dbus.service
     1725@@ -122,7 +121,7 @@
     1726        path = "/test/agent"
     1727        agent = Agent(bus, path)
     1728 
     1729-       mainloop = GObject.MainLoop()
     1730+       mainloop = gobject.MainLoop()
     1731 
     1732        if len(args) > 1:
     1733                if len(args) > 2:
     1734}}}
     1735  * Alternatively you can also pair using the compiled agent.c found in the bluez4 git tree [http://git.kernel.org/cgit/bluetooth/bluez.git/plain/test/agent.c?h=4.101 here]
     1736{{{#!bash
     1737# bluetoothd
     1738# ./agent 1234 54:46:6B:01:7B:2B
     1739Pincode request for device /org/bluez/2039/hci0/dev_54_46_6B_01_7B_2B
     1740Agent has been released
     1741}}}
     1742  - if this exist without the 'Agent has been released' message then pairing was unsuccessful
     1743  - this can be cross-compiled with the following (ie Yocto SDK):
     1744{{{#!bash
     1745$CC -DVERSION=4.101 $(pkg-config --cflags dbus-1) agent.c $(pkg-config --libs dbus-1) -o agent
     1746}}}
     1747  * For examples on how to pair using dbus messages see the simple-agent and agent.c source code
     1748 * BlueZ 3:
     1749 - The BlueZ 3.x bluetooth daemon stores persistent pairing details in {{{/var/lib/bluetooth/<hci_MAC>/pincodes}}} in the form of:
     1750{{{
     1751<mac> <pin>
     1752}}}
     1753  - therefore you can remove all pairing history by removing that file and restarting bluetoothd
     1754  - If you manually edit this file, you will need to restart the hcid bluetooth daemon:
     1755{{{#!bash
     1756# echo "00:02:72:C9:56:47 0000" >> /var/lib/bluetooth/00\:15\:83\:3D\:0A\:57/pincodes
     1757# /etc/init.d/bluez-utils restart
     1758}}}
     1759
     1760References:
     1761 * http://en.wikipedia.org/wiki/Bluetooth#Pairing_and_bonding
     1762
     1763
     1764[=#hardware]
     1765== Bluetooth Controller Hardware ==
     1766Gateworks has used and tested the following USB based controllers.
     1767
     1768=== USB based (btusb) ===
     1769Their is a large variety of USB based Bluetooth controllers supported by the {{{btusb}}} kernel driver. Here are some common ones that Gateworks has tested:
     1770 * [http://plugable.com/products/usb-bt4le Pluggable USB-BT4LE]: USB ID 0a5c:21e8 Broadcom BCM20702A0
     1771 * CSR 4.0 ([http://www.csr.com/products/bluecore-csr8510-a10-wlcsp CSR8510 A10 Bluetooth USB host]): USB ID 0a12:0001
     1772  - Available from various vendors for <$10
     1773   - http://www.bestbluetoothdongle.com/csr-bluetooth-dongle/
     1774   - https://www.adafruit.com/products/1327
     1775 * [http://www.intel.com/content/dam/www/public/us/en/documents/product-briefs/dual-band-wireless-ac-7260-bluetooth-brief.pdf Intel 7260HWM] - MiniPCIe form-factor 802.11ac / Bluetooth 4.0:
     1776  * Firmware: [http://git.kernel.org/cgit/linux/kernel/git/balbi/linux-firmware.git/plain/intel/ibt-hw-37.7.10-fw-1.80.2.3.d.bseq ibt-hw-37.7.10-fw-1.80.2.3.d.bseq] should be placed in /lib/firmware/intel/. For OpenWrt the driver/firmware is provided by the kmod-btusb kernel module package and the ibt-firmware package which are installed by default in our Ventana BSP since r621
     1777  * Main Ant is Wifi
     1778  * Aux Ant is Wifi + Bluetooth
     1779 * Canyon CN-BTU1: USB ID 0c10:0000
     1780
     1781
     1782
     1783=== DHXA-225 ===
     1784The [http://www.unex.com.tw/product/dhxa-225 Unex DHXA-225] is a MiniPCIe form-factor combo card using Atheros WB225/AR9485+AR3012 providing:
     1785 * 802.11bgn 1x1 MIMO wifi (PCIe device supported by the linux [http://wireless.kernel.org/en/users/Drivers/ath9k ath9k] driver)
     1786  * For OpenWrt this is provided by the kmod-ath9k kernel module package and is built into our default root filesystems by default
     1787 * Bluetooth 4.0 HCI (USB device supported by the linux [http://wireless.kernel.org/en/users/Drivers/ath3k ath3k] driver)
     1788  * Firmware: all *.dfu files in [https://git.kernel.org/cgit/linux/kernel/git/egrumbach/linux-firmware.git/tree/ar3k] should be copied to /lib/firmware/ar3k/
     1789  * For OpenWrt this is provided by the kmod-btusb kernel module package and ar3k-firmware package which are installed by default on our Ventana BSP since r621
     1790
     1791
     1792
     1793[=#code]
     1794== Writing code supporting Bluetooth ==
     1795If you wish to or need to write your own applications to support Bluetooth there are a variety of great resources out there on the Internet:
     1796 * http://people.csail.mit.edu/rudolph/Teaching/Articles/BTBook.pdf (PyBluez, libbluetooth, cmdline tools)
     1797 * [http://git.kernel.org/cgit/bluetooth/bluez.git/tree/doc BlueZ 5 API Documentation]
     1798 * [http://git.kernel.org/cgit/bluetooth/bluez.git/tree/doc?id=4.101 BlueZ 4 API Documentation]
     1799 * [http://git.kernel.org/cgit/bluetooth/bluez.git/tree/doc?h=utils-3.36 BlueZ 3 API Documentation]
     1800 * Don't forget to refer to the source code:
     1801  - bluez - see the docs/examples/test directories
     1802  - bluez-tools - C applications
     1803
     1804== iBeacon ==
     1805iBeacon is a form of BLE that was created by Apple to provide location based information and services to iPhones.
     1806
     1807For example, someone is walking around with an iPhone with a specific app loaded that is listening for these iBeacons. The app on the phone will respond when the iBeacon comes in range. (retail environment, sale special)