Unit 0 · Lesson 3

Cloning a Template Project

Nobody starts a robot project from a blank file. The right starting point gives you a working Gradle build, the correct folder structure, and a Robot.java that compiles on the first try — so you can focus on writing code, not fighting configuration.

By the end of this lesson, you will:

Explain why template projects exist and what they give you out of the box
Know the difference between TimedRobot, Command-Based, and a team template
Create a new project using the WPILib project wizard
Clone an existing project from GitHub using the terminal
Navigate and explain every file and folder in a standard WPILib robot project
Run your first successful Gradle build and interpret the output
Set your team number before deploying

Why You Don't Start from Scratch

A WPILib robot project isn't just Java files. It's a specific directory structure, a Gradle build system configured for the roboRIO's ARM architecture, a wpilib_preferences.json that stores your team number, and a Main.java entry point that WPILib's runtime expects to find in exactly the right place. Getting all of that right manually on the first try is unlikely — and unnecessary.

Templates solve this by giving you a known-good starting point. Every file is in the right place, the build works immediately, and the only thing you need to add is your actual robot logic.

💡 What "clone" means

Cloning is a Git operation that downloads a complete copy of a remote repository — including its full history — onto your local machine. For most competitive FRC teams, the team's robot project lives on GitHub, and cloning is how every programmer gets their own working copy to develop from. You'll use this workflow constantly throughout the season.

Three Ways to Start a Project

👇 Click each card to learn when to use it

⏱️

WPILib TimedRobot

tap to learn more

Best for

Learning and experimentation. TimedRobot runs your code in a simple periodic loop — no scheduler, no commands. You see immediate physical feedback and the structure is easy to reason about. This is where Unit 5 begins.

🗂️

WPILib Command-Based

tap to learn more

Best for

Competition robots with multiple mechanisms. Command-Based uses a scheduler to manage subsystems and commands, which scales to complex robots cleanly. Championship teams write all their competition code this way. Covered deeply in Unit 6.

🏆

Team Template

tap to learn more

Best for

Starting a season's robot. A team template is a Command-Based project pre-loaded with the team's vendor libraries, logging setup, drivetrain skeleton, and coding standards. Cloning it means the first commit your student makes is actual robot logic, not boilerplate.

💡 Which one is right for you right now?

For this lesson, create a TimedRobot project. It's simpler, builds faster, and gives you something physical to run when we reach Unit 5. We'll migrate to Command-Based in Unit 6 once you understand why the extra architecture exists — not just how to use it.

Getting Your Project

Use this when you're starting a brand-new project — for practice, for a prototype, or for the first robot of the season before the team has set up a shared repo.

Open WPILib VS Code
Make sure you're using the WPILib-bundled VS Code, not your system installation.
Open the Command Palette
Press Ctrl+Shift+P (or Cmd+Shift+P on Mac) and type WPILib: Create a new project. Select it from the dropdown.
Configure the project
A form appears with several fields:

Project Type: Template
Language: Java
Base: TimedRobot (for now)
Project Name: Something descriptive — MyFirstRobot or your team's name
Team Number: Your FRC team number — this is important, set it correctly
Folder: Where to save the project on your computer
Click "Generate Project"
WPILib creates the full project structure, opens it in VS Code, and runs an initial Gradle sync in the background. Wait for the sync to complete before opening Java files.
Run a build to verify
Press Ctrl+Shift+P → WPILib: Build Robot Code. You should see BUILD SUCCESSFUL in the terminal. If you do, your project is ready.

💡 Set your team number correctly

The team number you enter during project creation is stored in .wpilib/wpilib_preferences.json. WPILib uses it to find your roboRIO on the network during deployment. If it's wrong, deploy will fail with a "no robot found" error even if the robot is physically connected. You can change it later via WPILib: Set Team Number in the Command Palette.

Use this when you're joining an existing team project, picking up where last season left off, or cloning a reference implementation to learn from.

⚠️ Git is not bundled with WPILib

WPILib installs VS Code, Java, and Gradle — but not Git. Before you can clone anything, you need Git installed separately. Download it from git-scm.com and verify with git --version in your terminal. On macOS, Git is installed automatically when you install Xcode Command Line Tools.

Find the repository URL
On GitHub, navigate to the repository you want to clone. Click the green Code button and copy the HTTPS URL. It will look like:

https://github.com/team2910/2024-robot.git
Open a terminal
Open any terminal — the one inside WPILib VS Code works fine (Terminal → New Terminal). Navigate to the folder where you want the project to live:

cd ~/Documents/FRC
Run the clone command
git clone https://github.com/team2910/2024-robot.git

Git will download the full repository, including all branches and commit history, into a new folder named after the repo.
Open the cloned folder in WPILib VS Code
In VS Code: File → Open Folder → navigate to the cloned directory → click Open. VS Code will detect the Gradle project and prompt you to trust it — click Yes, I trust the authors.
Run a Gradle build
Ctrl+Shift+P → WPILib: Build Robot Code. On first build, Gradle downloads dependencies from the internet (or your offline Maven cache). This may take a minute. A BUILD SUCCESSFUL message means you're set up correctly.

💡 Private repos require authentication

If your team's repo is private, Git will ask for your GitHub credentials. The easiest setup is a Personal Access Token (PAT) — generate one at github.com → Settings → Developer Settings → Personal access tokens. Use the token as your password when Git prompts you. You only need to do this once per machine if you let your OS keychain save it.

What's Inside a WPILib Project

Every WPILib robot project — whether you created it with the wizard or cloned it from GitHub — has the same core structure. Click any file or folder below to learn what it does and why it matters.

MyFirstRobot/

📁 src/

📁 main/java/frc/robot/

☕ Main.java

🤖 Robot.java

☕ Constants.java

📁 vendordeps/

📁 .wpilib/

🙈 .gitignore

🐘 build.gradle

⚙️ gradlew / gradlew.bat

← click a file or folder to learn what it does

💡 Never rename the robot package

WPILib expects your main Java classes to live at src/main/java/frc/robot/. If you rename or restructure the package, the build will fail in ways that look confusing. The Gradle deploy system hard-codes this path — leave it alone, especially for your first few projects.

Reading Your First Build

After running WPILib: Build Robot Code, the terminal shows Gradle's output. Most of it is routine — but knowing what you're reading builds confidence when things go wrong. Click any line below to learn what it means.

TERMINAL — WPILib: Build Robot Code

./gradlew build > Configure project : Fetching vendordep from file: Phoenix6-frc2025-latest.json Fetching vendordep from file: REVLib-2025.json > Task :compileJava > Task :classes > Task :jar > Task :assemble > Task :check BUILD SUCCESSFUL in 8s 9 actionable tasks: 9 executed

← click a line to explain it

Common First-Build Failures

"Could not resolve com.ctre.phoenix6..." — Your vendor library is installed but you're offline and the offline jars aren't in the Maven cache. Run the offline installer (Lesson 2).
"error: package com.ctre.phoenix6 does not exist" — The vendordep JSON is missing. Re-install the library via Manage Vendor Libraries.
"Could not find tools.jar" — You're running the wrong Java. Make sure you opened the WPILib VS Code, not your system VS Code.
"BUILD FAILED" with no other message — Check the full terminal output by scrolling up. The first error is almost always the real cause; errors below it are usually cascading from the first one.

🔌 System Check

⚙️ Prerequisites Before You Deploy

Building compiles your code. Deploying sends it to the robot. The build in this lesson is laptop-only, but before your first deploy (Lesson 4), verify all of the following:

Team number: Open .wpilib/wpilib_preferences.json and confirm "teamNumber" matches your actual FRC team number. WPILib uses this to find your roboRIO over the network using the hostname roborio-XXXX-frc.local. A wrong team number means deploy always fails — not because of code, but because the tool is looking for a robot that doesn't exist at that address.
roboRIO imaged: The roboRIO must be running the current season's image. You can check the image year in the roboRIO web dashboard at 172.22.11.2 when connected via USB.
Git installed: Run git --version in your terminal. If the command is not found, install Git from git-scm.com before trying to clone any repo.
CAN IDs set: If your project references specific CAN IDs for motors or encoders (as it will starting in Unit 5), those IDs must match what's configured on the physical devices. A mismatch doesn't crash the program — it just silently controls the wrong device, or no device at all.

Knowledge Check

Click an answer to check your understanding.

You cloned your team's robot project and the build fails with "Could not find tools.jar". What is the most likely cause?

1The cloned repo is missing files — you need to clone again
2Your vendor libraries are out of date
3You opened the project in your system VS Code instead of the WPILib VS Code — the wrong Java version is being used
4The build.gradle file is corrupted and needs to be deleted

Your deploy fails with "No robot found at roborio-2910-frc.local" even though the robot is powered on and tethered. Before checking the code, what should you verify?

1That your Java version is 17
2That the team number in .wpilib/wpilib_preferences.json matches your actual team number
3That all vendor libraries are installed
4That Robot.java does not have any compilation errors

A teammate asks why the team uses Command-Based programming instead of TimedRobot for the competition robot. What is the most accurate answer?

1Command-Based compiles faster and produces smaller code
2TimedRobot doesn't support vendor libraries
3Command-Based uses a scheduler to manage subsystems and commands, which scales cleanly to complex robots with multiple mechanisms running concurrently
4FIRST requires all competition robots to use Command-Based

💪 Practice Prompt

Your First Working Project

Complete each step and note your results. You'll use this project in Lesson 4 for your first deploy.

Create a new WPILib TimedRobot project using the project wizard. Name it something meaningful — not Test or Robot1. Enter your real team number.
Open .wpilib/wpilib_preferences.json and confirm your team number is saved correctly. What other fields does this file contain?
Run WPILib: Build Robot Code. Record the build time reported at the end (e.g., BUILD SUCCESSFUL in 12s). Run it a second time — is it faster? Why?
Install CTRE Phoenix 6 and REVLib into this project (from Lesson 2). Run the build again. Does it still succeed?
Open Robot.java. Find the robotInit(), teleopPeriodic(), and autonomousPeriodic() methods. In your own words, write one sentence describing what each one is for. We'll fill them in starting in Unit 5.
Bonus: If your team has a GitHub repository from a past season, clone it. Does it build successfully? If not, what error do you get, and what would you need to fix?