The nRF51 Bluetooth Smart GATT/GAP Driver (from now on called the Driver) consists of a standard C dynamic library that lets a PC application set up and interact with an nRF51 SoftDevice through API function calls. The library mirrors the nRF51 S130 SoftDevice API and makes it available to the PC application.

Commands sent from the library are encoded and sent over UART to the nRF51 chip. The connectivity application running on the nRF51 chip decodes the commands and feeds them to the SoftDevice. Command responses and events are encoded and sent from the nRF51 chip to the PC library where they are decoded.

The library makes it possible to create applications on a PC that, in code, can be similar to applications that are running on the nRF51 chip.

Having this kind of API gives the following benefits:

• Setting up a peer device for a Device Under Test (DUT) using a test script.
• Coherent BLE APIs on a PC and an nRF51 chip.
• Creating prototype and test applications for an nRF51 chip on a PC.
• Migrating code between an nRF51 chip and a PC.

No guarantees are given regarding stability or backward compatibility. Interfaces are subject to change.

The following dependencies are required for building the Driver:

• Boost (=1.56.0)
• cmake (>=2.8.X)
• Python (>=2.7.6, <3.0.0)
• Swig (=2.0.12)
• git client

The source code is available from GitHub at the following URL: https://github.com/NordicSemiconductor/pc-ble-driver.git

• Download the [MinGW] (http://sourceforge.net/projects/mingw-w64/files/Toolchains%20targetting%20Win32/Personal%20Builds/mingw-builds/4.8.2/threads-posix/dwarf/) Compiler Suite.

• Install MinGW Compiler Suite according to the instructions.

• Verify that gnu patch utility is available in PATH. (e.g. c:\program files(x86)\git\bin)

• Install cmake according to the installation instructions for Windows.

• Install Microsoft Visual C++ Compiler for Python.

• Extract, compile and install Boost. We assume Boost is extracted into c:\Boost\boost_1_56_0. Issue the following commands in the directory:

  bootstrap

  b2 toolset=gcc link=static runtime-link=shared threading=multi

Run the following command to install compiler, dependencies and tools:

curl -L https://raw.githubusercontent.com/NordicSemiconductor/pc-ble-driver/master/scripts/setup-ubuntu-linux.sh | sh

You will be asked for root password during this process.

Run the following command to install compiler, dependencies and tools:

curl -L https://raw.githubusercontent.com/NordicSemiconductor/pc-ble-driver/master/scripts/setup-osx.sh | sh

You will be asked for root password during this process.

• Create a build directory outside the source directory.

• Create a directory to store Nordic Semiconductor software that the Driver depends on.

• Download the necessary Nordic Semiconductor dependencies and compile the Driver and Python binding with the command below.

  mkdir build

  mkdir deps

  cd build

  python ..\pc-ble-driver\scripts\build.py -srp \my_deps_directory -d -b (for Unix systems, replace \ with /)

• To package the release into a zip file, run the following command:

  python ..\pc-ble-driver\scripts\build.py -srp \my_deps_directory -p (for Unix systems, replace \ with /)

• If you later want to run the Behave tests you will need to compile all the examples, to do this run this command:

  python ..\pc-ble-driver\scripts\build.py -srp \my_deps_directory -e (for Unix systems, replace \ with /)

We have different types of tests:

• BDD tests
• Packaging tests
• Integration/unit tests (without hardware)
• Integration tests (with hardware)

Setup:

• Set the environment variable PYTHONUNBUFFERED to something or else Python will buffer stdout, which will make the BDD tests fail.

• Set the environment variable NORDICSEMI_NRF51_BLE_DRIVER_BUILD_PATH to the build directory of the Driver

• Set the environment variable NORDICSEMI_TARGET_SETUP to the file name of the test targets configuration. The test targets configuration contains information about nRF5X DK UART port and the drive letter it has been assigned to. Below is an example of a test_targets.json file:

  { "targets": [ { "id": 1, "drive": "E:\", "serial_port": "COM8", "pca": "PCA10028", "segger_sn": "680595231" }, { "id": 2, "drive": "D:\", "serial_port": "COM7", "pca": "PCA10028", "segger_sn": "681768567" } ] }

First, build and package the driver. Then, issue the following command to run the packaging tests:

cd <ROOT>\driver\tests
python setup.py test

There is a bug in Behave that prevents us from running the Behave tests from setup.py. A workaround is to run BDD tests from the bdd directory:

cd <ROOT>\driver\tests\bdd
behave

The BDD tests require nRF51 hardware connected to the computer. A combination of two devices of the following is required, two of one kind or one of each:

• nRF51 Development Kit (pca10028), or
• nRF51 Development Dongle (pca10031)

First, build the driver. Then, issue the following command to run the integration/unit tests:

python ..\pc-ble-driver\scripts\build.py -srp <ROOT>\my_deps_directory -t (for Unix systems, replace \ with /)

For the unit test uart_cpp_test, a set of loopback serial ports is required. You can achieve this by using:

• a pair of usb-to-serial adapters interconnected with a null-modem cable
• a pair of virtual serial ports (emulated serial ports) configured to be interconnected

uart_cpp_test also requires the environment variables TESTSERIALPORT1 and TESTSERIALPORT2 to be set to the serial port names:

Example values:
TESTSERIALPORT1=COM20
TESTSERIALPORT2=COM21

If you want to disable uart_cpp_test, comment out the test in the file driver/tests/CMakeLists.txt:

#add_test(NAME uart_cpp_test COMMAND "uart_cpp_test" ${test_params})

• Linux:
  • udev rules for tty symlink and usb mount points are found in folder tests/config/linux/. These rules must be put in /etc/udev/rules.d/
  • Remember to set the environment variable LD_LIBRARY_PATH to directories containing the libs*_nrf51_ble_driver.so so that the tests find the libs*_nrf51_ble_driver.so
• OSX:
  • We have not discovered yet how to force the mount point for JLink devices on MacOSX, because of which the tty/mount point location will come out of sync
  • Remember to set the environment variable DYLD_LIBRARY_PATH to directories containing the libs*_nrf51_ble_driver.dylib so that the tests find the libs*_nrf51_ble_driver.dylib