BTZen is a library to asynchronously access Bluetooth devices using Python
language. It provides simple API over complex D-Bus Bluez interface.
Features
========
The main features of BTZen are
1. Connect and access multiple Bluetooth devices in parallel with Python
asynchronous coroutines.
2. GATT notification interface integrated into main API of the library.
3. Automatic reconnections to devices.
4. Access to serial devices implementing Stollmann (Telit) protocol.
5. Support for devices, which do not follow the Bluetooth specification
fully like SensorTag (CC2650STK) or Thingy:52.
6. Support for Bluez managed interfaces of devices, i.e. battery level.
7. Allow to implement support for new devices easily.
The library can be used with any Bluetooth Smart device. It was tested with
1. SensorTag (CC2650STK) to read temperature, pressure, humidity, light,
accelerometer data and state of the buttons.
2. Thingy:52 to read temperature, pressure, humidity, light data and state
of the button.
3. Mi Smart Scale to read weight data.
4. OSTC dive computer to read serial device data using Stollmann (Telit)
protocol.
The library is tested with default `asyncio` event loop and its drop-in
replacement `uvloop <https://github.com/MagicStack/uvloop>`_. Use of
`uvloop` increases performance of the library.
The scripts in `scripts` directory demonstrate reading data from various
devices.
NOTE: The first version of SensorTag (CC2541DK) is not supported at the
moment. If you still own the device and would like it to be supported,
please `raise an issue <https://github.com/wrobell/btzen/issues>`_.
API Changes
===========
Please note that since version 0.6.0 the API changed. The benefits are
- support different makes of devices with single API
- it is much easier to implement functionality for new devices
- shutting down of BTZen connection sessions is more reliable
If pre-0.6.0 version of BTZen is required, then use appropriate versioning
in installation requirements of your project.
Documentation
=============
This project's documentation is lacking at the moment. Some useful tips
might be found in this README file and files at
https://github.com/wrobell/btzen/tree/master/doc
Installation
============
Use `pip` to install BTZen library (Cython needs to be installed first),
for example::
pip install --user cython
pip install --user btzen
BTZen uses experimental API of Bluez adapter interface to connect to
Bluetooth devices. The `bluetoothd` daemon has to be started with
experimental option on. This can be permanently achieved by setting
`Experimental` to `true` in `/etc/bluez/main.conf` file.
Change `AutoEnable` option to true in `/etc/bluetooth/main.conf` to
automate powering up of Bluetooth controllers. Otherwise a controller might
need to be switched on manually with `bluetoothctl` tool. BTZen library
does not perform this operation.
Connection Management
=====================
BTZen uses `ConnectDevice` method of Bluez adapter interface to discover
and connect to Bluetooth devices. MAC address of a device needs to be known
in order to connect.
BTZen connection manager allows to connect and disconnect Bluetooth devices
without restarting of an application. If an application is reading data
from multiple Bluetooth devices, the application can continue working if,
for example, a sensor requires battery change.
Please note
- when trying to connect to a device using BTZen library, do not start scan
with other programs, i.e. `bluetoothctl`
- if a device is disconnected with an external program, the external program
has to be used to reconnect
Obtaining MAC Address
=====================
If Bluetooth device MAC address is not known
1. Start `bluetoothctl`.
2. Start scan.
3. Save discovered MAC address.
4. Optionally, remove device with `remove` command of `bluetoothctl`
utility.
5. Start BTZen based application using the discovered MAC address.
Performance
===========
The library enables programmers to communicate with mutliple devices in
parallel without using threads. This avoids context switching of threads
and minimizes memory requirements, which makes BTZen more efficient than
other, similar libraries. To keep the library as fast as possible, Cython
is used to access Bluez D-Bus API. BTZen can be used with `uvloop` for even
more increased performance of an application.
Support for GATT notification interface allows efficient use of Bluetooth
devices. For example, data from sensors like accelerometers can be read
only when sensor wakes up and transmits data after sensor has been moved.
This limits amount of transferred data and avoids draining battery of the
sensor, which will happen if data is polled at regular, short intervals.
Requirements
============
BTZen library requires the following software components
- Python 3.11
- bluez 5.68
- `sd-bus` (kart of `systemd`)
- Cython 3.0.0
License
=======
BTZen library is licensed under terms of GPL license, version 3, see
`COPYING <https://www.gnu.org/licenses/gpl-3.0.en.html>`_ file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/wrobell/btzen",
"name": "btzen",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": "",
"keywords": "",
"author": "Artur Wroblewski",
"author_email": "wrobell@riseup.net",
"download_url": "https://files.pythonhosted.org/packages/25/d2/76202d67d42e44c9c6d9490ffadbd49e27d331906c9726057f681dfd7e0b/btzen-0.8.0.tar.gz",
"platform": null,
"description": "BTZen is a library to asynchronously access Bluetooth devices using Python\nlanguage. It provides simple API over complex D-Bus Bluez interface.\n\nFeatures\n========\n\nThe main features of BTZen are\n\n1. Connect and access multiple Bluetooth devices in parallel with Python\n asynchronous coroutines.\n2. GATT notification interface integrated into main API of the library.\n3. Automatic reconnections to devices.\n4. Access to serial devices implementing Stollmann (Telit) protocol.\n5. Support for devices, which do not follow the Bluetooth specification\n fully like SensorTag (CC2650STK) or Thingy:52.\n6. Support for Bluez managed interfaces of devices, i.e. battery level.\n7. Allow to implement support for new devices easily.\n\nThe library can be used with any Bluetooth Smart device. It was tested with\n\n1. SensorTag (CC2650STK) to read temperature, pressure, humidity, light,\n accelerometer data and state of the buttons.\n2. Thingy:52 to read temperature, pressure, humidity, light data and state\n of the button.\n3. Mi Smart Scale to read weight data.\n4. OSTC dive computer to read serial device data using Stollmann (Telit)\n protocol.\n\nThe library is tested with default `asyncio` event loop and its drop-in\nreplacement `uvloop <https://github.com/MagicStack/uvloop>`_. Use of\n`uvloop` increases performance of the library.\n\nThe scripts in `scripts` directory demonstrate reading data from various\ndevices.\n\nNOTE: The first version of SensorTag (CC2541DK) is not supported at the\nmoment. If you still own the device and would like it to be supported,\nplease `raise an issue <https://github.com/wrobell/btzen/issues>`_.\n\nAPI Changes\n===========\nPlease note that since version 0.6.0 the API changed. The benefits are\n\n- support different makes of devices with single API\n- it is much easier to implement functionality for new devices\n- shutting down of BTZen connection sessions is more reliable\n\nIf pre-0.6.0 version of BTZen is required, then use appropriate versioning\nin installation requirements of your project.\n\nDocumentation\n=============\nThis project's documentation is lacking at the moment. Some useful tips\nmight be found in this README file and files at\n\n https://github.com/wrobell/btzen/tree/master/doc\n\nInstallation\n============\nUse `pip` to install BTZen library (Cython needs to be installed first),\nfor example::\n\n pip install --user cython\n pip install --user btzen\n\nBTZen uses experimental API of Bluez adapter interface to connect to\nBluetooth devices. The `bluetoothd` daemon has to be started with\nexperimental option on. This can be permanently achieved by setting\n`Experimental` to `true` in `/etc/bluez/main.conf` file.\n\nChange `AutoEnable` option to true in `/etc/bluetooth/main.conf` to\nautomate powering up of Bluetooth controllers. Otherwise a controller might\nneed to be switched on manually with `bluetoothctl` tool. BTZen library\ndoes not perform this operation.\n\nConnection Management\n=====================\nBTZen uses `ConnectDevice` method of Bluez adapter interface to discover\nand connect to Bluetooth devices. MAC address of a device needs to be known\nin order to connect.\n\nBTZen connection manager allows to connect and disconnect Bluetooth devices\nwithout restarting of an application. If an application is reading data\nfrom multiple Bluetooth devices, the application can continue working if,\nfor example, a sensor requires battery change.\n\nPlease note\n\n- when trying to connect to a device using BTZen library, do not start scan\n with other programs, i.e. `bluetoothctl`\n- if a device is disconnected with an external program, the external program\n has to be used to reconnect\n\nObtaining MAC Address\n=====================\nIf Bluetooth device MAC address is not known\n\n1. Start `bluetoothctl`.\n2. Start scan.\n3. Save discovered MAC address.\n4. Optionally, remove device with `remove` command of `bluetoothctl`\n utility.\n5. Start BTZen based application using the discovered MAC address.\n\nPerformance\n===========\nThe library enables programmers to communicate with mutliple devices in\nparallel without using threads. This avoids context switching of threads\nand minimizes memory requirements, which makes BTZen more efficient than\nother, similar libraries. To keep the library as fast as possible, Cython\nis used to access Bluez D-Bus API. BTZen can be used with `uvloop` for even\nmore increased performance of an application.\n\nSupport for GATT notification interface allows efficient use of Bluetooth\ndevices. For example, data from sensors like accelerometers can be read\nonly when sensor wakes up and transmits data after sensor has been moved.\nThis limits amount of transferred data and avoids draining battery of the\nsensor, which will happen if data is polled at regular, short intervals.\n\nRequirements\n============\nBTZen library requires the following software components\n\n- Python 3.11\n- bluez 5.68\n- `sd-bus` (kart of `systemd`)\n- Cython 3.0.0\n\nLicense\n=======\nBTZen library is licensed under terms of GPL license, version 3, see\n`COPYING <https://www.gnu.org/licenses/gpl-3.0.en.html>`_ file for details.\n\n",
"bugtrack_url": null,
"license": "GPLv3+",
"summary": "BTZen - library to asynchronously access Bluetooth devices",
"version": "0.8.0",
"project_urls": {
"Homepage": "https://github.com/wrobell/btzen"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "25d276202d67d42e44c9c6d9490ffadbd49e27d331906c9726057f681dfd7e0b",
"md5": "3a74c3b998083d8b47190e228d79d0ac",
"sha256": "4d7dfb9d967fb49e8161b7a1b52ae12155ace39b8e3f35f25ea6e002e9517504"
},
"downloads": -1,
"filename": "btzen-0.8.0.tar.gz",
"has_sig": false,
"md5_digest": "3a74c3b998083d8b47190e228d79d0ac",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 355041,
"upload_time": "2023-07-20T21:44:13",
"upload_time_iso_8601": "2023-07-20T21:44:13.798253Z",
"url": "https://files.pythonhosted.org/packages/25/d2/76202d67d42e44c9c6d9490ffadbd49e27d331906c9726057f681dfd7e0b/btzen-0.8.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-20 21:44:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "wrobell",
"github_project": "btzen",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "btzen"
}
JSON
