From 2cfd4f8310cfde31a7737ebe3ab111256a0ad024 Mon Sep 17 00:00:00 2001 From: Westside Robotics Date: Tue, 22 Nov 2022 11:41:16 -0800 Subject: [PATCH 1/5] 11-22-22 restore title, after publication at ftc-docs --- Vumarks-calibration.md => Universal-IMU-Interface.md | 5 +++++ 1 file changed, 5 insertions(+) rename Vumarks-calibration.md => Universal-IMU-Interface.md (99%) diff --git a/Vumarks-calibration.md b/Universal-IMU-Interface.md similarity index 99% rename from Vumarks-calibration.md rename to Universal-IMU-Interface.md index 63fd35d..f717ab4 100644 --- a/Vumarks-calibration.md +++ b/Universal-IMU-Interface.md @@ -1,6 +1,11 @@ ## Introduction + + In September 2022, REV Robotics began shipping [**Control Hubs**](https://www.revrobotics.com/rev-31-1595/) with a different internal Inertial Measurement Unit (IMU). An IMU can measure many aspects of device motion; here we focus on **rotation**. The new IMU chip is designated [BHI260AP](https://www.bosch-sensortec.com/products/smart-sensors/bhi260ap/), replacing the old Hub's IMU chip [BNO055](https://www.bosch-sensortec.com/products/smart-sensors/bno055/). Both are from Bosch Sensortec. From 6be3ceef18937f59eb413a4829c444103c035370 Mon Sep 17 00:00:00 2001 From: Westside Robotics Date: Tue, 22 Nov 2022 12:44:47 -0800 Subject: [PATCH 2/5] 11-22-22 update links --- Universal-IMU-Interface.md | 53 +++++++++++++++++++------------------- 1 file changed, 27 insertions(+), 26 deletions(-) diff --git a/Universal-IMU-Interface.md b/Universal-IMU-Interface.md index f717ab4..2811798 100644 --- a/Universal-IMU-Interface.md +++ b/Universal-IMU-Interface.md @@ -41,7 +41,10 @@ The SDK 8.1 README provides more technical background: >Because of the new robot-centric coordinate system, the pitch and roll angles returned by the `IMU` interface will be different from the ones returned by the `BNO055IMU` interface. When you are migrating your code, pay careful attention to the documentation. -[

Return to Top](#introduction)

+ +

[[Return to Top|https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Universal-IMU-Interface]]

+ + ## Potential Usage @@ -71,7 +74,7 @@ The FTC SDK can also provide values for **angular velocity**, which is the rate Let's get started! -[

Return to Top](#introduction)

+

[[Return to Top|https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Universal-IMU-Interface]]

## Configure IMU @@ -91,7 +94,7 @@ When done, **save** and **activate** this configuration. _If a Blocks OpMode is open at the computer's programming screen, close and re-open that OpMode to capture this updated configuration. Blocks are provided only for devices in the configuration that's active **upon opening** an OpMode._ -[

Return to Top](#introduction)

+

[[Return to Top|https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Universal-IMU-Interface]]

## Axes Definition @@ -115,7 +118,7 @@ _Fun fact: the IMU is located approximately under the word "PROUD", near the low This tutorial will **not** discuss the FTC [Field Coordinate System](https://github.com/FIRST-Tech-Challenge/FtcRobotController/blob/master/FtcRobotController/src/main/java/org/firstinspires/ftc/robotcontroller/external/samples/FTC_FieldCoordinateSystemDefinition.pdf). Your OpModes might relate robot orientation to the overall field or ['global coordinates'](https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Vuforia-for-Blocks#vuforia-introduction) for navigation, but that's beyond the focus here on using the IMU. -[

Return to Top](#introduction)

+

[[Return to Top|https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Universal-IMU-Interface]]

## Physical Hub Mounting @@ -123,7 +126,7 @@ Under SDK 8.1, you can specify the **physical orientation** of the Hub on the ro Before jumping into programming, let's discuss your options for physically mounting the Hub on the robot. In general, the Hub's mounting can be considered **Orthogonal** or **Non-Orthogonal**. -[

Return to Top](#introduction)

+

[[Return to Top|https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Universal-IMU-Interface]]

**Orthogonal Mounting** @@ -143,7 +146,7 @@ Here are some common examples: With six cube faces, and four 90-degree positions on each face, there are **24 possible Orthogonal orientations**. -[

Return to Top](#introduction)

+

[[Return to Top|https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Universal-IMU-Interface]]

**Non-Orthogonal Mounting** @@ -157,7 +160,7 @@ Here are some scenarios, ranging from simple to complex: For any Non-Orthogonal scenarios, SDK 8.1 provides **two ways** to describe the Hub's orientation. See below for the **Angles** method and the **Quaternion** method. -[

Return to Top](#introduction)

+

[[Return to Top|https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Universal-IMU-Interface]]

## IMU Programming @@ -174,7 +177,7 @@ The programming steps include: The following sections cover these topics in order. -[

Return to Top](#introduction)

+

[[Return to Top|https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Universal-IMU-Interface]]

## Parameters @@ -184,7 +187,7 @@ In the FTC Blocks menu, under `Sensors` and `IMU`, see the three methods for spe [[/images/Universal-IMU-Interface/045-Blocks-parameters-toolbox-labels.png]] -[

Return to Top](#introduction)

+

[[Return to Top|https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Universal-IMU-Interface]]

### Parameters for Method 1, Orthogonal @@ -209,7 +212,7 @@ IMU.Parameters myIMUparameters; myIMUparameters = new IMU.Parameters(new RevHubOrientationOnRobot(RevHubOrientationOnRobot.LogoFacingDirection.UP, RevHubOrientationOnRobot.UsbFacingDirection.FORWARD)); ``` -[

Return to Top](#introduction)

+

[[Return to Top|https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Universal-IMU-Interface]]

### Hub Axes for Setting Parameters @@ -231,7 +234,7 @@ Hub rotations also follow the right-hand rule. _The legacy `BNO055IMU` driver used **different Hub axes**: its X axis pointed to the USB port, and Y axis pointed to the left-side motor ports. The new SDK 8.1 universal IMU driver uses the above Hub axes for BNO055 and BHI260AP._ -[

Return to Top](#introduction)

+

[[Return to Top|https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Universal-IMU-Interface]]

### Parameters for Method 2, Angles @@ -273,7 +276,7 @@ myIMUparameters = new IMU.Parameters(new RevHubOrientationOnRobot(new Orientatio _This example does not use the final Java parameter `acquisitionTime`, here set to 0._ -[

Return to Top](#introduction)

+

[[Return to Top|https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Universal-IMU-Interface]]

### Parameters for Method 3, Quaternion @@ -304,7 +307,7 @@ Here's a Quaternion-related **side note** from the SDK 8.1 README: >The `IMU` interface is also suitable for implementation by **third-party vendors for IMUs** that support providing the orientation in the form of a **quaternion**. --> -[

Return to Top](#introduction)

+

[[Return to Top|https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Universal-IMU-Interface]]

## Initialize IMU @@ -330,7 +333,7 @@ imu.initialize(new IMU.Parameters(new RevHubOrientationOnRobot(RevHubOrientation imu.initialize(myIMUparameters); ``` -[

Return to Top](#introduction)

+

[[Return to Top|https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Universal-IMU-Interface]]

## Read IMU Angles - Basic @@ -374,7 +377,7 @@ Note that the robot's orientation is described here **intrinsically**; the axes _Again, the IMU **output** results are given in the **Robot Coordinate System**, or Robot axes. Only for a non-Orthogonal orientation, **Hub axes** were used temporarily for **input** parameters, describing the Hub's rotation to achieve its mounted orientation._ -[

Return to Top](#introduction)

+

[[Return to Top|https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Universal-IMU-Interface]]

## Read IMU Angles - Flexible @@ -407,7 +410,7 @@ myRobotOrientation.thirdAngle _Pay close attention to the selection of **axes order**, which greatly affects the IMU results. If you care mostly about Heading (Yaw), choose an axes order that starts with Z._ -[

Return to Top](#introduction)

+

[[Return to Top|https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Universal-IMU-Interface]]

## Read Angular Velocity @@ -439,7 +442,7 @@ myRobotAngularVelocity.yRotationRate These are also shown in each of the Java **Sample OpModes** listed in a section below. -[

Return to Top](#introduction)

+

[[Return to Top|https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Universal-IMU-Interface]]

## Reset Heading @@ -494,7 +497,7 @@ There does seem to be some weirdness with the yaw reset, if both pitch and roll --> -[

Return to Top](#introduction)

+

[[Return to Top|https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Universal-IMU-Interface]]

## Sample OpModes @@ -506,15 +509,13 @@ Here's an [**image**](https://raw.githubusercontent.com/wiki/FIRST-Tech-Challeng In Java, three Sample OpModes demonstrate the new universal IMU interface: -- [**ConceptExploringIMUOrientation.java**](https://github.com/FIRST-Tech-Challenge/FtcRobotController/blob/master/FtcRobotController/src/main/java/org/firstinspires/ftc/robotcontroller/external/samples/ConceptExploringIMUOrientation.java) [**[draft link]**](https://github.com/WestsideRobotics/Universal-IMU-Interface/blob/main/Examples/ConceptExploringIMUOrientation.java) provides a tool to experiment with setting your Hub orientation on the robot +- [**ConceptExploringIMUOrientation.java**](https://github.com/FIRST-Tech-Challenge/FtcRobotController/blob/master/FtcRobotController/src/main/java/org/firstinspires/ftc/robotcontroller/external/samples/ConceptExploringIMUOrientation.java) provides a tool to experiment with setting your Hub orientation on the robot -- [**SensorIMUOrthogonal.java**](https://github.com/FIRST-Tech-Challenge/FtcRobotController/blob/master/FtcRobotController/src/main/java/org/firstinspires/ftc/robotcontroller/external/samples/SensorIMUOrthogonal.java) [**[draft link]**](https://github.com/WestsideRobotics/Universal-IMU-Interface/blob/main/Examples/SensorIMUOrthogonal.java) shows how to define your Hub orientation on the robot, for simple orthogonal (90 degree) mounting +- [**SensorIMUOrthogonal.java**](https://github.com/FIRST-Tech-Challenge/FtcRobotController/blob/master/FtcRobotController/src/main/java/org/firstinspires/ftc/robotcontroller/external/samples/SensorIMUOrthogonal.java) shows how to define your Hub orientation on the robot, for simple orthogonal (90 degree) mounting -- [**SensorIMUNonOrthogonal.java**](https://github.com/FIRST-Tech-Challenge/FtcRobotController/blob/master/FtcRobotController/src/main/java/org/firstinspires/ftc/robotcontroller/external/samples/SensorIMUNonOrthogonal.java) [**[draft link]**](https://github.com/WestsideRobotics/Universal-IMU-Interface/blob/main/Examples/SensorIMUNonOrthogonal.java) shows how to define (with the Angles method) your Hub orientation on the robot for a non-orthogonal orientation +- [**SensorIMUNonOrthogonal.java**](https://github.com/FIRST-Tech-Challenge/FtcRobotController/blob/master/FtcRobotController/src/main/java/org/firstinspires/ftc/robotcontroller/external/samples/SensorIMUNonOrthogonal.java) shows how to define (with the Angles method) your Hub orientation on the robot for a non-orthogonal orientationThese three Java samples include extensive comments describing the IMU interface, consistent with this tutorial. In particular, `SensorIMUNonOrthogonal.java` describes three helpful examples. -These three Java samples include extensive comments describing the IMU interface, consistent with this tutorial. In particular, `SensorIMUNonOrthogonal.java` describes three helpful examples. - -[

Return to Top](#introduction)

+

[[Return to Top|https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Universal-IMU-Interface]]

## SDK Resources @@ -536,7 +537,7 @@ The new universal IMU classes for SDK 8.1 are: The Javadocs describe other IMU methods and variables not covered in this basic tutorial. -[

Return to Top](#introduction)

+

[[Return to Top|https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Universal-IMU-Interface]]

## Summary @@ -554,7 +555,7 @@ Updating to SDK 8.1 is **optional** for POWERPLAY, if you are not planning to us However **all teams** are encouraged to begin using the universal IMU classes and methods for **new** Blocks and Java code, and consider migrating **existing** code. -[

Return to Top](#introduction)

+

[[Return to Top|https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Universal-IMU-Interface]]

Questions, comments and corrections to westsiderobotics@verizon.net From 7821a979011e9a98cd567fd17a7defc727b718f6 Mon Sep 17 00:00:00 2001 From: Westside Robotics Date: Mon, 5 Dec 2022 10:21:32 -0800 Subject: [PATCH 3/5] 12-5-22 update most references to SDK 8.1.1, and give deep links to Javadocs (with frames) --- Universal-IMU-Interface.md | 40 +++++++++++++++++++------------------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/Universal-IMU-Interface.md b/Universal-IMU-Interface.md index 2811798..58acad5 100644 --- a/Universal-IMU-Interface.md +++ b/Universal-IMU-Interface.md @@ -10,14 +10,14 @@ In September 2022, REV Robotics began shipping [**Control Hubs**](https://www.re The new IMU chip is designated [BHI260AP](https://www.bosch-sensortec.com/products/smart-sensors/bhi260ap/), replacing the old Hub's IMU chip [BNO055](https://www.bosch-sensortec.com/products/smart-sensors/bno055/). Both are from Bosch Sensortec. -The new [**FTC SDK**](https://github.com/FIRST-Tech-Challenge/FtcRobotController/releases) **version 8.1** provides a **universal interface** that supports both the BHI260AP and BNO055 IMU. This basic tutorial introduces some new features: +The new [**FTC SDK**](https://github.com/FIRST-Tech-Challenge/FtcRobotController/releases) **version 8.1.1** provides a **universal interface** that supports both the BHI260AP and BNO055 IMU. This basic tutorial introduces some new features: - robot configuration allows selection of IMU type - universal classes and methods supporting both IMU types - three ways to specify Hub mounting orientation on the robot -Teams using the new Control Hub IMU must use the new SDK 8.1. +Teams using the new Control Hub IMU must use the new SDK 8.1.1. -Updating to SDK 8.1 is **optional** for POWERPLAY, if you are not planning to use the new Control Hub IMU. +Updating to SDK 8.1 or 8.1.1 is **optional** for POWERPLAY, if you are not planning to use the new Control Hub IMU. However **all teams** are encouraged to begin using the universal IMU classes and methods for **new** Blocks and Java code. And, migrating **existing code** would allow you to switch easily (and perhaps urgently) to a new Control Hub during the season. @@ -32,7 +32,7 @@ Each Hub's IMU type is listed there, as of FTC SDK 8.0. _Reminder: REV Expansion Hubs purchased after December 2021 have no internal IMU._ -Do you have existing OpModes using the old IMU? Your code can run unchanged, using Hubs with the BNO055. The new SDK 8.1 fully supports legacy Blocks and Java code using classes and methods for the BNO055 IMU. +Do you have existing OpModes using the old IMU? Your code can run unchanged, using Hubs with the BNO055. The new SDK 8.1.1 fully supports legacy Blocks and Java code using classes and methods for the BNO055 IMU. The SDK 8.1 README provides more technical background: >Unlike the old `BNO055IMU` interface, which only worked correctly when the REV Hub was mounted flat on your robot, the `IMU` interface allows you to specify the orientation of the REV Hub on your robot. It will account for this, and give you your orientation in a Robot Coordinate System, instead of a special coordinate system for the REV Hub. As a result, your pitch and yaw will be 0 when your *robot* is level, instead of when the REV Hub is level, which will result in much more reliable orientation angle values for most mounting orientations. @@ -122,7 +122,7 @@ This tutorial will **not** discuss the FTC [Field Coordinate System](https://git ## Physical Hub Mounting -Under SDK 8.1, you can specify the **physical orientation** of the Hub on the robot. This allows you to receive IMU angle values expressed in **robot axes**, useful for understanding and managing the robot's movement. +Under SDK 8.1.1, you can specify the **physical orientation** of the Hub on the robot. This allows you to receive IMU angle values expressed in **robot axes**, useful for understanding and managing the robot's movement. Before jumping into programming, let's discuss your options for physically mounting the Hub on the robot. In general, the Hub's mounting can be considered **Orthogonal** or **Non-Orthogonal**. @@ -158,13 +158,13 @@ Here are some scenarios, ranging from simple to complex: - The Hub is tilted at multiple angles, with or without in-plane rotation. -For any Non-Orthogonal scenarios, SDK 8.1 provides **two ways** to describe the Hub's orientation. See below for the **Angles** method and the **Quaternion** method. +For any Non-Orthogonal scenarios, SDK 8.1.1 provides **two ways** to describe the Hub's orientation. See below for the **Angles** method and the **Quaternion** method.

[[Return to Top|https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Universal-IMU-Interface]]

## IMU Programming -SDK 8.1 offers new classes and methods that apply **universally** to both types of IMU. Once configured, the IMU type will not affect your programming. +SDK 8.1.1 offers new classes and methods that apply **universally** to both types of IMU. Once configured, the IMU type will not affect your programming. The programming steps include: - set the IMU **parameters**, or use defaults @@ -232,7 +232,7 @@ In this starting orientation, the Hub axes are **aligned with** the Robot Coordi Hub rotations also follow the right-hand rule. -_The legacy `BNO055IMU` driver used **different Hub axes**: its X axis pointed to the USB port, and Y axis pointed to the left-side motor ports. The new SDK 8.1 universal IMU driver uses the above Hub axes for BNO055 and BHI260AP._ +_The legacy `BNO055IMU` driver used **different Hub axes**: its X axis pointed to the USB port, and Y axis pointed to the left-side motor ports. The new SDK 8.1.1 universal IMU driver uses the above Hub axes for BNO055 and BHI260AP._

[[Return to Top|https://github.com/FIRST-Tech-Challenge/FtcRobotController/wiki/Universal-IMU-Interface]]

@@ -298,7 +298,7 @@ Or, consider a single rotation of +30 degrees about the X axis. Namely, the Hub new RevHubOrientationOnRobot(new Quaternion(0.9659258f, 0.258819f, 0.0f, 0.0f, 0)); ``` -This basic tutorial does not cover the math behind Quaternions, an advanced substitute for Euler Angles described above. The SDK 8.1 IMU interface supports the use of Quaternions, for FTC teams familiar with them. +This basic tutorial does not cover the math behind Quaternions, an advanced substitute for Euler Angles described above. The SDK 8.1.1 IMU interface supports the use of Quaternions, for FTC teams familiar with them.