Subsystem Tutorials - Lakers Team 2534

Learn to build FRC robot subsystems using industry-standard patterns

This repository contains a tutorial series for learning to build FRC robot subsystems using the Command-Based programming framework. Each tutorial includes comprehensive tests that verify your implementation - watch your tests go from RED to GREEN as you complete each tutorial!

What You'll Learn

Context Pattern for clean configuration
SubsystemBase extension and lifecycle
Command Factories and button binding
Sensor Integration with auto-stop logic
PID Control with motion profiling
Test-Driven Learning with immediate feedback

Tutorial Series

Tutorial 1: Simple Subsystem

Build a basic intake mechanism

Time: 30 minutes
Level: Beginner
Hardware: 1 TalonSRX motor
Tests: 13 tests to verify completion

Tutorial 2: Intermediate Subsystem

Build a game piece loader with sensors

Time: 45 minutes
Level: Intermediate
Hardware: 2 motors + 2 IR sensors
Tests: 20 tests to verify completion

Tutorial 3: Advanced Subsystem

Build a PID-controlled arm

Time: 60-90 minutes
Level: Advanced
Hardware: SparkMax + encoder + limit switches
Tests: 24 tests to verify completion

Best Practices Guide

Patterns, anti-patterns, and debugging tips

VSCode Git Integration & Workflow Guide

Tips for effectively using VSCode and Git

Git Configuration & Setup

Git configuration guide

Quick Start

Prerequisites

WPILib 2025 installed
Java 17
VS Code with WPILib extension
Git (optional, for version control)

Quick Installation and Setup

Installation of the prerequisites can be handled in 2 main steps:

Download and install WPILib as described in the WPILib Installation Guide. This includes the WPILib tools, Visual Studio Code, and all dependencies needed to develop and deploy code to the roboRIO.
Download and install Git

Windows: git-scm.com
MacOS: Install the Command Line Tools package in Terminal

Configure Git

Windows: Open Git Bash
MacOS: Open Terminal

In the terminal window that appears, specify your name and email via the commands below.

# Set your name and email (used in commits)
git config --global user.name "Your name"
git config --global user.email "Your email"

Setup

Clone or download this repository
- Open 2025 WPILib VS Code
- Open the Command Palette by pressing Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (Mac).
- Type Git: Clone and select the command.
- When prompted for the URL, enter https://github.com/BLlakers/lakers-subsystem-tutorials.git
- Select a local directory on your computer where you want the repository to be saved. This will be the parent directory for your new local copy.
- After the cloning is complete, a prompt will appear asking if you would like to Open Repository or Open Folder. Select one to open the newly cloned project in your workspace.
Build the project (skip tests initially)
- Open the Command Palette by pressing Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (Mac).
- Type WPILib: Run a command in Gradle and select the command.
- When prompted, enter build -x test
Why -x test? All tutorial tests are already written and will fail until you implement the subsystems. Use -x test to skip tests during initial setup and while working through tutorials. Once you complete a tutorial, run its tests to verify your implementation!

How to Use This Repository

Learning Path

1. Read Tutorial 1 markdown file
   ↓
2. Create IntakeContext.java (following tutorial)
   ↓
3. Build: ./gradlew build -x test
   ↓
4. Create Intake.java (following tutorial)
   ↓
5. Run tests: ./gradlew test --tests "frc.robot.tutorial1.*"
   ↓
6. Fix any failing tests
   ↓
7. All tests pass? Tutorial 1 Complete!
   ↓
8. Move to Tutorial 2

Test-Driven Learning

This repository uses test-driven learning:

RED: Tests fail because you haven't implemented the feature yet
GREEN: Tests pass when you've completed the tutorial correctly
Refactor: Clean up your code while keeping tests green

Example workflow:

# Run all Tutorial 1 tests
./gradlew test --tests "frc.robot.tutorial1.*"

# Run specific test class
./gradlew test --tests "frc.robot.tutorial1.IntakeContextTest"

# Run tests with detailed output
./gradlew test --tests "frc.robot.tutorial1.*" --info

Project Structure

frc-subsystem-tutorials/
├── docs/
│   └── dev/                 # Development guide markdown files
│       ├── 01_VSCODE_GIT_WORKFLOW.md
│       ├── 02_GIT_CONFIG_SETUP.md
│   └── tutorials/                 # Tutorial markdown files
│       ├── 01_SIMPLE_SUBSYSTEM_TUTORIAL.md
│       ├── 02_INTERMEDIATE_SUBSYSTEM_TUTORIAL.md
│       ├── 03_ADVANCED_SUBSYSTEM_TUTORIAL.md
        ├── 04_BEST_PRACTICES_GUIDE.md
│       └── ...
│
├── src/main/java/frc/robot/
│   ├── Main.java                   # Robot entry point
│   ├── Robot.java                  # Main robot class
│   ├── RobotContainer.java         # ← Add your subsystems here
│   ├── Constants.java              # Hardware port numbers
│   │
│   ├── support/                    # Support classes (pre-built)
│   │   ├── PIDSettings.java
│   │   ├── DIOChannel.java
│   │   └── sparkmax/
│   │       ├── TeamSparkMax.java
│   │       ├── TeamSparkMaxImpl.java
│   │       └── TeamSparkMaxSimImpl.java
│   │
│   └── subsystems/                 # ← Create your subsystems here
│       ├── intake/                 # Tutorial 1
│       ├── loader/                 # Tutorial 2
│       └── arm/                    # Tutorial 3
│
└── src/test/java/frc/robot/
    ├── tutorial1/                  # Tutorial 1 tests
    │   ├── README.md
    │   ├── IntakeContextTest.java
    │   └── IntakeTest.java
    │
    ├── tutorial2/                  # Tutorial 2 tests (coming soon)
    └── tutorial3/                  # Tutorial 3 tests (coming soon)

Verification System

Each tutorial has comprehensive tests that check:

Tutorial 1: Simple Subsystem (13 tests)

IntakeContext class exists and has correct structure
Context has proper @Builder and defaults() method
Context fields have sensible default values
Intake subsystem extends SubsystemBase
Intake has both constructors (no-arg and Context)
Command factory methods exist
Commands return proper Command objects

Tutorial 2: Intermediate Subsystem (20 tests)

Dual motor configuration
Sensor integration
Auto-stop logic
Telemetry implementation

Tutorial 3: Advanced Subsystem (24 tests)

PID controller configuration
Encoder integration
Limit switch safety
Position holding
Motion profiling

Useful Commands

# Build robot code (skip tests while learning)
./gradlew build -x test

# Run all tests (only after completing all tutorials)
./gradlew test

# Run Tutorial 1 tests only
./gradlew test --tests "frc.robot.tutorial1.*"

# Run Tutorial 2 tests only
./gradlew test --tests "frc.robot.tutorial2.*"

# Run Tutorial 3 tests only
./gradlew test --tests "frc.robot.tutorial3.*"

# Run tests with detailed output
./gradlew test --tests "frc.robot.tutorial1.*" --info

# Clean build
./gradlew clean

# Format code (Palantir Java Format)
./gradlew spotlessApply

# Check code formatting
./gradlew spotlessCheck

# Run robot simulator
./gradlew simulateJava

# Deploy to robot (skip tests)
./gradlew deploy -x test

Tracking Your Progress

Tutorial 1 Checklist

Tutorial 2 Checklist

Tutorial 3 Checklist

Learning Objectives

By completing all tutorials, you will be able to:

Use the Context pattern for clean configuration
Build subsystems following WPILib standards
Integrate motors, sensors, and encoders
Create both manual and automatic commands
Implement PID control with motion profiling
Add comprehensive safety features
Debug using SmartDashboard/Shuffleboard
Write testable, maintainable robot code
Follow Lakers Team 2534 coding standards

Getting Help

If Tests Are Failing

Read the error message - Tests provide specific guidance
Check the tutorial - Make sure you followed all steps
Review the code - Compare with tutorial examples
Run specific tests - Isolate which part is failing
Check SmartDashboard - Verify subsystem shows up

Common Issues

Build fails with test errors:

Problem: Running ./gradlew build fails because tests are failing
Solution: Add -x test to skip tests: ./gradlew build -x test
Tests will fail until you complete the tutorials - this is expected!

"Class not found" errors in tests:

Problem: Tests fail with ClassNotFoundException
Solution: This is normal! Tests are checking for classes you haven't created yet
Follow the tutorial to create the required classes

"Method not found" errors:

Check method name spelling
Verify method signature (parameters and return type)
Make sure the method is public

Motor controller errors:

Check CAN IDs in Constants.java
Verify motor is powered on
Use Phoenix Tuner to test motor

Gradle wrapper not executable (Mac/Linux):

Problem: ./gradlew fails with "Permission denied"
Solution: Make gradlew executable: chmod +x gradlew

Additional Resources

Completion Certificate

When you've completed all three tutorials with all tests passing, you will have:

Built 3 complete subsystems from scratch
Learned industry-standard FRC patterns
Written testable, maintainable code
Gained hands-on experience with:
- Motors (TalonSRX, SparkMax)
- Sensors (Analog IR, Digital, Encoders)
- PID Control
- Command-based programming
- Test-driven development

Congratulations - you're ready to contribute to the Lakers Team 2534 codebase!

Ready to start? Open Tutorial 1 and let's build your first subsystem!

Name		Name	Last commit message	Last commit date
Latest commit History 17 Commits
.wpilib		.wpilib
docs		docs
gradle/wrapper		gradle/wrapper
src		src
vendordeps		vendordeps
.gitattributes		.gitattributes
.gitignore		.gitignore
README.md		README.md
build.gradle		build.gradle
gradlew		gradlew
gradlew.bat		gradlew.bat
settings.gradle		settings.gradle

BLlakers/lakers-subsystem-tutorials

Folders and files

Latest commit

History

Repository files navigation