add button constants; improve examples and doc

README.rst

@@ -28,11 +28,20 @@ This is easily achieved by downloading
 Usage Example
 =============
 
+Normally this library is used with the
+`Adafruit_CircuitPython_BluefruitConnect
+<https://github.com/adafruit/Adafruit_CircuitPython_BluefruitConnnect>`_
+library
+(``adafruit_bluefruit_connect``). The included examples use that library.
+Below is a simple standalone example.
+
 .. code-block:: python
 
     from adafruit_bluefruit_connect.color_packet import ColorPacket
     from adafruit_bluefruit_connect.gyro_packet import GyroPacket
 
+    # [uart setup omitted]
+
     color_packet = ColorPacket((70,75,80))
     gyro_packet = GyroPacket.from_bytes(packet_buf)
     uart.write(gyro_packet.to_bytes())

adafruit_bluefruit_connect/button_packet.py

@@ -35,7 +35,25 @@
 from .packet import Packet
 
 class ButtonPacket(Packet):
-    """A packet containing a button name and its state"""
+    """A packet containing a button name and its state."""
+
+    BUTTON_1 = '1'
+    """Code for Button 1 on the Bluefruit LE Connect app Control Pad screen."""
+    BUTTON_2 = '2'
+    """Button 2."""
+    BUTTON_3 = '3'
+    """Button 3."""
+    BUTTON_4 = '4'
+    """Button 4."""
+    #pylint: disable= invalid-name
+    UP = '5'
+    """Up Button."""
+    DOWN = '6'
+    """Down Button."""
+    LEFT = '7'
+    """Left Button."""
+    RIGHT = '8'
+    """Right Button."""
 
     _FMT_PARSE = '<xxssx'
     PACKET_LENGTH = struct.calcsize(_FMT_PARSE)
@@ -76,7 +94,7 @@ def to_bytes(self):
 
     @property
     def button(self):
-        """Button designator: a single character string (not bytes)."""
+        """A single character string (not bytes) specifying the button."""
         return self._button
 
     @property

adafruit_bluefruit_connect/color_packet.py

@@ -58,7 +58,9 @@ def __init__(self, color):
 
     @classmethod
     def parse_private(cls, packet):
-        """Construct a ColorPacket from an incoming packet."""
+        """Construct a ColorPacket from an incoming packet.
+        Do not call this directly; call Packet.from_bytes() instead.
+        """
         return cls(struct.unpack(cls._FMT_PARSE, packet))
 
     def to_bytes(self):

docs/examples.rst

@@ -9,6 +9,6 @@ Ensure your device works with this simple test.
 
 This test demonstrates controlling an Adafruit Crickit board with Bluetooth.
 
-.. literalinclude:: ../examples/bluefruit_connect_crickit_test.py
-    :caption: examples/bluefruit_connect_crickit_test.py
+.. literalinclude:: ../examples/bluefruit_connect_accelerometer_packet_test.py
+    :caption: examples/bluefruit_connect_accelerometer_packet_test.py
     :linenos:

examples/bluefruit_connect_accelerometer_packet_test.py

@@ -0,0 +1,23 @@
+# Stream accelerometer data from your phone or tablet.
+# To use, start this program, and start the Adafruit Bluefruit LE Connect app.
+# Connect and go to the Controller screen. Turn on
+# STREAM SENSOR DATA -> Accelerometer to send data from the device's
+# accelerometer. See how it matches what this prints.
+
+from adafruit_ble.uart import UARTServer
+from adafruit_bluefruit_connect.packet import Packet
+# Only the packet classes that are imported will be known to Packet.
+from adafruit_bluefruit_connect.accelerometer_packet import AccelerometerPacket
+
+uart_server = UARTServer()
+
+while True:
+    # Advertise when not connected.
+    uart_server.start_advertising()
+    while not uart_server.connected:
+        pass
+
+    while uart_server.connected:
+        packet = Packet.from_stream(uart_server)
+        if isinstance(packet, AccelerometerPacket):
+            print(packet.x, packet.y, packet.z)

examples/bluefruit_connect_simpletest.py

@@ -1,4 +1,6 @@
-# Print out the color data from a ColorPacket.
+# Print out the color data from ColorPackets.
+# To use, start this program, and start the Adafruit Bluefruit LE Connect app.
+# Connect, and then select colors on the Controller->Color Picker screen.
 
 from adafruit_ble.uart import UARTServer
 from adafruit_bluefruit_connect.packet import Packet
@@ -7,18 +9,13 @@
 
 uart_server = UARTServer()
 
-advertising_now = False
-
 while True:
-    if not uart_server.connected:
-        if not advertising_now:
-            uart_server.start_advertising()
-            advertising_now = True
-        continue
-
-    # Connected, so no longer advertising
-    advertising_now = False
+    # Advertise when not connected.
+    uart_server.start_advertising()
+    while not uart_server.connected:
+        pass
 
-    packet = Packet.from_stream(uart_server)
-    if isinstance(packet, ColorPacket):
-        print(packet.color)
+    while uart_server.connected:
+        packet = Packet.from_stream(uart_server)
+        if isinstance(packet, ColorPacket):
+            print(packet.color)