GNU/Linux¶

Classes¶

There are two

class bluetooth.bluez.DeviceDiscoverer(device_id=-1)¶

Skeleton class for finer control of the device discovery process.

To implement asynchronous device discovery (e.g. if you want to do something as soon as a device is discovered), subclass DeviceDiscoverer and override device_discovered() and inquiry_complete() methods.

cancel_inquiry()¶

Cancel an inquiry in process.

Call this method to cancel an inquiry in process. inquiry_complete will still be called.

Raises: BluetoothError –

device_discovered(address, device_class, rssi, name)¶

Called when a bluetooth device is discovered.

Parameters

address (str) – the bluetooth address of the device
device_class (str) – the Class of Device, as specified in 1 passed in as a 3-byte string
rssi – the received signal strength indicator
name (str or None) – the user-friendly name of the device if lookup_names was set when the inquiry was started. otherwise None

Notes

This method exists to be overriden.

References

1: https://www.bluetooth.org/foundry/assignnumb/document/baseband

find_devices(lookup_names=True, duration=8, flush_cache=True)¶

Find bluetooth devices.

Call this method to initiate the device discovery process

Parameters

lookup_names (bool) – Set to True if you want to lookup the user-friendly names for each device found.
service_name – Set to the name of a service you’re looking for. Only devices with a service of this name will be returned in device_discovered () NOT YET IMPLEMENTED
duration (int, optional) – The number of 1.2 second units to spend searching for bluetooth devices. If lookup_names is True, then the inquiry process can take a lot longer.
flush_cache (bool, optional) – return devices discovered in previous inquiries

Warning

Don’t change duration or flush cache unless you know what you are doing.

Raises: BluetoothError –

inquiry_complete()¶: Called when an inquiry started by find_devices has completed.

pre_inquiry()¶

Called just after find_devices is invoked, but just before the inquiry is started.

This method exists to be overriden

process_event()¶

Process an hci event.

Waits for one event to happen, and processes it. The event will be either a device discovery, or an inquiry completion.

process_inquiry()¶: Repeatedly calls process_event () until the device inquiry has completed.

class bluetooth.bluez.BluetoothSocket(proto=bluetooth._bluetooth.RFCOMM, _sock=None)¶

dup() → socket object¶: Return a new socket object connected to the same system resource.

get_l2cap_options(sock, mtu)¶: Gets L2CAP options for the specified L2CAP socket. Options are: omtu, imtu, flush_to, mode, fcs, max_tx, txwin_size.

set_l2cap_mtu(sock, mtu)¶

Adjusts the MTU for the specified L2CAP socket. This method needs to be invoked on both sides of the connection for it to work! The default mtu that all L2CAP connections start with is 672 bytes.

mtu must be between 48 and 65535, inclusive.

set_l2cap_options(sock, options)¶: Sets L2CAP options for the specified L2CAP socket. The option list must be in the same format supplied by get_l2cap_options().

Functions¶

bluetooth.bluez.advertise_service(sock, name, service_id='', service_classes=[], profiles=[], provider='', description='', protocols=[])¶

Advertises a service with the local SDP server. sock must be a bound, listening socket. name should be the name of the service, and service_id (if specified) should be a string of the form “XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX”, where each ‘X’ is a hexadecimal digit.

service_classes is a list of service classes whose this service belongs to. Each class service is a 16-bit UUID in the form “XXXX”, where each ‘X’ is a hexadecimal digit, or a 128-bit UUID in the form “XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX”. There are some constants for standard services, e.g. SERIAL_PORT_CLASS that equals to “1101”. Some class constants:

SERIAL_PORT_CLASS LAN_ACCESS_CLASS DIALUP_NET_CLASS HEADSET_CLASS CORDLESS_TELEPHONY_CLASS AUDIO_SOURCE_CLASS AUDIO_SINK_CLASS PANU_CLASS NAP_CLASS GN_CLASS

profiles is a list of service profiles that thie service fulfills. Each profile is a tuple with ( uuid, version). Most standard profiles use standard classes as UUIDs. PyBluez offers a list of standard profiles, for example SERIAL_PORT_PROFILE. All standard profiles have the same name as the classes, except that _CLASS suffix is replaced by _PROFILE.

provider is a text string specifying the provider of the service

description is a text string describing the service

A note on working with Symbian smartphones:: bt_discover in Python for Series 60 will only detect service records with service class SERIAL_PORT_CLASS and profile SERIAL_PORT_PROFILE

bluetooth.bluez.discover_devices(duration=8, flush_cache=True, lookup_names=False, lookup_class=False, device_id=-1, iac=10390323)¶

performs a bluetooth device discovery using the first available bluetooth resource.

if lookup_names is False, returns a list of bluetooth addresses. if lookup_names is True, returns a list of (address, name) tuples

lookup_names=False: if set to True, then discover_devices also attempts to lookup the display name of each detected device.

if lookup_class is True, the class of the device is added to the tuple

bluetooth.bluez.find_service(name = None, uuid = None, address = None)¶

Searches for SDP services that match the specified criteria and returns the search results. If no criteria are specified, then returns a list of all nearby services detected. If more than one is specified, then the search results will match all the criteria specified. If uuid is specified, it must be either a 16-bit UUID in the form “XXXX”, where each ‘X’ is a hexadecimal digit, or as a 128-bit UUID in the form “XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX”. A special case of address is “localhost”, which will search for services on the local machine.

The search results will be a list of dictionaries. Each dictionary represents a search match and will have the following key/value pairs:

host - the bluetooth address of the device advertising the
service

name - the name of the service being advertised description - a description of the service being advertised provider - the name of the person/organization providing the service protocol - either ‘RFCOMM’, ‘L2CAP’, None if the protocol was not

specified, or ‘UNKNOWN’ if the protocol was specified but unrecognized

port - the L2CAP PSM # if the protocol is ‘L2CAP’, the RFCOMM
channel # if the protocol is ‘RFCOMM’, or None if it wasn’t specified

service-classes - a list of service class IDs (UUID strings). possibly
empty

profiles - a list of profiles - (UUID, version) pairs - the
service claims to support. possibly empty.

service-id - the Service ID of the service. None if it wasn’t set
See the Bluetooth spec for the difference between Service ID and Service Class ID List

bluetooth.bluez.lookup_name(address, timeout=10)¶: Tries to determine the friendly name (human readable) of the device with the specified bluetooth address. Returns the name on success, and None on failure.

bluetooth.bluez.read_local_bdaddr()¶

bluetooth.bluez.stop_advertising(sock)¶: Instructs the local SDP server to stop advertising the service associated with sock. You should typically call this right before you close sock.