btsocket 0.3.0

Overview

This library aims to offer assistance to accessing the BlueZ Bluetooth Management API 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.

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

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:

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.

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