FTC-Project-Gen/README.md

FTC Project Generator

Generate clean, testable FTC robot projects. Keep YOUR code separate from the FTC SDK bloat.

Philosophy

Normal FTC Way: Clone their repo, modify their code
This Way: Your code is clean, FTC SDK is just a dependency

One shared SDK, multiple clean projects. Test on PC, deploy when ready.

Quick Start

# Create your first project
./ftc-new-project my-robot

# Create another project (reuses same SDK!)
./ftc-new-project another-bot

# Use specific FTC version
./ftc-new-project test-bot --version v10.0.0

What It Does

1. Checks/clones FTC SDK (once, shared across projects)
2. Creates YOUR clean project with:
   • Minimal structure
   • Test scaffolding
   • Example subsystem
   • Composite build to SDK
3. Ready to code - tests run immediately

Generated Project Structure

my-robot/
├── build.gradle.kts          # Your build (references SDK)
├── settings.gradle.kts       # Composite build setup
├── gradlew                   # Gradle wrapper
├── README.md                 # Project-specific docs
└── src/
    ├── main/java/robot/
    │   ├── Pose2d.java              # Utility classes
    │   ├── subsystems/
    │   │   └── Drive.java           # Example subsystem
    │   ├── hardware/
    │   │   └── MecanumDrive.java    # Hardware impl stub
    │   └── opmodes/
    │       └── TeleOp.java          # FTC OpMode
    └── test/java/robot/
        └── subsystems/
            └── DriveTest.java       # Unit test

Separate (shared):
~/ftc-sdk/                    # FTC SDK (one copy for all projects)

Usage

Development (Day-to-Day)

cd my-robot

# Run tests
./gradlew test

# Watch mode (auto-rerun on save)
./gradlew test --continuous

# Write code, tests pass → you're good!

Deployment (When Ready for Robot)

# 1. Deploy your code to SDK
./gradlew deployToSDK

# 2. Build APK
cd ~/ftc-sdk
./gradlew build

# 3. Install to robot
# Use Android Studio's deploy button, or:
adb install FtcRobotController/build/outputs/apk/debug/FtcRobotController-debug.apk

Multiple Projects

The beauty: one SDK, many projects

# Create project 1
./ftc-new-project swerve-bot

# Create project 2 (reuses SDK!)
./ftc-new-project mecanum-bot

# Create project 3 (still same SDK!)
./ftc-new-project test-chassis

Each project:

• Has its own git repo
• Tests independently
• Deploys to shared SDK
• Can have different license
• Is YOUR code, not FTC's

Commands Reference

# Basic usage
./ftc-new-project <name>

# Specify FTC version
./ftc-new-project <name> --version v10.1.1

# Custom SDK location
./ftc-new-project <name> --sdk-dir ~/my-ftc

# Get help
./ftc-new-project --help

Environment Variables

# Set default SDK location
export FTC_SDK_DIR=~/ftc-sdk

# Now just:
./ftc-new-project my-robot

Pattern: Subsystems

Every generated project follows this pattern:

// Your subsystem
public class MySubsystem {
    private final Hardware hardware;
    
    public MySubsystem(Hardware hardware) {
        this.hardware = hardware;
    }
    
    // Business logic here - tests on PC
    public void doSomething() {
        hardware.doThing();
    }
    
    // Inner interface - implement for robot
    public interface Hardware {
        void doThing();
    }
}

// Test (inline mock)
class MySubsystemTest {
    static class MockHardware implements MySubsystem.Hardware {
        boolean didThing = false;
        public void doThing() { didThing = true; }
    }
    
    @Test
    void test() {
        MockHardware mock = new MockHardware();
        MySubsystem sys = new MySubsystem(mock);
        sys.doSomething();
        assertTrue(mock.didThing);
    }
}

// Hardware impl (for robot)
public class RealHardware implements MySubsystem.Hardware {
    private DcMotor motor;
    
    public RealHardware(HardwareMap map) {
        motor = map.get(DcMotor.class, "motor");
    }
    
    public void doThing() {
        motor.setPower(1.0);
    }
}

Why This Is Better

Traditional FTC:

• Clone 200MB repo
• Your code mixed with SDK
• Hard to test
• Hard to share
• Stuck with their structure

This Way:

• Your project: ~50KB
• SDK: shared, separate
• Easy to test (runs on PC)
• Easy to share (just your code)
• Your structure, your license

FAQ

Q: Can I use multiple FTC versions?
A: Yes! Different projects can reference different SDK dirs.

Q: What if I want to update the SDK?
A: cd ~/ftc-sdk && git pull && git checkout v10.2.0
Or specify new version when creating project.

Q: Does this work with Android Studio?
A: For deployment, yes. For development, use whatever you want (Sublime, vim, etc).

Q: Can I put my project on GitHub with a different license?
A: Yes! Your code is separate. Just don't include SDK files.

Q: What about Control Hub having multiple programs?
A: Each project creates OpModes. Deploy multiple projects to SDK, build once, all show up on Control Hub.

Installation

# Extract the generator
tar xzf ftc-project-generator.tar.gz
cd ftc-project-gen

# Option 1: Run install script (recommended)
./install.sh             # Shows options
sudo ./install.sh        # System-wide install

# Option 2: Manual symlink
sudo ln -s $(pwd)/ftc-new-project /usr/local/bin/

# Option 3: Add to PATH
echo "export PATH=\$PATH:$(pwd)" >> ~/.bashrc
source ~/.bashrc

# Verify installation
ftc-new-project --help

The Magic

When you run tests, your code uses interfaces and mocks - no FTC SDK needed.

When you deploy, your code gets copied to SDK's TeamCode and built with the real FTC libraries.

Your code stays clean. SDK is just a build tool.

Example Session

# Create project
$ ./ftc-new-project my-bot
>>> Checking FTC SDK...
SDK directory exists, checking version...
✓ SDK already at version v10.1.1
>>> Creating project: my-bot
✓ Project created: my-bot

# Develop
$ cd my-bot
$ ./gradlew test
BUILD SUCCESSFUL
2 tests passed

# Add code, tests pass...

# Ready to deploy
$ ./gradlew deployToSDK
Code deployed to TeamCode - ready to build APK

$ cd ~/ftc-sdk
$ ./gradlew build
BUILD SUCCESSFUL

# Install to robot...

Clean, simple, modular. As it should be.

Credits

Built by frustrated mentors who think the standard FTC setup is backwards.

License

MIT - do whatever you want. Unlike FTC's forced BSD license nonsense.