Robot Code

This guide walks new programmers through contributing to our FRC robot codebase. You’ll install the same tools the programming subteam uses, clone the repository, understand the layout, and follow the workflow for proposing changes.

---

Required Tooling

1. IntelliJ IDEA + WPILib Extensions

   1. Download IntelliJ IDEA (Community or Ultimate) from jetbrains.com/idea/download.
   2. Install the WPILib and Gradle plugins (WPILib uses GradleRIO behind the scenes).

   3. Install WPILib tools separately for Driver Station integration:

      https://github.com/wpilibsuite/allwpilib/releases

   Tip

   VS Code with the official WPILib extension also works, but the team standardizes on IntelliJ for deeper Gradle debugging.

2. Java 17 (Temurin)

   1. Download Temurin OpenJDK 17 MSI/PKG from adoptium.net.
   2. Install with defaults and ensure JAVA_HOME is set to the installed path.

   3. Verify the toolchain:

      java -version
      javac -version

3. Git + GitHub CLI (optional)

   1. Install Git from git-scm.com (or via Homebrew/winget).

   2. Configure your identity:

      git config —global user.name “Your Name”
      git config —global user.email “you@team4504.org”

   3. Install GitHub CLI if you prefer pushing/PRs from terminal.

4. Vendor & Driver Tools

   1. Install the latest CTRE Phoenix Tuner (for Talon / Victor controllers) and REV Hardware Client (for Spark MAX).
   2. Keep the roboRIO imaging tool (bundled with WPILib) handy for deploy day.
   3. Optional: install FRC Driver Station on your dev laptop for quick tethered testing.

   Caution

   Always match vendor library versions in build.gradle. Mixing Phoenix/REV releases causes deploy failures.

---

Clone & Build the Robot Code

1. Pick a working directory and clone the robot repository (replace with the actual repo name if different):

   git clone https://github.com/BC-Robotics-4504/robot-code.git
   cd robot-code

2. Import the project into IntelliJ:

   • From the Welcome screen choose Open, select the robot-code folder.
   • Let IntelliJ finish syncing Gradle (watch the status bar).

3. Run the initial dependency download:

   ./gradlew vendorDeps
   ./gradlew build

   The first build pulls WPILib and vendor libraries into ~/.gradle.

4. Configure the WPILib project settings:

   • WPILib Preferences → set Team Number to 4504 so deploy targets the right roboRIO.
   • Confirm Simulation settings match your operating system (GUI enabled).

5. Start a simulation test to verify everything works:

   ./gradlew simulateJava

6. For Windows devs, run IntelliJ inside WSL 2 or make sure the WPILib tools have USB access if deploying over USB.

Note

If Gradle fails with SSL or cache errors, delete the .gradle folder in the repo and re-run ./gradlew build.

---

Project Layout & Coding Guidelines

• src/main/java/frc/robot
  • Constants.java: only place for robot-wide constants. Keep fields public static final.
  • subsystems/: classes extending SubsystemBase that control hardware (Drivetrain, Shooter, etc.).
  • commands/: Command implementations referencing subsystems and operator controls.
  • RobotContainer.java: binds commands to joystick buttons and schedules default commands.
• src/main/deploy/: files copied to the roboRIO filesystem (paths, JSON configs).
• src/test/java: JUnit tests (use GradleRIO’s test runner). Add tests for math helpers, path planners, etc.
• vendordeps/: JSON definitions for CTRE/REV. Commit these files when updating vendor libraries.

Basic rules:

- One subsystem per hardware group.
- No hardware references from commands other than through subsystem APIs.
- Keep blocking `Thread.sleep` out of robot code; use `Command::waitSeconds`.
- Document new commands/subsystems with short class Javadoc + inline comments when logic is tricky.

Tip

Run ./gradlew spotlessApply (if configured) before committing. It auto-formats Java to match the style guide.

---

Day-to-Day Workflow

1. Make sure main is current:

   git checkout main
   git pull origin main

2. Create a branch for your task (ex: new auto routine):

   git checkout -b feat/add-4-note-auto

Note

Branches use the format feat/short-description, fix/issue-id, or docs/topic. Commits follow Conventional Commits (e.g., feat: add arm PID, fix(subsystems): null-check gyro) so history stays readable.

3. Implement the feature:

   • Add or update subsystems/commands/constants as needed.
   • Update RobotContainer bindings.
   • Document operator instructions in the readme or driver notes if required.

4. Test locally:

   • ./gradlew test for unit tests.
   • ./gradlew simulateJava for logic validation.
   • Deploy to a practice robot with ./gradlew deploy (requires network to roboRIO).

5. Review diffs and commit:

   git status
   git add src/main/java/frc/robot/subsystems/Drivetrain.java
   git commit -m "feat: add swerve teleop hold heading"

6. Push and open a PR:

   git push -u origin feat/add-4-note-auto
   gh pr create --fill # optional GitHub CLI helper

7. Request at least one reviewer from the programming lead. Incorporate feedback, re-run tests, and mark the PR ready to merge.

Caution

Never merge if ./gradlew build fails or if practice robot testing hasn’t happened for changes touching drivetrain or autonomous logic.

---

Deploy Checklist

• Branch rebased/merged with latest main.
• ./gradlew build passes.
• Simulation behaves as expected.
• Tested on physical robot (if hardware change).
• Driver station notes updated if controls changed.
• Pull request approved and merged via GitHub.

Following these steps keeps the robot codebase stable and ensures everyone can reproduce your environment quickly. Welcome to the programming team! 🚀