Updated BLE notifications. Updated documentation.

CHANGELOG.rst

@@ -2,6 +2,12 @@
 Change Log
 ==========
 
+v.0.7.1
+-------
+
+* revised documentation
+* improved BLE notifcation callbacks
+
 v.0.7.0
 -------
 

doc/apireference.rst

@@ -174,4 +174,11 @@ Running scripts
     PFxBrick.run_script
     PFxBrick.stop_script
 
+BLE Notifications
+-----------------
 
+.. currentmodule:: pfxbrick.pfxble
+
+.. autosummary::
+    PFxBrickBLE.set_notifications
+    PFxBrickBLE.disable_notifications

doc/conf.py

@@ -57,7 +57,7 @@
 # The short X.Y version.
 version = "0.7"
 # The full version, including alpha/beta/rc tags.
-release = "0.7.0"
+release = "0.7.1"
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

doc/examples.rst

@@ -322,3 +322,73 @@ The same script but implemented for a BLE connected PFx Brick:
     if len(pfxdevs) > 0:
         bricks = loop.run_until_complete(find_ble_pfxbricks(pfxdevs))
         loop.run_until_complete(brick_session(bricks[0]))
+
+BLE Notifications
+-----------------
+
+This example shows how to activate PFx Brick notifications to be sent asynchronously to a client application.  Notification events can trigger your own callback functions for handling within your application.
+
+.. code-block:: python
+
+    #! /usr/bin/env python3
+
+    # PFx Brick example script to demonstrate using notifications from PFx Brick
+
+    import asyncio
+
+    from pfxbrick import *
+
+
+    # our callback functions for notification events
+    def motor_a_stopped():
+        print("Motor ch A has stopped")
+
+    def motor_a_speed_change(speed):
+        print("Motor ch A has changed speed to %d" % (speed))
+
+    def audio_file_started(fileid, filename):
+        print("Audio playback has started for file %d: %s" % (fileid, filename))
+
+    async def brick_session(brickdev):
+        brick = PFxBrickBLE(dev_dict=brickdev, debug=False)
+        await brick.open()
+
+        # register our notification callback functions
+        brick.callback_motora_stop = motor_a_stopped
+        brick.callback_motora_speed = motor_a_speed_change
+        brick.callback_audio_play = audio_file_started
+
+        # activate our desired PFx Brick notifications
+        await brick.set_notifications(
+            PFX_NOTIFICATION_AUDIO_PLAY | 
+            PFX_NOTIFICATION_MOTORA_STOP | 
+            PFX_NOTIFICATION_MOTORA_CURR_SPD
+        )
+
+        # Motor channel A forward 50% speed
+        await brick.set_motor_speed([1], -50)
+        await asyncio.sleep(3)
+
+        # Stop motor A
+        await brick.stop_motor([1])
+        await asyncio.sleep(1)
+
+        # Motor channel A reverse 33% speed for 2 sec self-timed
+        await brick.set_motor_speed([1], 33, 2)
+
+        await asyncio.sleep(1)
+        await brick.play_audio_file(2)
+        await asyncio.sleep(2)
+
+        # turn off notifications
+        await brick.disable_notifications()
+
+        await brick.close()
+
+
+    loop = asyncio.get_event_loop()
+    pfxdevs = loop.run_until_complete(ble_device_scanner())
+    print("Found %d PFx Bricks" % (len(pfxdevs)))
+    if len(pfxdevs) > 0:
+        bricks = loop.run_until_complete(find_ble_pfxbricks(pfxdevs))
+        loop.run_until_complete(brick_session(bricks[0]))

doc/installation.rst

@@ -8,7 +8,7 @@ The PFx Brick python API has very few dependencies and should be relatively stra
 Dependencies
 ------------
 
-* Python 3.6
+* Python 3.6+
 
 * `HIDAPI <https://github.com/signal11/hidapi>`_
 

examples/ble_notifications.py

@@ -0,0 +1,65 @@
+#! /usr/bin/env python3
+
+# PFx Brick example script to demonstrate using notifications from PFx Brick
+
+import asyncio
+
+from pfxbrick import *
+
+
+# our callback functions for notification events
+def motor_a_stopped():
+    print("Motor ch A has stopped")
+
+
+def motor_a_speed_change(speed):
+    print("Motor ch A has changed speed to %d" % (speed))
+
+
+def audio_file_started(fileid, filename):
+    print("Audio playback has started for file %d: %s" % (fileid, filename))
+
+
+async def brick_session(brickdev):
+    brick = PFxBrickBLE(dev_dict=brickdev, debug=False)
+    await brick.open()
+
+    # register our notification callback functions
+    brick.callback_motora_stop = motor_a_stopped
+    brick.callback_motora_speed = motor_a_speed_change
+    brick.callback_audio_play = audio_file_started
+
+    # activate our desired PFx Brick notifications
+    await brick.set_notifications(
+        PFX_NOTIFICATION_AUDIO_PLAY
+        | PFX_NOTIFICATION_MOTORA_STOP
+        | PFX_NOTIFICATION_MOTORA_CURR_SPD
+    )
+
+    # Motor channel A forward 50% speed
+    await brick.set_motor_speed([1], -50)
+    await asyncio.sleep(3)
+
+    # Stop motor A
+    await brick.stop_motor([1])
+    await asyncio.sleep(1)
+
+    # Motor channel A reverse 33% speed for 2 sec self-timed
+    await brick.set_motor_speed([1], 33, 2)
+
+    await asyncio.sleep(1)
+    await brick.play_audio_file(2)
+    await asyncio.sleep(2)
+
+    # turn off notifications
+    await brick.disable_notifications()
+
+    await brick.close()
+
+
+loop = asyncio.get_event_loop()
+pfxdevs = loop.run_until_complete(ble_device_scanner())
+print("Found %d PFx Bricks" % (len(pfxdevs)))
+if len(pfxdevs) > 0:
+    bricks = loop.run_until_complete(find_ble_pfxbricks(pfxdevs))
+    loop.run_until_complete(brick_session(bricks[0]))

pfxbrick/__init__.py

@@ -4,7 +4,7 @@
 
 # fmt: off
 __project__ = 'pfxbrick'
-__version__ = '0.7.0'
+__version__ = '0.7.1'
 # fmt: on
 
 VERSION = __project__ + "-" + __version__