feat: Add template system to weevil new command
Implements template-based project creation allowing teams to start with
professional example code instead of empty projects.
Features:
- Two templates: 'basic' (minimal) and 'testing' (45-test showcase)
- Template variable substitution ({{PROJECT_NAME}}, etc.)
- Template validation with helpful error messages
- `weevil new --list-templates` command
- Template files embedded in binary at compile time
Technical details:
- Templates stored in templates/basic/ and templates/testing/
- Files ending in .template have variables replaced
- Uses include_dir! macro to embed templates in binary
- Returns file count for user feedback
Testing template includes:
- 3 complete subsystems (MotorCycler, WallApproach, TurnController)
- Hardware abstraction layer with mock implementations
- 45 comprehensive tests (unit, integration, system)
- Professional documentation (DESIGN_AND_TEST_PLAN.md, etc.)
Usage:
weevil new my-robot # basic template
weevil new my-robot --template testing # testing showcase
weevil new --list-templates # show available templates
This enables FTC teams to learn from working code and best practices
rather than starting from scratch.
This commit is contained in:
Eric Ratliff
199
templates/testing/ARCHITECTURE.md
Normal file
199
templates/testing/ARCHITECTURE.md
Normal file
@@ -0,0 +1,199 @@
|
||||
# Weevil Motor Cycle Demo - Architecture Overview
|
||||
|
||||
## What This Example Demonstrates
|
||||
|
||||
This is a minimal but complete FTC robot project showing how Weevil enables:
|
||||
1. Clean separation of business logic from hardware
|
||||
2. Unit testing on Windows JRE without FTC SDK
|
||||
3. Professional software architecture for robotics
|
||||
|
||||
## The Problem Weevil Solves
|
||||
|
||||
Traditional FTC projects:
|
||||
- Force you to edit SDK files directly (TeamCode folder)
|
||||
- Mix hardware dependencies with business logic
|
||||
- Make testing nearly impossible without a physical robot
|
||||
- Create monolithic OpMode classes that are hard to maintain
|
||||
|
||||
## Weevil's Solution
|
||||
|
||||
### Three-Layer Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────┐
|
||||
│ OpMode (Integration Layer) │ ← Only runs on robot
|
||||
│ - Wires everything together │
|
||||
└─────────────────────────────────┘
|
||||
▼
|
||||
┌─────────────────────────────────┐
|
||||
│ Business Logic Layer │ ← Runs everywhere!
|
||||
│ - MotorCycler │ Tests on Windows JRE
|
||||
│ - Pure Java, no FTC deps │
|
||||
└─────────────────────────────────┘
|
||||
▼
|
||||
┌─────────────────────────────────┐
|
||||
│ Hardware Abstraction Layer │ ← Interface + implementations
|
||||
│ - MotorController (interface) │
|
||||
│ - FtcMotorController (robot) │
|
||||
│ - MockMotorController (tests) │
|
||||
└─────────────────────────────────┘
|
||||
```
|
||||
|
||||
## File Breakdown
|
||||
|
||||
### Hardware Abstraction (`src/main/java/robot/hardware/`)
|
||||
|
||||
**MotorController.java** (17 lines)
|
||||
- Interface defining motor operations
|
||||
- No FTC SDK dependencies
|
||||
- Default methods for convenience
|
||||
|
||||
**FtcMotorController.java** (19 lines)
|
||||
- Wraps FTC SDK's DcMotor
|
||||
- Only compiled when building for robot
|
||||
- Implements MotorController interface
|
||||
|
||||
**MockMotorController.java** (27 lines - in test/)
|
||||
- Test implementation
|
||||
- Tracks state for assertions
|
||||
- No hardware required
|
||||
|
||||
### Business Logic (`src/main/java/robot/subsystems/`)
|
||||
|
||||
**MotorCycler.java** (95 lines)
|
||||
- Pure Java state machine
|
||||
- Time-based motor cycling
|
||||
- Zero FTC SDK dependencies
|
||||
- Fully testable in isolation
|
||||
|
||||
Core design:
|
||||
```java
|
||||
public void update(long currentTimeMs) {
|
||||
long elapsed = currentTimeMs - stateStartTime;
|
||||
|
||||
switch (state) {
|
||||
case OFF:
|
||||
if (elapsed >= offDurationMs) {
|
||||
motor.setPower(motorPower);
|
||||
state = ON;
|
||||
stateStartTime = currentTimeMs;
|
||||
}
|
||||
break;
|
||||
case ON:
|
||||
if (elapsed >= onDurationMs) {
|
||||
motor.setPower(0.0);
|
||||
state = OFF;
|
||||
stateStartTime = currentTimeMs;
|
||||
}
|
||||
break;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Integration (`src/main/java/robot/opmodes/`)
|
||||
|
||||
**MotorCycleOpMode.java** (44 lines)
|
||||
- FTC OpMode
|
||||
- Connects hardware to logic
|
||||
- Minimal glue code
|
||||
|
||||
### Tests (`src/test/java/`)
|
||||
|
||||
**MotorCyclerTest.java** (136 lines)
|
||||
- 9 comprehensive unit tests
|
||||
- Tests timing, state transitions, edge cases
|
||||
- Runs in milliseconds on PC
|
||||
- No robot or FTC SDK required
|
||||
|
||||
Test coverage:
|
||||
- Initialization
|
||||
- State transitions (OFF→ON, ON→OFF)
|
||||
- Full cycle sequences
|
||||
- Time tracking
|
||||
- Stop functionality
|
||||
- Edge cases (default power, tiny power values)
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### 1. Write Code Locally
|
||||
Edit files in `src/main/java/robot/` - your IDE works perfectly
|
||||
|
||||
### 2. Test Immediately
|
||||
```bash
|
||||
gradlew test
|
||||
```
|
||||
- Runs in seconds on Windows
|
||||
- No robot connection needed
|
||||
- Full JUnit reports
|
||||
|
||||
### 3. Deploy to Robot
|
||||
```bash
|
||||
build.bat # Compiles everything, builds APK
|
||||
deploy.bat # Copies APK to robot
|
||||
```
|
||||
|
||||
## Why This Architecture Matters
|
||||
|
||||
### For Students
|
||||
- Learn professional software engineering
|
||||
- Write testable code
|
||||
- Build confidence through tests
|
||||
- Debug logic without hardware
|
||||
|
||||
### For Teams
|
||||
- Multiple programmers can work simultaneously
|
||||
- Test changes before robot practice
|
||||
- Catch bugs early (compile-time, not drive-time)
|
||||
- Build more complex robots with confidence
|
||||
|
||||
### For Competitions
|
||||
- More reliable code
|
||||
- Faster iteration cycles
|
||||
- Better debugging capabilities
|
||||
- Professional development practices
|
||||
|
||||
## Technical Benefits
|
||||
|
||||
1. **Dependency Injection**: MotorCycler receives MotorController through constructor
|
||||
2. **Interface Segregation**: Clean interface with single responsibility
|
||||
3. **Testability**: Mock implementations enable isolated testing
|
||||
4. **Separation of Concerns**: Hardware, logic, and integration are distinct
|
||||
5. **Open/Closed Principle**: Easy to extend without modifying core logic
|
||||
|
||||
## Comparison to Traditional FTC
|
||||
|
||||
| Traditional FTC | Weevil Architecture |
|
||||
|----------------|---------------------|
|
||||
| Edit SDK files directly | Your code stays separate |
|
||||
| Mix hardware and logic | Clean separation |
|
||||
| No unit tests | Comprehensive tests |
|
||||
| Debug on robot only | Debug on PC first |
|
||||
| Monolithic OpModes | Modular subsystems |
|
||||
| Hard to maintain | Easy to understand |
|
||||
|
||||
## Extending This Example
|
||||
|
||||
Want to add more features? Keep the pattern:
|
||||
|
||||
1. **Add Interface** in `hardware/` (e.g., `ServoController`)
|
||||
2. **Implement Logic** in `subsystems/` (e.g., `ArmController`)
|
||||
3. **Create Mock** in `test/hardware/`
|
||||
4. **Write Tests** in `test/subsystems/`
|
||||
5. **Wire in OpMode** - just a few lines of glue code
|
||||
|
||||
The architecture scales from simple examples like this to complex multi-subsystem robots.
|
||||
|
||||
## Real-World Application
|
||||
|
||||
This demo shows the fundamentals. Real robots would have:
|
||||
- Multiple subsystems (drivetrain, arm, intake, etc.)
|
||||
- Command pattern for complex sequences
|
||||
- State machines for autonomous
|
||||
- Sensor integration (same abstraction pattern)
|
||||
- Configuration management
|
||||
|
||||
All testable. All maintainable. All professional.
|
||||
|
||||
---
|
||||
|
||||
**This is what Weevil enables: writing robot code like professional software.**
|
||||
Reference in New Issue
Block a user