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:

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
