From 7b78f3d40a1e36b8c0c14be64268116441b9e813 Mon Sep 17 00:00:00 2001
From: Dan Halbert <halbert@halwitz.org>
Date: Tue, 28 Jan 2020 12:42:24 -0500
Subject: [PATCH 1/3] use namedtuple for measurement_value

---
 adafruit_ble_heart_rate.py | 51 ++++++++++++++++++++++++++++++--------
 docs/api.rst               |  6 -----
 2 files changed, 41 insertions(+), 16 deletions(-)

diff --git a/adafruit_ble_heart_rate.py b/adafruit_ble_heart_rate.py
index 928fe5b..6ba4eda 100644
--- a/adafruit_ble_heart_rate.py
+++ b/adafruit_ble_heart_rate.py
@@ -42,6 +42,7 @@
 """
 import struct
 import _bleio
+from collections import namedtuple
 
 from adafruit_ble.services import Service
 from adafruit_ble.uuid import StandardUUID
@@ -51,6 +52,37 @@
 __version__ = "0.0.0-auto.0"
 __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_BLE_Heart_Rate.git"
 
+HeartRateMeasurementValue = namedtuple(
+    "HeartRateMeasurementValue",
+    ("heart_rate", "contact", "energy_expended", "rr_intervals"))
+"""Namedtuple for the parts of a measurement value.
+
+.. py:attribute:: HeartRateMeasurementValue.heart_rate
+
+        Heart rate (int), in beats per minute.
+
+.. py:attribute:: HeartRateMeasurementValue.contact
+
+        ``True`` if device is contacting the body, ``False`` if not,
+        ``None`` if device does not support contact detection.
+
+.. py:attribute:: HeartRateMeasurementValue.energy_expended
+
+        Energy expended (int), in kilo joules, or ``None`` if no value.
+
+.. py:attribute:: HeartRateMeasurementValue.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_value.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 HeartRateMeasurementValue
+        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 HeartRateMeasurementValue(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:
diff --git a/docs/api.rst b/docs/api.rst
index 6f77e54..0150144 100644
--- a/docs/api.rst
+++ b/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:

From b9b61af74be094e9f053b9ff4d9c0f6c646746e6 Mon Sep 17 00:00:00 2001
From: Dan Halbert <halbert@halwitz.org>
Date: Tue, 28 Jan 2020 13:03:50 -0500
Subject: [PATCH 2/3] pylint: fix import order

---
 adafruit_ble_heart_rate.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/adafruit_ble_heart_rate.py b/adafruit_ble_heart_rate.py
index 6ba4eda..8f0f423 100644
--- a/adafruit_ble_heart_rate.py
+++ b/adafruit_ble_heart_rate.py
@@ -41,9 +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

From 72e90cbdcfdee6f7da86f0fb05c1f2e0dcd52484 Mon Sep 17 00:00:00 2001
From: Dan Halbert <halbert@halwitz.org>
Date: Tue, 28 Jan 2020 13:48:52 -0500
Subject: [PATCH 3/3] Fix HeartRateMeasurementValues to be plural to match
 original property

---
 adafruit_ble_heart_rate.py | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/adafruit_ble_heart_rate.py b/adafruit_ble_heart_rate.py
index 8f0f423..507634f 100644
--- a/adafruit_ble_heart_rate.py
+++ b/adafruit_ble_heart_rate.py
@@ -52,25 +52,25 @@
 __version__ = "0.0.0-auto.0"
 __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_BLE_Heart_Rate.git"
 
-HeartRateMeasurementValue = namedtuple(
-    "HeartRateMeasurementValue",
+HeartRateMeasurementValues = namedtuple(
+    "HeartRateMeasurementValues",
     ("heart_rate", "contact", "energy_expended", "rr_intervals"))
-"""Namedtuple for the parts of a measurement value.
+"""Namedtuple for measurement values.
 
-.. py:attribute:: HeartRateMeasurementValue.heart_rate
+.. py:attribute:: HeartRateMeasurementValues.heart_rate
 
         Heart rate (int), in beats per minute.
 
-.. py:attribute:: HeartRateMeasurementValue.contact
+.. py:attribute:: HeartRateMeasurementValues.contact
 
         ``True`` if device is contacting the body, ``False`` if not,
         ``None`` if device does not support contact detection.
 
-.. py:attribute:: HeartRateMeasurementValue.energy_expended
+.. py:attribute:: HeartRateMeasurementValues.energy_expended
 
         Energy expended (int), in kilo joules, or ``None`` if no value.
 
-.. py:attribute:: HeartRateMeasurementValue.rr_intervals
+.. 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.
@@ -80,7 +80,7 @@
 
 For example::
 
-    bpm = svc.measurement_value.heart_rate
+    bpm = svc.measurement_values.heart_rate
 """
 
 class _HeartRateMeasurement(ComplexCharacteristic):
@@ -141,7 +141,7 @@ def __init__(self, service=None):
 
     @property
     def measurement_values(self):
-        """All the measurement values, returned as a HeartRateMeasurementValue
+        """All the measurement values, returned as a HeartRateMeasurementValues
         namedtuple.
 
         Return ``None`` if no packet has been read yet.
@@ -179,7 +179,7 @@ def measurement_values(self):
                 rr_val = struct.unpack_from("<H", buf, offset)[0]
                 rr_values.append(rr_val)
 
-        return HeartRateMeasurementValue(bpm, contact, energy_expended, rr_values)
+        return HeartRateMeasurementValues(bpm, contact, energy_expended, rr_values)
 
     @property
     def location(self):