Expanded on guidance for setting robot configs and MOI (#247)

docs/document-settings.md

@@ -1,91 +1,91 @@
-## Start by downloading Choreo from **[Releases](https://github.com/SleipnirGroup/Choreo/releases)**
+# Robot Configuration
 
-## Robot Config
+The trajectory optimizer depends upon the following user-specified parameters, which are entered in the Robot Configuration panel. The more accurately you enter these paramters, the more confident you can be that your robot will follow the time-optimized trajectory on the first attempt.
 
-The trajectory optimizer depends upon the following user-specified parameters, which are entered in the Robot Configuration panel. This helps the optimizer understand the robot's projected path very accurately.
+!!! tip
+
+    While more precision is always better, you'll most likely get diminishing returns after 3-4 significant figures.
 
 Access the robot-config by accessing the drawer via hamburger icon on top left of screen, then clicking "Document Settings"
 
 ![Document Settings](./media/document-settings.png)
 
-### Dimensions
-
-- **Mass** [kg]: The mass of the robot with battery and bumpers
-- **MoI** [kg * m<sup>2</sup>]: The resistance to change in rotational velocity in response to a torque applied to the robot about the vertical axis
-- **Max Velocity** [m/s]: The maximum tangential speed of the wheel
-
-!!! tip "How to measure Max Velocity"
+!!! tip "Saving Robot Config"
+    Saving a copy of the robotConfig somewhere safe, like the root of a robot project, is highly recommended. This is so you can correlate that robot project to your robot's specifications, and thus your paths.
 
-    A reasonable choice of Max Velocity is that corresponding to ~80% of free speed experienced at the drive motor(s).
+!!! tip "Undo + Redo"
+    Undo and Redo shortcuts work for all of these values.
 
-- **Max Torque** [N * m]: The maximum torque applied at the wheel
+## Dimensions
 
-!!! tip "How to measure Max Torque"
+In this panel, enter some basic properties of your robot chassis.
 
-    A reasonable choice of Max Torque is that corresponding to a current draw of approximately `1.5 * BreakerValue` experienced at the drive motor(s).
+- **Mass** $[kg]$: The mass of the robot with battery and bumpers
+- **MoI** $[kg * m^2]$: The robot's moment of inertia, a measure of resistance to change in rotational velocity in response to a torque applied about the vertical axis
+- **Bumper Width** and **Bumper Length** $[m]$: The overall size of the robot's bumper.
+- **Wheelbase and Trackwidth** $[m]$: The largest distances between the robot's wheel centers
 
-- **Wheelbase and Trackwidth** [m]: The largest distances between the robot's wheel centers
-- **Length and Width** [m]: The overall size of the robot's _bumper_.
+## Drive Motor
 
-!!! tip "Saving Robot Config"
-    Saving a copy of the robotConfig somewhere safe, like the root of a robot project, is highly recommended. This is so you can correlate that robot project to your robot's specifications, and thus your paths.
+This panel asks for details about the drive motors used to propel the robot around the playing field.
 
-!!! tip "Undo + Redo"
-    Undo and Redo shortcuts work for all of these values.
+### Geometric properties
 
-### Measuring Moment of Inertia (MoI)
+- Wheel Radius $[m]$: The radius of the drive wheel
+- Gearing (unitless): The ratio of $(\text{Drive motor rotations} / \text{Wheel rotations})$
 
-The robot's rotational inertia has a significant impact on how quickly it can follow complex paths. For the best results, it is recommended to get as accurate an estimate of this parameter as possible. This can be accomplished via:
+### Motor performance properties
 
-- Faithful CAD loaded with mass properties
-- Physical experimentation
-- Other System Identification methods
+These values can be pre-filled using the [Motor Calculator](#motor-calculator) panel:
 
-If none of these techniques are possible, a reasonable estimate of MoI would be mass _ length _ width / 6 based on the assumption of a rectangle of uniformly-distributed mass.
+- **Motor Max Speed** $[\text{RPM}]$: The maximum speed of each drive motor
 
-!!! tip
+!!! tip "Choosing a Motor Max Speed"
 
-    Of course, more precision is always better. But after ~3 decimals, you will most likely get diminishing returns.
+    A reasonable choice of Motor Max Speed is ~80% of the free speed of the drive motor(s). Although your motors have more speed available, this headroom helps ensure that your robot is able to close any errors and return to the planned trajectory. Use the [Motor Calculator](#motor-calculator) to help select an appropriate value.
 
-### Drive Motor
+- **Motor Max Torque** $[N * m]$: The maximum torque applied by each drive motor
 
-For presets to these values, jump to [Motor Calculator](#motor-calculator)
+!!! tip "Choosing a Max Torque"
 
+    A reasonable choice of Max Torque is that corresponding to a current draw of approximately `1.5 * BreakerValue` experienced at the drive motor(s). Although your motors have more torque available, this headroom helps ensure that your robot is able to close any errors and return to the planned trajectory. Use the [Motor Calculator](#motor-calculator) to help select an appropriate value.
 
-### Theoretical
+## Theoretical
 
-Calculated robot metrics for reference and validation.
+This panel displays calculated metrics about your robot, for reference and validation.
 
 ![robot-config-theoretical.png](./media/robot-config-theoretical.png)
 
-- **Floor Speed** [m/s]: Linear Maximum speed when not rotating
-- **Floor Accel** [m/s<sup>2</sup>]: Linear Maximum acceleration when not rotating
-- **Ang Speed** [rad/s]: Maximum angular speed when spinning in place
-- **Ang Accel** [rad/s<sup>2</sup>]: Maximum angular acceleration when spinning in place
+- **Floor Speed** $[m/s]$: The maximum speed reached by the robot when driving in a straight line and not rotating
+- **Floor Accel** $[m/s^2]$: The maximum acceleration reached by the robot when driving in a straight line and not rotating
+- **Ang Speed** $[rad/s]$: The robot's maximum angular speed when spinning in place
+- **Ang Accel** $[rad/s^2]$: The robot's maximum angular acceleration when spinning in place
+
+## Motor Calculator
 
-### Motor Calculator
+This panel helps you select appropriate drive motor parameters, using motor performance data from [reca.lc/motors](https://reca.lc/motors).
 
 ![robot-config-motor-calculator](./media/robot-config-motor-calculator.png)
 
-Choose from the following motor presets and a current limit in Amps.
+Choose a motor, then enter a current limit in Amps. The calculator displays the following preview values:
+
+- **Preview Max Speed** $[\text{RPM}]$: Estimated speed under load (~80% of free speed)
+- **Preview Max Torque** $[N * m]$: Motor torque at the given current limit
+
+Pressing APPLY will apply these preview values to the [Drive Motor](#drive-motor) panel above.
+
+!!! warning
 
-In addition to modifying the above [Drive Motor](#drive-motor) values, it shows:
+    Make sure to press the APPLY button, or else your values will not save. Don't worry, you can always hit undo at any time to revert.
 
-- **Preview Max Speed** [RPM]: Estimated speed under load (~80% of free speed)
-- **Preview Max Torque** [N • m]: Motor torque at the given current limit
+### Supported motors
 
-Motors Supported:
+The following motors are supported by the calculator:
 
 - Falcon 500
-- Falcon with FOC
+- Falcon 500 with FOC
 - NEO
 - NEO Vortex
 - Kraken X60
-- Kraken with FOC
+- Kraken X60 with FOC
 - CIM
-
-!!! warning
-
-    Make sure to press the APPLY button, or else your values will not save. Don't worry, you can always hit undo at any time to revert.
-
-Free Speed and Torque are from [reca.lc/motors](https://reca.lc/motors)

docs/estimating-moi.md

@@ -0,0 +1,39 @@
+# Estimating and measuring Moment of Inertia (MoI)
+
+The robot's rotational inertia has a significant impact on how quickly it can follow complex, twisty paths. For the best results, it is recommended to get as accurate an estimate of this parameter as possible.
+
+In this section, we present various approaches to determine a resonably accurate estimate of this key property.
+
+## Faithful CAD loaded with mass properties
+
+Most popular CAD tools can calculate the mass properties of solid modeled objects. However, a disciplined approach to CAD work is required for these values to be accurate. 
+
+![REV-2024-starterBot-massProps](./media/REV-2024-starterBot-massProps.png)
+Pictured: [2024 REV ION FRC Starter Bot](https://www.revrobotics.com/ion/frc-starter-bot-24/)
+
+## Physical experimentation
+
+The MoI of irregular objects can be determined experimentally using a compound-pendulum method as described in [The Experimental Determination of the Moments of Inertia of Airplanes by a Simplified Compound-Pendulum Method](https://ntrs.nasa.gov/citations/19930082299), NACA Technical Note No. 1629.
+
+![NACA-TN-1629-figure3](./media/NACA-TN-1629-figure3.png)
+
+## System Identification methods
+
+If thorough System Identification has been performed, the system's MoI can be calculated from:
+
+$$ I = \text{mass} * \dfrac{trackwidth}{2} * \dfrac{kA_\text{angular}}{kA_\text{linear}} $$
+
+where $kA_\text{angular}$ is the angular acceleration feedforward constant of the drivetrain and $kA_\text{linear}$ is the linear acceleration feedforward constant.
+
+## Assuming a simplified mass distribution
+
+If the robot is considered a solid rectangular plate of uniformly-distributed mass, its MoI would be:
+
+$$ I = \dfrac{1}{12} * \text{mass} * (\text{length}^2 + \text{width}^2) $$
+
+However, this would likely be an underestimate because most FRC robots tend to have mass concentrations (e.g. swerve modules) located along the frame perimeter, and are otherwise relatively hollow.
+
+A better estimate could by found by summing each subsystem's contributions to the robot's overall MoI, based on its mass and average distance from the axis of rotation:
+
+$$ I = \sum_{i=1}^n \text{mass}\_\text{subsystem i} * \text{radius}\_\text{subsystem i}^2 $$
+

docs/index.md

@@ -1,15 +1,3 @@
----
-hide:
-  - toc
-  - navigation
----
-
-!!! tip inline end
-
-    See the navigation links in the header or side-bar.
-
-    Click :octicons-three-bars-16: (top left) on mobile.
-
 # Welcome
 
 Welcome to the [Choreo](https://github.com/SleipnirGroup/Choreo) documentation.