From c5ff1807a6c0b4ef19f985219969fd03d988946e Mon Sep 17 00:00:00 2001 From: Alex Schokking Date: Sat, 3 Oct 2026 14:53:03 -0700 Subject: [PATCH] Migrate the remaining substantive wiki pages Closes the last real gaps found in the wiki-vs-docs coverage audit. Curriculum: - challenges/advanced-swerve-challenges.md - the only curriculum challenge still missing from the docs. Ported as-is. - robot-fundamentals/coordinate-conventions.md - the robot and field reference frames, and which direction is positive for each axis. Tooling: - swerve-debugging.md - on-robot bring-up procedure for a swerve drivetrain. Ported with the "[insert year here]" placeholders resolved to "the current season's repository", and the on-blocks safety step promoted to a warning at the top rather than buried at step 4. - update-seriouslycommonlib.md - REWRITTEN rather than ported. The wiki version walked through updating a git submodule, but neither XbotEdu nor TeamXbot2026 has an SCL submodule any more (no .gitmodules, no directory, empty submodule status). SCL is a Maven artifact pinned by SeriouslyCommonLibVersion in build.gradle, so the page now documents bumping that version, plus the -DuseLocalCommonLib=true path for testing unpublished SCL changes. Co-Authored-By: Claude Opus 5 (1M context) --- docs/.vitepress/config.mts | 4 ++ .../challenges/advanced-swerve-challenges.md | 23 +++++++++ docs/curriculum/index.md | 7 +++ .../coordinate-conventions.md | 19 ++++++++ docs/tooling/swerve-debugging.md | 41 ++++++++++++++++ docs/tooling/update-seriouslycommonlib.md | 47 +++++++++++++++++++ 6 files changed, 141 insertions(+) create mode 100644 docs/curriculum/challenges/advanced-swerve-challenges.md create mode 100644 docs/curriculum/robot-fundamentals/coordinate-conventions.md create mode 100644 docs/tooling/swerve-debugging.md create mode 100644 docs/tooling/update-seriouslycommonlib.md diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 98aa1ae..5c51d12 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -75,12 +75,14 @@ export default defineConfig({ { text: 'Upgrading Using the SeriouslyCommonLib', link: '/curriculum/challenges/upgrading-using-seriouslycommonlib' }, { text: 'Running on a Real Robot', link: '/curriculum/challenges/running-on-a-real-robot' }, { text: 'Auto-stopping Collector', link: '/curriculum/challenges/auto-stopping-collector' }, + { text: 'Advanced Swerve Challenges', link: '/curriculum/challenges/advanced-swerve-challenges' }, ], }, { text: 'Reference', items: [ { text: 'Robot Architecture', link: '/curriculum/robot-fundamentals/robot-architecture' }, + { text: 'Robot Coordinate Conventions', link: '/curriculum/robot-fundamentals/coordinate-conventions' }, { text: 'Mapping Buttons to Commands', link: '/curriculum/robot-fundamentals/operator-command-map' }, { text: 'Git Introduction', link: '/curriculum/getting-started/git-introduction' }, { text: 'Clone with GitHub Desktop', link: '/curriculum/getting-started/clone-with-github-desktop' }, @@ -112,6 +114,8 @@ export default defineConfig({ { text: 'AdvantageScope', link: '/tooling/advantagescope' }, { text: 'QDriverStation', link: '/tooling/qdriverstation' }, { text: 'Elastic', link: '/tooling/elastic' }, + { text: 'Debugging Swerve Drive', link: '/tooling/swerve-debugging' }, + { text: 'Updating SeriouslyCommonLib', link: '/tooling/update-seriouslycommonlib' }, ], }, ], diff --git a/docs/curriculum/challenges/advanced-swerve-challenges.md b/docs/curriculum/challenges/advanced-swerve-challenges.md new file mode 100644 index 0000000..abf0d9c --- /dev/null +++ b/docs/curriculum/challenges/advanced-swerve-challenges.md @@ -0,0 +1,23 @@ +# Advanced Swerve Challenges + +Every robot we've built recently uses **swerve drive**: instead of two fixed sides like tank drive, each of the four wheels can both steer to any angle and drive at its own speed. That makes the robot able to translate in any direction while rotating at the same time. + +This challenge has you drive one from scratch. It builds directly on the rotation and PID work you've already done, so finish the beginner challenges first. + +Notable files: + +* `src/main/java/competition/subsystems/drive/commands/SwerveDriveWithJoysticksCommand.java` +* `src/main/java/competition/subsystems/drive/SwerveDriveSubsystem.java` + +SwerveDriveWithJoysticksCommand: +* Determine how you want to map a desired X velocity (meters/second), Y velocity (meters/second), and rotational velocity (radians/second) from the gamepad and send it to the `move` method on the SwerveDriveSubsystem. + +SwerveDriveSubsystem: +* There is already code to go from ChassisSpeeds to SwerveModuleStates. See the line that sets `desiredSwerveModuleStates` in the `move()` function. `desiredSwerveModuleStates` is an array of 4 `SwerveModuleState`, each of which has a `speedMetersPerSecond` and an `angle` (in radians). +* You will need to have each swerve module point to its respective `angle`. This is very similar to [the earlier challenge about pointing the whole robot to an angle](/curriculum/challenges/rotating-to-a-target-orientation), except here, you are only moving a single swerve module - and the same circular-math gotchas apply, so [PID and Heading for Target Orientation](/curriculum/challenges/pid-and-heading-for-target-orientation) is worth re-reading. +* You will need to have each swerve module drive at its goal velocity. This can also use PID, but note that the goal here is a little different than previous challenges - once the motor has reached its target speed, you will need to keep applying power or the motor will slow down again. + +You can check on your progress using AdvantageScope when the robot code is run in Simulation mode. +* Create a "Swerve" tab and drag AdvantageKit/RealOutputs/SwerveDriveSubsystem/CurrentSwerveState into the Red state, and AdvantageKit/RealOutputs/SwerveDriveSubsystem/DesiredSwerveStates into the Blue state. + * Note that DesiredSwerveStates won't appear until you enable the robot and ensure that the `move()` method is called at least once. +* Create an Odometry or 3D Field tab and drag AdvantageKit/RealOutputs/PoseSubsystem/Location into Poses or 2D Poses, respectively. diff --git a/docs/curriculum/index.md b/docs/curriculum/index.md index 27a7a71..792040f 100644 --- a/docs/curriculum/index.md +++ b/docs/curriculum/index.md @@ -23,6 +23,7 @@ Background you will be pointed at from the challenges, and can come back to any | Page | What It Covers | |------|----------------| | [Robot Architecture](robot-fundamentals/robot-architecture) | Subsystems, Commands, the Scheduler, and how they fit together | +| [Robot Coordinate Conventions](robot-fundamentals/coordinate-conventions) | Which way is positive, for both the robot and the field | | [Mapping Buttons to Commands](robot-fundamentals/operator-command-map) | Binding commands to gamepad buttons | | [Git Introduction](getting-started/git-introduction) | What source control is, and the terms you will see | | [Clone with GitHub Desktop](getting-started/clone-with-github-desktop) | Getting a copy of a repository onto your computer | @@ -57,6 +58,12 @@ Hands-on exercises in the [XbotEdu](https://github.com/Team488/XbotEdu) practice | [Running on a Real Robot](challenges/running-on-a-real-robot) | Deploy your code to a RoboRIO | | [Auto-stopping Collector](challenges/auto-stopping-collector) | Build a subsystem and commands from scratch | +Once those are done, there is one more, considerably harder: + +| Advanced | What You Will Build | +|------|---------------------| +| [Advanced Swerve Challenges](challenges/advanced-swerve-challenges) | Drive a swerve chassis: steer and drive each module independently | + ## AI Tools | Module | What You Will Learn | diff --git a/docs/curriculum/robot-fundamentals/coordinate-conventions.md b/docs/curriculum/robot-fundamentals/coordinate-conventions.md new file mode 100644 index 0000000..c51016d --- /dev/null +++ b/docs/curriculum/robot-fundamentals/coordinate-conventions.md @@ -0,0 +1,19 @@ +# Robot Coordinate Conventions + +What is "forward?" Is it north? Towards the front face of the robot? Towards the red end of the field? The blue? How does rotation fit into all of this? + +We have questions like this constantly when programming the robot, and so we've created a convention that we can all agree on - meaning when the Robot Positioning System needs to talk to the Robot Motion system, they both agree about where "+1 foot distance" will take them. + +Here are the simple rules: +- There are two reference frames: Robot and Field +- Robot + - From the center of mass towards the front of the robot is Positive Y + - From the center of mass towards the right of the robot is Positive X + - When the robot rotates left, that is Positive Yaw + - When the front of the robot is higher than the back of the robot (like a wheelie), that is Positive Pitch + - When the right side of the robot is higher than the left side of the robot, that is Positive Roll +- Field + - From our player station towards the opposing player station is Positive Y + - From the left side of our player station towards the right side of our player station is Positive X + - When anything rotates left, that is Positive Yaw + - (Pitch and Roll are not currently accounted for) diff --git a/docs/tooling/swerve-debugging.md b/docs/tooling/swerve-debugging.md new file mode 100644 index 0000000..319a874 --- /dev/null +++ b/docs/tooling/swerve-debugging.md @@ -0,0 +1,41 @@ +# Debugging the Swerve Drive System + +How to bring up a swerve drivetrain on a real robot and check that every motor is wired and configured correctly. Use this when a robot is new, has been rebuilt, or is driving strangely. + +::: warning +Put the robot **on blocks** before any of this, with the wheels free and not touching anything. A miswired swerve module can drive the robot in an unexpected direction at full power. +::: + +## Set up before testing + +1. Get an Xbox controller for the robot. +2. Update the `main` branch in Git or GitHub Desktop. +3. Open the current season's robot repository (for example `TeamXbot2026`), then run the **Build Robot** configuration. +4. Put the robot you want to test **on blocks**. Make sure the wheels are free and not touching anything. +5. Turn the robot on, then connect to it -- WiFi if it works, otherwise a cable. +6. Open **FRC Driver Station**. +7. Run the **Build & Deploy Robot** configuration while connected to the robot, then connect the controller to your computer. +8. Carefully enable the robot through FRC Driver Station. +9. Open **Elastic (WPILib)**. Choose File, then open layout, find the season repo's `elasticLayout` file, and open it. Halve all the speed limits and set the correct Electrical Contract. + +## Test individual motors + +1. Press **up on the D-Pad** to put the robot into motor testing mode. Press **right on the D-Pad** to switch between individual motors. +2. Test each motor: + - Push the **left joystick** slowly upwards. If that motor's wheel moves in the intended direction, the drive motor works. + - Push the **right joystick** slowly to the right. If the wheel steers in the intended direction, the steering motor works. +3. Repeat for every motor. You only need the up-arrow step once. + +If a motor moves the wrong way or not at all, fix its configuration in the code before continuing. + +## Back to normal driving + +1. Press **down on the D-Pad** to return the robot to normal drive mode. +2. Push the left joystick. All motors should now move together, in the direction you expect. +3. **If the motors jitter**, they may be inverted in the code. Correct the inversion in the [Electrical Contract](/curriculum/robot-fundamentals/electrical-contract). + +## Related + +- [Robot Coordinate Conventions](/curriculum/robot-fundamentals/coordinate-conventions) -- which way is positive, for both the robot and the field +- [Swerve Drive](/core-programming/patterns/swerve-drive) -- how the swerve code is structured +- [Elastic](/tooling/elastic) -- the dashboard used above diff --git a/docs/tooling/update-seriouslycommonlib.md b/docs/tooling/update-seriouslycommonlib.md new file mode 100644 index 0000000..13d7c13 --- /dev/null +++ b/docs/tooling/update-seriouslycommonlib.md @@ -0,0 +1,47 @@ +# Updating SeriouslyCommonLib + +[SeriouslyCommonLib](https://github.com/Team488/SeriouslyCommonLib) (SCL) is the shared library all our robot code builds on. Updating a robot project to a newer SCL means bumping one version number and opening a pull request. + +::: info +SCL used to be a **git submodule** inside each robot project, and updating it meant running git commands inside that submodule folder. That is no longer how it works -- SCL is now a published Maven artifact, and the robot projects pin a version of it. If you find older instructions that tell you to `cd SeriouslyCommonLib`, they are out of date. +::: + +## Bump the version + +1. Make a branch off `main` -- in GitHub Desktop, **Current branch** then **New branch**, named something like `update-scl`. +2. Find the latest published version on the [XBot Azure Artifacts feed](https://dev.azure.com/Team488/Team%20488%20Builds/_artifacts/feed/XBot). +3. Open `build.gradle` and update the version: + + ```groovy + // When in doubt, use the latest version from + // https://dev.azure.com/Team488/Team%20488%20Builds/_artifacts/feed/XBot + def SeriouslyCommonLibVersion = '20260405.5' + ``` + + One constant feeds both the `implementation` and `customAspectJ` dependencies, so this is the only line to change. + +4. Build the project to pull the new version down and confirm it still compiles. +5. Run the tests. SCL changes can alter behavior your robot code depends on, so a green build is not enough on its own. +6. Commit, push, and open a pull request. + +## Testing unreleased SCL changes + +If you need to try SCL changes that have not been published yet, the robot projects support building against a local clone instead of the Maven artifact. + +1. Clone SeriouslyCommonLib **next to** the robot project, so the two sit side by side as `../SeriouslyCommonLib`. +2. Build with the flag: + + ```bash + ./gradlew build -DuseLocalCommonLib=true + ``` + + or set the environment variable `USE_LOCAL_COMMON_LIB=true`. + +Gradle prints which source it used, so you can confirm which one you got: + +``` +✓ Using local SeriouslyCommonLib from ../SeriouslyCommonLib for development +→ Using SeriouslyCommonLib from Maven repository +``` + +Leave the flag off for normal work, and never commit a change that depends on an unpublished local build -- the version in `build.gradle` is what everyone else and the build server will use.