ABlePeripheral¶

ABlePeripheral is the core class that ABle revolves around. This is the class which accepts advertisements 1 to advertise, handles the GATT table 2 the peripheral will be using with ABleService and ABleCharacteristic, and operates as a socket server, waiting for and returning ABleCentral instances once a central connects which can be communicated with similarly to how a Berkeley socket would 3.

Class Definition¶

class able.peripheral.ABlePeripheralServer(name='ABle', *, auto_recover=True, adapter_path=None, auto_configure=False, loop=<_UnixSelectorEventLoop running=False closed=False debug=False>)[source]¶

A platform agnostic Ble Peripheral Server Class. This class serves as the high level client for the ABle library and serves as the main interface into the low level platform specific-backends.

Class attribute _app will be the AbleApplication for the platform this server is running on (eg. BluezDbus App).

Note that this class doesn’t track the advertisements, services, nor characteristics that the application tracks under the hood.

Parameters

name (str) – The name you wish to bind to this application on the DBus, defaults to “ABle”
auto_recover (bool) – Set to True if you want the underlying application to attempt to recover on driver or other incidents
auto_configure (bool) – Set to True if you want ABle to do a best effort attempt to configure permissions on your system to allow ABle to work, defaults to False

Methods¶

Initialization¶

This must be ran before any other methods as it will handle all the underlying setup required on the platform to be able to add advertisements, services, characteristics and more later on.

async able.peripheral.ABlePeripheralServer.setup_peripheral_server(self)¶

Handle all the setup that the underlying application needs to do within the running event loop. This needs to be a separate asynchronous function from the initializer for the class because the setup() function for the app may be async as well.

TODO(Bernie): Is there a scenario where we have the __init__() call this directly?

Return type: None
Returns: None

Setup¶

These are used to do any setup before launching the server, setup the gatt table and configure advertisements here.

async able.peripheral.ABlePeripheralServer.add_advertisement(self, advertisement)¶

Add an advertisement to the peripheral server. Note that the underlying application manages checking whether or not you are over the advertisement limit, if the advertisement has already been added and more on a platform specific basis.

TODO(Ori): As we develop the OSX backend there may be duplicated code in the _app.add_advertisement(): implementation that we should extract to here?

Parameters: advertisement (ABleAdvertisement) – An instance of ABleAdvertisement to add to the application this server is running.
Return type: None
Returns: None

async able.peripheral.ABlePeripheralServer.remove_advertisement(self, advertisement)¶

Removes an advertisement from the underlying application, note that the application will handle removal with a bunch of validation.

TODO(Bernie): Ensure that this works at runtime, we should be able to have the APS remove an advert: and refresh the application to make it vanish.

Parameters: advertisement (ABleAdvertisement) – The advertisement you want to have removed from the server.
Return type: None
Returns: None

able.peripheral.ABlePeripheralServer.add_service(self, service)¶

Adds a BLEService to the peripheral server using the underlying application.

Parameters: service (ABleService) – the service to add to the application
Return type: None
Returns: None

able.peripheral.ABlePeripheralServer.add_characteristic(self, service, characteristic, is_comms_char=False)¶

Adds a BLECharacteristic to the peripheral server using the underlying application.

Parameters

is_comms_char (bool) – True will set the characteristic as the communications characteristic, defaults to False
service (ABleService) – the service to add the characteristic too
characteristic (Union[List[ABleCharacteristic], ABleCharacteristic]) – the characteristic to add, this can also be a list of ABleCharacteristics and each will be added for batch adding.

Return type

None

Returns

None

State¶

Run the listen method to start the peripheral server and close to stop it.

async able.peripheral.ABlePeripheralServer.listen(self, remove_connected=False)¶

Listen is the equivalent its Berkeley Socket API counterpart, it will handle any binding that is required and sets the application to be in a “listening state”.

Parameters: remove_connected (bool) – if True remove all currently connected centrals, (default is False)
Return type: None
Returns: None

async able.peripheral.ABlePeripheralServer.close(self)¶

Equivalent to the socket API’s close, this will cleanup all existing connections that the app is managing and trigger all cleanup within the app (eg. removing match rules).

Return type: None
Returns: None

Connections¶

Just as you would with a berkeley socket, use the accept function to get ABleCentral once a connection has been established, see the programming guide for the peripheral server for more.

async able.peripheral.ABlePeripheralServer.accept(self)¶

Blocking call which polls the new connection queue (NCQ) of the underlying application to see if there are any new connections. Will only return a ABleCentral once it is present on the NCQ and the app’s connected central dict.

Return type: ABleCentral
Returns: A newly connected ABleCentral object ready to be interacted with

Broadcasting¶

On top of communicating with just one central, the peripheral can broadcast to all peripherals on a given characteristic using broadcast

async able.peripheral.ABlePeripheralServer.broadcast(self, data, characteristic=None)¶

This function will notify all connected centrals on the provided characteristic of new data, for example notifying all centrals of the battery level, a state of this peripheral, etc.

# TODO(Bernie): How should we handle this with possibly different MTU’s for different centrals

Parameters

characteristic (ABleCharacteristic) – the characteristic to notify all connected centrals on, defaults to the comms characteristic
data (Union[bytes, str]) – the data to notify the centrals on

Return type

None

Returns

None

References¶

1: Quickstart to BLE Advertisements
2: Introduction to GATT Tables
3: Berkeley Socket API