FTC-Project-Gen/QUICKSTART.md

# Quick Start Guide

## Installation

### Linux/macOS

```bash
# 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

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

## Creating Your First Project

```bash
# 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
```bash
./gradlew test --continuous
```

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

### 4. Deploy to Robot

When ready:

```bash
# 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:**
```java
// 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:**
```java
// 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:**
```bash
./gradlew test
```

**4. Create hardware implementation:**
```java
// 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:**
```java
// 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

```bash
# 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:

```bash
# 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:**
```bash
./gradlew clean test
```

**Build fails:**
```bash
./gradlew clean build --refresh-dependencies
```

**Can't deploy:**
```bash
# Check adb connection
adb devices

# Try manual connection
adb connect 192.168.43.1:5555
```

**Gradle issues:**
```bash
# Regenerate wrapper
gradle wrapper --gradle-version 8.9
```

## Next Steps

- Read the full [README.md](README.md)
- Check out [DEVELOPER.md](DEVELOPER.md) if you want to contribute
- See [CHANGELOG.md](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! 🤖