Merge pull request #2 from dhalbert/master

use namedtuple for measurement_value

Author: dhalbert

adafruit_ble_heart_rate.py

@@ -41,8 +41,9 @@
 * Adafruit's BLE library: https://github.com/adafruit/Adafruit_CircuitPython_BLE
 """
 import struct
-import _bleio
+from collections import namedtuple
 
+import _bleio
 from adafruit_ble.services import Service
 from adafruit_ble.uuid import StandardUUID
 from adafruit_ble.characteristics import Characteristic, ComplexCharacteristic
@@ -51,6 +52,37 @@
 __version__ = "0.0.0-auto.0"
 __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_BLE_Heart_Rate.git"
 
+HeartRateMeasurementValues = namedtuple(
+    "HeartRateMeasurementValues",
+    ("heart_rate", "contact", "energy_expended", "rr_intervals"))
+"""Namedtuple for measurement values.
+
+.. py:attribute:: HeartRateMeasurementValues.heart_rate
+
+        Heart rate (int), in beats per minute.
+
+.. py:attribute:: HeartRateMeasurementValues.contact
+
+        ``True`` if device is contacting the body, ``False`` if not,
+        ``None`` if device does not support contact detection.
+
+.. py:attribute:: HeartRateMeasurementValues.energy_expended
+
+        Energy expended (int), in kilo joules, or ``None`` if no value.
+
+.. py:attribute:: HeartRateMeasurementValues.rr_intervals
+
+        Sequence of RR intervals, measuring the time between
+        beats. Oldest first, in ints that are units of 1024ths of a second.
+        This sequence will be empty if the device does not report the intervals.
+        *Caution:* inexpensive heart rate monitors may not measure this
+        accurately. Do not use for diagnosis.
+
+For example::
+
+    bpm = svc.measurement_values.heart_rate
+"""
+
 class _HeartRateMeasurement(ComplexCharacteristic):
     """Notify-only characteristic of streaming heart rate data."""
     uuid = StandardUUID(0x2A37)
@@ -109,15 +141,10 @@ def __init__(self, service=None):
 
     @property
     def measurement_values(self):
-        """All the measurement values, as a tuple:
-        (heart_rate, contact, energy_expended, rr_intervals)
-        * heart_rate: int (beats per minute)
-        * contact: True if contacting, False if not, None if unknown
-        * energy_expended: int (Kilo joules), or None if no value
-        * rr_intervals: list of RR-intervals, if any,
-        oldest first, in ints that are1024ths of a second,
-
-        Return None if no packet has been read yet.
+        """All the measurement values, returned as a HeartRateMeasurementValues
+        namedtuple.
+
+        Return ``None`` if no packet has been read yet.
         """
         buf = self._measurement_buf
         packet_length = self.heart_rate_measurement.readinto(buf)
@@ -152,7 +179,7 @@ def measurement_values(self):
                 rr_val = struct.unpack_from("<H", buf, offset)[0]
                 rr_values.append(rr_val)
 
-        return (bpm, contact, energy_expended, rr_values)
+        return HeartRateMeasurementValues(bpm, contact, energy_expended, rr_values)
 
     @property
     def location(self):
@@ -163,6 +190,10 @@ def location(self):
         For instance, some armbands are meant to be worn just below the inner elbow,
         but that is not a prescribed location. So the sensor will report something
         else, such as "Wrist".
+
+        Possible values are:
+        "Other", "Chest", "Wrist", "Finger", "Hand", "Ear Lobe", "Foot", and
+        "InvalidLocation" (if value returned does not match the specification).
         """
 
         try:

docs/api.rst

@@ -1,8 +1,2 @@
-
-.. If you created a package, create one automodule per module in the package.
-
-.. If your library file(s) are nested in a directory (e.g. /adafruit_foo/foo.py)
-.. use this format as the module name: "adafruit_foo.foo"
-
 .. automodule:: adafruit_ble_heart_rate
    :members: