Using Blatann on macOS Catalina

Edit 22/03/21: These instructions work equally well for macOS Big Sur. Blatann’s author has now added instructions for remapping pc-ble-driver to use Homebrew Python should you wish to use that instead.

The Blatann Python library is a great tool for integrating Nordic’s pc-ble-driver-py library and its underlying driver into Python applications. Using it is far more efficient than attempting to use Nordic’s library directly, particularly when building and manipulating GATT databases. I use Blatann as the basis for some BLE simulators and it must have saved me at least a week’s worth of development effort, so thank you, ThomasGerstenberg!

I wrote the simulators a while ago, before the deprecation of support for Python 2 at the start of 2020 and before either of the libraries supported Python 3. With the release of Blatann v0.3+, which supports Python 3, I have now updated the simulators. Given that I use a Mac for development, which can often cause a headache when trying to use Python, I thought it would be useful to share the steps I went through to get the new simulators up and running again using the latest version of Blatann.

First and foremost, you’ll need Python 3. This seemingly simple step is where I suspect most people will run into problems on a Mac, as it turns out that the pc-ble-driver-py library has a hard requirement for the primary distribution of Python. This is the one you can download from python.org. So, download and install the latest version (v3.9.1), which will be installed at /Library/Frameworks/Python.framework/Versions/3.9.

Now, create a virtual environment that uses this version of Python:

$ mkvirtualenv whodeenie -p /Library/Frameworks/Python.framework/Versions/3.9/bin/python3

And then install Blatann:

(whodeenie) $ pip install blatann

This will install the latest version of Blatann (v0.3.6) and pc-ble-driver-py (v0.15.0) as a dependency.

Now, run the example to test your setup:

(whodeenie) $ python -m blatann.examples scanner <COM>

Where <COM> is the COM port that your nRF5 Dev Kit (DK) is connected to, e.g., /dev/cu.usbmodem0006820573161.

If the installation was successful, the example will start the DK as a BLE scanner and you’ll see a list of the BLE devices advertising in your area. If this doesn’t work, and assuming your hardware setup is correct, the error you’ll see will most likely look something like this:

ImportError: dlopen(/Users/Whodeenie/venvs/whodeenie/lib/python3.9/site-packages/pc_ble_driver_py/lib/_nrf_ble_driver_sd_api_v5.so, 2): Library not loaded: /Library/Frameworks/Python.framework/Versions/3.9/Python
  Referenced from: /Users/Whodeenie/venvs/whodeenie/lib/python3.9/site-packages/pc_ble_driver_py/lib/_nrf_ble_driver_sd_api_v5.so
  Reason: image not found

This error means that you’re trying to use Blatann with the wrong distribution of Python and not the primary distribution installed via the official website. Because of this, pc-ble-driver-py, which is hardcoded to use the primary distribution at its default installation location, can’t find that Python image and so can’t use it to load the resources it needs.