Level 100

Adapter

Class and methods that represent a Bluetooth Adapter.

class bluezero.adapter.Adapter(adapter_addr=None)

Bluetooth Adapter Class.

This class instantiates an object that interacts with the physical Bluetooth device.

Example:
>>> from bluezero import adapter
>>> dongle = adapter.Adapter()
>>> dongle.powered = True
address

Return the adapter MAC address.

alias

Return the adapter alias.

Parameters:new_alias – the new alias of the adapter.
static available()

A generator yielding an Adapter object for every attached adapter.

bt_class

Return the Bluetooth class of device.

discoverable

Discoverable state of the Adapter.

discoverabletimeout

Discoverable timeout of the Adapter.

discovering

Return whether the adapter is discovering.

get_all()

Return dictionary of all the Adapter attributes.

hide_duplicates()

Hide advertisements from a device during Device Discovery if it contains information already discovered

name

Return the adapter name.

nearby_discovery(timeout=10)

Start discovery of nearby Bluetooth devices.

pairable

pairable state of the Adapter.

Parameters:new_state – boolean.
pairabletimeout

The pairable timeout of the Adapter.

powered

power state of the Adapter.

Parameters:new_state – boolean.
quit()

Stop the EventLoop for async operations

remove_device(device_path)

Removes device at the given D-Bus path

run()

Start the EventLoop for async operations

show_duplicates()

Show every advertisement from a device during Device Discovery if it contains ManufacturerData and/or ServiceData irrespective of whether they have been

discovered previously
start_discovery()

Start discovery of nearby Bluetooth devices.

Returns:True on success otherwise False
stop_discovery()

Stop scanning of nearby Bluetooth devices.

uuids

List of 128-bit UUIDs that represent available remote services.

exception bluezero.adapter.AdapterError

Custom exception for missing Bluetooth adapter

bluezero.adapter.list_adapters()

Return list of adapters address available on system.

Device

Class and methods that represent a remote Bluetooth Device.

Classes:

  • Device – Remote Bluetooth Device Class
class bluezero.device.Device(adapter_addr, device_addr)

Remote Bluetooth Device Class.

This class instantiates an object that interacts with a remote Bluetooth device.

RSSI

Received Signal Strength Indicator of the remote device.

(This is inquiry or advertising RSSI).

adapter

The address of the adapter the device belongs to.

address

Return the remote device address.

alias

remote device alias

appearance

External appearance of device, as found on GAP service.

static available(adapter_address=None)

A generator yielding a Device object for every discovered device.

blocked

Indicate whether the remote device is seen as blocked.

bt_class

The Bluetooth class of device of the remote device.

cancel_pairing()

This method can be used to cancel a pairing operation initiated by the pair method

connect(profile=None, timeout=35)

Initiate a connection to the remote device.

Parameters:
  • profile – (optional) profile to use for the connection.
  • timeout – (optional) the number of seconds to spend trying to connect.
connected

Indicate whether the remote device is currently connected.

disconnect()

Disconnect from the remote device.

icon

Proposed icon name.

This is set according to the freedesktop.org icon naming specification.

legacy_pairing

Indicate the legacy pairing status.

Set to true if the device only supports the pre-2.1 pairing mechanism.

manufacturer_data

Manufacturer specific advertisement data.

Keys are 16 bits Manufacturer ID followed by its byte array value.

modalias

Remote Device ID information in modalias format.

Used by the kernel and udev.

name

Return the remote device name.

pair()

Pair the device

paired

Indicate whether the remote device is paired.

service_data

Service advertisement data.

Keys are the UUIDs in string format followed by its byte array value.

services_available

Get a list of Service UUIDs available on this device

services_resolved

Indicate whether or not service discovery has been resolved.

trusted

Indicate whether the remote device is seen as trusted.

tx_power

Advertised transmitted power level (inquiry or advertising).

uuids

List of 128-bit UUIDs that represent available remote services.

Advertisement

Class and methods that represent LE Advertising. This class requires BlueZ to have the experimental flag enabled

Classes:

  • Advertisement – Specifies the Advertisement Data to be broadcast
  • AdvertisingManager – register Advertisement Data which should be broadcast to devices
class bluezero.advertisement.AdvertisingManager(adapter_addr=None)

Associate the advertisement to an adapter. If no adapter specified then first adapter in list is used

register_advertisement(advertisement, options=<MagicMock name='mock()' id='140263644682640'>)

Registers an advertisement object to be sent over the LE Advertising channel :param advertisement: Advertisement object :param options: :return:

unregister_advertisement(advertisement)
This unregisters the services that has been
previously registered. The advertisement object must match the value that was used on registration
Parameters:advertisement
Returns:
bluezero.advertisement.register_ad_cb()

Advertisement registration callback.

bluezero.advertisement.register_ad_error_cb(error)

Advertisement registration error callback.

Remote Device GATT

Classes that represent the GATT features of a remote device.

class bluezero.GATT.Characteristic(adapter_addr, device_addr, srv_uuid, chrc_uuid)

Remote GATT Characteristic.

UUID

Return the value of the Characteristic UUID for this path.

Returns:string example ‘00002a00-0000-1000-8000-00805f9b34fb’
add_characteristic_cb(callback=None)

Add a callback for this characteristic.

Parameters:callback – callback function to be added.
flags

Return a list of how this characteristic’s value can be used.

Returns:list example [‘read’, ‘write’, ‘notify’]
notifying

Return whether this characteristic has notifications enabled.

Returns:Boolean
props_changed_cb(iface, changed_props, invalidated_props)

Callback indicating that properties have changed.

Parameters:
  • iface – Interface associated with the callback.
  • changed_props – Properties changed that triggered the callback.
  • invalidated_props – Unused.
read_raw_value(flags='')

Return this characteristic’s value (if allowed).

Parameters:flags – “offset”: Start offset “device”: Device path (Server only)
Returns:
Possible Errors: org.bluez.Error.Failed
org.bluez.Error.InProgress org.bluez.Error.NotPermitted org.bluez.Error.InvalidValueLength org.bluez.Error.NotAuthorized org.bluez.Error.NotSupported
resolve_gatt()

Get the methods and properties for the discovered characteristics :return: Boolean of if characteristics have been resolved

service

Return the DBus object for this characteristic’s service.

Returns:DBus object of device
start_notify()

Initialise notifications for this characteristic.

start_notify_cb()

Callback associated with enabling notifications.

stop_notify()

Stop notifications for this characteristic.

stop_notify_cb()

Callback associated with disabling notifications.

value

The cached value of the characteristic.

This property gets updated only after a successful read request and when a notification or indication is received, upon which a PropertiesChanged signal will be emitted.

Returns:DBus byte array
write_value(value, flags='')

Write a new value to the characteristic.

Parameters:
  • value – A list of byte values
  • flags – Optional dictionary.

Typically empty. Values defined at: https://git.kernel.org/pub/scm/bluetooth/bluez.git/tree/doc/gatt-api.txt

class bluezero.GATT.Descriptor(adapter_addr, device_addr, srv_uuid, chrc_uuid, dscr_uuid)

Remote GATT Descriptor.

UUID

Return the value of the Descriptor UUID for this path.

Returns:string example ‘00002a00-0000-1000-8000-00805f9b34fb’
characteristic

Object path of the GATT characteristic’s descriptor.

Returns:DBus object
flags

Return a list of how this descriptor value can be used.

Returns:list example [‘read’, ‘write’]
read_raw_value(flags='')

Issue a request to read the value of the descriptor.

Returns the value if the operation was successful.

Parameters:flags – “offset”: Start offset “device”: Device path (Server only)
Returns:dbus byte array
resolve_gatt()

Get the methods and properties for the discovered Descriptors :return:

value

The cached value of the descriptor.

This property gets updated only after a successful read request, upon which a PropertiesChanged signal will be emitted.

Returns:DBus byte array
write_value(value, flags='')

Issue a request to write the value of the descriptor.

Parameters:
  • value – DBus byte array
  • flags – “offset”: Start offset “device”: Device path (Server only)
Returns:

class bluezero.GATT.GattManager(adapter_addr)

GATT Manager.

register_application(application, options)

Register an application with the GATT Manager.

Parameters:
  • application – Application object.
  • options
Returns:

unregister_application(application)

Unregister an application with the GATT Manager.

Parameters:application – Application object.
Returns:
class bluezero.GATT.Profile(adapter_addr, device_addr, profile_uuid)

Remote GATT Profile.

UUIDs

128-bit GATT service UUIDs to auto connect.

Returns:list of UUIDs
release()

Release the profile.

Returns:
class bluezero.GATT.Service(adapter_addr, device_addr, srv_uuid)

Remote GATT Service.

UUID

Return the value of the Service UUID for this path.

Returns:string for example ‘00001800-0000-1000-8000-00805f9b34fb’
device

Return the DBus object that this service belongs to.

Returns:DBus object of device
primary

Return a boolean saying if this a primary service.

Returns:boolean
resolve_gatt()

Get the methods and properties for the discovered Services :return:

bluezero.GATT.generic_error_cb(error)

Generic Error Callback function.

bluezero.GATT.register_app_cb()

Application registration callback.

bluezero.GATT.register_app_error_cb(error)

Application registration error callback.

Local Device GATT

Classes required to create a Bluetooth Peripheral.

Current classes include: - Service – Bluetooth Service - Characteristic – Bluetooth Characteristic - Descriptor – Bluetooth Descriptor

BlueZ Media Player Control

Access BlueZ Media Player functionality

class bluezero.media_player.MediaPlayer(device_addr)

Bluetooth MediaPlayer Class. This class instantiates an object that is able to interact with the player of a Bluetooth device and get audio from its source.

browsable

If present indicates the player can be browsed using MediaFolder interface.

device

Return Device object path

equalizer

Return the equalizer value.

fast_forward()

Fast forward playback, this action is only stopped when another method in this interface is called.

name

Return the player name

next()

Goes the next track and play it.

pause()

Pause the track.

play()

Resume the playback.

playlist

Return the Playlist object path.

position

Return the playback position in milliseconds.

previous()

Goes the previous track and play it

repeat

Return the repeat value

rewind()

Rewind playback, this action is only stopped when another method in this interface is called.

searchable

If present indicates the player can be searched using MediaFolder interface.

shuffle

Return the shuffle value

status

Return the status of the player Possible status: “playing”, “stopped”, “paused”, “forward-seek”, “reverse-seek” or “error”

stop()

Stops the playback.

subtype

Return the player subtype

track

Return a dict of the track metadata.

type(player_type)

Player type Possible values:

“Audio” “Video” “Audio Broadcasting” “Video Broadcasting”
exception bluezero.media_player.MediaPlayerError

Custom exception