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.
Adapters
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:
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:
- Bluetooth subsystem support, CONFIG_BT
- SCO links support, CONFIG_BT_SCO
- RFCOMM protocol support, CONFIG_BT_RFCOMM
On top of these options, most configurations will also require:
- HCI USB driver, CONFIG_BT_HCIUSB
- SCO (voice) support, CONFIG_BT_HCIUSB_SCO
Pairing
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:
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.
Hardware
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:
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.
Some suggestions for resolution:
- Try configuring the packet interval to 20ms or less, and configuring the output buffer size to a much larger value, e.g. 100ms or more.
- With ALSA drivers, the dmix plugin is configured by
default, and can arbitrarily constrain the buffering
parameters. The packet size and total buffer size used by the
dmix plugin can be customized by editing
/etc/asound.conf. If you suspect the dmix plugin is causing problems, you can try configuring the raw device by specifying plughw:0 in the device/options field. Beware, however, that this will make it impossible for HFP for Linux to share your sound card with any other applications, and likewise HFP for Linux will be unable to open your sound card if any other applications have it open.
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.
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.
Latency
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:
- Check the reported "Real Packet Size" value. It should
be less than 25ms.
- To try to reduce this value, configure the Packet Interval slider on the configuration page to the smallest possible value, perhaps 5ms, and restart Feedback Test mode. The Real Packet Size value should change. If it does not, your sound driver may need low level configuration tweaks.
- With ALSA drivers, the dmix plugin is configured by
default, and will affect the lower bound of latency.
The packet size used by the dmix plugin defaults to 20ms,
but can be customized by editing
/etc/asound.conf. If you suspect the dmix plugin is causing problems, you can try configuring the raw device by specifying plughw:0 in the device/options field. Beware, however, that this will make it impossible for HFP for Linux to share your sound card with any other applications, and likewise HFP for Linux will be unable to open your sound card if any other applications have it open.
- Try setting the Output Buffer slider on the configuration
page to a value twice the Real Packet Size.
- After trying the above tweaks, if you still can't reduce the latency to a subjectively acceptable level, shoot me an email.
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:
- Noise
The noise reduction feature can remove some amount of white noise from the microphone input signal. It is enabled by default. - Volume Variations
When the ambient noise level changes, a talker will raise or lower his/her voice to compensate, and the volume level observed by the microphone will change. When a talker gets closer to or farther from a microphone, the observed volume level will also change. This variation is unpleasant to the remote party, and has a detrimental effect on call quality. The auto gain feature attempts to adapt the volume level to the current conditions. It is enabled by default. - Acoustic Echo
When speech from the remote party is played back through the local speakers, it can be re-captured through the microphone and transmitted back to the remote party as an echo. This has a detrimental effect on call quality. The acoustic echo canceler attempts to remove echo from the microphone input signal. It is enabled by default.
Signal processing settings can be configured by hfconsole's configuration dialog, in the Signal Processing tab.
To evaluate signal processing settings without starting a call, hfconsole includes a three-step guided signal processing test.