A modern, cross-platform project generator for FIRST Tech Challenge (FTC) robotics that creates clean, testable, and maintainable robot projects — without forcing students to edit their SDK installation.

The Problem

The official FTC SDK requires teams to:

Clone the entire SDK repository
Edit files directly inside the SDK
Mix team code with framework code
Navigate through hundreds of unfamiliar files
Risk breaking the SDK with every change

This approach works against standard software engineering practices and creates unnecessary barriers for students learning to code. Industry uses libraries, JARs, and dependency management for good reasons — it's time FTC robotics caught up.

The Solution

Weevil generates standalone robot projects that:

✅ Keep your code separate from the SDK
✅ Support local unit testing (no robot needed!)
✅ Work with multiple SDK versions simultaneously
✅ Generate all build/deploy scripts automatically
✅ Enable proper version control workflows
✅ Are actually testable and maintainable
✅ Work seamlessly with Android Studio
✅ Support proxy/air-gapped environments

Students focus on building robots, not navigating SDK internals.

Features

🎯 Clean Project Structure

my-robot/
├── src/
│   ├── main/java/robot/     # Your robot code lives here
│   └── test/java/robot/     # Unit tests (run on PC!)
├── .idea/                   # Android Studio integration (auto-generated)
├── build.sh / build.bat     # One command to build
├── deploy.sh / deploy.bat   # One command to deploy
└── .weevil.toml            # Project configuration

🚀 Simple Commands

# Set up development environment
weevil setup

# Create a new robot project
weevil new awesome-robot

# Test your code (no robot required!)
cd awesome-robot
./gradlew test

# Build and deploy to robot
./build.sh
./deploy.sh --wifi

🔧 Project Management

# Check system health
weevil doctor

# Upgrade project infrastructure
weevil upgrade awesome-robot

# View/change SDK configuration
weevil config awesome-robot
weevil config awesome-robot --set-sdk /path/to/different/sdk

# Check SDK status
weevil sdk status

# Remove installed components
weevil uninstall --dry-run
weevil uninstall

🌐 Proxy Support (v1.1.0)

Work behind corporate firewalls or in air-gapped environments:

# Use HTTP proxy for all downloads
weevil --proxy http://proxy.company.com:8080 setup
weevil --proxy http://proxy.company.com:8080 new my-robot

# Bypass proxy (for local/direct connections)
weevil --no-proxy setup

# Proxy auto-detected from HTTPS_PROXY/HTTP_PROXY environment variables
export HTTPS_PROXY=http://proxy:8080
weevil setup  # Uses proxy automatically

💻 Android Studio Integration (v1.1.0)

Projects work seamlessly with Android Studio:

One-click deployment - Run configurations appear automatically in the Run dropdown
Clean file tree - Internal directories hidden, only your code visible
No configuration needed - Just open the project and hit Run

See Android Studio Setup for details.

✨ Smart Features

Per-project SDK configuration - Different projects can use different SDK versions
Automatic Gradle wrapper - No manual setup required
Cross-platform - Works on Linux, macOS, and Windows
Zero SDK modification - Your SDK stays pristine
Git-ready - Projects initialize with proper .gitignore
Upgrade-safe - Update build scripts without losing code
System diagnostics - weevil doctor checks your environment health
Selective uninstall - Remove specific components without nuking everything

Installation

From Source

git clone https://www.nxgit.dev/nexus-workshops/weevil.git
cd weevil
cargo build --release
sudo cp target/release/weevil /usr/local/bin/

# Or add to PATH
export PATH="$PATH:$(pwd)/target/release"

Prerequisites

Rust 1.70+ (for building Weevil)
Java 11+ (for running Gradle)
Android SDK with platform-tools (for deployment)
FTC SDK (Weevil can install it for you)

Quick Start

1. Set Up Your Environment

# Check what's installed
weevil doctor

# Install everything automatically
weevil setup

# Or install to custom location
weevil setup --ftc-sdk ~/my-sdks/ftc --android-sdk ~/my-sdks/android

Weevil will:

Download and install FTC SDK
Download and install Android SDK (if needed)
Set up Gradle wrapper
Verify all dependencies

2. Create Your First Project

weevil new my-robot
cd my-robot

Weevil generates:

Clean project structure
Android Studio run configurations
Example test files
Build and deploy scripts
Git repository with .gitignore

3. Write Some Code

Create src/main/java/robot/MyOpMode.java:

package robot;

import com.qualcomm.robotcore.eventloop.opmode.TeleOp;
import com.qualcomm.robotcore.eventloop.opmode.LinearOpMode;

@TeleOp(name="My OpMode")
public class MyOpMode extends LinearOpMode {
    @Override
    public void runOpMode() {
        telemetry.addData("Status", "Initialized");
        telemetry.update();
        
        waitForStart();
        
        while (opModeIsActive()) {
            telemetry.addData("Status", "Running");
            telemetry.update();
        }
    }
}

4. Test Locally (No Robot!)

./gradlew test

Write unit tests in src/test/java/robot/ that run on your PC. No need to deploy to a robot for every code change!

5. Deploy to Robot

# Build APK
./build.sh

# Deploy via USB
./deploy.sh --usb

# Deploy via WiFi
./deploy.sh --wifi -i 192.168.49.1

# Auto-detect (tries USB, falls back to WiFi)
./deploy.sh

Android Studio Setup

Opening a Weevil Project

Launch Android Studio
Choose Open (not "New Project")
Navigate to your project directory (e.g., my-robot)
Click OK

Android Studio will index the project. After a few seconds, you'll see:

Clean file tree - Only src/, scripts, and essential files visible
Run configurations - Dropdown next to the green play button shows:
- Build - Builds APK without deploying
- Deploy (auto) - Auto-detects USB or WiFi
- Deploy (USB) - Forces USB connection
- Deploy (WiFi) - Forces WiFi connection
- Test - Runs unit tests

First-Time Setup: Shell Script Plugin

Important: Android Studio requires the Shell Script plugin to run Weevil's deployment scripts.

Go to File → Settings (or Ctrl+Alt+S)
Navigate to Plugins
Click the Marketplace tab
Search for "Shell Script"
Install the plugin (by JetBrains)
Restart Android Studio

After restart, the run configurations will work.

Running from Android Studio

Select a configuration from the dropdown (e.g., "Deploy (auto)")
Click the green play button (▶) or press Shift+F10
Watch the output in the Run panel at the bottom

That's it! Students can now build and deploy without leaving the IDE.

Platform Notes

Linux/macOS: Uses the Unix run configurations (.sh scripts)
Windows: Uses the Windows run configurations (.bat scripts)
Android Studio automatically hides the configurations for the other platform

Advanced Usage

Proxy Configuration

Corporate Environments

# Set proxy for all Weevil operations
weevil --proxy http://proxy.company.com:8080 setup
weevil --proxy http://proxy.company.com:8080 new robot-project

# Or use environment variables (auto-detected)
export HTTPS_PROXY=http://proxy:8080
export HTTP_PROXY=http://proxy:8080
weevil setup  # Automatically uses proxy

Air-Gapped / Offline Installation

If you're on an isolated network without internet:

Download SDKs manually on a connected machine:
- FTC SDK: git clone https://github.com/FIRST-Tech-Challenge/FtcRobotController.git
- Android SDK: Download from https://developer.android.com/studio
- Gradle: Download distribution from https://gradle.org/releases/
Transfer to isolated machine via USB drive

Install using local paths:

weevil setup --ftc-sdk /path/to/FtcRobotController --android-sdk /path/to/android-sdk

Bypass Proxy

# Force direct connection (ignore proxy environment variables)
weevil --no-proxy setup

Multiple SDK Versions

Working with multiple SDK versions? No problem:

# Create project with specific SDK
weevil new experimental-bot --ftc-sdk /path/to/sdk-v11.0

# Later, switch SDKs
weevil config experimental-bot --set-sdk /path/to/sdk-v11.1

# Rebuild with new SDK
weevil upgrade experimental-bot
cd experimental-bot
./build.sh

Upgrading Projects

When Weevil releases new features:

weevil upgrade my-robot

This updates:

Build scripts
Deployment scripts
Gradle configuration
Android Studio run configurations
Project templates

Your code in src/ is never touched.

System Maintenance

# Check what's installed
weevil doctor

# See what can be uninstalled
weevil uninstall --dry-run

# Remove specific components
weevil uninstall --only 1  # Removes FTC SDK only

# Full uninstall (removes everything Weevil installed)
weevil uninstall

Cross-Platform Development

All scripts work on Windows, Linux, and macOS:

Linux/Mac:

./build.sh
./deploy.sh --wifi

Windows:

build.bat
deploy.bat

Android Studio: Works identically on all platforms

Project Configuration

Each project has a .weevil.toml file:

project_name = "my-robot"
weevil_version = "1.1.0"
ftc_sdk_path = "/home/user/.weevil/ftc-sdk"
ftc_sdk_version = "v10.1.1"
android_sdk_path = "/home/user/.weevil/android-sdk"

You can edit this manually or use:

weevil config my-robot                    # View config
weevil config my-robot --set-sdk /new/sdk # Change SDK

Development Workflow

Recommended Git Workflow

# Create project
weevil new competition-bot
cd competition-bot

# Project is already a git repo!
git remote add origin https://nxgit.dev/team/robot.git
git push -u origin main

# Make changes
# ... edit code ...
./gradlew test
git commit -am "Add autonomous mode"
git push

# Deploy to robot
./deploy.sh

Testing Strategy

Unit Tests - Test business logic on your PC

./gradlew test
# Or from Android Studio: select "Test" and click Run

Integration Tests - Test on actual hardware

./build.sh
./deploy.sh --usb
# Run via Driver Station

Team Collaboration

Project Structure is Portable:

# Team member clones repo
git clone https://nxgit.dev/team/robot.git
cd robot

# Check SDK location
weevil config .

# Set SDK to local path (if different from .weevil.toml)
weevil config . --set-sdk ~/ftc-sdk

# Build and deploy
./build.sh
./deploy.sh

Android Studio users: Just open the project. The .idea/ folder contains all run configurations.

Command Reference

Environment Commands

Command	Description
`weevil doctor`	Check system health and dependencies
`weevil setup`	Install FTC SDK, Android SDK, and dependencies
`weevil setup --ftc-sdk <path>`	Install to custom FTC SDK location
`weevil uninstall`	Remove all Weevil-managed components
`weevil uninstall --dry-run`	Show what would be removed
`weevil uninstall --only <N>`	Remove specific component by index

Project Commands

Command	Description
`weevil new <name>`	Create new FTC project
`weevil new <name> --ftc-sdk <path>`	Create with specific SDK
`weevil upgrade <path>`	Update project infrastructure
`weevil config <path>`	View project configuration
`weevil config <path> --set-sdk <sdk>`	Change FTC SDK path

SDK Commands

Command	Description
`weevil sdk status`	Show SDK locations and status
`weevil sdk install`	Download and install SDKs
`weevil sdk update`	Update SDKs to latest versions

Global Flags

Flag	Description
`--proxy <url>`	Use HTTP proxy for all network operations
`--no-proxy`	Bypass proxy (ignore HTTPS_PROXY env vars)

Deployment Options

deploy.sh / deploy.bat flags:

Flag	Description
`--usb`	Force USB deployment
`--wifi`	Force WiFi deployment
`-i <ip>`	Custom Control Hub IP
`--timeout <sec>`	WiFi connection timeout

Architecture

How It Works

Project Generation
- Creates standalone Java project structure
- Generates Gradle build files that reference FTC SDK
- Sets up deployment scripts
- Creates Android Studio run configurations
Build Process
- Runs deployToSDK Gradle task
- Copies your code to FTC SDK's TeamCode directory
- Builds APK using SDK's Android configuration
- Leaves your project directory clean
Deployment
- Finds built APK in SDK
- Connects to Control Hub (USB or WiFi)
- Installs APK using adb
Proxy Support
- reqwest HTTP client respects --proxy flag and HTTPS_PROXY env vars
- git2/libgit2 gets temporary proxy env vars during clone/fetch
- Gradle wrapper reads HTTPS_PROXY natively

Why This Approach?

Separation of Concerns:

Your code: my-robot/src/
Build infrastructure: my-robot/*.gradle.kts
FTC SDK: System-level installation
IDE integration: Auto-generated, auto-upgraded

Benefits:

Test code without SDK complications
Multiple projects per SDK installation
SDK updates don't break your projects
Proper version control (no massive SDK in repo)
Industry-standard project structure
Students use familiar tools (Android Studio)

Testing

Weevil includes comprehensive tests:

# Run all tests
cargo test

# Run specific test suites
cargo test --test integration
cargo test --test project_lifecycle
cargo test --test proxy_integration
cargo test config_tests

Test Coverage:

✅ Project creation and structure
✅ Configuration persistence
✅ SDK detection and validation
✅ Build script generation
✅ Upgrade workflow
✅ CLI commands
✅ Proxy configuration and network operations
✅ Environment setup and health checks

Troubleshooting

"FTC SDK not found"

# Check system health
weevil doctor

# Install SDK
weevil setup

# Or specify custom location
weevil new my-robot --ftc-sdk /custom/path/to/sdk

"adb: command not found"

Install Android platform-tools:

Linux:

# Weevil can install it for you
weevil setup

# Or install manually
sudo apt install android-tools-adb

macOS:

brew install android-platform-tools

Windows: Download Android SDK Platform Tools from Google or run weevil setup.

"Build failed"

# Clean and rebuild
cd my-robot
./gradlew clean
./build.sh

# Check SDK path
weevil config .

# Verify system health
weevil doctor

"Deploy failed - No devices"

USB:

Connect robot via USB
Run adb devices to verify connection
Try ./deploy.sh --usb

WiFi:

Connect to robot's WiFi network
Find Control Hub IP (usually 192.168.43.1 or 192.168.49.1)
Try ./deploy.sh -i <ip>

Android Studio: "Unknown run configuration type ShellScript"

The Shell Script plugin is not installed. See Android Studio Setup for installation instructions.

Proxy Issues

# Test proxy connectivity
weevil --proxy http://proxy:8080 sdk status

# Bypass proxy if it's causing issues
weevil --no-proxy setup

# Check environment variables
echo $HTTPS_PROXY
echo $HTTP_PROXY

Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch
Write tests for new features
Ensure cargo test passes with zero warnings
Submit a pull request

Development Setup

git clone https://www.nxgit.dev/nexus-workshops/weevil.git
cd weevil
cargo build
cargo test

# Run locally
cargo run -- new test-project

Philosophy

Why "Weevil"?

Like the boll weevil that bores through complex cotton bolls to reach the valuable fibers inside, this tool bores through the complexity of the FTC SDK structure to help students reach what matters: building robots and learning to code.

Design Principles:

Students first - Minimize cognitive load for learners
Industry practices - Teach real software engineering
Testability - Enable TDD and proper testing workflows
Simplicity - One command should do one obvious thing
Transparency - Students should understand what's happening
Tool compatibility - Work with tools students already know

License

MIT License - See LICENSE file for details.

Acknowledgments

Created by Eric Ratliff for Nexus Workshops LLC

Built with frustration at unnecessarily complex robotics frameworks, and hope that students can focus on robotics instead of build systems.

For FIRST Tech Challenge teams everywhere - may your builds be fast and your deployments successful. 🤖

Project Status

Current Version: 1.1.0

What Works:

✅ Project generation
✅ Cross-platform build/deploy
✅ SDK management and auto-install
✅ Configuration management
✅ Project upgrades
✅ Local unit testing
✅ System diagnostics (weevil doctor)
✅ Selective uninstall
✅ Proxy support for corporate/air-gapped environments
✅ Android Studio integration with one-click deployment

Roadmap:

📋 Package management for FTC libraries
📋 Template system for common robot configurations
📋 VS Code integration
📋 Team collaboration features
📋 Automated testing on robot hardware
📋 Multi-robot support (manage multiple Control Hubs)

Questions? Issues? Suggestions?

📧 Email: eric@nxlearn.net
🐛 Issues: Open an issue on the repository

Building better tools so you can build better robots. 🤖

Releases 7

v1.0.0 - First Stable Release 🎉 Latest

2026-01-27 01:39:34 +00:00

Languages

Rust 72.1%

Java 27.1%

Shell 0.8%