diff --git a/README.rst b/README.rst index d056559..a402fba 100644 --- 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 index dff7225..11be4c1 100644 --- 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 `_ +* `Adafruit 9-DOF Orientation IMU Fusion Breakout + `_ (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 `_ """ __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 index 059f0bd..d32e56f 100644 --- 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 index 194d439..4a26ee1 100644 --- 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 index f968268..6f4db04 100644 --- 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 index ecae971..7ffae53 100644 --- 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 index f7dd4b3..f2327eb 100644 --- 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 index 193e210..ad67567 100644 --- 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 + + .. toctree:: :caption: Related Products -* `Adafruit BNO08x Breakout `_ + Adafruit 9-DOF Orientation IMU Fusion Breakout - BNO085 .. toctree:: diff --git a/examples/bno08x_calibration.py b/examples/bno08x_calibration.py index 9a98f10..83bb028 100644 --- 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 index fd77924..7f426ea 100644 --- 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() diff --git a/examples/bno08x_simpletest_spi.py b/examples/bno08x_simpletest_spi.py index 747a7dc..fbbb22c 100644 --- a/examples/bno08x_simpletest_spi.py +++ b/examples/bno08x_simpletest_spi.py @@ -3,12 +3,11 @@ # SPDX-License-Identifier: Unlicense from time import sleep import board -import busio from digitalio import DigitalInOut, Direction from adafruit_bno08x.spi import BNO08X_SPI -# need to limit clock to 3Mhz -spi = busio.SPI(board.SCK, MISO=board.MISO, MOSI=board.MOSI) +# need to limit clock to 3MHz +i2c = board.I2C() # uses board.SCL and board.SDA cs = DigitalInOut(board.D5) cs.direction = Direction.OUTPUT