Create Your Test Drivetrain Program¶

Configure a drivetrain project for your motor controllers and deploy it to Systemcore. The next page covers motor testing with the wheels off the floor.

Use the Java, C++, or Python walkthrough below, or start with a Blocks sample.

Before beginning, confirm that WPILib and any language-specific tools from Step 2 are installed, Step 3 is complete, and you know the motor-controller type, port numbers or CAN IDs, and team number for your robot.

Start with the WPILib Getting Started example, then check its motor configuration before deploying it to your robot.

Creating a New WPILib Project (Java/C++)
Creating a New WPILib Project (Python)
Starting a Drivetrain Project in Blocks

Important

Choose the hardware tab that matches the motor controllers on your robot. The PWM tab covers the motor controller included in the FRC Kit of Parts. The CTRE tabs cover Talon controllers, and the REV tab covers SPARK controllers. Before deploying a CAN example, install the required vendor library, update the devices, and assign unique CAN IDs using the manufacturer’s instructions.

Starting a Drivetrain Project in Blocks¶

In the Blocks editor, select Samples…, choose a drivetrain sample, then select Create New Project From Sample to make an editable copy. Choose the sample that matches your hardware:

DifferentialDrive301: a two-motor differential drivetrain with A301 motor controllers.
MecanumRobot301: a four-motor mecanum drivetrain with A301 motor controllers.
MecanumRobotExpansionHub: a four-motor mecanum drivetrain with motors connected to a REV Expansion Hub.

See Complete Drivetrain Samples for screenshots and links to each sample’s source. Before running a sample, check the motor connections, controller assignment, and inversion against your robot. A sample for a different motor controller is not a drop-in replacement for your hardware.

Note

The detailed Systemcore Blocks deployment walkthrough is still being completed. Once your program is deployed, FRC teams can follow Running Your Test Program for the pre-enable checks and first drive.

Note

More drivetrain examples for Blocks are coming soon.

The remaining sections describe the Java, C++, and Python workflow.

Creating a New WPILib Project (Java/C++)¶

Open WPILib VS Code. Open the WPILib command palette and select Create a new project:

The WPILib New Project Creator opens.

The project type selector of the WPILib New Project Creator

Select Example, then Next. This starts from a working WPILib example instead of an empty template.

The next page asks for a language and project base.

The language and base page of the WPILib New Project Creator

Language: select Java or C++ to match your choice in Step 2.
Project Base: select Getting Started for this walkthrough.

After making the selections, click Next.

On the Project and Configuration page, choose where to save the project and enter your team number.

The project and configuration page of the WPILib New Project Creator

Base Folder: This determines the folder in which the robot project will be located.
Project Name: The name of the robot project. This also specifies the name that the project folder will be given if the Create New Folder box is checked.
Create a New Folder: If this is checked, a new folder will be created to hold the project within the previously-specified folder. If it is not checked, the project will be located directly in the previously-specified folder. An error will be thrown if the folder is not empty and this is not checked.
Team Number: The team number for the project, which will be used for package names within the project and to locate the robot when deploying code.
Enable Desktop Support: Enables unit test and simulation support (see Introduction to Robot Simulation). While WPILib supports this, third party software libraries may not. If libraries do not support desktop, then your code may not compile or may crash. It should be left unchecked unless unit testing or simulation is needed and all libraries support it. For this example, do not check this box.

Warning

Creating projects on OneDrive is not supported as OneDrive’s caching interferes with the build system. Some Windows installations put the Documents and Desktop folders on OneDrive by default.

Once all the above have been configured, click Next.

This will bring up the Review and Create window. The Review and Create page shows the settings you selected.

The review and create page of the WPILib New Project Creator

Check the language, example, folder, and team number. Use Back to correct a setting, then select Create Project.

Expected result: VS Code offers to open the new project. If creation fails, read the error notification before trying again.

Note

Any errors in project generation will appear in the bottom right-hand corner of the screen.

Opening the New Project¶

Accept the prompt to open your new project. To open it later, press Ctrl+K then Ctrl+O (or Command+O on macOS) and select the project folder.

Click Yes I trust the authors.

The file explorer shows the project folders. Open the Robot source file to inspect the example you will configure in the following sections.

The robot.java code shown after opening a new project.

C++ Configurations (C++ Only)¶

For a C++ project, accept the prompt to refresh C++ configurations. Select Yes to set up IntelliSense for this project.

You must choose "Yes" to refresh the C++ configurations.

Creating a New WPILib Project (Python)¶

Running the robotpy init command will initialize a new robot project:

Windows

py -3 -m robotpy init

macOS

python3 -m robotpy init

Linux

python3 -m robotpy init

This will create a robot.py and pyproject.toml file, but will not overwrite an existing file.

The pyproject.toml file contains the requirements for your project, which are downloaded and installed via the robotpy sync command.
The robot.py file is where you will put your Robot class.

Basic Drivetrain Example¶

Read the complete PWM example below to see how the Robot class connects controller input to motor output. Then use the hardware tabs in the following sections to configure the example for your motor controllers.

Note

the Python example below is from https://github.com/robotpy/mostrobotpy/tree/main/examples/robot/GettingStarted

JAVA

// Copyright (c) FIRST and other WPILib contributors.
// Open Source Software; you can modify and/or share it under the terms of
// the WPILib BSD license file in the root directory of this project.

package org.wpilib.examples.gettingstarted;

import org.wpilib.drive.DifferentialDrive;
import org.wpilib.drivers.motor.PWMSparkMax;
import org.wpilib.driverstation.Gamepad;
import org.wpilib.framework.TimedRobot;
import org.wpilib.system.Timer;

/**
 * The methods in this class are called automatically corresponding to each mode, as described in
 * the TimedRobot documentation. If you change the name of this class or the package after creating
 * this project, you must also update the manifest file in the resource directory.
 */
public class Robot extends TimedRobot {
  private final PWMSparkMax leftDrive = new PWMSparkMax(0);
  private final PWMSparkMax rightDrive = new PWMSparkMax(1);
  private final DifferentialDrive robotDrive =
      new DifferentialDrive(leftDrive::setThrottle, rightDrive::setThrottle);
  private final Gamepad controller = new Gamepad(0);
  private final Timer timer = new Timer();

  /** Called once at the beginning of the robot program. */
  public Robot() {
    // We need to invert one side of the drivetrain so that positive voltages
    // result in both sides moving forward. Depending on how your robot's
    // gearbox is constructed, you might have to invert the left side instead.
    rightDrive.setInverted(true);
  }

  /** This function is run once each time the robot enters autonomous mode. */
  @Override
  public void autonomousInit() {
    timer.restart();
  }

  /** This function is called periodically during autonomous. */
  @Override
  public void autonomousPeriodic() {
    // Drive for 2 seconds
    if (timer.get() < 2.0) {
      // Drive forwards half velocity, make sure to turn input squaring off
      robotDrive.arcadeDrive(0.5, 0.0, false);
    } else {
      robotDrive.arcadeDrive(0.0, 0.0, false); // stop robot
    }
  }

  /** This function is called once each time the robot enters teleoperated mode. */
  @Override
  public void teleopInit() {}

  /** This function is called periodically during teleoperated mode. */
  @Override
  public void teleopPeriodic() {
    robotDrive.arcadeDrive(-controller.getLeftY(), -controller.getRightX());
  }

  /** This function is called once each time the robot enters utility mode. */
  @Override
  public void utilityInit() {}

  /** This function is called periodically during utility mode. */
  @Override
  public void utilityPeriodic() {}
}

C++

// Copyright (c) FIRST and other WPILib contributors.
// Open Source Software; you can modify and/or share it under the terms of
// the WPILib BSD license file in the root directory of this project.

#include "wpi/drive/DifferentialDrive.hpp"
#include "wpi/drivers/motor/PWMSparkMax.hpp"
#include "wpi/driverstation/Gamepad.hpp"
#include "wpi/framework/TimedRobot.hpp"
#include "wpi/system/Timer.hpp"

class Robot : public wpi::TimedRobot {
 public:
  Robot() {
    // We need to invert one side of the drivetrain so that positive voltages
    // result in both sides moving forward. Depending on how your robot's
    // gearbox is constructed, you might have to invert the left side instead.
    right.SetInverted(true);
    robotDrive.SetExpiration(100_ms);
    timer.Start();
  }

  void AutonomousInit() override { timer.Restart(); }

  void AutonomousPeriodic() override {
    // Drive for 2 seconds
    if (timer.Get() < 2_s) {
      // Drive forwards half velocity, make sure to turn input squaring off
      robotDrive.ArcadeDrive(0.5, 0.0, false);
    } else {
      // Stop robot
      robotDrive.ArcadeDrive(0.0, 0.0, false);
    }
  }

  void TeleopInit() override {}

  void TeleopPeriodic() override {
    // Drive with arcade style (use right stick to steer)
    robotDrive.ArcadeDrive(-controller.GetLeftY(), controller.GetRightX());
  }

  void UtilityInit() override {}

  void UtilityPeriodic() override {}

 private:
  // Robot drive system
  wpi::PWMSparkMax left{0};
  wpi::PWMSparkMax right{1};
  wpi::DifferentialDrive robotDrive{
      [&](double output) { left.SetThrottle(output); },
      [&](double output) { right.SetThrottle(output); }};

  wpi::Gamepad controller{0};
  wpi::Timer timer;
};

#ifndef RUNNING_WPILIB_TESTS
int main() {
  return wpi::StartRobot<Robot>();
}
#endif

PYTHON

#!/usr/bin/env python3
#
# Copyright (c) FIRST and other WPILib contributors.
# Open Source Software; you can modify and/or share it under the terms of
# the WPILib BSD license file in the root directory of this project.
#

import wpilib
import wpilib_drivers


class MyRobot(wpilib.TimedRobot):
    def __init__(self):
        """
        This function is called upon program startup and
        should be used for any initialization code.
        """
        super().__init__()
        self.left_drive = wpilib_drivers.PWMSparkMax(0)
        self.right_drive = wpilib_drivers.PWMSparkMax(1)
        self.robot_drive = wpilib.DifferentialDrive(self.left_drive, self.right_drive)
        self.controller = wpilib.Gamepad(0)
        self.timer = wpilib.Timer()

        # We need to invert one side of the drivetrain so that positive voltages
        # result in both sides moving forward. Depending on how your robot's
        # gearbox is constructed, you might have to invert the left side instead.
        self.right_drive.set_inverted(True)

    def autonomous_init(self):
        """This function is run once each time the robot enters autonomous mode."""
        self.timer.restart()

    def autonomous_periodic(self):
        """This function is called periodically during autonomous."""

        # Drive for two seconds
        if self.timer.get() < 2.0:
            # Drive forwards half velocity, make sure to turn input squaring off
            self.robot_drive.arcade_drive(0.5, 0, square_inputs=False)
        else:
            self.robot_drive.arcade_drive(0, 0)  # Stop robot

    def teleop_init(self):
        """This function is called once each time the robot enters teleoperated mode."""

    def teleop_periodic(self):
        """This function is called periodically during teleoperated mode."""
        self.robot_drive.arcade_drive(
            -self.controller.get_left_y(), -self.controller.get_right_x()
        )

    def utility_init(self):
        """This function is called once each time the robot enters utility mode."""

    def utility_periodic(self):
        """This function is called periodically during utility mode."""

Now let’s look at various parts of the code.

Robot Initialization¶

Java

  public Robot() {
    // We need to invert one side of the drivetrain so that positive voltages
    // result in both sides moving forward. Depending on how your robot's
    // gearbox is constructed, you might have to invert the left side instead.
    rightDrive.setInverted(true);
  }

C++

  Robot() {
    // We need to invert one side of the drivetrain so that positive voltages
    // result in both sides moving forward. Depending on how your robot's
    // gearbox is constructed, you might have to invert the left side instead.
    right.SetInverted(true);
    robotDrive.SetExpiration(100_ms);
    timer.Start();
  }

Python

    def __init__(self):
        """
        This function is called upon program startup and
        should be used for any initialization code.
        """
        super().__init__()
        # We need to invert one side of the drivetrain so that positive voltages
        # result in both sides moving forward. Depending on how your robot's
        # gearbox is constructed, you might have to invert the left side instead.
        self.right_drive.set_inverted(True)

The Robot constructor for our sample program inverts the right side of the drivetrain. Depending on your drive setup, you might need to invert the left side instead.

Simple Autonomous Example¶

JAVA

  /** This function is run once each time the robot enters autonomous mode. */
  @Override
  public void autonomousInit() {
    timer.restart();
  }

  /** This function is called periodically during autonomous. */
  @Override
  public void autonomousPeriodic() {
    // Drive for 2 seconds
    if (timer.get() < 2.0) {
      // Drive forwards half velocity, make sure to turn input squaring off
      robotDrive.arcadeDrive(0.5, 0.0, false);
    } else {
      robotDrive.arcadeDrive(0.0, 0.0, false); // stop robot
    }
  }

C++

  void AutonomousInit() override { timer.Restart(); }

  void AutonomousPeriodic() override {
    // Drive for 2 seconds
    if (timer.Get() < 2_s) {
      // Drive forwards half velocity, make sure to turn input squaring off
      robotDrive.ArcadeDrive(0.5, 0.0, false);
    } else {
      // Stop robot
      robotDrive.ArcadeDrive(0.0, 0.0, false);
    }
  }

PYTHON

    def autonomous_init(self):
        """This function is run once each time the robot enters autonomous mode."""
        self.timer.restart()

    def autonomous_periodic(self):
        """This function is called periodically during autonomous."""

        # Drive for two seconds
        if self.timer.get() < 2.0:
            # Drive forwards half velocity, make sure to turn input squaring off
            self.robot_drive.arcade_drive(0.5, 0, square_inputs=False)
        else:
            self.robot_drive.arcade_drive(0, 0)  # Stop robot

The AutonomousInit method is run once each time the robot transitions to autonomous from another mode. In this program, we restart the Timer in this method.

AutonomousPeriodic is run once every period while the robot is in autonomous mode. In the TimedRobot class the period is a fixed time, which defaults to 20ms. In this example, the periodic code checks if the timer is less than 2 seconds and if so, drives forward at half speed using the ArcadeDrive method of the DifferentialDrive class. If more than 2 seconds has elapsed, the code stops the robot drive.

Joystick Control for Teleoperation¶

JAVA

  /** This function is called once each time the robot enters teleoperated mode. */
  @Override
  public void teleopInit() {}

  /** This function is called periodically during teleoperated mode. */
  @Override
  public void teleopPeriodic() {
    robotDrive.arcadeDrive(-controller.getLeftY(), -controller.getRightX());
  }

C++

  void TeleopInit() override {}

  void TeleopPeriodic() override {
    // Drive with arcade style (use right stick to steer)
    robotDrive.ArcadeDrive(-controller.GetLeftY(), controller.GetRightX());
  }

PYTHON

    def teleop_init(self):
        """This function is called once each time the robot enters teleoperated mode."""

    def teleop_periodic(self):
        """This function is called periodically during teleoperated mode."""
        self.robot_drive.arcade_drive(
            -self.controller.get_left_y(), -self.controller.get_right_x()
        )

Like in Autonomous, the Teleop mode has a TeleopInit and TeleopPeriodic function. In this example we don’t have anything to do in TeleopInit, it is provided for illustration purposes only. In TeleopPeriodic, the code uses the ArcadeDrive method to map the Y-axis of the left thumbstick of the Gamepad to forward/back motion of the drive motors and the X-axis to turning motion.

Utility Mode¶

JAVA

  /** This function is called once each time the robot enters utility mode. */
  @Override
  public void utilityInit() {}

  /** This function is called periodically during utility mode. */
  @Override
  public void utilityPeriodic() {}

C++

  void UtilityInit() override {}

  void UtilityPeriodic() override {}

PYTHON

    def utility_init(self):
        """This function is called once each time the robot enters utility mode."""

    def utility_periodic(self):
        """This function is called periodically during utility mode."""

Utility Mode is used for testing robot functionality or running other code that shouldn’t be run in a match. Similar to TeleopInit, the UtilityInit and UtilityPeriodic methods are provided here for illustrative purposes only.

Deploying the Project to a Robot¶

Before deploying, save the program and check that:

The project’s team number matches Systemcore and the Driver Station.
Motor ports or CAN IDs match the wired devices.
The required vendor libraries are installed for a CAN example.
The controller is assigned to the port used by the example.

Connect the computer using the USB or robot-network path verified in Step 3. Keep the robot disabled, then use the command for your language below.

Java/C++

In Visual Studio Code, click the WPILib logo in the top right to launch the WPILib Command Palette. Select Deploy Robot Code to deploy the code to the robot.

Note

The run button in VS Code’s debug view is not used to run robot code. Instead, use the Deploy Robot Code command as described above. The debug view’s run button is used for running and debugging code on the local machine in simulation, which is not applicable for robot code that runs on Systemcore.

For more detailed instructions, see Deploy Java/C++ code.

Python

In the terminal, run the following command to deploy the code to the robot:

Windows

py -3 -m robotpy deploy

macOS

python3 -m robotpy deploy

Linux

python3 -m robotpy deploy

For more detailed instructions, see Deploy Python code.

Expected result: the terminal reports deployment success, and Driver Station shows both robot communication and robot code. If either is missing, read the deploy output and resolve the first error before continuing.

Leave the robot disabled. Continue to Running Your Test Program for the controller checks and first drive test.

✓ Your drivetrain program is deployed.

Continue to the safety checks and first-enable procedure before running the motors.

← Step 4: Write and Drive

Run Your Test Program Safely →

Create Your Test Drivetrain Program¶

Starting a Drivetrain Project in Blocks¶

Creating a New WPILib Project (Java/C++)¶

Opening the New Project¶

C++ Configurations (C++ Only)¶

Creating a New WPILib Project (Python)¶

Basic Drivetrain Example¶

Imports/Includes¶

Defining the variables for our sample robot¶

Robot Initialization¶

Simple Autonomous Example¶

Joystick Control for Teleoperation¶

Utility Mode¶

Deploying the Project to a Robot¶