Package: blatann
Blatannblå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'spc-ble-driver-pylibrary
and the associated Connectivity firmware.Documentation is available onReadTheDocsNOTEAs 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.Installpip install blatannUsing with macOS brew pythonpc-ble-driver-pyconsists of a shared object which is linked to mac's system python.
In order to use it with brew's python install, you'll need to runinstall_name_toolto modify the.soto
point to brew python instead of system python.Note: This is the case with any custom-installed python on mac (like anaconda), brew is the most popular and what has been testedAn example shell script to do so can be foundhereSupported Devices/SoftwareThis library has been tested using both the nRF52 Dev Kits, the nRF52840 USB Dongle and theABSniffer 528flashed with Connectivity FirmwareSupported Versions:Blatann VersionPython VersionSoftDevice Versionpc-ble-driver-py VersionSupported Devicesv0.2.x2.7 Onlyv3<=0.11.4nRF52832 Dev KitABSniffer BLE DonglenRF52840 Dev Kit/Dongle (using S132 connectivity image)*v0.3+3.7+v5>=0.12.0Same 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 DongleWhen 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 ofpc-ble-driverand is also bundled withpc-ble-driver-pyinstall,
allowing the Dev Kit and USB Dongle to be flashed. The devices can be updated usingnRF Connect Desktop AppRoadmap/Supported BLE FeaturesBelow lists the supported BLE features and ones that are on the roadmap to implement (eventually)Documentation (majority covered, still needs some updates)ReadTheDocs integrationBetter type hintingGAPBLE Enable parametersBLE Connection parameters (functional, needs some work)AdvertisingData Length ExtensionsPHY selectionCoded PHY not supported, only 1 and 2 Mbps PHYsScanningDocumentationRSSITransmit PowerAdvertising channel selectionSMPPrivate resolvable/non-resolvable advertisingEncryption/Authentication processMITM/Passcode pairing supportStore bonding infoIdentity resolveBonding as PeripheralBonding as CentralLESC pairingDocumentationGATTConfigurable MTUGeneric Access service configurationService Changed characteristicGATT ServerCharacteristic ReadsCharacteristic WritesNotifications/IndicationsLong reads/writesCharacteristic User Description/Presentation formatCCCD CachingCustom Read/Write authorization (#10)DocumentationGATT ClientDatabase Discovery procedureClient readsClient writesClient long writesNotifications/IndicationsCCCD CachingService Discovery Caching (#89)DocumentationExamplesAdvertiser/BroadcasterScanner/ObserverCentral, ProceduralCentral, Event DrivenCentral, Multiple Connections (#77)PeripheralMulti-rolePasscode PairingLESC Numeric Comparison Pairing (glucose peripheral, no central example)Bonding (glucose peripheral, no central example)Bluetooth ServicesDevice Info ServiceBattery ServiceCurrent Time ServicePeripheralCentral (Partially implemented)Glucose ServicePeripheralCentralNordic UART ServiceMore TBD (or on request)LicenseUnit TestsIntegration Tests (partial -- below are implemented)AdvertisingScanningGATT Writes/ReadsGATT throughput testing/benchmarksPairing/BondingThe 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 passedobject sender, EventArgs eparameters.
Additionally, all asynchronous function calls return aWaitableobject which can be waited on (with timeout)
until the event associated with the function call returns.ExamplesThere are several example scripts which showcase different functionality of the library underblatann/examples.
Examples can be run usingpython -m blatann.examples [example_filename] [device_comport].Example usage:python -m blatann.examples scanner COM3Running TestsThe integrated tests can be ran using the builtinunittestrunner 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 deviceBLATANN_DEV_2- Serial port of the second Nordic deviceOptionally a thirdBLATANN_DEV_3can 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=1can 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 usingmake run-tests.