Expand kinematics introduction with why/when guidance

source/docs/software/kinematics-and-odometry/intro-and-chassis-speeds.rst

@@ -9,6 +9,115 @@ The kinematics suite contains classes for differential drive, swerve drive, and
 ## What is odometry?
 Odometry involves using sensors on the robot to create an estimate of the position of the robot on the field. In FRC, these sensors are typically several encoders (the exact number depends on the drive type) and a gyroscope to measure robot angle. The odometry classes utilize the kinematics classes along with periodic user inputs about speeds (and angles in the case of swerve) to create an estimate of the robot's location on the field.
 
+## Why use kinematics and odometry?
+
+Teams should use WPILib's kinematics and odometry classes for several important reasons:
+
+### Enhanced Autonomous Performance
+
+**Accurate path following**: Kinematics and odometry enable your robot to precisely follow complex paths during autonomous. Instead of time-based driving ("go forward for 2 seconds"), your robot can navigate to specific field coordinates and execute sophisticated multi-step autonomous routines.
+
+**Position tracking**: Knowing where your robot is on the field allows you to:
+
+- Drive to specific game pieces or scoring locations
+- Dynamically adjust paths based on current position
+- Create reliable autonomous routines that work consistently
+
+**Self-correction**: Combined with vision systems (like AprilTag detection), odometry can be continuously updated to correct for drift and maintain accuracy throughout a match.
+
+### Field-Oriented Control
+
+For holonomic drivetrains (swerve and mecanum), field-oriented control dramatically improves driver experience:
+
+- Driver joystick inputs remain consistent regardless of robot orientation
+- Pushing forward on the joystick always moves toward the opposite alliance station
+- Robot can face any direction while moving in any direction
+- Significantly reduces driver cognitive load during teleoperation
+
+### Trajectory Generation and Following
+
+Kinematics integrates with WPILib's trajectory generation to create smooth, dynamically-constrained paths:
+
+- Generate realistic trajectories that respect your drivetrain's physical limits
+- Follow paths with feedback control for disturbance rejection
+- Combine with path planning tools like PathPlanner or Choreo
+
+### Common Use Cases
+
+**Autonomous routines**: Navigate to game pieces, score at specific locations, execute multi-step sequences
+
+**Vision-assisted driving**: Use AprilTags or other vision targets to update odometry and drive to precise field locations
+
+**Teleoperation enhancement**: Field-oriented control for intuitive driving of holonomic robots
+
+**Match strategy**: Plan routes that avoid defense, optimize cycle times, coordinate with alliance partners
+
+## When to use each drivetrain type
+
+### Differential Drive
+
+**Best for:**
+- Traditional tank drive, "West Coast Drive", or skid-steer robots
+- 6-wheel or 8-wheel configurations with traction wheels
+- Teams new to advanced control systems
+- When pushing power and traction are priorities
+
+**Characteristics:**
+- Cannot strafe (move sideways)
+- Must turn to change direction
+- High traction and pushing power
+- Simpler mechanical design
+- Non-holonomic (requires Ramsete controller for path following)
+
+**Example code**: See the RamseteCommand example in :doc:`/docs/software/examples-tutorials/wpilib-examples`
+
+### Swerve Drive
+
+**Best for:**
+- Maximum maneuverability and control
+- Competitive teams with advanced programming and build experience
+- When field-oriented control is desired
+- Robots that need to move and rotate independently
+
+**Characteristics:**
+- Holonomic (can move in any direction while facing any direction)
+- Highest mobility and control
+- Most complex mechanically and in software
+- Requires precise module control and calibration
+- Can use high-traction wheels
+
+**Example code**: See the SwerveBot and SwerveControllerCommand examples in :doc:`/docs/software/examples-tutorials/wpilib-examples`
+
+### Mecanum Drive
+
+**Best for:**
+- Teams wanting holonomic drive with simpler mechanics than swerve
+- Robots that benefit from strafing but don't need maximum pushing power
+- When compactness is important
+
+**Characteristics:**
+- Holonomic (can strafe)
+- Simpler than swerve mechanically
+- Lower pushing power due to mecanum wheel design
+- Wheels more prone to wear and slipping
+- Slower when strafing than when driving forward (due to 45° roller angle)
+- Requires careful weight distribution to keep all wheels on ground
+
+**Example code**: See the MecanumBot and MecanumControllerCommand examples in :doc:`/docs/software/examples-tutorials/wpilib-examples`
+
+## Important considerations
+
+**Odometry drift**: Position estimates accumulate error over time, especially during physical contact with other robots. This is normal and expected. Vision-based corrections (using AprilTags) help maintain accuracy.
+
+**Sensor requirements**: All kinematics implementations require:
+- Encoders for measuring wheel/module speeds and positions
+- Gyroscope for measuring robot angle (critical for accurate odometry)
+- For swerve: absolute encoders for module angles
+
+**Autonomous period accuracy**: Odometry is typically very accurate during autonomous (15 seconds) because there's less robot-to-robot contact. Estimates may drift more during teleoperation.
+
+**Coordinate system**: WPILib uses a specific coordinate system. See :doc:`/docs/software/basic-programming/coordinate-system` for details.
+
 ## The ChassisSpeeds Class
 The ``ChassisSpeeds`` object is essential to the new WPILib kinematics and odometry suite. The ``ChassisSpeeds`` object represents the speeds of a robot chassis. This struct has three components: