BlueZ is the name for the entire Bluetooth software stack on Linux. When you plug a Bluetooth dongle into your Linux PC, BlueZ is the software layer that talks to the hardware via the USB driver, implements all the Bluetooth protocols (HCI, L2CAP, RFCOMM, SDP, AVDTP, etc.), and exposes APIs so that user-space programs (like your music player or file manager) can use Bluetooth without knowing anything about the low-level radio protocol.

The key insight is that BlueZ is split across two layers: kernel space (the actual protocol stack implemented as kernel modules) and user space (the daemon bluetoothd and utilities like hcitool). The kernel part handles the time-sensitive radio protocol; the user-space part handles policy decisions and exposes APIs to applications via D-Bus.

Before you start experimenting with BlueZ, you need to gather a few items:

Installing BlueZ tools on Ubuntu/Debian:

sudo apt-get update
sudo apt-get install bluetooth bluez bluez-tools
# Also install development libraries if you want to write C programs
sudo apt-get install libbluetooth-dev
# Verify bluetoothd daemon is running
sudo systemctl status bluetooth

hciconfig is the first command you will use. It does for Bluetooth what ifconfig (or ip) does for network interfaces — it shows the status of your Bluetooth adapter and lets you bring it up or down.

The most informative form of the command is:

sudo hciconfig -a

Running this on a machine with a USB Bluetooth dongle produces output like this:

hci0: Type: BR/EDR Bus: USB
BD Address: 00:1B:DC:05:B5:B3  ACL MTU: 310:10  SCO MTU: 64:8
UP RUNNING PSCAN
RX bytes:1127 acl:0 sco:0 events:39 errors:0
TX bytes:655  acl:0 sco:0 commands:38 errors:0
Features: 0xff 0xff 0x8f 0x7e 0xd8 0x1f 0x5b 0x87
Packet type: DM1 DM3 DM5 DH1 DH3 DH5 HV1 HV2 HV3
Link policy: RSWITCH HOLD SNIFF PARK
Link mode: SLAVE ACCEPT
Name: 'ubuntu-1'
Class: 0x6e0100
Service Classes: Networking, Rendering, Capturing, Audio, Telephony
Device Class: Computer, Uncategorized
HCI Version: 4.0 (0x6)  Revision: 0x1d86
LMP Version: 4.0 (0x6)  Subversion: 0x1d86
Manufacturer: Cambridge Silicon Radio (10)

Just like a network interface can be brought up or down, you can enable or disable your Bluetooth adapter with two commands. These require root privileges (either run as root or prefix with sudo).

To turn OFF (disable) the Bluetooth adapter:

sudo hciconfig hci0 down

To turn ON (enable) and initialise the Bluetooth adapter:

sudo hciconfig hci0 up

After running hci0 up, the adapter reinitialises — it resets the controller hardware, downloads firmware if needed, and puts the adapter in a ready state. You can verify it worked by running hciconfig again and checking for the UP RUNNING flags.

Why would you turn it off? Sometimes BlueZ or a Bluetooth controller gets into a bad state after a crash or a failed connection. Doing a down followed by up is the Bluetooth equivalent of restarting a network interface — it clears any stuck state and re-initialises the hardware cleanly.

Once your adapter is up and running, you want to find other Bluetooth devices nearby. The hcitool command is your Swiss Army knife for this. There are two ways to scan:

hcitool inq

hcitool scan

Example output from both commands:

# hcitool inq — raw inquiry, no names
$ hcitool inq
Inquiring ...
  68:ED:43:25:0E:99   clock offset: 0x298e   class: 0x7a020c
  00:17:83:DC:72:E9   clock offset: 0x7596   class: 0x1a0114

# hcitool scan — inquiry + name lookup
$ hcitool scan
Scanning ...
  00:17:83:DC:72:E9   WM_nareshg
  68:ED:43:25:0E:99   BlackBerry 8520

Getting detailed info about a specific device:

# Get the remote device's clock (tests that you can reach it)
hcitool info 00:17:83:DC:72:E9

# Check RSSI (signal strength) — negative dBm, closer to 0 is stronger
hcitool rssi 00:17:83:DC:72:E9

# Get the link quality (0–255, higher is better)
hcitool lq 00:17:83:DC:72:E9

After discovering a device’s address with hcitool, the next step is usually to ask that device “what Bluetooth services do you support?” This is done through the SDP — Service Discovery Protocol.

Every Bluetooth device that offers services (like a headset offering the Hands-Free profile, or a phone offering audio streaming) registers those services with its own local SDP server. When another device connects and asks “what can you do?”, the SDP server responds with a list of service records.

The command to query a remote device’s SDP server is:

sdptool browse [BD_ADDR]

# Example: browse services on a BlackBerry phone
sdptool browse 68:ED:43:25:0E:99

# Browse ALL services recursively
sdptool browse --tree 68:ED:43:25:0E:99

Example partial output from sdptool browse:

Browsing 68:ED:43:25:0E:99 ...
Service Name: Headset
Service RecHandle: 0x10000
Service Class ID List:
  "Headset" (0x1108)
  "Generic Audio" (0x1203)
Protocol Descriptor List:
  "L2CAP" (0x0100)
  "RFCOMM" (0x0003)
    Channel: 1

Service Name: Handsfree
Service RecHandle: 0x10001
Service Class ID List:
  "Handsfree" (0x111e)
  "Generic Audio" (0x1203)
Protocol Descriptor List:
  "L2CAP" (0x0100)
  "RFCOMM" (0x0003)
    Channel: 2

Service Name: Audio Source
Service RecHandle: 0x10002
Service Class ID List:
  "Audio Source" (0x110a)
Protocol Descriptor List:
  "L2CAP" (0x0100)
  "AVDTP" (0x0019)
    Version: 0x0102

The SDP browse always happens on L2CAP channel with PSM (Protocol Service Multiplexer) value 1 — this is the reserved PSM for SDP across all Bluetooth devices. You do not need to know the service’s channel number in advance; SDP discovery tells you which RFCOMM channel or AVDTP PSID to connect on.

Searching for a specific profile instead of browsing all services:

# Search only for A2DP Source service
sdptool search --bdaddr 68:ED:43:25:0E:99 AUDIO_SOURCE

# Search for Hands-Free Profile
sdptool search --bdaddr 68:ED:43:25:0E:99 Handsfree

# List services on your own local machine
sdptool browse local

Here is the typical sequence a developer follows when exploring an unknown Bluetooth device for the first time. These are the exact steps you would run in a terminal:

The command-line tools are great for manual exploration, but when you are writing a Bluetooth application in C, you interact with BlueZ through the HCI socket API directly. Here is a minimal C example that performs device inquiry (the equivalent of hcitool scan) programmatically:

#include <stdio.h>
#include <bluetooth/bluetooth.h>
#include <bluetooth/hci.h>
#include <bluetooth/hci_lib.h>

int main(void)
{
    int dev_id, sock;
    inquiry_info *devices = NULL;
    int max_rsp = 255;
    int num_rsp;
    int i;
    char addr[19] = { 0 };
    char name[248] = { 0 };

    /* Get the first available HCI device (hci0) */
    dev_id = hci_get_route(NULL);

    /* Open an HCI socket on that device */
    sock = hci_open_dev(dev_id);
    if (dev_id < 0 || sock < 0) {
        perror("Failed to open HCI device");
        return 1;
    }

    /* Allocate memory for inquiry results */
    devices = (inquiry_info*) malloc(max_rsp * sizeof(inquiry_info));

    /*
     * hci_inquiry: perform a Bluetooth inquiry
     * 8 = inquiry length in units of 1.28s → total ~10 seconds
     * IREQ_CACHE_FLUSH = flush the cache before starting
     */
    num_rsp = hci_inquiry(dev_id, 8, max_rsp, NULL, &devices, IREQ_CACHE_FLUSH);

    printf("Found %d devices:\n", num_rsp);

    for (i = 0; i < num_rsp; i++) {
        /* Convert binary BD_ADDR to human-readable string */
        ba2str(&(devices+i)->bdaddr, addr);
        memset(name, 0, sizeof(name));

        /* Read the remote device's Bluetooth name */
        if (hci_read_remote_name(sock, &(devices+i)->bdaddr,
                                  sizeof(name), name, 0) < 0) {
            strcpy(name, "[unknown]");
        }
        printf("  %s  %s\n", addr, name);
    }

    free(devices);
    close(sock);
    return 0;
}

Compile and run:

# -lbluetooth links against the BlueZ client library
gcc bt_scan.c -o bt_scan -lbluetooth

# Run with sudo (HCI raw sockets need root)
sudo ./bt_scan

What this code does step by step:

1. hci_get_route(NULL) — finds the default HCI device (hci0)
2. hci_open_dev(dev_id) — opens a raw HCI socket to that adapter
3. hci_inquiry() — sends Inquiry radio packets for ~10 seconds and collects BD_ADDRs
4. hci_read_remote_name() — for each found device, connects briefly and requests its name
5. ba2str() — converts the 6-byte binary address into a human-readable colon-separated string