From ea0e64b39f8a17f4ce21cb64cf4e9c901da9651e Mon Sep 17 00:00:00 2001 From: jasondaming Date: Thu, 9 Oct 2025 21:59:59 -0500 Subject: [PATCH 1/2] Expand kinematics introduction with why/when guidance - Added 'Why use kinematics and odometry' section explaining benefits - Enhanced autonomous performance discussion (path following, position tracking) - Field-oriented control benefits for holonomic drives - Trajectory generation and common use cases - Added 'When to use each drivetrain type' section - Differential drive: best for traction, pushing power, simpler builds - Swerve drive: maximum maneuverability, most complex - Mecanum drive: holonomic with simpler mechanics than swerve - Added important considerations (drift, sensors, accuracy) - Links to example code for each drivetrain type Fixes #1291 --- .../intro-and-chassis-speeds.rst | 109 ++++++++++++++++++ 1 file changed, 109 insertions(+) diff --git a/source/docs/software/kinematics-and-odometry/intro-and-chassis-speeds.rst b/source/docs/software/kinematics-and-odometry/intro-and-chassis-speeds.rst index e96551569c..85e7986958 100644 --- a/source/docs/software/kinematics-and-odometry/intro-and-chassis-speeds.rst +++ b/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: From 7a33e588c61426e78c6132d2a898e64cddbe3d52 Mon Sep 17 00:00:00 2001 From: jasondaming Date: Wed, 15 Oct 2025 22:20:56 -0500 Subject: [PATCH 2/2] Address review feedback on kinematics introduction MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Changes based on reviewer feedback: 1. Removed "When to use each drivetrain type" section - reviewers felt drivetrain selection should drive code choice, not vice versa, and these characteristics aren't directly related to kinematics/odometry 2. Removed "Field-Oriented Control" section - field-oriented control doesn't require full kinematics/odometry (just gyro), so it was misleading to include here 3. Replaced WPILib example references with vendor examples that follow best practices: - CTRE Phoenix6 examples (differential and swerve with PathPlanner) - REV MAXSwerve Template - YAGSL (Yet Another Generic Swerve Library) This addresses allwpilib#5098 which notes WPILib swerve examples use quadrature encoders instead of absolute encoders 4. Added mecanum odometry accuracy considerations including: - Wheel slipping issues - Benefits of dead wheels for improved accuracy - Vision-based correction recommendations 5. Applied minor wording improvements: - Added "and field elements" to odometry drift explanation - Changed "teleoperation" to "the Teleoperated Period" per manual glossary - Simplified sensor requirements to remove confusing "module speeds and positions" wording 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .../intro-and-chassis-speeds.rst | 77 ++++--------------- 1 file changed, 14 insertions(+), 63 deletions(-) diff --git a/source/docs/software/kinematics-and-odometry/intro-and-chassis-speeds.rst b/source/docs/software/kinematics-and-odometry/intro-and-chassis-speeds.rst index 85e7986958..15e22fe74a 100644 --- a/source/docs/software/kinematics-and-odometry/intro-and-chassis-speeds.rst +++ b/source/docs/software/kinematics-and-odometry/intro-and-chassis-speeds.rst @@ -25,15 +25,6 @@ Teams should use WPILib's kinematics and odometry classes for several important **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: @@ -52,69 +43,29 @@ Kinematics integrates with WPILib's trajectory generation to create smooth, dyna **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` +## Example Code -### Swerve Drive +For drivetrain-specific implementation examples: -**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` +- **Differential Drive**: See the `CTRE Swerve & Swerve Drivetrain examples `__ which also include differential drive path following +- **Swerve Drive**: + - `REV MAXSwerve Template `__ - Complete swerve template from REV Robotics + - `YAGSL (Yet Another Generic Swerve Library) `__ - Vendor-agnostic swerve library + - `CTRE Swerve examples `__ - Swerve with PathPlanner integration +- **Mecanum Drive**: See mecanum-specific examples in vendor documentation ## 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. +**Odometry drift**: Position estimates accumulate error over time, especially during physical contact with other robots and field elements. 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 +- Encoders for measuring wheel speeds - Gyroscope for measuring robot angle (critical for accurate odometry) -- For swerve: absolute encoders for module angles +- For swerve: absolute encoders for measuring module angles + +**Mecanum odometry accuracy**: Mecanum drive odometry can be less accurate than differential or swerve due to wheel slipping. The accuracy depends on movement complexity, robot speed, and weight distribution. For improved accuracy, consider using dead wheels (omni wheels that don't provide drive power but only measure movement) or combining with vision-based corrections. -**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. +**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 the Teleoperated Period. **Coordinate system**: WPILib uses a specific coordinate system. See :doc:`/docs/software/basic-programming/coordinate-system` for details.