Merge branch 'develop' and PR #49

Pipfile

@@ -17,3 +17,4 @@ tqdm = "*"
 pytest = "*"
 sphinx = "*"
 sphinx-rtd-theme = "*"
+pylint = "*"

docs/source/client.rst

@@ -10,7 +10,7 @@ The MetaWear client provided by this package. It can be used as such:
     from pymetawear.client import MetaWearClient
     c = MetaWearClient('DD:3A:7D:4D:56:F0')
 
-The client can now be used for e.g. subscribing to data signals or logging data.
+The client can now be used for either reading the current module data or activating some functionality in it. 
 
 API
 ---

docs/source/modules/accelerometer.rst

@@ -10,7 +10,10 @@ It is initialized at the creation of the :py:class:`~MetaWearClient`
 client and can then be accessed in the ``accelerometer``
 attribute of the client.
 
-Example usage:
+Data streaming example
+----------------------
+
+If you need a real time stream of sensor data, use the :py:method:`notifications` method on the :py:mod:`accelerometer` module:
 
 .. code-block:: python
 
@@ -28,6 +31,58 @@ Example usage:
     # Enable notifications and register a callback for them.
     c.accelerometer.notifications(acc_callback)
 
+Logging example
+---------------
+
+If you want to log data to the MetaWear board and retrieve it after some time, then use the
+:py:method:`start_logging`, :py:method:`stop_logging` and :py:method:`download_log` methods:
+
+.. code-block:: python
+
+    import json
+    from pymetawear.client import MetaWearClient
+    from pymetawear.exceptions import PyMetaWearException, PyMetaWearDownloadTimeout
+
+    c = MetaWearClient('DD:3A:7D:4D:56:F0')
+
+    # Set data rate to 200 Hz and measuring range to +/- 8g
+    c.accelerometer.set_settings(data_rate=200.0, data_range=8)
+
+    # Log data for 10 seconds.
+    client.accelerometer.start_logging()
+    print("Logging accelerometer data...")
+
+    time.sleep(10.0)
+
+    client.accelerometer.stop_logging()
+    print("Finished logging.")
+
+    # Download the stored data from the MetaWear board.
+    print("Downloading data...")
+    download_done = False
+    n = 0
+    data = None
+    while download_done and n < 3:
+        try:
+            data = client.accelerometer.download_log()
+            download_done = True
+        except PyMetaWearDownloadTimeout:
+            print("Download of log interrupted. Trying to reconnect...")
+            client.disconnect()
+            client.connect()
+            n += 1
+    if data is None:
+        raise PyMetaWearException("Download of logging data failed.")
+
+    print("Disconnecting...")
+    client.disconnect()
+
+    # Save the logged data.
+    data_file = os.path.join(os.getcwd(), "logged_data.json")
+    print("Saving the data to file: {0}".format(data_file))
+    with open("logged_data.json", "wt") as f:
+        json.dump(data, f, indent=2)
+    
 API
 ---
 

docs/source/modules/ambientlight.rst

@@ -0,0 +1,39 @@
+.. _modules_accelerometer:
+
+Ambient light module
+====================
+
+The PyMetaWear implementation of the ``libmetawear``
+ambient light module.
+
+It is initialized at the creation of the :py:class:`~MetaWearClient`
+client and can then be accessed in the ``ambient_light``
+attribute of the client.
+
+Data streaming example
+----------------------
+
+If you need a real time stream of sensor data, use the :py:method:`notifications` method on the :py:mod:`ambient_light` module:
+
+.. code-block:: python
+
+    from pymetawear.client import MetaWearClient
+
+    c = MetaWearClient('DD:3A:7D:4D:56:F0')
+
+    print("Write ambient light settings...")
+    c.ambient_light.set_settings(gain=4, integration_time=200, measurement_rate=200)
+
+    def ambient_light_callback(data):
+        """Handle a (epoch, data) ambient light data tuple."""
+        print("Epoch time: [{0}] Data: {1}".format(data[0], data[1]))
+
+    # Enable notifications and register a callback for them.
+    c.ambient_light.notifications(ambient_light_callback)
+    
+
+API
+---
+
+.. automodule:: pymetawear.modules.ambientlight
+   :members:

docs/source/modules/gyroscope.rst

@@ -12,7 +12,10 @@ attribute of the client.
 
 The only MetaWear gyroscope available is the BMI160 sensor.
 
-Example usage:
+Data streaming example
+----------------------
+
+If you need a real time stream of sensor data, use the :py:method:`notifications` method on the :py:mod:`gyroscope` module:
 
 .. code-block:: python
 
@@ -30,6 +33,58 @@ Example usage:
     # Enable notifications and register a callback for them.
     c.gyroscope.notifications(gyro_callback)
 
+Logging Example
+---------------
+
+If you want to log data to the MetaWear board and retrieve it after some time, then use the 
+:py:method:`start_logging`, :py:method:`stop_logging` and :py:method:`download_log` methods:
+
+.. code-block:: python
+
+    import json
+    from pymetawear.client import MetaWearClient
+    from pymetawear.exceptions import PyMetaWearException, PyMetaWearDownloadTimeout
+
+    c = MetaWearClient('DD:3A:7D:4D:56:F0')
+
+    # Set data rate to 200 Hz and measuring range to +/- 1000 DPS
+    c.gyroscope.set_settings(data_rate=200.0, data_range=1000.0)
+
+    # Log data for 10 seconds.
+    client.gyroscope.start_logging()
+    print("Logging gyroscope data...")
+
+    time.sleep(10.0)
+
+    client.gyroscope.stop_logging()
+    print("Finished logging.")
+
+    # Download the stored data from the MetaWear board.
+    print("Downloading data...")
+    download_done = False
+    n = 0
+    data = None
+    while download_done and n < 3:
+        try:
+            data = client.gyroscope.download_log()
+            download_done = True
+        except PyMetaWearDownloadTimeout:
+            print("Download of log interrupted. Trying to reconnect...")
+            client.disconnect()
+            client.connect()
+            n += 1
+    if data is None:
+        raise PyMetaWearException("Download of logging data failed.")
+
+    print("Disconnecting...")
+    client.disconnect()
+
+    # Save the logged data.
+    data_file = os.path.join(os.getcwd(), "logged_data.json")
+    print("Saving the data to file: {0}".format(data_file))
+    with open("logged_data.json", "wt") as f:
+        json.dump(data, f, indent=2)
+
 API
 ---
 

docs/source/modules/index.rst

@@ -12,8 +12,51 @@ MetaWear modules
    magnetometer
    barometer
    led
+   ambientlight
    settings
    haptic
    switch
    temperature
    sensor_fusion
+
+
+There are two major modalities for obtaining data from sensors: subscribing to data from it or logging the data 
+to the MetaWear board for subsequent download.
+
+Streaming data
+--------------
+
+Streaming the data is a method of data extraction that is preferable if you have a need of the data in real-time,
+e.g. for IMU navigation. It sends a epoch time tagged dictionary to a callback function specified by you, to process
+as you see fit.
+
+Streaming is also the only option that allows for access to high frequency (>400 Hz) data for accelerometer and gyroscope.
+
+Modules supporting continuous data streaming:
+
+- :py:mod:`accelerometer`
+- :py:mod:`gyroscope`
+- :py:mod:`magnetometer`
+- :py:mod:`barometer`
+- :py:mod:`switch`
+- :py:mod:`ambientlight`
+- :py:mod:`sensor_fusion`
+
+Modules supporting notification protocol, but notifications are received by manually triggering them:
+
+- :py:mod:`temperature`
+- :py:mod:`settings` (battery)
+
+Logging data
+------------
+
+If you are not dependent on having data delivered continuously but rather just need it saved for analysis later on, then
+logging it to the board is a better choice. It reduces the potential for BLE disconnections during data recording, making
+it a more stable means of ensuring that data is actually collected.
+
+Modules supporting logging data (at least with PyMetaWear implementation):
+
+- :py:mod:`accelerometer`
+- :py:mod:`gyroscope`
+- :py:mod:`magnetometer`
+- :py:mod:`sensor_fusion`

docs/source/modules/magnetometer.rst

@@ -10,7 +10,10 @@ It is initialized at the creation of the :py:class:`~MetaWearClient`
 client and can then be accessed in the ``magnetometer``
 attribute of the client.
 
-Example usage:
+Example streaming data
+----------------------
+
+If you need a real time stream of sensor data, use the :py:method:`notifications` method on the :py:mod:`magnetometer` module:
 
 .. code-block:: python
 
@@ -30,6 +33,59 @@ Example usage:
     # Enable notifications and register a callback for them.
     c.magnetometer.notifications(magnetometer_callback)
 
+Logging Example
+---------------
+
+If you want to log data to the MetaWear board and retrieve it after some time, then use the 
+:py:method:`start_logging`, :py:method:`stop_logging` and :py:method:`download_log` methods:
+
+.. code-block:: python
+
+    import json
+    from pymetawear.client import MetaWearClient
+    from pymetawear.exceptions import PyMetaWearException, PyMetaWearDownloadTimeout
+
+    c = MetaWearClient('DD:3A:7D:4D:56:F0')
+
+    # Set Power preset to low power.
+    c.magnetometer.set_settings(power_preset='low_power')
+
+    # Log data for 10 seconds.
+    client.magnetometer.start_logging()
+    print("Logging magnetometer data...")
+
+    time.sleep(10.0)
+
+    client.magnetometer.stop_logging()
+    print("Finished logging.")
+
+    # Download the stored data from the MetaWear board.
+    print("Downloading data...")
+    download_done = False
+    n = 0
+    data = None
+    while download_done and n < 3:
+        try:
+            data = client.magnetometer.download_log()
+            download_done = True
+        except PyMetaWearDownloadTimeout:
+            print("Download of log interrupted. Trying to reconnect...")
+            client.disconnect()
+            client.connect()
+            n += 1
+    if data is None:
+        raise PyMetaWearException("Download of logging data failed.")
+
+    print("Disconnecting...")
+    client.disconnect()
+
+    # Save the logged data.
+    data_file = os.path.join(os.getcwd(), "logged_data.json")
+    print("Saving the data to file: {0}".format(data_file))
+    with open("logged_data.json", "wt") as f:
+        json.dump(data, f, indent=2)
+
+
 API
 ---
 

examples/accelerometer_logging.py

@@ -62,13 +62,5 @@
 for d in data:
     print(d)
 
-pattern = client.led.load_preset_pattern('blink', repeat_count=10)
-client.led.write_pattern(pattern, 'g')
-client.led.play()
-
-time.sleep(5.0)
-
-client.led.stop_and_clear()
-
 print("Disconnecting...")
 client.disconnect()

examples/gyroscope_logging.py

@@ -49,13 +49,5 @@
 for d in data:
     print(d)
 
-pattern = client.led.load_preset_pattern('blink', repeat_count=10)
-client.led.write_pattern(pattern, 'g')
-client.led.play()
-
-time.sleep(5.0)
-
-client.led.stop_and_clear()
-
 print("Disconnecting...")
 client.disconnect()

examples/magnetometer.py

@@ -29,7 +29,7 @@
 
 time.sleep(1.0)
 
-print("Write accelerometer settings...")
+print("Write magnetometer settings...")
 c.magnetometer.set_settings(power_preset='REGULAR')
 
 time.sleep(1.0)