==============================
BlueZ Bluetooth Management API
==============================
A Python library to interact with Bluez Bluetooth Management API on Linux.
At this time it should be seen as a very early stage proof of concept.
If you are new to Bluetooth this might not be the best library to start with
Overview
--------
This library aims to offer assistance to accessing the `BlueZ Bluetooth
Management API
<https://git.kernel.org/pub/scm/bluetooth/bluez.git/tree/doc/mgmt-api.txt>`_
using Python.
With the `mgmt` API there are no commands for reading and writing data on a
connected device.
This library has to have root privilege to access most things.
Three Levels
------------
This library has tried to split things in to the how, what and when. The aim
is by keeping the transport, protocol, and programming paradigm separate a
plug and play approach can be taken. For example, if the Python bug in sockets
gets fixed, just that part can be updated without too much disruption.
It should also be possible to use different programming paradigms (models)
for how commands and responses are handled and still use the socket and
protocol pieces.
Socket (How)
############
This library came into being because of a Bug in Python as documented at:
https://bugs.python.org/issue36132
Python currently does not allow any way to initialize hci_channel, so you
cannot use a `user channel` socket and so instead `btmgmt_socket` in
**btsocket/btmgmt_socket.py** accesses the `user channel` by using the
underlying libc socket.
Protocol (What)
###############
The file **btsocket/btmgmt_protocol.py** is to assist in encoding and decoding
the binary format that is used to communicate
This module assists in encoding and decoding the binary data
Programming Paradigm (When)
###########################
Handling communication with the sockets can be done a number of different ways
and there are trade-offs for each of them. Initially this library is supporting
two types. A procedural approach with **btsocket/btmgmt_sync.py** and
a callback (or event-driven) approach with **btsocket/btmgmt_callback.py**.
For actions like turning the controller on and off then these can be done
with either methodology. For listening for async events like the discovery
of devices, then only the callback model is practical.
Commands
--------
For the vast majority of the commands, the process of creating the
mgmt socket is required to have the CAP_NET_ADMIN capability
(e.g. root/sudo would have this).
The documentation for commands is at:
https://git.kernel.org/pub/scm/bluetooth/bluez.git/tree/doc/mgmt-api.txt
That documentation has been used to auto-generate parts of `btmgmt_protocol.py`
To take one command as an example; powered command:
::
Set Powered Command
===================
Command Code: 0x0005
Controller Index: <controller id>
Command Parameters: Powered (1 Octet)
Return Parameters: Current_Settings (4 Octets)
To power-on adapter at index zero, the following command would be sent with the
synchronous API
.. code-block:: python
from btsocket import btmgmt_sync
response = btmgmt_sync.send('SetPowered', 0, 1)
The format of the `send` command is :
`response = send(<command_name>, <adapter index>, <positional paramters>)`
The command name is taken from the heading in the documentation with the spaces
and the word "Command" removed. A typical response is given below:
::
Response(
header=<
event_code=CommandCompleteEvent,
controller_idx=0,
param_len=7>,
event_frame=<
command_opcode=SetPowered,
status=Success>,
cmd_response_frame=<
current_settings=2752>)
An example of the Python to access the values in the response is:
.. code-block:: Python
print(response.event_frame.command_opcode,
response.event_frame.status)
Callbacks on Events
-------------------
The structure for running with callbacks on events is below.
Getting the event loop and running until complete should be familiar to
regular users of asyncio.
`mgmt = btmgmt_callback.Mgmt()` sets up the sockets and the readers and writers
to the sockets.
`mgmt.add_event_callback` takes two arguments, the first is the btmgmt event
and the second is the callback function to use when that event is detected.
`mgmt.send` is how to send commands and is similar to the synchronous API
except it doesn't get a response. You will have to add an event callback to
access the response.
The command(s) are not sent until `mgmt.start()` as this is what
starts the writers and readers of the sockets.
.. code-block:: Python
from btsocket import btmgmt_callback
from btsocket import btmgmt_protocol
def device_found(response, mgmt_obj):
print('New device found', response.event_frame.address)
# To exit set running to False
mgmt_obj.stop()
def app():
mgmt = btmgmt_callback.Mgmt()
mgmt.add_event_callback(btmgmt_protocol.Events.DeviceFoundEvent,
device_found)
mgmt.send('StartDiscovery', 0, [btmgmt_protocol.AddressType.LEPublic,
btmgmt_protocol.AddressType.LERandom,
btmgmt_protocol.AddressType.BREDR])
mgmt.start()
if __name__ == '__main__':
app()
There are more examples in the examples folder
Raw data
{
"_id": null,
"home_page": "https://github.com/ukBaz/python-btsocket",
"name": "btsocket",
"maintainer": "Barry Byford",
"docs_url": null,
"requires_python": null,
"maintainer_email": "barry_byford@yahoo.co.uk",
"keywords": "BlueZ Bluetooth Management MGMT API",
"author": "Barry Byford",
"author_email": "barry_byford@yahoo.co.uk",
"download_url": "https://files.pythonhosted.org/packages/b2/b1/0ae262ecf936f5d2472ff7387087ca674e3b88d8c76b3e0e55fbc0c6e956/btsocket-0.3.0.tar.gz",
"platform": null,
"description": "==============================\nBlueZ Bluetooth Management API\n==============================\nA Python library to interact with Bluez Bluetooth Management API on Linux.\nAt this time it should be seen as a very early stage proof of concept.\nIf you are new to Bluetooth this might not be the best library to start with\n\nOverview\n--------\nThis library aims to offer assistance to accessing the `BlueZ Bluetooth\nManagement API\n<https://git.kernel.org/pub/scm/bluetooth/bluez.git/tree/doc/mgmt-api.txt>`_\nusing Python.\nWith the `mgmt` API there are no commands for reading and writing data on a\nconnected device.\nThis library has to have root privilege to access most things.\n\n\nThree Levels\n------------\nThis library has tried to split things in to the how, what and when. The aim\nis by keeping the transport, protocol, and programming paradigm separate a\nplug and play approach can be taken. For example, if the Python bug in sockets\ngets fixed, just that part can be updated without too much disruption.\nIt should also be possible to use different programming paradigms (models)\nfor how commands and responses are handled and still use the socket and\nprotocol pieces.\n\nSocket (How)\n############\nThis library came into being because of a Bug in Python as documented at:\nhttps://bugs.python.org/issue36132\n\nPython currently does not allow any way to initialize hci_channel, so you\ncannot use a `user channel` socket and so instead `btmgmt_socket` in\n**btsocket/btmgmt_socket.py** accesses the `user channel` by using the\nunderlying libc socket.\n\nProtocol (What)\n###############\nThe file **btsocket/btmgmt_protocol.py** is to assist in encoding and decoding\nthe binary format that is used to communicate\n\nThis module assists in encoding and decoding the binary data\n\nProgramming Paradigm (When)\n###########################\nHandling communication with the sockets can be done a number of different ways\nand there are trade-offs for each of them. Initially this library is supporting\ntwo types. A procedural approach with **btsocket/btmgmt_sync.py** and\na callback (or event-driven) approach with **btsocket/btmgmt_callback.py**.\n\nFor actions like turning the controller on and off then these can be done\nwith either methodology. For listening for async events like the discovery\nof devices, then only the callback model is practical.\n\nCommands\n--------\nFor the vast majority of the commands, the process of creating the\nmgmt socket is required to have the CAP_NET_ADMIN capability\n(e.g. root/sudo would have this).\n\nThe documentation for commands is at:\nhttps://git.kernel.org/pub/scm/bluetooth/bluez.git/tree/doc/mgmt-api.txt\n\nThat documentation has been used to auto-generate parts of `btmgmt_protocol.py`\n\nTo take one command as an example; powered command:\n::\n\n Set Powered Command\n ===================\n\n Command Code:\t\t0x0005\n Controller Index:\t<controller id>\n Command Parameters:\tPowered (1 Octet)\n Return Parameters:\tCurrent_Settings (4 Octets)\n\nTo power-on adapter at index zero, the following command would be sent with the\nsynchronous API\n\n.. code-block:: python\n\n from btsocket import btmgmt_sync\n response = btmgmt_sync.send('SetPowered', 0, 1)\n\nThe format of the `send` command is :\n\n`response = send(<command_name>, <adapter index>, <positional paramters>)`\n\nThe command name is taken from the heading in the documentation with the spaces\nand the word \"Command\" removed. A typical response is given below:\n::\n\n Response(\n header=<\n event_code=CommandCompleteEvent,\n controller_idx=0,\n param_len=7>,\n event_frame=<\n command_opcode=SetPowered,\n status=Success>,\n cmd_response_frame=<\n current_settings=2752>)\n\nAn example of the Python to access the values in the response is:\n\n.. code-block:: Python\n\n print(response.event_frame.command_opcode,\n response.event_frame.status)\n\nCallbacks on Events\n-------------------\nThe structure for running with callbacks on events is below.\n\nGetting the event loop and running until complete should be familiar to\nregular users of asyncio.\n\n`mgmt = btmgmt_callback.Mgmt()` sets up the sockets and the readers and writers\nto the sockets.\n\n`mgmt.add_event_callback` takes two arguments, the first is the btmgmt event\nand the second is the callback function to use when that event is detected.\n\n`mgmt.send` is how to send commands and is similar to the synchronous API\nexcept it doesn't get a response. You will have to add an event callback to\naccess the response.\nThe command(s) are not sent until `mgmt.start()` as this is what\nstarts the writers and readers of the sockets.\n\n.. code-block:: Python\n\n from btsocket import btmgmt_callback\n from btsocket import btmgmt_protocol\n\n def device_found(response, mgmt_obj):\n print('New device found', response.event_frame.address)\n # To exit set running to False\n mgmt_obj.stop()\n\n def app():\n mgmt = btmgmt_callback.Mgmt()\n mgmt.add_event_callback(btmgmt_protocol.Events.DeviceFoundEvent,\n device_found)\n mgmt.send('StartDiscovery', 0, [btmgmt_protocol.AddressType.LEPublic,\n btmgmt_protocol.AddressType.LERandom,\n btmgmt_protocol.AddressType.BREDR])\n mgmt.start()\n\n\n if __name__ == '__main__':\n app()\n\nThere are more examples in the examples folder\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python library for BlueZ Bluetooth Management API",
"version": "0.3.0",
"project_urls": {
"Homepage": "https://github.com/ukBaz/python-btsocket"
},
"split_keywords": [
"bluez",
"bluetooth",
"management",
"mgmt",
"api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "672b9bf3481131a24cb29350d69469448349362f6102bed9ae4a0a5bb228d731",
"md5": "fd19e1ddc7205c6b234b5caf83d9647f",
"sha256": "949821c1b580a88e73804ad610f5173d6ae258e7b4e389da4f94d614344f1a9c"
},
"downloads": -1,
"filename": "btsocket-0.3.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "fd19e1ddc7205c6b234b5caf83d9647f",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 14807,
"upload_time": "2024-06-10T07:05:26",
"upload_time_iso_8601": "2024-06-10T07:05:26.381987Z",
"url": "https://files.pythonhosted.org/packages/67/2b/9bf3481131a24cb29350d69469448349362f6102bed9ae4a0a5bb228d731/btsocket-0.3.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b2b10ae262ecf936f5d2472ff7387087ca674e3b88d8c76b3e0e55fbc0c6e956",
"md5": "c1537280fdc36fa93e4a74ac57ccc1fd",
"sha256": "7ea495de0ff883f0d9f8eea59c72ca7fed492994df668fe476b84d814a147a0d"
},
"downloads": -1,
"filename": "btsocket-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "c1537280fdc36fa93e4a74ac57ccc1fd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 19563,
"upload_time": "2024-06-10T07:05:27",
"upload_time_iso_8601": "2024-06-10T07:05:27.426609Z",
"url": "https://files.pythonhosted.org/packages/b2/b1/0ae262ecf936f5d2472ff7387087ca674e3b88d8c76b3e0e55fbc0c6e956/btsocket-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-10 07:05:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ukBaz",
"github_project": "python-btsocket",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "btsocket"
}
JSON
