Introduction
============
.. image:: https://readthedocs.org/projects/adafruit-blinka-bleio/badge/?version=latest
:target: https://circuitpython.readthedocs.io/projects/blinka_bleio/en/latest/
:alt: Documentation Status
.. image:: https://img.shields.io/discord/327254708534116352.svg
:target: https://adafru.it/discord
:alt: Discord
.. image:: https://github.com/adafruit/Adafruit_Blinka_bleio/workflows/Build%20CI/badge.svg
:target: https://github.com/adafruit/Adafruit_Blinka_bleio/actions
:alt: Build Status
`_bleio` for Blinka based on `bleak <https://github.com/hbldh/bleak>`_ and bluez.
Dependencies
=============
This driver depends on:
* `bleak <https://github.com/hbldh/bleak>`_
It optionally also depends on these Debian packages not install on Raspbian by default:
* ``bluez-hcidump``
Installing from PyPI
=====================
On supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally `from
PyPI <https://pypi.org/project/adafruit-blinka-bleio/>`_. To install for current user:
.. code-block:: shell
pip3 install adafruit-blinka-bleio
To install system-wide (this may be required in some cases):
.. code-block:: shell
sudo pip3 install adafruit-blinka-bleio
To install in a virtual environment in your current project:
.. code-block:: shell
mkdir project-name && cd project-name
python3 -m venv .env
source .env/bin/activate
pip3 install adafruit-blinka-bleio
Support for Duplicate Advertisement scanning on Linux
=====================================================
.. note::
Read this section if you are using advertising to transmit changing
data and need to receive all advertisements to receive this data.
One example of using advertising for data is described in the Adafruit Learn Guide
`Bluetooth LE Sensor Nodes to Raspberry Pi WiFi Bridge
<https://learn.adafruit.com/bluetooth-le-broadcastnet-sensor-node-raspberry-pi-wifi-bridge>`_.
The regular Linux kernel ``bluez`` driver is set up to suppress
multiple advertisements sent from the same BLE device. As of this
writing, this cannot be changed. If you are using BLE advertisements
to send changing data that you retrieve by scanning, the
de-duplication can cause you to lose data when scanning via ``bleak``.
To get around this problem, this library can instead look at raw BLE
scanning data using the ``hcidump`` and ``hcitool`` tools and avoid
going through the kernel driver. But this requires special setup.
Normally, only root has enough privileges to do see the raw scanning
data. Since running as root is dangerous, you can instead use Linux
capabilities to grant ``hcitool`` and ``hcidump`` raw network
access. This is very powerful and not something to do casually. To
limit access we recommend you change file execution permissions to
restrict this capability to users in the ``bluetooth`` group.
**If you are not using advertising to transmit changing data, you do
not need to add these permissions. This library falls back to using**
``bleak`` **for regular scanning if** ``hcitool`` **does not have
these extra permissions.**
If you **explicitly** want to choose the backend to ensure consistent
behavior, you can do the following:
.. code-block:: python
ble = BLERadio()
ble._adapter.ble_backend = "bleak" # Forces bleak even if hcitool works.
# ble._adapter.ble_backend = "hcitool" # Forces hcitool. Raises exception if unavailable.
To add yourself to the ``bluetooth`` group do:
.. code-block:: shell
sudo usermod -a -G bluetooth <your username>
You must then logout and log back in to be in the new group.
To set permissions on ``hcitool`` and ``hcidump`` do:
.. code-block:: shell
sudo chown :bluetooth /usr/bin/hcitool /usr/bin/hcidump
sudo chmod o-x /usr/bin/hcitool /usr/bin/hcidump
sudo setcap 'cap_net_raw,cap_net_admin+eip' /usr/bin/hcitool
sudo setcap 'cap_net_raw,cap_net_admin+eip' /usr/bin/hcidump
Usage Example
=============
Do not use this library directly. Use CircuitPython BLE instead:
https://github.com/adafruit/Adafruit_CircuitPython_BLE/
Contributing
============
Contributions are welcome! Please read our `Code of Conduct
<https://github.com/adafruit/Adafruit_Blinka_bleio/blob/master/CODE_OF_CONDUCT.md>`_
before contributing to help this project stay welcoming.
Documentation
=============
For information on building library documentation, please check out `this guide <https://learn.adafruit.com/creating-and-sharing-a-circuitpython-library/sharing-our-docs-on-readthedocs#sphinx-5-1>`_.
Troubleshooting
================
Raspberry Pi 3b Rev 1.2
^^^^^^^^^^^^^^^^^^^^^^^^
The Raspberry Pi 3b's BLE chip is connected over UART to the main processor without flow control.
This can cause unreliability with BLE. To improve reliability, we can slow the UART. To do so,
edit ``/usr/bin/btuart`` and replace the ``921600`` with ``460800``.
Raw data
{
"_id": null,
"home_page": null,
"name": "adafruit-blinka-bleio",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "adafruit, blinka, circuitpython, micropython, blinka_bleio, bleio, bleak",
"author": null,
"author_email": "Adafruit Industries <circuitpython@adafruit.com>",
"download_url": "https://files.pythonhosted.org/packages/d5/58/c955780ace5c7a98f6da44a0d54fbfa3d55a053927e635dd85977bc40e92/adafruit-blinka-bleio-4.1.2.tar.gz",
"platform": null,
"description": "Introduction\n============\n\n.. image:: https://readthedocs.org/projects/adafruit-blinka-bleio/badge/?version=latest\n :target: https://circuitpython.readthedocs.io/projects/blinka_bleio/en/latest/\n :alt: Documentation Status\n\n.. image:: https://img.shields.io/discord/327254708534116352.svg\n :target: https://adafru.it/discord\n :alt: Discord\n\n.. image:: https://github.com/adafruit/Adafruit_Blinka_bleio/workflows/Build%20CI/badge.svg\n :target: https://github.com/adafruit/Adafruit_Blinka_bleio/actions\n :alt: Build Status\n\n`_bleio` for Blinka based on `bleak <https://github.com/hbldh/bleak>`_ and bluez.\n\n\nDependencies\n=============\nThis driver depends on:\n\n* `bleak <https://github.com/hbldh/bleak>`_\n\nIt optionally also depends on these Debian packages not install on Raspbian by default:\n\n* ``bluez-hcidump``\n\nInstalling from PyPI\n=====================\n\nOn supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally `from\nPyPI <https://pypi.org/project/adafruit-blinka-bleio/>`_. To install for current user:\n\n.. code-block:: shell\n\n pip3 install adafruit-blinka-bleio\n\nTo install system-wide (this may be required in some cases):\n\n.. code-block:: shell\n\n sudo pip3 install adafruit-blinka-bleio\n\nTo install in a virtual environment in your current project:\n\n.. code-block:: shell\n\n mkdir project-name && cd project-name\n python3 -m venv .env\n source .env/bin/activate\n pip3 install adafruit-blinka-bleio\n\n\nSupport for Duplicate Advertisement scanning on Linux\n=====================================================\n\n.. note::\n Read this section if you are using advertising to transmit changing\n data and need to receive all advertisements to receive this data.\n One example of using advertising for data is described in the Adafruit Learn Guide\n `Bluetooth LE Sensor Nodes to Raspberry Pi WiFi Bridge\n <https://learn.adafruit.com/bluetooth-le-broadcastnet-sensor-node-raspberry-pi-wifi-bridge>`_.\n\nThe regular Linux kernel ``bluez`` driver is set up to suppress\nmultiple advertisements sent from the same BLE device. As of this\nwriting, this cannot be changed. If you are using BLE advertisements\nto send changing data that you retrieve by scanning, the\nde-duplication can cause you to lose data when scanning via ``bleak``.\n\nTo get around this problem, this library can instead look at raw BLE\nscanning data using the ``hcidump`` and ``hcitool`` tools and avoid\ngoing through the kernel driver. But this requires special setup.\n\nNormally, only root has enough privileges to do see the raw scanning\ndata. Since running as root is dangerous, you can instead use Linux\ncapabilities to grant ``hcitool`` and ``hcidump`` raw network\naccess. This is very powerful and not something to do casually. To\nlimit access we recommend you change file execution permissions to\nrestrict this capability to users in the ``bluetooth`` group.\n\n**If you are not using advertising to transmit changing data, you do\nnot need to add these permissions. This library falls back to using**\n``bleak`` **for regular scanning if** ``hcitool`` **does not have\nthese extra permissions.**\n\nIf you **explicitly** want to choose the backend to ensure consistent\nbehavior, you can do the following:\n\n.. code-block:: python\n\n ble = BLERadio()\n ble._adapter.ble_backend = \"bleak\" # Forces bleak even if hcitool works.\n # ble._adapter.ble_backend = \"hcitool\" # Forces hcitool. Raises exception if unavailable.\n\nTo add yourself to the ``bluetooth`` group do:\n\n.. code-block:: shell\n\n sudo usermod -a -G bluetooth <your username>\n\nYou must then logout and log back in to be in the new group.\n\nTo set permissions on ``hcitool`` and ``hcidump`` do:\n\n.. code-block:: shell\n\n sudo chown :bluetooth /usr/bin/hcitool /usr/bin/hcidump\n sudo chmod o-x /usr/bin/hcitool /usr/bin/hcidump\n sudo setcap 'cap_net_raw,cap_net_admin+eip' /usr/bin/hcitool\n sudo setcap 'cap_net_raw,cap_net_admin+eip' /usr/bin/hcidump\n\nUsage Example\n=============\n\nDo not use this library directly. Use CircuitPython BLE instead:\nhttps://github.com/adafruit/Adafruit_CircuitPython_BLE/\n\nContributing\n============\n\nContributions are welcome! Please read our `Code of Conduct\n<https://github.com/adafruit/Adafruit_Blinka_bleio/blob/master/CODE_OF_CONDUCT.md>`_\nbefore contributing to help this project stay welcoming.\n\nDocumentation\n=============\n\nFor information on building library documentation, please check out `this guide <https://learn.adafruit.com/creating-and-sharing-a-circuitpython-library/sharing-our-docs-on-readthedocs#sphinx-5-1>`_.\n\nTroubleshooting\n================\n\nRaspberry Pi 3b Rev 1.2\n^^^^^^^^^^^^^^^^^^^^^^^^\n\nThe Raspberry Pi 3b's BLE chip is connected over UART to the main processor without flow control.\nThis can cause unreliability with BLE. To improve reliability, we can slow the UART. To do so,\nedit ``/usr/bin/btuart`` and replace the ``921600`` with ``460800``.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "`_bleio` for Blinka based on `bleak`",
"version": "4.1.2",
"project_urls": {
"Homepage": "https://github.com/adafruit/Adafruit_Blinka_bleio.git"
},
"split_keywords": [
"adafruit",
" blinka",
" circuitpython",
" micropython",
" blinka_bleio",
" bleio",
" bleak"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9705b5fa1fcc4cc68bda4bd317cb60a826eef753d9ab8efcd2d28fbcc7d60dd2",
"md5": "1f27d27428fd501f732e9377311e9d00",
"sha256": "f4e21ed7072d05e86261c69b43c72b050c3d8b1b3297b6c71b36292ffbfc3275"
},
"downloads": -1,
"filename": "adafruit_blinka_bleio-4.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1f27d27428fd501f732e9377311e9d00",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 25390,
"upload_time": "2024-03-20T15:59:43",
"upload_time_iso_8601": "2024-03-20T15:59:43.305322Z",
"url": "https://files.pythonhosted.org/packages/97/05/b5fa1fcc4cc68bda4bd317cb60a826eef753d9ab8efcd2d28fbcc7d60dd2/adafruit_blinka_bleio-4.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d558c955780ace5c7a98f6da44a0d54fbfa3d55a053927e635dd85977bc40e92",
"md5": "0cf362b94bcd5aec6a45c197c2fc58a3",
"sha256": "4fb2bab1984a827e28e09e518d3e6777689566eb96d2d00ce14f596c10937fa3"
},
"downloads": -1,
"filename": "adafruit-blinka-bleio-4.1.2.tar.gz",
"has_sig": false,
"md5_digest": "0cf362b94bcd5aec6a45c197c2fc58a3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 45807,
"upload_time": "2024-03-20T15:59:44",
"upload_time_iso_8601": "2024-03-20T15:59:44.527520Z",
"url": "https://files.pythonhosted.org/packages/d5/58/c955780ace5c7a98f6da44a0d54fbfa3d55a053927e635dd85977bc40e92/adafruit-blinka-bleio-4.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-20 15:59:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "adafruit",
"github_project": "Adafruit_Blinka_bleio",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "adafruit-blinka-bleio"
}
JSON
