notifications.rst

Working with notifications

In bluepy, notifications are processed by creating a "delegate" object and registering it with the Peripheral. A method in the delegate is called whenever a notification is received from the peripheral, as shown below:

.. function:: handleNotification(cHandle, data)

    Called when a notification has been received from a ``Peripheral``. Normally
    you will call the peripheral's ``waitForNotifications()`` method to allow this,
    but note that a Bluetooth LE device may transmit notifications at any time. This
    means that *handleNotification()* can potentially be called when any BluePy call
    is in progress.

    The *cHandle* parameter is the GATT 'handle' for the characteristic which is
    sending the notification. If a peripheral sends notifications for more than one
    characteristic, this may be used to distinguish them. The 'handle' value can be
    found by calling the ``getHandle()`` method of a ``Characteristic`` object.

    The *data* parameter is a ``str`` (Python 2.x) or ``bytes`` (Python 3.x) value
    containing the notification data. It is recommended you use Python's ``struct``
    module to unpack this, to allow portability between language versions.

It is recommended that the class used for the delegate object is derived from btle.DefaultDelegate. This will ensure that an appropriate default method exists for any future calls which may be added to the delegate interface.

Example code

Code to receive notifications from a peripheral can follow the outline below:

import btle

class MyDelegate(btle.DefaultDelegate):
    def __init__(self, params):
        btle.DefaultDelegate.__init__(self)
        # ... initialise here

    def handleNotification(self, cHandle, data):
        # ... perhaps check cHandle
        # ... process 'data'


# Initialisation  -------

p = btle.Peripheral( address )
p.setDelegate( MyDelegate(params) )

# Setup to turn notifications on, e.g.
#   svc = p.getServiceByUUID( service_uuid )
#   ch = svc.getCharacteristics( char_uuid )[0]
#   ch.write( setup_data )

# Main loop --------

while True:
    if p.waitForNotifications(1.0):
        # handleNotification() was called
        continue

    print "Waiting..."
    # Perhaps do something else here