Python)¶

Once everything is installed, we’re ready to create a robot program. WPILib comes with several templates for robot programs. Use of these templates is highly recommended for new users; however, advanced users are free to write their own robot code from scratch. This article walks through creating a project from one of the provided examples which has some code already written to drive a basic robot.

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

Important

This guide includes code examples that involve vendor hardware for the convenience of the user. In this document, PWM refers to the motor controller included in the KOP. The CTRE tab references the Talon FX motor controller (Falcon 500 motor), but usage is similar for TalonSRX and VictorSPX. The REV tab references the CAN SPARK MAX controlling a brushless motor, but it’s similar for brushed motor. There is an assumption that the user has already installed the required vendordeps and configured the device(s) (update firmware, assign CAN IDs, etc) according to the manufacturer documentation (CTRE / REV).

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

In Visual Studio Code, click the WPILib logo in the top right to launch the WPILib Command Palette. Select Create a new project:

This will bring up the “WPILIb New Project Creator”

The project type selector of the WPILib New Project Creator

The Project Type chooses between an empty template project, or a WPILib example project. For this example, select Example and then choose Next.

This will bring up the language and base selection window.

The language and base page of the WPILib New Project Creator

Language: This is the language (C++ or Java) that will be used for this project.
Project Base: This box is used to select the base class or example to generate the project from. For this example, select Getting Started

After making the selections, click Next.

This will bring up the Project and Configuration window.

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 of the WPILib New Project Creator

Double check all the settings and click Create Project. If anything is not correct, click Back and make the necessary corrections.

Note

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

Opening The New Project¶

After successfully creating your project, VS Code will give the option of opening the project as shown above. We can choose to do that now or later by typing Ctrl+K then Ctrl+O (or just Command+O on macOS) and select the folder where we saved our project.

Click Yes I trust the authors.

Once opened we will see the project hierarchy on the left. Double clicking on the file will open that file in the editor.

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

C++ Configurations (C++ Only)¶

For C++ projects, there is one more step to set up IntelliSense. Whenever we open a project, we should get a pop-up in the bottom right corner asking to refresh C++ configurations. Click “Yes” to set up IntelliSense.

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 the your Robot class.

Basic Drivetrain example¶

First, here is what a simple code can look like for a Drivetrain with PWM controlled motors (such as SparkMax).

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.driverstation.Gamepad;
import org.wpilib.framework.TimedRobot;
import org.wpilib.hardware.motor.PWMSparkMax;
import org.wpilib.system.Timer;
import org.wpilib.util.sendable.SendableRegistry;

/**
 * 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() {
    SendableRegistry.addChild(robotDrive, leftDrive);
    SendableRegistry.addChild(robotDrive, rightDrive);

    // 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.stopMotor(); // 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/driverstation/Gamepad.hpp"
#include "wpi/framework/TimedRobot.hpp"
#include "wpi/hardware/motor/PWMSparkMax.hpp"
#include "wpi/system/Timer.hpp"

class Robot : public wpi::TimedRobot {
 public:
  Robot() {
    wpi::util::SendableRegistry::AddChild(&robotDrive, &left);
    wpi::util::SendableRegistry::AddChild(&robotDrive, &right);

    // 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


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.leftDrive = wpilib.PWMSparkMax(0)
        self.rightDrive = wpilib.PWMSparkMax(1)
        self.robotDrive = wpilib.DifferentialDrive(self.leftDrive, self.rightDrive)
        self.controller = wpilib.NiDsXboxController(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.rightDrive.setInverted(True)

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

    def autonomousPeriodic(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.robotDrive.arcadeDrive(0.5, 0, squareInputs=False)
        else:
            self.robotDrive.stopMotor()  # Stop robot

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

    def teleopPeriodic(self):
        """This function is called periodically during teleoperated mode."""
        self.robotDrive.arcadeDrive(
            -self.controller.getLeftY(), -self.controller.getRightX()
        )

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

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

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

Robot Initialization¶

Java

  /** 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);
  }

C++

 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();
  }

Python

def robotInit(self):

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.stopMotor(); // 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 autonomousInit(self):
        """This function is run once each time the robot enters autonomous mode."""
        self.timer.restart()

    def autonomousPeriodic(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.robotDrive.arcadeDrive(0.5, 0, squareInputs=False)
        else:
            self.robotDrive.stopMotor()  # 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());
  }

  void UtilityInit() override {}

PYTHON

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

    def teleopPeriodic(self):
        """This function is called periodically during teleoperated mode."""
        self.robotDrive.arcadeDrive(
            -self.controller.getLeftY(), -self.controller.getRightX()
        )

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 utilityInit(self):
        """This function is called once each time the robot enters utility mode."""

    def utilityPeriodic(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¶

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.

Creating your Test Drivetrain Program (Java/C++/Python)¶

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¶