FTC-Project-Gen/QUICKSTART.md

Quick Start Guide

Installation

Linux/macOS

# Option 1: System-wide install (recommended)
sudo ./install.sh

# Option 2: User install
INSTALL_DIR=~/.local/bin ./install.sh
# (Make sure ~/.local/bin is in your PATH)

# Option 3: Use directly
./ftc-new-project my-robot

Windows

REM Add directory to PATH or use directly
ftc-new-project.bat my-robot

Creating Your First Project

# Create project
ftc-new-project my-robot

# Enter and start development
cd my-robot
./gradlew test --continuous

That's it! You now have a clean FTC project with:

• ✓ Example drive subsystem
• ✓ Unit tests that run on PC
• ✓ Build scripts
• ✓ Deploy scripts
• ✓ Git repository initialized

Development Workflow

1. Write Code

Edit files in src/main/java/robot/:

• subsystems/ - Your robot logic
• hardware/ - FTC hardware implementations
• opmodes/ - FTC OpModes

2. Write Tests

Edit files in src/test/java/robot/:

• Create tests for each subsystem
• Tests run instantly on PC (no robot needed!)

3. Test Continuously

./gradlew test --continuous

This watches your files and re-runs tests whenever you save. Fast iteration!

4. Deploy to Robot

When ready:

# 1. Uncomment FTC imports in:
#    - src/main/java/robot/hardware/MecanumDrive.java
#    - src/main/java/robot/opmodes/TeleOp.java

# 2. Deploy
./deploy-to-robot.sh

Adding a New Subsystem

1. Create the subsystem:

// src/main/java/robot/subsystems/Intake.java
package robot.subsystems;

public class Intake {
    private final Hardware hardware;
    
    public Intake(Hardware hardware) {
        this.hardware = hardware;
    }
    
    public void grab() {
        hardware.setPower(1.0);
    }
    
    public void release() {
        hardware.setPower(-1.0);
    }
    
    public void stop() {
        hardware.setPower(0.0);
    }
    
    // Hardware interface - inner interface pattern
    public interface Hardware {
        void setPower(double power);
    }
}

2. Create the test:

// src/test/java/robot/subsystems/IntakeTest.java
package robot.subsystems;

import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.*;

class IntakeTest {
    // Inline mock - no FTC SDK needed!
    static class MockHardware implements Intake.Hardware {
        double power = 0;
        public void setPower(double p) { power = p; }
    }
    
    @Test
    void testGrab() {
        MockHardware mock = new MockHardware();
        Intake intake = new Intake(mock);
        
        intake.grab();
        
        assertEquals(1.0, mock.power);
    }
    
    @Test
    void testRelease() {
        MockHardware mock = new MockHardware();
        Intake intake = new Intake(mock);
        
        intake.release();
        
        assertEquals(-1.0, mock.power);
    }
}

3. Test it:

./gradlew test

4. Create hardware implementation:

// src/main/java/robot/hardware/IntakeHardware.java  
package robot.hardware;

import robot.subsystems.Intake;
// import com.qualcomm.robotcore.hardware.DcMotor;
// import com.qualcomm.robotcore.hardware.HardwareMap;

public class IntakeHardware implements Intake.Hardware {
    // private final DcMotor motor;
    
    public IntakeHardware(/* HardwareMap hardwareMap */) {
        // motor = hardwareMap.get(DcMotor.class, "intake");
    }
    
    @Override
    public void setPower(double power) {
        // motor.setPower(power);
    }
}

5. Use in OpMode:

// In your TeleOp init():
// IntakeHardware intakeHw = new IntakeHardware(hardwareMap);
// Intake intake = new Intake(intakeHw);

// In your TeleOp loop():
// if (gamepad1.a) intake.grab();
// if (gamepad1.b) intake.release();

Common Commands

# Run tests once
./gradlew test

# Watch tests (auto-rerun)
./gradlew test --continuous

# Build (compile check)
./gradlew build
# or
./build.sh

# Deploy to robot
./deploy-to-robot.sh

# Deploy via WiFi to custom IP
./deploy-to-robot.sh -i 192.168.1.100

# Clean build
./gradlew clean build

# List all available Gradle tasks
./gradlew tasks

Upgrading Your Project

When a new version of the generator is released:

# Commit your work first
git add .
git commit -m "Save before upgrade"

# Run upgrade
ftc-new-project my-robot --upgrade

# Review changes
git diff

# Test
./gradlew test

Only infrastructure files are updated. Your code is never touched!

Tips

1. Keep FTC imports commented during development
2. Write tests for everything - they're fast and catch bugs early
3. Use continuous testing - ./gradlew test --continuous
4. Commit often - Git protects you during upgrades
5. One SDK, many projects - Create multiple projects, they share the SDK

Troubleshooting

Tests fail:

./gradlew clean test

Build fails:

./gradlew clean build --refresh-dependencies

Can't deploy:

# Check adb connection
adb devices

# Try manual connection
adb connect 192.168.43.1:5555

Gradle issues:

# Regenerate wrapper
gradle wrapper --gradle-version 8.9

Next Steps

• Read the full README.md
• Check out DEVELOPER.md if you want to contribute
• See CHANGELOG.md for version history

Getting Help

• Check documentation in README.md
• Review example code in generated project
• Look at test examples in src/test/java/robot/

Happy coding! 🤖