Merge pull request #12 from jposada202020/improving_docs

improving docs and varia

Author: kattni

README.rst

@@ -62,10 +62,9 @@ For use with the ICM20649:
 
     import time
     import board
-    import busio
     import adafruit_icm20x
 
-    i2c = busio.I2C(board.SCL, board.SDA)
+    i2c = board.I2C()   # uses board.SCL and board.SDA
     icm = adafruit_icm20x.ICM20649(i2c)
 
     while True:
@@ -80,10 +79,9 @@ For use with the ICM20948:
 
     import time
     import board
-    import busio
     import adafruit_icm20x
 
-    i2c = busio.I2C(board.SCL, board.SDA)
+    i2c = board.I2C()  # uses board.SCL and board.SDA
     icm = adafruit_icm20x.ICM20948(i2c)
 
     while True:

adafruit_icm20x.py

@@ -112,25 +112,25 @@ def is_valid(cls, value):
 
 
 class AccelRange(CV):
-    """Options for ``accelerometer_range``"""
+    """Options for :attr:`ICM20X.accelerometer_range`"""
 
     pass  # pylint: disable=unnecessary-pass
 
 
 class GyroRange(CV):
-    """Options for ``gyro_data_range``"""
+    """Options for :attr:`ICM20X.gyro_data_range`"""
 
     pass  # pylint: disable=unnecessary-pass
 
 
 class GyroDLPFFreq(CV):
-    """Options for ``gyro_dlpf_cutoff``"""
+    """Options for :attr:`ICM20X.gyro_dlpf_cutoff`"""
 
     pass  # pylint: disable=unnecessary-pass
 
 
 class AccelDLPFFreq(CV):
-    """Options for ``accel_dlpf_cutoff``"""
+    """Options for :attr:`ICM20X.accel_dlpf_cutoff`"""
 
     pass  # pylint: disable=unnecessary-pass
 
@@ -140,7 +140,7 @@ class ICM20X:  # pylint:disable=too-many-instance-attributes
 
 
     :param ~busio.I2C i2c_bus: The I2C bus the ICM20X is connected to.
-    :param address: The I2C slave address of the sensor
+    :param int address: The I2C address of the device.
 
     """
 
@@ -227,7 +227,7 @@ def __init__(self, i2c_bus, address):
         self.initialize()
 
     def initialize(self):
-        """Configure the sensors with the default settings. For use after calling `reset()`"""
+        """Configure the sensors with the default settings. For use after calling :meth:`reset`"""
 
         self._sleep = False
         self.accelerometer_range = AccelRange.RANGE_8G  # pylint: disable=no-member
@@ -262,7 +262,7 @@ def _sleep(self, sleep_enabled):
 
     @property
     def acceleration(self):
-        """The x, y, z acceleration values returned in a 3-tuple and are in m / s ^ 2."""
+        """The x, y, z acceleration values returned in a 3-tuple and are in :math:`m / s ^ 2.`"""
         self._bank = 0
         raw_accel_data = self._raw_accel_data
         sleep(0.005)
@@ -275,7 +275,8 @@ def acceleration(self):
 
     @property
     def gyro(self):
-        """The x, y, z angular velocity values returned in a 3-tuple and are in degrees / second"""
+        """The x, y, z angular velocity values returned in a 3-tuple and
+        are in :math:`degrees / second`"""
         self._bank = 0
         raw_gyro_data = self._raw_gyro_data
         x = self._scale_gyro_data(raw_gyro_data[0])
@@ -331,12 +332,19 @@ def gyro_range(self, value):
 
     @property
     def accelerometer_data_rate_divisor(self):
-        """The divisor for the rate at which accelerometer measurements are taken in Hz
+        """
+        The divisor for the rate at which accelerometer measurements are taken in Hz
+
+        .. note::
+            The data rates are set indirectly by setting a rate divisor according to the
+            following formula:
+
+            .. math::
 
-        Note: The data rates are set indirectly by setting a rate divisor according to the
-        following formula: ``accelerometer_data_rate = 1125/(1+divisor)``
+                \\text{accelerometer_data_rate} = \\frac{1125}{1 + divisor}
 
         This function sets the raw rate divisor.
+
         """
         self._bank = 2
         raw_rate_divisor = self._accel_rate_divisor
@@ -355,10 +363,16 @@ def accelerometer_data_rate_divisor(self, value):
 
     @property
     def gyro_data_rate_divisor(self):
-        """The divisor for the rate at which gyro measurements are taken in Hz
+        """
+        The divisor for the rate at which gyro measurements are taken in Hz
 
-        Note: The data rates are set indirectly by setting a rate divisor according to the
-        following formula: ``gyro_data_rate = 1100/(1+divisor)``
+        .. note::
+            The data rates are set indirectly by setting a rate divisor according to the
+            following formula:
+
+            .. math::
+
+                \\text{gyro_data_rate} = \\frac{1100}{1 + divisor}
 
         This function sets the raw rate divisor.
         """
@@ -388,8 +402,14 @@ def _gyro_rate_calc(self, divisor):  # pylint:disable=no-self-use
     def accelerometer_data_rate(self):
         """The rate at which accelerometer measurements are taken in Hz
 
-        Note: The data rates are set indirectly by setting a rate divisor according to the
-        following formula: ``accelerometer_data_rate = 1125/(1+divisor)``
+        .. note::
+
+            The data rates are set indirectly by setting a rate divisor according to the
+            following formula:
+
+            .. math::
+
+                \\text{accelerometer_data_rate} = \\frac{1125}{1 + divisor}
 
         This function does the math to find the divisor from a given rate but it will not be
         exactly as specified.
@@ -408,8 +428,14 @@ def accelerometer_data_rate(self, value):
     def gyro_data_rate(self):
         """The rate at which gyro measurements are taken in Hz
 
-        Note: The data rates are set indirectly by setting a rate divisor according to the
-        following formula: ``gyro_data_rate = 1100/(1+divisor)``
+        .. note::
+            The data rates are set indirectly by setting a rate divisor according to the
+            following formula:
+
+            .. math::
+
+                \\text{gyro_data_rate } = \\frac{1100}{1 + divisor}
+
         This function does the math to find the divisor from a given rate but it will not
         be exactly as specified.
         """
@@ -429,8 +455,11 @@ def accel_dlpf_cutoff(self):
         above the given frequency will be filtered out. Must be an ``AccelDLPFCutoff``.
         Use AccelDLPFCutoff.DISABLED to disable the filter
 
-        **Note** readings immediately following setting a cutoff frequency will be
-        inaccurate due to the filter "warming up" """
+        .. note::
+            Readings immediately following setting a cutoff frequency will be
+            inaccurate due to the filter "warming up"
+
+        """
         self._bank = 2
         return self._accel_dlpf_config
 
@@ -452,8 +481,11 @@ def gyro_dlpf_cutoff(self):
         given frequency will be filtered out. Must be a ``GyroDLPFFreq``. Use
         GyroDLPFCutoff.DISABLED to disable the filter
 
-        **Note** readings immediately following setting a cutoff frequency will be
-        inaccurate due to the filter "warming up" """
+        .. note::
+            Readings immediately following setting a cutoff frequency will be
+            inaccurate due to the filter "warming up"
+
+        """
         self._bank = 2
         return self._gyro_dlpf_config
 
@@ -484,7 +516,32 @@ class ICM20649(ICM20X):
     """Library for the ST ICM-20649 Wide-Range 6-DoF Accelerometer and Gyro.
 
     :param ~busio.I2C i2c_bus: The I2C bus the ICM20649 is connected to.
-    :param address: The I2C slave address of the sensor
+    :param int address: The I2C address of the device. Defaults to :const:`0x68`
+
+    **Quickstart: Importing and using the ICM20649 temperature sensor**
+
+        Here is an example of using the :class:`ICM2020649` class.
+        First you will need to import the libraries to use the sensor
+
+        .. code-block:: python
+
+            import board
+            import adafruit_icm20x
+
+        Once this is done you can define your `board.I2C` object and define your sensor object
+
+        .. code-block:: python
+
+            i2c = board.I2C()   # uses board.SCL and board.SDA
+            icm = adafruit_icm20x.ICM20649(i2c)
+
+        Now you have access to the acceleration using :attr:`acceleration` attribute and
+        the gyro information using the :attr:`gyro` attribute.
+
+        .. code-block:: python
+
+                acceleration = icm.acceleration
+                gyro = icm.gyro
 
     """
 
@@ -526,7 +583,7 @@ def __init__(self, i2c_bus, address=_ICM20649_DEFAULT_ADDRESS):
 
 
 class MagDataRate(CV):
-    """Options for ``magnetometer_data_rate``"""
+    """Options for :attr:`ICM20948.magnetometer_data_rate`"""
 
     pass  # pylint: disable=unnecessary-pass
 
@@ -535,7 +592,36 @@ class ICM20948(ICM20X):  # pylint:disable=too-many-instance-attributes
     """Library for the ST ICM-20948 Wide-Range 6-DoF Accelerometer and Gyro.
 
     :param ~busio.I2C i2c_bus: The I2C bus the ICM20948 is connected to.
-    :param address: The I2C slave address of the sensor
+    :param int address: The I2C address of the device. Defaults to :const:`0x69`
+
+    **Quickstart: Importing and using the ICM20948 temperature sensor**
+
+        Here is an example of using the :class:`ICM20948` class.
+        First you will need to import the libraries to use the sensor
+
+        .. code-block:: python
+
+            import board
+            import adafruit_icm20x
+
+        Once this is done you can define your `board.I2C` object and define your sensor object
+
+        .. code-block:: python
+
+            i2c = board.I2C()   # uses board.SCL and board.SDA
+            icm = adafruit_icm20x.ICM20948(i2c)
+
+        Now you have access to the acceleration using :attr:`acceleration` attribute,
+        the gyro information using the :attr:`gyro` attribute and the magnetic information
+        using the :attr:`magnetic` attribute
+
+        .. code-block:: python
+
+                acceleration = icm.acceleration
+                gyro = icm.gyro
+                magnetic = icm.magnetic
+
+
     """
 
     _slave_finished = ROBit(_ICM20X_I2C_MST_STATUS, 6)
@@ -670,7 +756,7 @@ def magnetic(self):
 
     @property
     def magnetometer_data_rate(self):
-        """The rate at which the magenetometer takes measurements to update its output registers"""
+        """The rate at which the magnetometer takes measurements to update its output registers"""
         # read mag DR register
         self._read_mag_register(_AK09916_CNTL2)
 
@@ -707,7 +793,7 @@ def _read_mag_register(self, register_addr, slave_addr=0x0C):
         finished = False
         for _i in range(100):
             finished = self._slave_finished
-            if finished:  # bueno!
+            if finished:  # bueno! :)
                 break
             sleep(0.010)
 
@@ -737,7 +823,7 @@ def _write_mag_register(self, register_addr, value, slave_addr=0x0C):
         finished = False
         for _i in range(100):
             finished = self._slave_finished
-            if finished:  # bueno!
+            if finished:  # bueno! :)
                 break
             sleep(0.010)
 

docs/api.rst

@@ -6,3 +6,4 @@
 
 .. automodule:: adafruit_icm20x
    :members:
+   :member-order: bysource

docs/examples.rst

@@ -1,12 +1,53 @@
-Simple test
-------------
+ICM20649 Simple test
+--------------------
 
-Ensure your device works with one of these simple tests.
+Ensure your ICM20649 device works with one of these simple tests.
 
 .. literalinclude:: ../examples/icm20x_icm20649_simpletest.py
     :caption: examples/icm20x_icm20649_simpletest.py
     :linenos:
 
+ICM20649 Full test
+------------------
+
+Test using all the ICM20649 sensor capabilities
+
+.. literalinclude:: ../examples/icm20x_icm20649_full_test.py
+    :caption: examples/examples/icm20x_icm20649_full_test.py
+    :linenos:
+
+ICM20948 Simple test
+--------------------
+
+Ensure your ICM20948 device works with one of these simple tests.
+
 .. literalinclude:: ../examples/icm20x_icm20948_simpletest.py
     :caption: examples/icm20x_icm20948_simpletest.py
     :linenos:
+
+ICM20948 Acceleration data rate test
+------------------------------------
+
+Example showing ICM20948 sensor cycling between two acceleration data rates
+
+.. literalinclude:: ../examples/icm20x_icm20948_accel_data_rate_test.py
+    :caption: examples/icm20x_icm20948_accel_data_rate_test.py
+    :linenos:
+
+ICM20948 Gyro data rate test
+----------------------------
+
+Example showing ICM20948 sensor cycling between two gyro data rates
+
+.. literalinclude:: ../examples/icm20x_icm20948_gyro_data_rate_test.py
+    :caption: examples/icm20x_icm20948_gyro_data_rate_test.py
+    :linenos:
+
+ICM20948 Magnetic data rate test
+--------------------------------
+
+Example showing ICM20948 sensor cycling between two magnetic data rates
+
+.. literalinclude:: ../examples/icm20x_icm20948_mag_data_rate_test.py
+    :caption: examples/icm20x_icm20948_mag_data_rate_test.py
+    :linenos:

docs/index.rst

@@ -23,10 +23,14 @@ Table of Contents
 .. toctree::
     :caption: Tutorials
 
+    Adafruit's ICM20649 Learning Guide <https://learn.adafruit.com/adafruit-icm20649-wide-range-6-dof-imu-accelerometer-and-gyro>
+    Adafruit's ICM20948 Learning Guide <https://learn.adafruit.com/adafruit-tdk-invensense-icm-20948-9-dof-imu>
+
 .. toctree::
     :caption: Related Products
 
     Adafruit's ICM20649 Breakout <https://adafruit.com/product/4464>
+    Adafruit's ICM20948 Breakout <https://www.adafruit.com/product/4554>
 
 
 .. toctree::

examples/icm20x_icm20649_full_test.py

@@ -3,7 +3,6 @@
 
 import time
 import board
-import busio
 from adafruit_icm20x import ICM20649, AccelRange, GyroRange
 
 
@@ -15,7 +14,7 @@ def printNewMax(value, current_max, axis):
 
 
 # pylint:disable=no-member
-i2c = busio.I2C(board.SCL, board.SDA)
+i2c = board.I2C()  # uses board.SCL and board.SDA
 
 ism = ICM20649(i2c)