weevil/templates/testing/ARCHITECTURE.md

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:

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

gradlew test

• Runs in seconds on Windows
• No robot connection needed
• Full JUnit reports

3. Deploy to Robot

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.