# Install bluez on the Raspberry Pi ## Overview Danger: This guide will walk through how to compile and install [bluez](http://www.bluez.org/) on the Raspberry Pi.  Bluez is the Linux Bluetooth system and allows a Raspberry Pi to communicate with Bluetooth classic and Bluetooth low energy (LE) devices.  Although bluez is quite full-featured it can be somewhat challenging to install and use.  However this guide will show you step-by-step what you need to do to compile and install the latest version of bluez.  Grab a Bluetooth USB adapter, like this handy [Bluetooth 4.0 USB module](https://www.adafruit.com/product/1327), and follow this guide to get setup using bluez in almost no time. As a companion to this guide, check out [the following video](https://www.youtube.com/watch?v=5fQR2PHMDWE) which dives into Bluetooth low energy and installing and using bluez on the Pi: https://www.youtube.com/watch?v=5fQR2PHMDWE In addition you might want to read this [Introduction to Bluetooth Low Energy](../../../../introduction-to-bluetooth-low-energy/introduction) guide for more information on BLE. You will also want to be familiar with the basics of using a Raspberry Pi, like loading an operating system on a microSD card and connecting to a command terminal on the Pi.  Check out the [learn Raspberry Pi series](../../../../category/learn-raspberry-pi) for more information on the basics.   # Install bluez on the Raspberry Pi ## Installation Danger: Follow the instructions below to download, compile, install, and configure bluez on the Raspberry Pi.  Before you get started you'll need to make sure your Raspberry Pi has access to the internet, either through a wired or wireless connection.  In addition you'll want to be familiar with accessing a command terminal on the Pi, like [with the SSH tool](../../../../adafruits-raspberry-pi-lesson-6-using-ssh/overview). You will also need to make sure your Raspberry Pi is running the latest version of the **[Raspbian Jessie](https://www.raspberrypi.org/downloads/raspbian/)** operating system (either the full or lite version).  These instructions **won't work** with the older Wheezy release--make sure you're running Jessie and its systemd service host. # Download Source To install [bluez](http://www.bluez.org/) you'll need to download and compile the latest version of its source code.  You could install bluez from a prebuilt package in the Raspbian repository **however** the version in the repository almost certainly is out of date.  If you're using Bluetooth low energy features you really want to be running the absolute latest version of bluez to get the latest bug fixes and features.  Compiling bluez from source will ensure you have the latest and greatest release. Visit the [bluez download page](http://www.bluez.org/download/) and copy the link to the latest source release (under the **User Space BlueZ Package** section).  For example at the time of this guide's writing the latest version of bluez is **5.37** and can be downloaded from:  ``` http://www.kernel.org/pub/linux/bluetooth/bluez-5.37.tar.xz ``` Connect to a terminal on your Pi and execute the following command to download and open the bluez source archive.   **Remember, find the latest version of bluez from its homepage and use that download URL--the instructions below show using version 5.37 of bluez.** ``` cd ~ wget http://www.kernel.org/pub/linux/bluetooth/bluez-5.37.tar.xz tar xvf bluez-5.37.tar.xz ``` You might need to change the tar command above to specify the filename for the version of bluez you're using.   After the command runs you should see it unzip the bluez source into a new folder, like bluez-5.37.  Now change into that directory to continue with the installtion by running (note change the cd command to use the directory for the version of bluez you downloaded): ``` cd bluez-5.37 ``` # Install Dependencies Now you'll need to install a few dependencies that the bluez library uses.  Run the following commands to install these dependencies: ``` sudo apt-get update sudo apt-get install -y libusb-dev libdbus-1-dev libglib2.0-dev libudev-dev libical-dev libreadline-dev ``` After the commands run you should see them install a few dependencies and finish without any error messages. # Compile & Install bluez To compile bluez you'll use the standard configure, make, and sudo make install commands as most other Linux software.  From inside the bluez source directory run the configure script as follows: ```python ./configure --enable-library ``` You should see the script finish without any error messages like below: ![](https://cdn-learn.adafruit.com/assets/assets/000/030/822/medium800/raspberry_pi_Screen_Shot_2016-02-28_at_9.41.15_PM.png?1456724514) If you do see an error message it likely means you need a dependent library installed.  Go back and check you installed all of the libraries mentioned in the install dependencies section above.  Also check what library the configure script detected as missing and see if you can install it from the Raspbian repository (most libraries are named 'libX-dev' where X is the name of the library, like GLib or readline).  You can rerun the configure script until it finishes successfully. Once the configure script has successfully run you're ready to compile the bluez code.  This compilation will take about 10-20 minutes on a Raspberry Pi 2 (and slightly longer on a Pi 1 or Zero).  Start the compile by running: ``` make ``` You should see output as the make command compiles different parts of bluez.  Once it's finished you should see no error messages like the following: ![](https://cdn-learn.adafruit.com/assets/assets/000/030/823/medium800/raspberry_pi_Screen_Shot_2016-02-28_at_10.01.35_PM.png?1456725817) If you do see errors check that the configure script ran without any errors, and make sure all the dependencies are installed and try again. After bluez has been compiled it can be installed by running the following command: ``` sudo make install ``` You should see the command finish with no errors like the following: ![](https://cdn-learn.adafruit.com/assets/assets/000/030/824/medium800/raspberry_pi_Screen_Shot_2016-02-28_at_10.02.06_PM.png?1456725860) That's all there is to installing bluez from source!  Now you'll learn a few tips about configuring bluez to run on the Pi. # Setup bluez Service After installing bluez from source there's one more step to enable the bluetoothd service in bluez.  This service talks to a part of bluez in the kernel and exposes bluetooth devices to user programs.  The bluez service must be running for its tools and libraries to work! With Raspbian Jessie the bluez service is run with systemd.  Systemd is a process that controls other processes on the Pi, like the bluez service.  First you can check that the bluez service is installed and in a good state by running the following command: ``` systemctl status bluetooth ``` You'll likely see the bluez service is loaded but not active, like: ``` ● bluetooth.service - Bluetooth service Loaded: loaded (/lib/systemd/system/bluetooth.service; disabled) Active: inactive (dead) Docs: man:bluetoothd(8) ``` You can manually start the bluez service by running the following command: ``` sudo systemctl start bluetooth ``` After running the above, run the status command again and you should see the service is now active: ``` ● bluetooth.service - Bluetooth service Loaded: loaded (/lib/systemd/system/bluetooth.service; disabled) Active: active (running) since Mon 2016-02-29 04:56:27 UTC; 1s ago Docs: man:bluetoothd(8) Main PID: 715 (bluetoothd) Status: "Running" CGroup: /system.slice/bluetooth.service └─715 /usr/local/libexec/bluetooth/bluetoothd ``` You can stop the service by running: ``` sudo systemctl stop bluetooth ``` And again the status command should now show the bluez service as inactive. If you just want to intermittently use bluez tools & programs you could manually start and stop the service as shown above.  Make sure to start the bluez service before running programs that depend on it. However you probably want the bluez service to run automatically when the Raspberry Pi boots.  To enable the bluez service to run at boot run the following command: ``` sudo systemctl enable bluetooth ``` Now reboot the Pi and run the status command again to check the bluez bluetooth service is running. If you ever want to disable the bluez service from automatically starting, run the following command: ``` sudo systemctl disable bluetooth ``` # Enable Bluetooth Low Energy Features One final configuration change you can make is to enable the bluetooth low energy features in bluez.  These are special APIs that allow bluez to interact with bluetooth low energy devices, however they're still in development and put behind an experimental flag that must be enabled first. To enable bluez's experimental features like BLE you can modify the bluez service configuration.  Edit this configuration by running: ``` sudo nano /lib/systemd/system/bluetooth.service ``` You should see a configuration file similar to the following: ``` [Unit] Description=Bluetooth service Documentation=man:bluetoothd(8) ConditionPathIsDirectory=/sys/class/bluetooth [Service] Type=dbus BusName=org.bluez ExecStart=/usr/local/libexec/bluetooth/bluetoothd NotifyAccess=main #WatchdogSec=10 #Restart=on-failure CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_BIND_SERVICE LimitNPROC=1 [Install] WantedBy=bluetooth.target Alias=dbus-org.bluez.service ``` Enable the experimental features by adding **--experimental** to the ExecStart line, for example the configuration should look like: ``` [Unit] Description=Bluetooth service Documentation=man:bluetoothd(8) ConditionPathIsDirectory=/sys/class/bluetooth [Service] Type=dbus BusName=org.bluez ExecStart=/usr/local/libexec/bluetooth/bluetoothd --experimental NotifyAccess=main #WatchdogSec=10 #Restart=on-failure CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_BIND_SERVICE LimitNPROC=1 [Install] WantedBy=bluetooth.target Alias=dbus-org.bluez.service ``` Save the file and exit the editor by pressing **Ctrl-o** , **enter** , then **Ctrl-x**. Now tell systemd to reload its configuration files by running: ``` sudo systemctl daemon-reload ``` If the bluez service was previously running you'll want to restart it by running: ``` sudo systemctl restart bluetooth ``` Or if the service wasn't running you can start it with the start command previously shown. Once the bluez service is running you can check the experimental features are enabled by running the status command again.  You should see output similar to the following (notice the --experimental on the last line): ``` ● bluetooth.service - Bluetooth service Loaded: loaded (/lib/systemd/system/bluetooth.service; disabled) Active: active (running) since Mon 2016-02-29 05:15:55 UTC; 4s ago Docs: man:bluetoothd(8) Main PID: 1022 (bluetoothd) Status: "Running" CGroup: /system.slice/bluetooth.service └─1022 /usr/local/libexec/bluetooth/bluetoothd --experimental ``` That's all there is to configuring and running bluez on the Raspberry Pi!  At this point you're ready to start using bluez tools like bluetoothctl, hcitool, etc. ## Featured Products ### Xinghuatian Tech Bluetooth® 4.0 USB Module [Xinghuatian Tech Bluetooth® 4.0 USB Module](https://www.adafruit.com/product/1327) Add Bluetooth® capability to your computer super fast with a Xinghuatian Tech Bluetooth® 4.0 USB Module. This adapter is backwards compatible with v2.1 and earlier, but also supports the latest v4.0/ Bluetooth® Low Energy. Inside lies a In Stock [Buy Now](https://www.adafruit.com/product/1327) [Related Guides to the Product](https://learn.adafruit.com/products/1327/guides) ### Raspberry Pi 2 - Model B v1.2 - ARM Cortex-A53 with 1G RAM [Raspberry Pi 2 - Model B v1.2 - ARM Cortex-A53 with 1G RAM](https://www.adafruit.com/product/2358) Didn't think the Raspberry Pi could get any better? You're in for a big surprise! The Raspberry Pi 2 Model B is out and it's amazing! With an upgraded ARM Cortex-A53 quad-core processor, Dual Core VideoCore IV Multimedia coprocessor, and a full Gigabyte of RAM, this... No Longer Stocked [Buy Now](https://www.adafruit.com/product/2358) [Related Guides to the Product](https://learn.adafruit.com/products/2358/guides) ### Raspberry Pi Model B+ 512MB RAM [Raspberry Pi Model B+ 512MB RAM](https://www.adafruit.com/product/1914) OMG OMG OMG, did you hear? There's a Raspberry Pi called the Model B+ and check it out...more USB ports, more GPIO, better power supply, four mounting holes, less sticky-out SD card! Yep, that's right, the fantastic engineers at Raspberry Pi HQ have blessed us with a new design.... In Stock [Buy Now](https://www.adafruit.com/product/1914) [Related Guides to the Product](https://learn.adafruit.com/products/1914/guides) ### Raspberry Pi Model A+ 512MB RAM [Raspberry Pi Model A+ 512MB RAM](https://www.adafruit.com/product/2266) **Note:** As of August 10th, 2016 the Raspberry Pi A+ now includes 512 MB of RAM! The Raspberry Pi Model A+ is the perfect board for the minimalist Pi fan. This low-cost Pi uses the same processor as the model B+, but does away with the Ethernet jack and three of the USB... No Longer Stocked [Buy Now](https://www.adafruit.com/product/2266) [Related Guides to the Product](https://learn.adafruit.com/products/2266/guides) ### Raspberry Pi Zero - Version 1.3 [Raspberry Pi Zero - Version 1.3](https://www.adafruit.com/product/2885) At first glance, the Pi Zero isn't much.  It just looks like a slimmed down version of the Raspberry Pi we know and love.  But when we started to think of the possibilities - [and what a well-chosen set of accessories could add](https://www.adafruit.com/product/2816) -... Out of Stock [Buy Now](https://www.adafruit.com/product/2885) [Related Guides to the Product](https://learn.adafruit.com/products/2885/guides) ## Related Guides - [Adafruit QT Py RP2040](https://learn.adafruit.com/adafruit-qt-py-2040.md) - [BLE Synth with the Feather nRF52840 and Circuit Playground Bluefruit](https://learn.adafruit.com/ble-synth-with-the-feather-nrf52840-and-circuit-playground-bluefruit.md) - [OpenClaw on Raspberry Pi](https://learn.adafruit.com/openclaw-on-raspberry-pi.md) - [Adafruit Speaker Bonnet for Raspberry Pi](https://learn.adafruit.com/adafruit-speaker-bonnet-for-raspberry-pi.md) - [Mini Mac Pi](https://learn.adafruit.com/mini-mac-pi.md) - [Adafruit's Raspberry Pi Lesson 2. First Time Configuration](https://learn.adafruit.com/adafruits-raspberry-pi-lesson-2-first-time-configuration.md) - [Adafruit EYESPI Pi Beret](https://learn.adafruit.com/eyespi-pi-beret.md) - [Chumby Hacker Board](https://learn.adafruit.com/chumby-hacker-board.md) - [Bluefruit Playground App](https://learn.adafruit.com/bluefruit-playground-app.md) - [Adafruit 2.13" Monochrome E-Ink Bonnet for Raspberry Pi](https://learn.adafruit.com/2-13-in-e-ink-bonnet.md) - [Embedded Linux Board Comparison](https://learn.adafruit.com/embedded-linux-board-comparison.md) - [CircuitPython BLE Libraries on Any Computer](https://learn.adafruit.com/circuitpython-ble-libraries-on-any-computer.md) - [Local LLMs on Raspberry Pi](https://learn.adafruit.com/local-llms-on-raspberry-pi.md) - [Build a Bluetooth App using Swift 5](https://learn.adafruit.com/build-a-bluetooth-app-using-swift-5.md) - [eInk Slow Movie Player](https://learn.adafruit.com/eink-slow-movie-player.md)