An easy-to-use Bluetooth Python 3 library, built on the asynchronous Tornado framework, for interacting with Bluez5 over the DBus API. It currently supports the A2DP (music streaming), HFP (hands-free phone) and PBAP (phonebook transfer) profiles.

Bluez5 documentation available in the Bluez5 source code repository.

Theoretically this library can run on any Linux distribution that can support the dependencies in the section below. This does mean that Windows is not supported due to the close integration with Bluez5.

This library depends on many system packages and Python modules. The sections below describe each set of dependencies in detail.

The table below lists the packages for an Ubuntu 18.04 (Bionic) system. The names will most likely differ for non-Ubuntu distributions. Documentation contributions are welcome!

Pytooth interfaces with a C-based SBC codec library called libsbc directly via Python ctypes. This allows for fast and reliable decoder code when using A2DP. The source code comes bundled with Pytooth and is built during installation.

This section details how to configure the various depedency systems and install the Pytooth library. There are a few installation use cases:

• Integration into a larger project
• Non-interactive (via the provided test apps)
• Development of the library

These instructions are generally distribution-agnostic, however configuration file locations may vary between distributions. The instructions are correct for Ubuntu and (most likely) Debian-based distros. The instructions assume a distro running systemd. For those that do not, the reader will need to substitute in the correct steps. Again, documentation contributions are welcome =)

Enable Bluez5 custom commands by appending --compat to the ExecStart section of the systemd unit file /usr/lib/systemd/system/bluetooth.service, like so:

ExecStart=/usr/libexec/bluetooth/bluetoothd --compat

Restart Bluetooth with systemctl restart bluetooth.service.

Allow Pytooth to send DBus messages and claim ownership of the ishkanan.pytooth namespace by changing:

<deny own="*"/>

to

<allow own="*"/>

and

<deny send_type="method_call"/>

to

<allow send_type="method_call"/>

in the DBus system config file /usr/share/dbus-1/system.conf. DBus should apply the changes immediately.

Decide which user will be running the application/test apps and add that user to the following groups:

• audio
• lp

Existing user sessions will need to be restarted for the membership changes to take effect.

It is recommended practice to run Python applications in Python Virtual Environments. The pros and cons for doing so are aplenty on the internet, and are beyond the scope of this documentation. The installer assumes it is running in a virtual environment. System-level installation of the library is currently untested.

The final step is to install the library itself. This will differ based on the installation use case. The installer is based on Python setuptools however it is not currently listed on PyPI so cannot be installed with pip. The file setup.py in the root folder is the installer entry point. The installer builds and installs all source gzips located in the packages/src folder (dbus-python and libsbc). Some of the commands require root privileges so the installer will prompt for elevation.

For integration into a larger project, ensure that the project's deployment processes invoke the setup.py script with the install command, for example:

#!bash
$ python setup.py install

Pytooth provides a bare-bones test script for each supported Bluetooth profile, located in the pytooth/tests folder. The A2DP script provides full playback functionality. The HFP script provides audio functionality but no remote control functions (e.g. answer, hang-up, etc). The PBAP script downloads the internal phonebook for example purposes, so it's not really suitable for this use case.

First, install the library with:

#!bash
$ python setup.py install

The installer creates a test command, pytooth-test, that is used to launch one or more test scripts simultaneously. It is executed like so:

#!bash
$ pytooth-test -c <config file>

where <config file> is a copy of (or the actual file) pytooth/tests/test_config.json.

To install the library for development purposes, clone the repository and invoke the setup.py script with the develop command, like so:

#!bash
$ python setup.py develop

The test scripts can be run as described in the section above.

The lead developer, Anthony Ishkan (anthony.ishkan@gmail.com). He only bites if he's hungover or hungry =)