From b9abeda8e3fb8b4f9fca36e0d01a4d198ffc69eb Mon Sep 17 00:00:00 2001 From: Erol444 Date: Fri, 30 Jul 2021 12:22:31 +0200 Subject: [PATCH 1/5] Added IMU node and IMUData message docs --- docs/source/components/messages/imu_data.rst | 26 ++++ docs/source/components/nodes/imu.rst | 130 ++++++++++++++++++ .../samples/imu_accelerometer_gyroscope.rst | 13 ++ docs/source/samples/imu_rotation_vector.rst | 14 ++ 4 files changed, 183 insertions(+) create mode 100644 docs/source/components/messages/imu_data.rst create mode 100644 docs/source/components/nodes/imu.rst diff --git a/docs/source/components/messages/imu_data.rst b/docs/source/components/messages/imu_data.rst new file mode 100644 index 000000000..caee03085 --- /dev/null +++ b/docs/source/components/messages/imu_data.rst @@ -0,0 +1,26 @@ +IMUData +======= + +IMU data message is created by the :ref:`IMU` node. + +Reference +######### + +.. tabs:: + + .. tab:: Python + + .. autoclass:: depthai.IMUData + :members: + :inherited-members: + :noindex: + + .. tab:: C++ + + .. doxygenclass:: dai::IMUData + :project: depthai-core + :members: + :private-members: + :undoc-members: + +.. include:: ../../includes/footer-short.rst diff --git a/docs/source/components/nodes/imu.rst b/docs/source/components/nodes/imu.rst new file mode 100644 index 000000000..9da38781f --- /dev/null +++ b/docs/source/components/nodes/imu.rst @@ -0,0 +1,130 @@ +IMU +=== + +IMU (`intertial measurement unit `__) node can be used to recieve data from the IMU chip on the device. +Our DepthAI devices use `BNO085 `__ 9-axis sensor (`datasheet here `__) +that supports sensor fusion on the (IMU) chip itself. The IMU chip is connected to the Myriad X (VPU) over SPI (we have integrated +`this driver `__ to the DepthAI). + + +How to place it +############### + +.. tabs:: + + .. code-tab:: py + + pipeline = dai.Pipeline() + spi = pipeline.create(dai.node.IMU) + + .. code-tab:: c++ + + dai::Pipeline pipeline; + auto spi = pipeline.create(); + + +Inputs and Outputs +################## + +.. code-block:: + + ┌──────────────┐ + │ │ + │ │ out + │ IMU ├─────────► + │ │ + │ │ + └──────────────┘ + +**Message types** + +- :code:`out` - :ref:`IMUData` + +Maximum frequencies +################### + +Maximum output frequencies are 500 Hz raw accelerometer, 1000 Hz raw gyroscope values individually, and 500 Hz combined (synced) output. +You can obtain the combined (synced) 500 Hz output with :code:`imu.enableIMUSensor([dai.IMUSensor.RAW_ACCELEROMETER, dai.IMUSensor.RAW_GYROSCOPE], 500)`. + +Usage +##### + +.. tabs:: + + .. code-tab:: py + + pipeline = dai.Pipeline() + imu = pipeline.create(dai.node.IMU) + + # enable ACCELEROMETER and GRAVITY at 100 hz rate + imu.enableIMUSensor([dai.IMUSensor.ACCELEROMETER, dai.IMUSensor.GRAVITY], 100) + # above this threshold packets will be sent in batch of X, if the host is not blocked and USB bandwidth is available + imu.setBatchReportThreshold(1) + # maximum number of IMU packets in a batch, if it's reached device will block sending until host can receive it + # if lower or equal to batchReportThreshold then the sending is always blocking on device + # useful to reduce device's CPU load and number of lost packets, if CPU load is high on device side due to multiple nodes + imu.setMaxBatchReports(10) + + .. code-tab:: c++ + + dai::Pipeline pipeline; + auto imu = pipeline.create(); + + // enable ACCELEROMETER and GRAVITY at 100 hz rate + imu->enableIMUSensor({dai::IMUSensor::ACCELEROMETER, dai::IMUSensor::GRAVITY}, 100); + // above this threshold packets will be sent in batch of X, if the host is not blocked and USB bandwidth is available + imu->setBatchReportThreshold(1); + // maximum number of IMU packets in a batch, if it's reached device will block sending until host can receive it + // if lower or equal to batchReportThreshold then the sending is always blocking on device + // useful to reduce device's CPU load and number of lost packets, if CPU load is high on device side due to multiple nodes + imu->setMaxBatchReports(10); + + +IMU sensors +########### + +When enabling the IMU sensors (:code:`imu.enableIMUSensor()`), you can select between the following sensors: + +- :code:`ACCELEROMETER_RAW` +- :code:`ACCELEROMETER` +- :code:`LINEAR_ACCELERATION` +- :code:`GRAVITY` +- :code:`GYROSCOPE_RAW` +- :code:`GYROSCOPE_CALIBRATED` +- :code:`GYROSCOPE_UNCALIBRATED` +- :code:`MAGNETOMETER_RAW` +- :code:`MAGNETOMETER_CALIBRATED` +- :code:`MAGNETOMETER_UNCALIBRATED` +- :code:`ROTATION_VECTOR` +- :code:`GAME_ROTATION_VECTOR` +- :code:`GEOMAGNETIC_ROTATION_VECTOR` +- :code:`ARVR_STABILIZED_ROTATION_VECTOR` +- :code:`ARVR_STABILIZED_GAME_ROTATION_VECTOR` + +Examples of functionality +######################### + +- :ref:`IMU Accelerometer & Gyroscope` +- :ref:`IMU Rotation Vector` + +Reference +######### + +.. tabs:: + + .. tab:: Python + + .. autoclass:: depthai.node.IMU + :members: + :inherited-members: + :noindex: + + .. tab:: C++ + + .. doxygenclass:: dai::node::IMU + :project: depthai-core + :members: + :private-members: + :undoc-members: + +.. include:: ../../includes/footer-short.rst diff --git a/docs/source/samples/imu_accelerometer_gyroscope.rst b/docs/source/samples/imu_accelerometer_gyroscope.rst index b421f2bc1..bb82c0527 100644 --- a/docs/source/samples/imu_accelerometer_gyroscope.rst +++ b/docs/source/samples/imu_accelerometer_gyroscope.rst @@ -7,6 +7,19 @@ Returns acceleration [m/s^2] and angular velocity [rad/s]. Demo #### +Example script output + +.. code-block:: + + ~/depthai-python/examples$ python3 imu_gyroscope_accelerometer.py + Accelerometer timestamp: 0.000 ms + Accelerometer [m/s^2]: x: -0.162806 y: 6.445191 z: 3.189077 + Gyroscope timestamp: 1.642 ms + Gyroscope [rad/s]: x: -0.040480 y: 0.088417 z: -0.168312 + Accelerometer timestamp: 2.073 ms + Accelerometer [m/s^2]: x: -0.229843 y: 6.263232 z: 3.572149 + Gyroscope timestamp: 3.663 ms + Gyroscope [rad/s]: x: -0.072438 y: 0.115049 z: -0.350472 Setup ##### diff --git a/docs/source/samples/imu_rotation_vector.rst b/docs/source/samples/imu_rotation_vector.rst index a9366becb..6e284df89 100644 --- a/docs/source/samples/imu_rotation_vector.rst +++ b/docs/source/samples/imu_rotation_vector.rst @@ -7,6 +7,20 @@ Returns quaternion. Demo #### +Example script output + +.. code-block:: + + ~/depthai-python/examples$ python3 imu_rotation_vector.py + Rotation vector timestamp: 0.000 ms + Quaternion: i: 0.089355 j: 0.355103 k: 0.034058 real: 0.929932 + Accuracy (rad): 3.141602 + Rotation vector timestamp: 3.601 ms + Quaternion: i: 0.088928 j: 0.354004 k: 0.036560 real: 0.930298 + Accuracy (rad): 3.141602 + Rotation vector timestamp: 6.231 ms + Quaternion: i: 0.094604 j: 0.344543 k: 0.040955 real: 0.933105 + Accuracy (rad): 3.141602 Setup ##### From 158679962e7cb5fd02fab9aba8201f4700100f83 Mon Sep 17 00:00:00 2001 From: Erol444 Date: Sat, 7 Aug 2021 09:16:16 +0200 Subject: [PATCH 2/5] Fixed PR issues --- docs/source/components/nodes/imu.rst | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/source/components/nodes/imu.rst b/docs/source/components/nodes/imu.rst index 9da38781f..5d5665a34 100644 --- a/docs/source/components/nodes/imu.rst +++ b/docs/source/components/nodes/imu.rst @@ -15,12 +15,12 @@ How to place it .. code-tab:: py pipeline = dai.Pipeline() - spi = pipeline.create(dai.node.IMU) + imu = pipeline.create(dai.node.IMU) .. code-tab:: c++ dai::Pipeline pipeline; - auto spi = pipeline.create(); + auto imu = pipeline.create(); Inputs and Outputs @@ -101,6 +101,11 @@ When enabling the IMU sensors (:code:`imu.enableIMUSensor()`), you can select be - :code:`ARVR_STABILIZED_ROTATION_VECTOR` - :code:`ARVR_STABILIZED_GAME_ROTATION_VECTOR` +Here are **descriptions of all sensors**: + +.. autoclass:: depthai.IMUSensor + :noindex: + Examples of functionality ######################### From 25d7ff63ef160514f448730282ed20c770a17c92 Mon Sep 17 00:00:00 2001 From: Erol444 Date: Mon, 9 Aug 2021 14:49:11 +0200 Subject: [PATCH 3/5] Fixed IMU sensors --- docs/source/components/nodes/imu.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/source/components/nodes/imu.rst b/docs/source/components/nodes/imu.rst index 5d5665a34..08e1145bd 100644 --- a/docs/source/components/nodes/imu.rst +++ b/docs/source/components/nodes/imu.rst @@ -56,8 +56,8 @@ Usage pipeline = dai.Pipeline() imu = pipeline.create(dai.node.IMU) - # enable ACCELEROMETER and GRAVITY at 100 hz rate - imu.enableIMUSensor([dai.IMUSensor.ACCELEROMETER, dai.IMUSensor.GRAVITY], 100) + # enable ACCELEROMETER and MAGNETOMETER_CALIBRATED at 100 hz rate + imu.enableIMUSensor([dai.IMUSensor.ACCELEROMETER, dai.IMUSensor.MAGNETOMETER_CALIBRATED], 100) # above this threshold packets will be sent in batch of X, if the host is not blocked and USB bandwidth is available imu.setBatchReportThreshold(1) # maximum number of IMU packets in a batch, if it's reached device will block sending until host can receive it @@ -70,8 +70,8 @@ Usage dai::Pipeline pipeline; auto imu = pipeline.create(); - // enable ACCELEROMETER and GRAVITY at 100 hz rate - imu->enableIMUSensor({dai::IMUSensor::ACCELEROMETER, dai::IMUSensor::GRAVITY}, 100); + // enable ACCELEROMETER and MAGNETOMETER_CALIBRATED at 100 hz rate + imu->enableIMUSensor({dai::IMUSensor::ACCELEROMETER, dai::IMUSensor::MAGNETOMETER_CALIBRATED}, 100); // above this threshold packets will be sent in batch of X, if the host is not blocked and USB bandwidth is available imu->setBatchReportThreshold(1); // maximum number of IMU packets in a batch, if it's reached device will block sending until host can receive it From aeec778ac046735d29d55251f907ee4ebd75fcce Mon Sep 17 00:00:00 2001 From: Erol444 Date: Mon, 9 Aug 2021 14:51:23 +0200 Subject: [PATCH 4/5] Fixed typo --- docs/source/components/nodes/imu.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/components/nodes/imu.rst b/docs/source/components/nodes/imu.rst index 08e1145bd..0b959072e 100644 --- a/docs/source/components/nodes/imu.rst +++ b/docs/source/components/nodes/imu.rst @@ -1,7 +1,7 @@ IMU === -IMU (`intertial measurement unit `__) node can be used to recieve data from the IMU chip on the device. +IMU (`intertial measurement unit `__) node can be used to receive data from the IMU chip on the device. Our DepthAI devices use `BNO085 `__ 9-axis sensor (`datasheet here `__) that supports sensor fusion on the (IMU) chip itself. The IMU chip is connected to the Myriad X (VPU) over SPI (we have integrated `this driver `__ to the DepthAI). From 4bc73b031b9a7f0aae2ec537ae82e05d62e7ca39 Mon Sep 17 00:00:00 2001 From: Erik Date: Mon, 9 Aug 2021 16:09:14 +0200 Subject: [PATCH 5/5] Update imu.rst --- docs/source/components/nodes/imu.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/source/components/nodes/imu.rst b/docs/source/components/nodes/imu.rst index 0b959072e..ba68f9336 100644 --- a/docs/source/components/nodes/imu.rst +++ b/docs/source/components/nodes/imu.rst @@ -56,8 +56,8 @@ Usage pipeline = dai.Pipeline() imu = pipeline.create(dai.node.IMU) - # enable ACCELEROMETER and MAGNETOMETER_CALIBRATED at 100 hz rate - imu.enableIMUSensor([dai.IMUSensor.ACCELEROMETER, dai.IMUSensor.MAGNETOMETER_CALIBRATED], 100) + # enable RAW_ACCELEROMETER and RAW_GYROSCOPE at 100 hz rate + imu.enableIMUSensor([dai.IMUSensor.RAW_ACCELEROMETER, dai.IMUSensor.RAW_GYROSCOPE], 100) # above this threshold packets will be sent in batch of X, if the host is not blocked and USB bandwidth is available imu.setBatchReportThreshold(1) # maximum number of IMU packets in a batch, if it's reached device will block sending until host can receive it @@ -70,8 +70,8 @@ Usage dai::Pipeline pipeline; auto imu = pipeline.create(); - // enable ACCELEROMETER and MAGNETOMETER_CALIBRATED at 100 hz rate - imu->enableIMUSensor({dai::IMUSensor::ACCELEROMETER, dai::IMUSensor::MAGNETOMETER_CALIBRATED}, 100); + // enable RAW_ACCELEROMETER and RAW_GYROSCOPE at 100 hz rate + imu->enableIMUSensor({dai::IMUSensor::RAW_ACCELEROMETER, dai::IMUSensor::RAW_GYROSCOPE}, 100); // above this threshold packets will be sent in batch of X, if the host is not blocked and USB bandwidth is available imu->setBatchReportThreshold(1); // maximum number of IMU packets in a batch, if it's reached device will block sending until host can receive it