Initial release: FTC Project Generator
Generate clean, testable FTC robot projects with proper separation from SDK bloat. Features: - Composite build setup - one shared SDK, multiple clean projects - Subsystem pattern with hardware interfaces for easy testing - JUnit scaffolding - tests run on PC without robot - Minimal project structure (~50KB vs 200MB SDK) - Support for multiple FTC SDK versions Philosophy: Your code should be YOUR code. SDK is just a dependency. Built by Nexus Workshops for FTC teams tired of fighting the standard structure. License: MIT
This commit is contained in:
Eric Ratliff
295
README.md
Normal file
295
README.md
Normal file
@@ -0,0 +1,295 @@
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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)
|
||||
|
||||
```bash
|
||||
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)
|
||||
|
||||
```bash
|
||||
# 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**
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```java
|
||||
// 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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.
|
||||
Reference in New Issue
Block a user