Core Classes

Below are quick descriptions and links to the primary/core classes that are used to perform the various Bluetooth operations. This information, including more thorough usage, can be found within example code (Examples)

Events

The Event type is the basic building block of the blatann library.

Bluetooth operations are inherently asynchronous, thus asynchronous events must be used in order to communicate when things happen.

Almost all of the classes below implement one or more Events which can have multiple handler functions registered to process incoming data. Event properties are commonly named in the format of on_*, such as on_timeout or on_read_complete. The event properties also document the parameter types that the handler should accept. Majority of the events emit two parameters, a sender parameter, which provides the event source, and an event_args parameter, which provides the data associated with the event. Those familiar with C#/.NET, this should look very similar.

def my_handler(sender, event_args):
    # Handle the event
some_object.on_some_event.register(my_handler)

Waitables

Waitable, EventWaitable

Waitables are the solution to providing an API which supports synchronous, procedural code given the asynchronous nature of Bluetooth. For every asynchronous Bluetooth operation that is performed a Waitable object is returned which the user can then wait() on to block the current thread until the operation completes.

sender, event_args = characteristic.read().wait(timeout=5)

Note

Take care to not call wait() within an event handler as the system will deadlock (see Threading section under Library Architecture for more info).

Asynchronous paradigms are also supported through waitables where the user can register a handler to be called when the operation completes:

def my_characteristic_read_handler(sender, event_args):
    # Handle read complete
characteristic.read().then(my_characteristic_read_handler)

BLE Device

The BleDevice represents Nordic Bluetooth microcontroller itself. It is the root object of everything within this library.

To get started, instantiate a BleDevice and open it:

from blatann import BleDevice

ble_device = BleDevice("COM1")
ble_device.configure()
ble_device.open()
# Ready to use

The BLE Device is also responsible for initiating connections to peripheral devices and managing the local GATT database.

Advertising

The Advertiser component is accessed through the ble_device.advertiser attribute. It is configured using AdvertisingData objects to set the payloads to advertise

from blatann.gap.advertising import AdvertisingData
adv_data = AdvertisingData(flags=0x06, local_name="My Name")
scan_data = AdvertisingData(service_uuid16s="123F")
ble_device.advertiser.set_advertise_data(adv_data, scan_data)
ble_device.advertiser.start(adv_interval_ms=50)

Scanning

The Scanner component is accessed through the ble_device.scanner attribute.

The scanner output consists of a ScanReportCollection, which is comprised of ScanReport objects that represent advertising packets discovered.

scan_report_collection = ble_device.scanner.start_scan().wait(timeout=20)

Peer

The Peer class represents a Bluetooth connection to another device.

For connections as a peripheral to a central device, this peer object is static and accessed via the ble_device.client attribute. For connections as a central to a peripheral device, the peer is created as a result of BleDevice.connect.

Regardless of the connection type, the Peer is the basis for any connection-oriented Bluetooth operation, such as configuring the MTU, discovering databases, reading/writing characteristics, etc.

# Connect to a peripheral and exchange MTU
peer = ble_device.connect(peer_address).wait()
peer.exchange_mtu(144).wait()
# Exchange the MTU with a client
ble_device.client.exchange_mtu(183).wait()

Security

The processes for pairing and bonding is managed by a peer’s SecurityManager, accessed via the peer.security attribute.

Local GATT Database

The GattsDatabase is accessed through the ble_device.database attribute. The database holds all of the services and characteristics that can be discovered and interacted with by a client.

GattsService s can be added to the database and GattsCharacteristic s are added to the services. The primary interaction point is through characteristics, which provides methods for setting values, handling writes, and notifying values to the client.

Remote GATT Database

The peer’s GattcDatabase is accessed through the peer.database attribute. The database is populated through the peer.discover_services procedure. From there, the Peer’s GattcCharacteristic s can be read, written, and subscribed to.