Documentation

The SimpleBleClient class

class simpleble.SimpleBleClient(iface=0, scanCallback=None, notificationCallback=None)

Bases: object

This is a class implementation of a simple BLE client.

Parameters:

• iface (int, optional) – The Bluetooth interface on which to make the connection. On Linux, 0 means /dev/hci0, 1 means /dev/hci1 and so on., defaults to 0
• scanCallback (function, optional) – A function handle of the form callback(client, device, isNewDevice, isNewData), where client is a handle to the simpleble.SimpleBleClient that invoked the callback and device is the detected simpleble.SimpleBleDevice object. isNewDev is True if the device (as identified by its MAC address) has not been seen before by the scanner, and False otherwise. isNewData is True if new or updated advertising data is available, defaults to None
• notificationCallback (function, optional) – A function handle of the form callback(client, characteristic, data), where client is a handle to the simpleble.SimpleBleClient that invoked the callback, characteristic is the notified bluepy.blte.Characteristic object and data is a bytearray containing the updated value. Defaults to None

connect(device)

Attempts to connect client to a given simpleble.SimpleBleDevice object and returns a bool indication of the result.

Parameters:device (SimpleBleDevice) – An instance of the device to which we want to connect. Normally acquired by calling simpleble.SimpleBleClient.scan() or simpleble.SimpleBleClient.searchDevice() Returns:True if connection was successful, False otherwise Return type:bool

disconnect()

Drops existing connection. Note that the current version of the project assumes that the client can be connected to at most one device at a time.

getCharacteristics(startHnd=1, endHnd=65535, uuids=None)

Returns a list containing bluepy.btle.Characteristic objects for the peripheral. If no arguments are given, will return all characteristics. If startHnd and/or endHnd are given, the list is restricted to characteristics whose handles are within the given range.

Parameters:

• startHnd (int, optional) – Start index, defaults to 1
• endHnd (int, optional) – End index, defaults to 0xFFFF
• uuids (list, optional) – a list of UUID strings, defaults to None

Returns:

List of returned bluepy.btle.Characteristic objects

Return type:

list

isConnected()

Check to see if client is connected to a device

Returns:True if connected, False otherwise Return type:bool

printFoundDevices()

Print all devices discovered during the last scan. Should only be called after a simpleble.SimpleBleClient.scan() has been called first.

readCharacteristic(characteristic=None, uuid=None)

Reads the current value of the characteristic identified by either a bluepy.btle.Characteristic object characteristic, or a UUID string uuid. If both are provided, then the characteristic will be read on the basis of the characteristic object. A bluepy.btle.BTLEException.GATT_ERROR is raised if no inputs are specified or the requested characteristic was not found.

Parameters:

• characteristic (bluepy.btle.Characteristic, optional) – A bluepy.btle.Characteristic object, defaults to None
• uuid (string, optional) – A given UUID string, defaults to None

Raises:

bluepy.btle.BTLEException.GATT_ERROR: If no inputs are specified or the requested characteristic was not found.

Returns:

The value read from the characteristic

Return type:

bytearray

scan(timeout=10.0)

Scans for and returns detected nearby devices

Parameters:timeout (float, optional) – Specify how long (in seconds) the scan should last, defaults to 10.0 Returns:List of simpleble.SimpleBleDevice objects Return type:list

searchDevice(name=None, mac=None, timeout=10.0)

Searches for and returns, given it exists, a simpleble.SimpleBleDevice device objects, based on the provided name and/or mac address. If both a name and a mac are provided, then the client will only return a device that matches both conditions.

Par am name:

The “Complete Local Name” Generic Access Attribute (GATT) of the device, defaults to None

Parameters:

• mac (str, optional) – The MAC address of the device, defaults to None
• timeout (float, optional) – Specify how long (in seconds) the scan should last, defaults to 10.0. Internally, it serves as an input to the invoked simpleble.SimpleBleClient.scan() method.

Raises:

AssertionError – If neither a name nor a mac inputs have been provided

Returns:

A simpleble.SimpleBleDevice object if search was succesfull, None otherwise

Return type:

simpleble.SimpleBleDevice | None

setNotificationCallback(callback)

Set the callback function to be executed when a device sends a notification to the client.

Parameters:callback (function, optional) – A function handle of the form callback(client, characteristic, data), where client is a handle to the simpleble.SimpleBleClient that invoked the callback, characteristic is the notified bluepy.blte.Characteristic object and data is a bytearray containing the updated value. Defaults to None

setScanCallback(callback)

Set the callback function to be executed when a device is detected by the client.

Parameters:callback (function) – A function handle of the form callback(client, device, isNewDevice, isNewData), where client is a handle to the simpleble.SimpleBleClient that invoked the callback and device is the detected simpleble.SimpleBleDevice object. isNewDev is True if the device (as identified by its MAC address) has not been seen before by the scanner, and False otherwise. isNewData is True if new or updated advertising data is available.

writeCharacteristic(val, characteristic=None, uuid=None, withResponse=False)

Writes the data val (of type str on Python 2.x, byte on 3.x) to the characteristic identified by either a bluepy.btle.Characteristic object characteristic, or a UUID string uuid. If both are provided, then the characteristic will be read on the basis of the characteristic object. A bluepy.btle.BTLEException.GATT_ERROR is raised if no inputs are specified or the requested characteristic was not found. If withResponse is True, the client will await confirmation that the write was successful from the device.

Parameters:

• val (str on Python 2.x, byte on 3.x) – Value to be written in characteristic
• characteristic (bluepy.btle.Characteristic, optional) – A bluepy.btle.Characteristic object, defaults to None
• uuid (string, optional) – A given UUID string, defaults to None
• withResponse (bool, optional) – If withResponse is True, the client will await confirmation that the write was successful from the device, defaults to False

Raises:

bluepy.btle.BTLEException.GATT_ERROR: If no inputs are specified or the requested characteristic was not found.

Returns:

True or False indicating success or failure of write operation, in the case that withResponce is True

Return type:

bool

The SimpleBleDevice class

class simpleble.SimpleBleDevice(client, addr=None, addrType='public', iface=0, data=None, rssi=0, connectable=False, updateCount=0)

Bases: bluepy.btle.Peripheral

This is a conceptual class representation of a simple BLE device (GATT Server). It is essentially an extended combination of the bluepy.btle.Peripheral and bluepy.btle.ScanEntry classes

Parameters:

• client (class:simpleble.SimpleBleClient) – A handle to the simpleble.SimpleBleClient client object that detected the device
• addr (str, optional) – Device MAC address, defaults to None
• addrType (str, optional) – Device address type - one of ADDR_TYPE_PUBLIC or ADDR_TYPE_RANDOM, defaults to ADDR_TYPE_PUBLIC
• iface (int, optional) – Bluetooth interface number (0 = /dev/hci0) used for the connection, defaults to 0
• data (list, optional) – A list of tuples (adtype, description, value) containing the AD type code, human-readable description and value for all available advertising data items, defaults to None
• rssi (int, optional) – Received Signal Strength Indication for the last received broadcast from the device. This is an integer value measured in dB, where 0 dB is the maximum (theoretical) signal strength, and more negative numbers indicate a weaker signal, defaults to 0
• connectable (bool, optional) – True if the device supports connections, and False otherwise (typically used for advertising ‘beacons’)., defaults to False
• updateCount (int, optional) – Integer count of the number of advertising packets received from the device so far, defaults to 0

connect()

Attempts to initiate a connection with the device.

Returns:True if connection was successful, False otherwise Return type:bool

disconnect()

Drops existing connection to device

getCharacteristics(startHnd=1, endHnd=65535, uuids=None)

Returns a list containing bluepy.btle.Characteristic objects for the peripheral. If no arguments are given, will return all characteristics. If startHnd and/or endHnd are given, the list is restricted to characteristics whose handles are within the given range.

Parameters:

• startHnd (int, optional) – Start index, defaults to 1
• endHnd (int, optional) – End index, defaults to 0xFFFF
• uuids (list, optional) – a list of UUID strings, defaults to None

Returns:

List of returned bluepy.btle.Characteristic objects

Return type:

list

getServices(uuids=None)

Returns a list of bluepy.blte.Service objects representing the services offered by the device. This will perform Bluetooth service discovery if this has not already been done; otherwise it will return a cached list of services immediately..

Parameters:uuids (list, optional) – A list of string service UUIDs to be discovered, defaults to None Returns:A list of the discovered bluepy.blte.Service objects, which match the provided uuids Return type:list On Python 3.x, this returns a dictionary view object, not a list

isConnected()

Checks to see if device is connected

Returns:True if connected, False otherwise Return type:bool

printInfo()

Print info about device

setNotificationCallback(callback)

Set the callback function to be executed when the device sends a notification to the client.

Parameters:callback (function, optional) – A function handle of the form callback(client, characteristic, data), where client is a handle to the simpleble.SimpleBleClient that invoked the callback, characteristic is the notified bluepy.blte.Characteristic object and data is a bytearray containing the updated value. Defaults to None

The SimpleBleScanDelegate class

class simpleble.SimpleBleScanDelegate(callback, client=None)

Bases: bluepy.btle.DefaultDelegate

handleDiscovery(scanEntry, isNewDevice, isNewData)

The SimpleBleNotificationDelegate class

class simpleble.SimpleBleNotificationDelegate(callback, client)

Bases: bluepy.btle.DefaultDelegate

handleNotification(characteristic, data)