| Name | blatann JSON |
| Version |
0.6.0
JSON |
| download |
| home_page | None |
| Summary | Python BLE library for using Nordic nRF52 with Connectivity firmware |
| upload_time | 2024-09-18 05:41:22 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.7 |
| license | BSD 3-Clause |
| keywords |
ble
bluetooth
nrf52
nordic
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Blatann
blåtann: Norwegian word for "blue tooth"
Blatann aims to provide a high-level, object-oriented interface for interacting
with Bluetooth Low Energy (BLE) devices through Python. It operates using
the Nordic Semiconductor nRF52 through Nordic's ``pc-ble-driver-py`` library
and the associated Connectivity firmware for the device.
Documentation is available on [ReadTheDocs](https://blatann.readthedocs.io)
### Install
`pip install blatann`
#### Using with macOS brew python
`pc-ble-driver-py` consists 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 run `install_name_tool` to modify the `.so` to
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 tested_
An example shell script to do so can be found [here](./tools/macos_retarget_pc_ble_driver_py.sh)
#### Supported Devices/Software
This library has been tested with the following hardware:
- the [nRF52-DK](https://www.nordicsemi.com/Products/Development-hardware/nrf52-dk): a Dev Kit for the nRF52832 (PCA10040)
- the [nRF52840-DK](https://www.nordicsemi.com/Products/Development-hardware/nRF52840-DK): a Dev Kit for the nRF52840 (PCA10056)
- the [nRF52840-Dongle](https://www.nordicsemi.com/Products/Development-hardware/nrf52840-dongle): a nRF52840 USB Dongle (PCA10059)
- the [ABSniffer-528](https://wiki.aprbrother.com/en/ABSniffer_USB_Dongle_528.html): a nRF52832 USB Dongle
Flashed with specific Connectivity firmware released by Nordic Semiconductor.
When using the nRF52840, it should be flashed using the S132/SoftDevice v5 connectivity images. Both the hex files and DFU packages are distributed
with v4.1.4 of [pc-ble-driver](https://github.com/NordicSemiconductor/pc-ble-driver/releases/tag/v4.1.4) and is also provided in the `pc-ble-driver-py` install.
The Nordic devices can be flashed using [nRF Connect Desktop App](https://www.nordicsemi.com/Software-and-Tools/Development-Tools/nRF-Connect-for-desktop) or the `nrfutil` CLI tool.
### Roadmap/Supported BLE Features
As of v0.3.0, the public-facing API of Blatann is stable. There will not
likely be any major changes in method/property naming or functionality
and all features added will aim to maintain backwards compatibility.
Below lists the supported BLE features and ones that are on the roadmap to implement (eventually)
- [X] GAP
- [X] BLE Enable parameters
- [X] BLE Connection parameters (functional, needs some work)
- [X] Advertising
- [X] Data Length Extensions
- [X] PHY selection
- Coded PHY not supported, only 1 and 2 Mbps PHYs
- [X] Scanning
- [X] Documentation
- [X] RSSI
- [X] Transmit Power
- [X] Advertising channel selection
- [X] SMP
- [X] Private resolvable/non-resolvable advertising
- [X] Encryption/Authentication process
- [X] MITM/Passcode pairing support
- [X] Store bonding info
- [X] Identity resolve
- [X] Bonding as Peripheral
- [X] Bonding as Central
- [X] LESC pairing
- [X] Documentation
- [ ] GATT
- [X] Configurable MTU
- [X] Generic Access service configuration
- [ ] Service Changed characteristic
- [ ] GATT Server
- [X] Characteristic Reads
- [X] Characteristic Writes
- [X] Notifications/Indications
- [X] Long reads/writes
- [X] Characteristic User Description/Presentation format
- [ ] CCCD Caching
- [ ] Custom Read/Write authorization (#10)
- [X] Documentation
- [ ] GATT Client
- [X] Database Discovery procedure
- [X] Client reads
- [X] Client writes
- [X] Client long writes
- [X] Notifications/Indications
- [ ] CCCD Caching
- [ ] Service Discovery Caching (#89)
- [X] Documentation
- [ ] Examples
- [X] Advertiser/Broadcaster
- [X] Scanner/Observer
- [X] Central, Procedural
- [X] Central, Event Driven
- [ ] Central, Multiple Connections (#77)
- [X] Peripheral
- [ ] Multi-role
- [X] Passcode Pairing
- [X] LESC Numeric Comparison Pairing (glucose peripheral, no central example)
- [X] Bonding (glucose peripheral, no central example)
- [ ] Bluetooth Services
- [X] Device Info Service
- [X] Battery Service
- [ ] Current Time Service
- [X] Peripheral
- [ ] Central (Partially implemented)
- [ ] Glucose Service
- [X] Peripheral
- [ ] Central
- [X] Nordic UART Service
- More TBD (or on request)
- [X] License
- [ ] Unit Tests
- [X] Integration Tests (partial -- below are implemented)
- Advertising
- Scanning
- GATT Writes/Reads
- GATT throughput testing/benchmarks
- Pairing/Bonding
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`.
Raw data
{
"_id": null,
"home_page": null,
"name": "blatann",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "ble, bluetooth, nrf52, nordic",
"author": null,
"author_email": "Thomas Gerstenberg <tgerst6@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/61/90/b603fc89f0c45c8f7d5c9fad150911e51035dc6917f742bbbdca877b102a/blatann-0.6.0.tar.gz",
"platform": null,
"description": "# Blatann\r\n\r\nbl\u00e5tann: Norwegian word for \"blue tooth\"\r\n\r\nBlatann aims to provide a high-level, object-oriented interface for interacting\r\nwith Bluetooth Low Energy (BLE) devices through Python. It operates using\r\nthe Nordic Semiconductor nRF52 through Nordic's ``pc-ble-driver-py`` library\r\nand the associated Connectivity firmware for the device.\r\n\r\nDocumentation is available on [ReadTheDocs](https://blatann.readthedocs.io)\r\n\r\n### Install\r\n\r\n`pip install blatann`\r\n\r\n#### Using with macOS brew python\r\n\r\n`pc-ble-driver-py` consists of a shared object which is linked to mac's system python.\r\nIn order to use it with brew's python install, you'll need to run `install_name_tool` to modify the `.so` to \r\npoint to brew python instead of system python.\r\n\r\n_Note: This is the case with any custom-installed python on mac (like anaconda), brew is the most popular and what has been tested_\r\n\r\nAn example shell script to do so can be found [here](./tools/macos_retarget_pc_ble_driver_py.sh) \r\n\r\n#### Supported Devices/Software\r\n\r\nThis library has been tested with the following hardware:\r\n\r\n- the [nRF52-DK](https://www.nordicsemi.com/Products/Development-hardware/nrf52-dk): a Dev Kit for the nRF52832 (PCA10040)\r\n- the [nRF52840-DK](https://www.nordicsemi.com/Products/Development-hardware/nRF52840-DK): a Dev Kit for the nRF52840 (PCA10056)\r\n- the [nRF52840-Dongle](https://www.nordicsemi.com/Products/Development-hardware/nrf52840-dongle): a nRF52840 USB Dongle (PCA10059)\r\n- the [ABSniffer-528](https://wiki.aprbrother.com/en/ABSniffer_USB_Dongle_528.html): a nRF52832 USB Dongle\r\n\r\nFlashed with specific Connectivity firmware released by Nordic Semiconductor.\r\n\r\nWhen using the nRF52840, it should be flashed using the S132/SoftDevice v5 connectivity images. Both the hex files and DFU packages are distributed\r\nwith v4.1.4 of [pc-ble-driver](https://github.com/NordicSemiconductor/pc-ble-driver/releases/tag/v4.1.4) and is also provided in the `pc-ble-driver-py` install.\r\n\r\nThe Nordic devices can be flashed using [nRF Connect Desktop App](https://www.nordicsemi.com/Software-and-Tools/Development-Tools/nRF-Connect-for-desktop) or the `nrfutil` CLI tool.\r\n\r\n### Roadmap/Supported BLE Features\r\n\r\nAs of v0.3.0, the public-facing API of Blatann is stable. There will not\r\nlikely be any major changes in method/property naming or functionality\r\nand all features added will aim to maintain backwards compatibility.\r\n\r\nBelow lists the supported BLE features and ones that are on the roadmap to implement (eventually)\r\n\r\n- [X] GAP\r\n - [X] BLE Enable parameters\r\n - [X] BLE Connection parameters (functional, needs some work)\r\n - [X] Advertising\r\n - [X] Data Length Extensions\r\n - [X] PHY selection\r\n - Coded PHY not supported, only 1 and 2 Mbps PHYs\r\n - [X] Scanning\r\n - [X] Documentation\r\n - [X] RSSI\r\n - [X] Transmit Power\r\n - [X] Advertising channel selection\r\n- [X] SMP\r\n - [X] Private resolvable/non-resolvable advertising \r\n - [X] Encryption/Authentication process\r\n - [X] MITM/Passcode pairing support\r\n - [X] Store bonding info\r\n - [X] Identity resolve\r\n - [X] Bonding as Peripheral\r\n - [X] Bonding as Central\r\n - [X] LESC pairing\r\n - [X] Documentation\r\n- [ ] GATT\r\n - [X] Configurable MTU\r\n - [X] Generic Access service configuration\r\n - [ ] Service Changed characteristic\r\n- [ ] GATT Server\r\n - [X] Characteristic Reads\r\n - [X] Characteristic Writes\r\n - [X] Notifications/Indications\r\n - [X] Long reads/writes\r\n - [X] Characteristic User Description/Presentation format\r\n - [ ] CCCD Caching\r\n - [ ] Custom Read/Write authorization (#10)\r\n - [X] Documentation\r\n- [ ] GATT Client\r\n - [X] Database Discovery procedure\r\n - [X] Client reads\r\n - [X] Client writes\r\n - [X] Client long writes\r\n - [X] Notifications/Indications\r\n - [ ] CCCD Caching\r\n - [ ] Service Discovery Caching (#89)\r\n - [X] Documentation\r\n- [ ] Examples\r\n - [X] Advertiser/Broadcaster\r\n - [X] Scanner/Observer\r\n - [X] Central, Procedural\r\n - [X] Central, Event Driven\r\n - [ ] Central, Multiple Connections (#77)\r\n - [X] Peripheral\r\n - [ ] Multi-role\r\n - [X] Passcode Pairing\r\n - [X] LESC Numeric Comparison Pairing (glucose peripheral, no central example)\r\n - [X] Bonding (glucose peripheral, no central example)\r\n- [ ] Bluetooth Services\r\n - [X] Device Info Service\r\n - [X] Battery Service\r\n - [ ] Current Time Service\r\n - [X] Peripheral\r\n - [ ] Central (Partially implemented)\r\n - [ ] Glucose Service\r\n - [X] Peripheral\r\n - [ ] Central\r\n - [X] Nordic UART Service\r\n - More TBD (or on request)\r\n- [X] License\r\n- [ ] Unit Tests\r\n- [X] Integration Tests (partial -- below are implemented)\r\n - Advertising\r\n - Scanning\r\n - GATT Writes/Reads\r\n - GATT throughput testing/benchmarks\r\n - Pairing/Bonding\r\n\r\nThe library aims to support both event-driven and procedural program styles. It takes similar paradigms from C#/.NET's event function signatures,\r\nwhere event handlers are passed `object sender, EventArgs e` parameters.\r\nAdditionally, all asynchronous function calls return a `Waitable` object which can be waited on (with timeout)\r\nuntil the event associated with the function call returns.\r\n\r\n### Examples\r\n\r\nThere are several example scripts which showcase different functionality of the library under `blatann/examples`.\r\nExamples can be run using `python -m blatann.examples [example_filename] [device_comport]`.\r\n\r\nExample usage: `python -m blatann.examples scanner COM3`\r\n\r\n### Running Tests\r\n\r\nThe integrated tests can be ran using the builtin `unittest` runner and depends on a few environment variables to find the connected Nordic devices.\r\n\r\nAt a minimum, two nordic devices are required to run the unit tests. These are specified using environment variables:\r\n\r\n- `BLATANN_DEV_1` - Serial port of the first Nordic device\r\n- `BLATANN_DEV_2` - Serial port of the second Nordic device\r\n\r\nOptionally 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.\r\n\r\nIn order to speed up the tests, `BLATANN_TEST_QUICK=1` can be defined to skip long-running tests. \r\nNote that test cases which are defined as \"long-running\" is subjective and relative--the test suite will still take awhile to run, \r\nbut in general test cases which take longer than 20 seconds are skipped.\r\n\r\nThe tests can also be ran through the makefile using `make run-tests`.\r\n",
"bugtrack_url": null,
"license": "BSD 3-Clause",
"summary": "Python BLE library for using Nordic nRF52 with Connectivity firmware",
"version": "0.6.0",
"project_urls": {
"Changelog": "https://blatann.readthedocs.io/en/latest/changelog.html",
"Documentation": "https://blatann.readthedocs.io/en/latest/",
"Repository": "https://github.com/ThomasGerstenberg/blatann"
},
"split_keywords": [
"ble",
" bluetooth",
" nrf52",
" nordic"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b7c1a4b782b4199ec410d58da91a9095b661d9e801051b9b17f1dbe472cc1b1d",
"md5": "7b9b88c2e456c6fbe047dd6d87a8108d",
"sha256": "be873e48f229b6bc7ffecf5607b18450e6438ae165cf64f63e8cc10c501c39e7"
},
"downloads": -1,
"filename": "blatann-0.6.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7b9b88c2e456c6fbe047dd6d87a8108d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 256477,
"upload_time": "2024-09-18T05:41:21",
"upload_time_iso_8601": "2024-09-18T05:41:21.301734Z",
"url": "https://files.pythonhosted.org/packages/b7/c1/a4b782b4199ec410d58da91a9095b661d9e801051b9b17f1dbe472cc1b1d/blatann-0.6.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6190b603fc89f0c45c8f7d5c9fad150911e51035dc6917f742bbbdca877b102a",
"md5": "7f47b5b08c1c1b5391be24ccd42d4cc4",
"sha256": "1db64634e3b069cac502a41e231c19ea66bd8f6d38f72049fb1a63832a1a1954"
},
"downloads": -1,
"filename": "blatann-0.6.0.tar.gz",
"has_sig": false,
"md5_digest": "7f47b5b08c1c1b5391be24ccd42d4cc4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 206821,
"upload_time": "2024-09-18T05:41:22",
"upload_time_iso_8601": "2024-09-18T05:41:22.886606Z",
"url": "https://files.pythonhosted.org/packages/61/90/b603fc89f0c45c8f7d5c9fad150911e51035dc6917f742bbbdca877b102a/blatann-0.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-18 05:41:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ThomasGerstenberg",
"github_project": "blatann",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "blatann"
}
