Merge pull request #23 from jposada202020/improving_docs

improving_docs
adafruit · May 25, 2021 · d96dc95 · d96dc95
2 parents 0303c9a + c7cbbe3
commit d96dc95
Show file tree

Hide file tree

Showing 11 changed files with 230 additions and 41 deletions.
diff --git a/README.rst b/README.rst
@@ -62,17 +62,15 @@ Usage Example
 .. code-block:: python3
 
     import board
-    import busio
-    from adafruit_bno08x.i2c import BNO08X_I2C
-    from adafruit_bno08x import BNO_REPORT_ACCELEROMETER
+    import adafruit_bno08x
 
-    i2c = busio.I2C(board.SCL, board.SDA)
-    bno = BNO08X_I2C(i2c)
-    bno.enable_feature(BNO_REPORT_ACCELEROMETER)
+    i2c = board.I2C()  # uses board.SCL and board.SDA
+    bno = adafruit_bno08x.BNO08X(i2c)
 
     while True:
-        accel_x, accel_y, accel_z = bno.acceleration  # pylint:disable=no-member
-        print("X: %0.6f  Y: %0.6f Z: %0.6f  m/s^2" % (accel_x, accel_y, accel_z))
+        quat = bno.rotation_vector
+        print("Rotation Vector Quaternion:")
+        print("I: %0.3f J: %0.3f K: %0.3f Accuracy: %0.3f"%(quat.i, quat.j, quat.k, quat.accuracy))
 
 Contributing
 ============

diff --git a/adafruit_bno08x/__init__.py b/adafruit_bno08x/__init__.py
@@ -4,7 +4,7 @@
 # SPDX-License-Identifier: MIT
 """
 `adafruit_bno08x`
-================================================================================
+=================
 
 Helper library for the Hillcrest Laboratories BNO08x IMUs
 
@@ -16,14 +16,17 @@
 
 **Hardware:**
 
-* `Adafruit BNO08x Breakout <https:www.adafruit.com/products/4754>`_
+* `Adafruit 9-DOF Orientation IMU Fusion Breakout
+  <https://www.adafruit.com/products/4754>`_ (Product ID: 4566)
 
 **Software and Dependencies:**
 
 * Adafruit CircuitPython firmware for the supported boards:
-  https:# github.com/adafruit/circuitpython/releases
+  https://circuitpython.org/downloads
+
+* Adafruit's Bus Device library:
+  https://github.com/adafruit/Adafruit_CircuitPython_BusDevice
 
-* `Adafruit's Bus Device library <https:# github.com/adafruit/Adafruit_CircuitPython_BusDevice>`_
 """
 __version__ = "0.0.0-auto.0"
 __repo__ = "https:# github.com/adafruit/Adafruit_CircuitPython_BNO08x.git"
@@ -483,7 +486,11 @@ def is_error(cls, header):
 class BNO08X:  # pylint: disable=too-many-instance-attributes, too-many-public-methods
     """Library for the BNO08x IMUs from Hillcrest Laboratories
 
-    :param ~busio.I2C i2c_bus: The I2C bus the BNO08x is connected to.
+    This sensor is able to communicate over I2C, SPI, or UART:
+
+    * I2C: :class:`adafruit_bno08x.i2c.BNO08X_I2C`
+    * SPI: :class:`adafruit_bno08x.spi.BNO08X_SPI`
+    * UART: :class:`adafruit_bno08x.uart.BNO08X_UART`
 
     """
 

diff --git a/adafruit_bno08x/i2c.py b/adafruit_bno08x/i2c.py
@@ -2,9 +2,8 @@
 #
 # SPDX-License-Identifier: MIT
 """
-
-    Subclass of `adafruit_bno08x.BNO08X` to use I2C
-
+Subclass of `adafruit_bno08x.BNO08X` to use I2C
+===============================================
 """
 from struct import pack_into
 import adafruit_bus_device.i2c_device as i2c_device
@@ -17,6 +16,48 @@ class BNO08X_I2C(BNO08X):
     """Library for the BNO08x IMUs from Hillcrest Laboratories
 
     :param ~busio.I2C i2c_bus: The I2C bus the BNO08x is connected to.
+    :param ~digitalio.DigitalInOut reset: Optional for I2C use. Connected to the RST pin;
+     used to hard-reset the device.
+    :param int address: The I2C device address. Defaults to :const:`0x4A`
+    :param bool debug: Enables print statements used for debugging. Defaults to `False`
+
+
+    **Quickstart: Importing and using the device**
+
+        Here is an example of using the :class:`BNO08X_I2C` class.
+        First you will need to import the libraries to use the sensor
+
+        .. code-block:: python
+
+            import board
+            from adafruit_bno08x.i2c import BNO08X_I2C
+
+        Once this is done you can define your `board.I2C` object and define your sensor object
+
+        .. code-block:: python
+
+            # The sensor can communicate over I2C at 400kHz if you need the higher speed.
+            i2c = board.I2C()  # uses board.SCL and board.SDA
+            bno = BNO08X_I2C(i2c)
+
+        For this particular you need to define some things to get some data.
+
+        .. code-block:: python
+
+            bno.enable_feature(adafruit_bno08x.BNO_REPORT_ACCELEROMETER)
+            bno.enable_feature(adafruit_bno08x.BNO_REPORT_GYROSCOPE)
+            bno.enable_feature(adafruit_bno08x.BNO_REPORT_MAGNETOMETER)
+            bno.enable_feature(adafruit_bno08x.BNO_REPORT_ROTATION_VECTOR)
+
+        Now you have access to the :attr:`acceleration`, :attr:`gyro`
+        :attr:`magnetic` and :attr:`quaternion` attributes
+
+        .. code-block:: python
+
+            accel_x, accel_y, accel_z = bno.acceleration
+            gyro_x, gyro_y, gyro_z = bno.gyro
+            mag_x, mag_y, mag_z = bno.magnetic
+            quat_i, quat_j, quat_k, quat_real = bno.quaternion
 
     """
 
@@ -59,7 +100,6 @@ def _read_packet(self):
         with self.bus_device_obj as i2c:
             i2c.readinto(self._data_buffer, end=4)  # this is expecting a header?
         self._dbg("")
-        # print("SHTP READ packet header: ", [hex(x) for x in self._data_buffer[0:4]])
 
         header = Packet.header_from_buffer(self._data_buffer)
         packet_byte_count = header.packet_byte_count
@@ -117,5 +157,4 @@ def _data_ready(self):
         else:
             ready = header.data_length > 0
 
-        # self._dbg("\tdata ready", ready)
         return ready
diff --git a/adafruit_bno08x/spi.py b/adafruit_bno08x/spi.py
@@ -2,9 +2,8 @@
 #
 # SPDX-License-Identifier: MIT
 """
-
-    Subclass of `adafruit_bno08x.BNO08X` to use SPI
-
+Subclass of `adafruit_bno08x.BNO08X` to use SPI
+================================================
 """
 import time
 from struct import pack_into
@@ -15,20 +14,55 @@
 
 
 class BNO08X_SPI(BNO08X):
-    """Instantiate a `adafruit_bno08x.BNO08X_SPI` instance to communicate with
+    """
+    Instantiate a `adafruit_bno08x.spi.BNO08X_SPI` instance to communicate with
     the sensor using SPI
 
-    Args:
-        spi_bus ([busio.SPI]): The SPI bus to use to communicate with the BNO08x
-        cs_pin ([digitalio.DigitalInOut]): The pin object to use for the SPI Chip Select
-        debug (bool, optional): Enables print statements used for debugging. Defaults to False.
-    """
+    :param ~busio.SPI spi_bus: The SPI bus to use to communicate with the BNO08x
+    :param ~digitalio.DigitalInOut cspin: The pin object to use for the SPI Chip Select
+    :param ~digitalio.DigitalInOut intpin: The pin object to interrupt
+    :param ~digitalio.DigitalInOut resetpin: Required for SPI mode. Connected to the
+     RST pin on the device, and used to hard-reset the device.
+    :param int baudrate: baudrate of the SPI bus. Defaults to :const:`1000000`
+    :param bool debug: Enables print statements used for debugging. Defaults to `False`
+
+    **Quickstart: Importing and using the device**
+
+        Here is an example of using the :class:`BNO08X_SPI` class.
+        First you will need to import the libraries to use the sensor
+
+        .. code-block:: python
+
+            import board
+            from adafruit_bno08x.spi import BNO08X_SPI
 
-    # """Library for the BNO08x IMUs from Hillcrest Laboratories
+        Once this is done you can define your `board.SPI` object and define your sensor object
 
-    #     :param ~busio.SPI spi_bus: The SPI bus the BNO08x is connected to.
+        .. code-block:: python
 
-    # """
+            spi = board.SPI()
+            bno = BNO08X_SPI(spi)
+
+        For this particular you need to define some things to get some data.
+
+        .. code-block:: python
+
+            bno.enable_feature(adafruit_bno08x.BNO_REPORT_ACCELEROMETER)
+            bno.enable_feature(adafruit_bno08x.BNO_REPORT_GYROSCOPE)
+            bno.enable_feature(adafruit_bno08x.BNO_REPORT_MAGNETOMETER)
+            bno.enable_feature(adafruit_bno08x.BNO_REPORT_ROTATION_VECTOR)
+
+        Now you have access to the :attr:`acceleration`, :attr:`gyro`
+        :attr:`magnetic` and :attr:`quaternion` attributes
+
+        .. code-block:: python
+
+            accel_x, accel_y, accel_z = bno.acceleration
+            gyro_x, gyro_y, gyro_z = bno.gyro
+            mag_x, mag_y, mag_z = bno.magnetic
+            quat_i, quat_j, quat_k, quat_real = bno.quaternion
+
+    """
 
     def __init__(
         self, spi_bus, cspin, intpin, resetpin, baudrate=1000000, debug=False

diff --git a/adafruit_bno08x/uart.py b/adafruit_bno08x/uart.py
@@ -2,9 +2,8 @@
 #
 # SPDX-License-Identifier: MIT
 """
-
-    Subclass of `adafruit_bno08x.BNO08X` to use UART
-
+Subclass of `adafruit_bno08x.BNO08X` to use UART
+================================================
 """
 import time
 from struct import pack_into
@@ -21,7 +20,48 @@
 class BNO08X_UART(BNO08X):
     """Library for the BNO08x IMUs from Hillcrest Laboratories
 
-    :param uart: The UART devce the BNO08x is connected to.
+    :param uart: The UART device the BNO08x is connected to.
+    :param ~digitalio.DigitalInOut reset: The pin object to reset
+    :param bool debug: Enables print statements used for debugging. Defaults to `False`
+
+
+    **Quickstart: Importing and using the device**
+
+        Here is an example of using the :class:`BNO08X_UART` class.
+        First you will need to import the libraries to use the sensor
+
+        .. code-block:: python
+
+            import board
+            import busio
+            from adafruit_bno08x.uart import BNO08X_UART
+
+        Once this is done you can define your `busio.UART` object and define your sensor object
+
+        .. code-block:: python
+
+            uart = busio.UART(board.TX, board.RX, baudrate=3000000, receiver_buffer_size=2048)
+            bno = BNO08X_UART(uart)
+
+        For this particular you need to define some things to get some data.
+
+        .. code-block:: python
+
+            bno.enable_feature(adafruit_bno08x.BNO_REPORT_ACCELEROMETER)
+            bno.enable_feature(adafruit_bno08x.BNO_REPORT_GYROSCOPE)
+            bno.enable_feature(adafruit_bno08x.BNO_REPORT_MAGNETOMETER)
+            bno.enable_feature(adafruit_bno08x.BNO_REPORT_ROTATION_VECTOR)
+
+
+        Now you have access to the :attr:`acceleration`, :attr:`gyro`
+        :attr:`magnetic` and :attr:`quaternion` attributes
+
+        .. code-block:: python
+
+            accel_x, accel_y, accel_z = bno.acceleration
+            gyro_x, gyro_y, gyro_z = bno.gyro
+            mag_x, mag_y, mag_z = bno.magnetic
+            quat_i, quat_j, quat_k, quat_real = bno.quaternion
 
     """
 

diff --git a/docs/api.rst b/docs/api.rst
@@ -6,3 +6,13 @@
 
 .. automodule:: adafruit_bno08x
    :members:
+   :exclude-members: PacketError
+
+.. automodule:: adafruit_bno08x.i2c
+   :members:
+
+.. automodule:: adafruit_bno08x.spi
+   :members:
+
+.. automodule:: adafruit_bno08x.uart
+   :members:
diff --git a/docs/examples.rst b/docs/examples.rst
@@ -6,3 +6,63 @@ Ensure your device works with this simple test.
 .. literalinclude:: ../examples/bno08x_simpletest.py
     :caption: examples/bno08x_simpletest.py
     :linenos:
+
+
+Simple test SPI
+---------------
+
+This is the simple test using the SPI bus
+
+.. literalinclude:: ../examples/bno08x_simpletest_spi.py
+    :caption: examples/bno08x_simpletest_spi.py
+    :linenos:
+
+
+Simple test UART
+----------------
+
+This is the simple test using the UART bus
+
+.. literalinclude:: ../examples/bno08x_simpletest_uart.py
+    :caption: examples/bno08x_simpletest_uart.py
+    :linenos:
+
+
+Quaternion Service
+------------------
+
+Example showing the quaternion service
+
+.. literalinclude:: ../examples/bno08x_quaternion_service.py
+    :caption: examples/bno08x_quaternion_service.py
+    :linenos:
+
+
+Reports Example
+---------------
+
+Example showing how to produce reports
+
+.. literalinclude:: ../examples/bno08x_more_reports.py
+    :caption: examples/bno08x_more_reports.py
+    :linenos:
+
+
+Finding heading example
+-----------------------
+
+This illustrate how to find the heading
+
+.. literalinclude:: ../examples/bno08x_more_reports.py
+    :caption: examples/bno08x_more_reports.py
+    :linenos:
+
+
+Calibration Example
+-------------------
+
+How to calibrate the device
+
+.. literalinclude:: ../examples/bno08x_calibration.py
+    :caption: examples/bno08x_calibration.py
+    :linenos:
diff --git a/docs/index.rst b/docs/index.rst
@@ -23,10 +23,13 @@ Table of Contents
 .. toctree::
     :caption: Tutorials
 
+    Adafruit 9-DOF Orientation IMU Fusion Breakout - BNO085 Learning Guide <https://learn.adafruit.com/adafruit-9-dof-orientation-imu-fusion-breakout-bno085/>
+
+
 .. toctree::
     :caption: Related Products
 
-* `Adafruit BNO08x Breakout <https:www.adafruit.com/products/4754>`_
+    Adafruit 9-DOF Orientation IMU Fusion Breakout - BNO085 <https://www.adafruit.com/products/4754>
 
 
 .. toctree::

diff --git a/examples/bno08x_calibration.py b/examples/bno08x_calibration.py
@@ -3,12 +3,11 @@
 # SPDX-License-Identifier: Unlicense
 import time
 import board
-import busio
 from digitalio import DigitalInOut
 import adafruit_bno08x
 from adafruit_bno08x.i2c import BNO08X_I2C
 
-i2c = busio.I2C(board.SCL, board.SDA)
+i2c = board.I2C()  # uses board.SCL and board.SDA
 reset_pin = DigitalInOut(board.D5)
 bno = BNO08X_I2C(i2c, reset=reset_pin, debug=False)
 

diff --git a/examples/bno08x_quaternion_service.py b/examples/bno08x_quaternion_service.py
@@ -8,7 +8,7 @@
 from adafruit_ble_adafruit.quaternion_service import QuaternionService
 from adafruit_bno08x import BNO08X
 
-i2c = board.I2C()
+i2c = board.I2C()  # uses board.SCL and board.SDA
 bno = BNO08X(i2c)
 
 quat_svc = QuaternionService()