Python bindings for the nRF5 Bluetooth Low Energy GAP/GATT driver

Introduction

pc-ble-driver-py is a serialization library over serial port that provides Python bindings for the nrf-ble-driver library.

The Python bindings require that the development kit you use is programmed with the correct connectivity firmware. Hardware setup

License

See the license file for details.

Installing from PyPI

To install the latest published version from the Python Package Index simply type:

pip install pc-ble-driver-py

Note: On Windows, the runtime libraries targeted when building the library must be present when running code using the library. If you get one of the following errors:

• Missing MSVC*120.DLL or MSVC*140.DLL
• RuntimeError: Could not load shared library <path>/pc_ble_driver_shared.dll : '[Error 193] %1 is not a valid Win32 application'.

please install the redistributable installer for Visual Studio 2013 or Visual Studio 2015 respectively. Make sure to install the one corresponding to the architecture of your Python installation (x86 or x64).

Building from source

Before building pc-ble-driver-py you will need to install nrf-ble-driver as a CMake module. The easiest way to do this is to install it with vcpkg.

vcpkg install nrf-ble-driver

To use a different triplet than the default one, see documentation in vcpkg:

vcpkg help triplet
vcpkg help install

Triplet must match the version of python you are building the binding for.

Running vcpkg install starts compilation and installation of nrf-ble-driver.

Before compiling the binding do the following:

• Make sure that the VCPKG_ROOT environment variable is set to the location of the vcpkg directory

• install the python install requirements:

    pip install -r requirements-dev.txt
  

Building a release of the binding and automatically running tests afterwards can be initiated with tox. tox is a generic virtualenv management and test command line tool.

Two development kits must be attached to the computer and the UART ports for them must be specified through envionment variables (PORT_A, PORT_B).

> export PORT_A=/dev/ttyACM0
> export PORT_B=/dev/ttyACM1
> tox

The config tox.ini contains the Python interpreter versions currently supported. Python wheels will be created for every supported version it finds on the system. To run tox, type:

tox -e <python environment> # For example py37, if you have that installed

See tox.ini for more configuration of the build and running of tests.

To build a release build of the binding run the following command:

> python setup.py bdist_wheel --build-type Release

To build a debug build of the binding:

> python setup.py bdist_wheel --build-type Debug

The wheel packages are found in the dist directory

Dependencies

To build this project you will need the following tools:

• SWIG (>= 4.0)
• Python (==2.7 && >=3.7)
• vcpkg
• A C/C++ toolchain (should already have been installed to build nrf-ble-driver)

See the following sections for platform-specific instructions on the installation of the dependencies.

Windows

• Install the latest CMake stable release by downloading the Windows Installer from CMake site

• Install the latest SWIG stable release by downloading the swigwin-x.y.z package from SWIG site

Then extract it into a folder of your choice. Append the SWIG folder to your PATH, for example if you have installed SWIG in c:\swig\swigwin-x.y.z:

PATH=%PATH%;c:\swig\swigwin-x.y.z;

• Install Python 2.7.x or 3.7.3 or newer by downloading the installer from Python Windows Downloads

Note: Select the Python architecture (32 or 64-bit) that you plan to build for.

Install Microsoft Visual Studio matching the Python version. For an overview of recommended versions of Visual Studio to use, see this table.

The distributable files will be placed in dist.

Ubuntu Linux

Install the required packages to build the bindings:

$ sudo apt-get install cmake swig libudev-dev python python-dev

macOS (OS X) 10.11 and later

Install cmake and swig with Homebrew with the brew command on a terminal:

$ brew install cmake
$ brew install swig