Skip to main content
Python Software Foundation 20th Year Anniversary Fundraiser  Donate today!

API for controlling nRF52 connectivity devices through pc-ble-driver-py

Project description

Blatann

blåtann: Norwegian word for "blue tooth"

The goal of this library is to provide a high-level, object-oriented interface for performing bluetooth operations using the Nordic nRF52 through Nordic's pc-ble-driver-py library and the associated Connectivity firmware.

Documentation is available on ReadTheDocs

Install

pip install blatann

Supported Devices/Software

This library has been tested using both the nRF52 Dev Kits, the nRF52840 USB Dongle and the ABSniffer 528 flashed with Connectivity Firmware

Supported Versions:

Blatann Version Python Version SoftDevice Version pc-ble-driver-py Version Supported Devices
v0.2.x 2.7 Only v3 <=0.11.4 nRF52832 Dev Kit
ABSniffer BLE Dongle
nRF52840 Dev Kit/Dongle (using S132 connectivity image)*
v0.3+ 3.7+ v5 >=0.12.0 Same as above

* I have not personally tested the nRF52840 compatibility for v0.2.x, only heard second-hand accounts of it working. v0.3+ has been tested with the nRF52840 USB Dongle

When using the nRF52840, it should be flashed using the S132/SoftDevice v5 connectivity images. Both hex files and DFU packages are distributed by default with v4.1.1 of pc-ble-driver and is also bundled with pc-ble-driver-py install, allowing the Dev Kit and USB Dongle to be flashed. The devices can be updated using nRF Connect Desktop App

Roadmap

NOTE

As of v0.3.0, the public-facing API is stable. There is not likely to be any major changes in method/property naming or functionality and all features added will aim to maintain backwards compatibility.

  • <input type="checkbox" disabled="" /> Documentation (majority covered, still needs some updates)
    • <input type="checkbox" disabled="" /> ReadTheDocs integration
      • <input type="checkbox" disabled="" /> Better type hinting
  • <input type="checkbox" disabled="" /> GAP
    • <input type="checkbox" disabled="" /> BLE Enable parameters
      • <input type="checkbox" disabled="" /> BLE Connection parameters (functional, needs some work)
      • <input type="checkbox" disabled="" /> Advertising
      • <input type="checkbox" disabled="" /> Data Length Extensions
      • <input type="checkbox" disabled="" /> Scanning
      • <input type="checkbox" disabled="" /> Documentation
  • <input type="checkbox" disabled="" /> SMP
    • <input type="checkbox" disabled="" /> Encryption/Authentication process
      • <input type="checkbox" disabled="" /> MITM/Passcode pairing support
      • <input type="checkbox" disabled="" /> Store bonding info
        • Currently uses pickle which is not secure
      • <input type="checkbox" disabled="" /> Identity resolve
      • <input type="checkbox" disabled="" /> Bonding as Peripheral
      • <input type="checkbox" disabled="" /> Bonding as Central
      • <input type="checkbox" disabled="" /> LESC pairing
      • <input type="checkbox" disabled="" /> Documentation
  • <input type="checkbox" disabled="" /> GATT
    • <input type="checkbox" disabled="" /> Configurable MTU
      • <input type="checkbox" disabled="" /> Generic Access service configuration
      • <input type="checkbox" disabled="" /> Service Changed characteristic
  • <input type="checkbox" disabled="" /> GATT Server
    • <input type="checkbox" disabled="" /> Characteristic Reads
      • <input type="checkbox" disabled="" /> Characteristic Writes
      • <input type="checkbox" disabled="" /> Notifications/Indications
      • <input type="checkbox" disabled="" /> Long reads/writes
      • <input type="checkbox" disabled="" /> Characteristic User Description/Presentation format
      • <input type="checkbox" disabled="" /> CCCD Caching
      • <input type="checkbox" disabled="" /> Custom Read/Write authorization (#10)
      • <input type="checkbox" disabled="" /> Documentation
  • <input type="checkbox" disabled="" /> GATT Client
    • <input type="checkbox" disabled="" /> Database Discovery procedure
      • <input type="checkbox" disabled="" /> Client reads
      • <input type="checkbox" disabled="" /> Client writes
      • <input type="checkbox" disabled="" /> Client long writes
      • <input type="checkbox" disabled="" /> Notifications/Indications
      • <input type="checkbox" disabled="" /> CCCD Caching
      • <input type="checkbox" disabled="" /> Service Discovery Caching
      • <input type="checkbox" disabled="" /> Documentation
  • <input type="checkbox" disabled="" /> Examples
    • <input type="checkbox" disabled="" /> Advertiser/Broadcaster
      • <input type="checkbox" disabled="" /> Scanner/Observer
      • <input type="checkbox" disabled="" /> Central, Procedural
      • <input type="checkbox" disabled="" /> Central, Event Driven
      • <input type="checkbox" disabled="" /> Central, Multiple Connections
      • <input type="checkbox" disabled="" /> Peripheral
      • <input type="checkbox" disabled="" /> Multi-role
      • <input type="checkbox" disabled="" /> Passcode Pairing
      • <input type="checkbox" disabled="" /> LESC Numeric Comparison Pairing (glucose peripheral, no central example)
      • <input type="checkbox" disabled="" /> Bonding (glucose peripheral, no central example)
  • <input type="checkbox" disabled="" /> Bluetooth Services
    • <input type="checkbox" disabled="" /> Device Info Service
      • <input type="checkbox" disabled="" /> Battery Service
      • <input type="checkbox" disabled="" /> Current Time Service
        • <input type="checkbox" disabled="" /> Peripheral
        • <input type="checkbox" disabled="" /> Central (Partially implemented)
      • <input type="checkbox" disabled="" /> Glucose Service
        • <input type="checkbox" disabled="" /> Peripheral
        • <input type="checkbox" disabled="" /> Central
      • <input type="checkbox" disabled="" /> Nordic UART Service
      • More TBD (or on request)
  • <input type="checkbox" disabled="" /> License
  • <input type="checkbox" disabled="" /> Unit Tests
  • <input type="checkbox" disabled="" /> Integration Tests
    • In progress. Advertising and Scanning mostly done

The library aims to support both event-driven and procedural program styles. It takes similar paradigms from C#/.NET's event function signatures, where event handlers are passed object sender, EventArgs e parameters. Additionally, all asynchronous function calls return a Waitable object which can be waited on (with timeout) until the event associated with the function call returns.

Examples

There are several example scripts which showcase different functionality of the library under blatann/examples. Examples can be run using python -m blatann.examples [example_filename] [device_comport].

Example usage: python -m blatann.examples scanner COM3

Running Tests

The integrated tests can be ran using the builtin unittest runner and depends on a few environment variables to find the connected Nordic devices.

At a minimum, two nordic devices are required to run the unit tests. These are specified using environment variables:

  • BLATANN_DEV_1 - Serial port of the first Nordic device
  • BLATANN_DEV_2 - Serial port of the second Nordic device

Optionally a third BLATANN_DEV_3 can be specified to run tests which require more than two devices. If this environment variable is not defined, tests which require 3 devices are skipped.

In order to speed up the tests, BLATANN_TEST_QUICK=1 can be defined to skip long-running tests. Note that test cases which are defined as "long-running" is subjective and relative--the test suite will still take awhile to run, but in general test cases which take longer than 20 seconds are skipped.

The tests can also be ran through the makefile using make run-tests.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for blatann, version 0.3.6
Filename, size File type Python version Upload date Hashes
Filename, size blatann-0.3.6-py3-none-any.whl (186.6 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size blatann-0.3.6.tar.gz (141.3 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page