HFP for Linux is a keystone application. Many other subsystems must function correctly in order for HFP for Linux to be usable. As such, it can be difficult to configure. This page is intended as a guide to configuring HFP for Linux.


The base BlueZ software components must be installed in order for HFP for Linux to function. Most Linux distributions, such as Ubuntu, will install these components by default, and is not often a concern. Packages include the bluez-utils package and the bluetooth kernel modules.


A Bluetooth dongle or integrated Bluetooth module must be installed in order for HFP for Linux to communicate with mobile phones. HFP for Linux components can be started with or without available Bluetooth hardware. Bluetooth dongles may be inserted or removed while HFP for Linux components are running, and such changes of available Bluetooth hardware will be noticed by HFP for Linux.

When no Bluetooth adapters are detected, the condition will be reported in the hfconsole status bar:

hfconsole Status Bar -- No Bluetooth

Failures to detect Bluetooth hardware can be confirmed with the hcitool command:

hcitool dev

This should display a list of your Bluetooth dongles. If the list is unexpectedly empty, your low-level Bluetooth drivers are likely misconfigured. Consult the documentation for your Linux distribution for information about troubleshooting specific Bluetooth problems. For example, Gentoo has created their Linux Bluetooth Guide for using Bluetooth on Gentoo Linux systems.

Kernel Configuration

HFP for Linux may also have trouble using your Bluetooth hardware if your kernel is not built with appropriate support. Kernels packaged with most major Linux distrubutions, e.g. Ubuntu, Fedora, will not have this type of problem. With techie distributions, e.g. Gentoo, Arch, one frequently builds a custom kernel, and in this situation, it is very easy to accidentally disable or omit one of the required options. For reference, these include:

On top of these options, most configurations will also require:


The base BlueZ software components are also responsible for handling PIN authentication. If you request your mobile phone to pair with your Linux system, you should receive some prompts similar to below:

Bluetooth pairing request notice Bluetooth PIN entry prompt

If you request pairing, and your mobile phone reports failure, but no PIN request dialog is presented, your base BlueZ software components may be misconfigured. It is the responsibility of your Linux distribution to configure this correctly. End user oriented distributions such as Ubuntu rarely have problems with this.


Audio configuration is the most complex and delicate part of HFP for Linux. Having merely functional audio can be difficult enough. Beyond functionality, there are several factors that can affect call quality. HFP for Linux comes with intelligent defaults, but may require manual tweaking.


Any full-duplex sound card supported by ALSA should be sufficient for HFP for Linux. Most integrated motherboard audio devices produced within the last ten years should be sufficient. USB headsets with built-in microphones should be sufficient. Problems detecting and configring sound cards on Linux, at least for audio output, are beyond the scope of this guide. If your system is unable to play music files, resolve that problem before attempting to set up HFP for Linux.

While it is possible to use two separate sound cards with HFP for Linux, where one is used for microphone input and the other for speaker output, this is not recommended. The two sound cards will not have synchronized clocks, and the effectiveness of the echo canceler will be reduced.

Volume Levels

Configuring acceptable volume levels, both for speakers and microphone, is absolutely critical. Currently, HFP for Linux does not support internal control of mixers and volume levels. Your Linux distribution must provide a mixer control.

Feedback Mode

To verify that the audio input and output paths are functional, hfconsole provides a software feedback test feature. As the name suggests, software feedback mode transfers audio data from your microphone input, through the HFP for Linux audio components, and back out to your speakers. If it functions correctly, it confirms the functionality of a large number of dependent components. To enable software feedback mode, open the hfconsole configuration dialog, select the Audio Device tab, and click the Feedback Test toggle:

Configuration -- Feedback Test

When enabled, you should be able to speak loudly into your microphone and hear your voice through your speakers. If you hear nothing from your speakers, or hear excessively loud feedback tones, open your system mixer configuration and adjust volume levels until output volume levels are acceptable.

Buffer Overruns/Underruns

Software feedback mode can help to diagnose buffer overrun/underrun tendencies that would occur duing a call. Buffer overrun/underrun events will be indicated by a warning message underneath the "Feedback Test" button in the configuration dialog box. A healthy audio setup should experience buffer overruns/underruns very infrequently if ever.

Buffer overrun warning during feedback mode

Some suggestions for resolution:

Capture/Playback Clock Skew

Software feedback mode can help to diagnose clock skew between the capture and playback halves of your primary sound card. Clock skew events will be indicated by a warning message beneath the "Feedback Test" button in the configuration dialog box, including an estimate of the severity of the skew. Clock skew causes samples to be dropped or silence-padded, and negates adaptations made by the acoustic echo canceler. It is a highly undesirable attribute of an audio setup.

Clock skew warning during feedback mode

If your sound card driver configuration explicitly specifies different hardware devices for capture and playback, you should consider using a single hardware device for both capture and playback. If you are already using a single hardware device, it is likely that your device uses separate clocks for capture and playback. If you have such a device, consider replacing it with one that uses the same sample clock for both capture and playback.


Software feedback mode also allows subjective evaluation of latency. Audio data is buffered as it is captured from the microphone and buffered again before it is played back through the speakers. In software feedback mode, this manifests as a delay between making a sound to your microphone and hearing it play through your speakers. The same latency observed in software feedback mode will be present on all phone calls serviced by HFP for Linux. For best call quality, the audible latency should be as short as possible, on the order of 1/10th of a second. It should not be too short either, as this will over-use CPU resources.

If you observe excessive latency, try the following:

Digital Signal Processing

HFP for Linux employs the libspeexdsp software digital signal processing library from the Speex Project to try to solve problems common to voice telephony applications. These include:

Signal processing settings can be configured by hfconsole's configuration dialog, in the Signal Processing tab.

Configuration -- Signal Processing

To evaluate signal processing settings without starting a call, hfconsole includes a three-step guided signal processing test.