WPILib supports a robot programming methodology called “command-based” programming. In general, “command-based” can refer both the general programming paradigm, and to the set of WPILib library resources included to facilitate it.

“Command-based” programming is one possible design pattern for robot software. It is not the only way to write a robot program, but it is a very effective one. Command-based robot code tends to be clean, extensible, and (with some tricks) easy to re-use from year to year.

The command-based paradigm is also an example of declarative programming. The command-based library allow users to define desired robot behaviors while minimizing the amount of iteration-by-iteration robot logic that they must write. For example, in the command-based program, a user can specify that “the robot should perform an action when a condition is true” (note the use of a lambda):

Subsystems and Commands

The command-based pattern is based around two core abstractions: commands, and subsystems.

Commands represent actions the robot can take. Commands run when scheduled, until they are interrupted or their end condition is met. Commands are very recursively composable: commands can be composed to accomplish more-complicated tasks. See Commands for more info.

Subsystems represent independently-controlled collections of robot hardware (such as motor controllers, sensors, pneumatic actuators, etc.) that operate together. Subsystems back the resource-management system of command-based: only one command can use a given subsystem at the same time. Subsystems allow users to “hide” the internal complexity of their actual hardware from the rest of their code - this both simplifies the rest of the robot code, and allows changes to the internal details of a subsystem’s hardware without also changing the rest of the robot code.

How Commands Are Run

Note

For a more detailed explanation, see The Command Scheduler.

Commands are run by the CommandScheduler (Java, C++, Python) singleton, which polls triggers (such as buttons) for commands to schedule, preventing resource conflicts, and executing scheduled commands. The scheduler’s run() method must be called; it is generally recommended to call it from the robotPeriodic() method of the Robot class, which is run at a default frequency of 50Hz (once every 20ms).

Multiple commands can run concurrently, as long as they do not require the same resources on the robot. Resource management is handled on a per-subsystem basis: commands specify which subsystems they interact with, and the scheduler will ensure that no more more than one command requiring a given subsystem is scheduled at a time. This ensures that, for example, users will not end up with two different pieces of code attempting to set the same motor controller to different output values.

Command Compositions

It is often desirable to build complex commands from simple pieces. This is achievable by creating a composition of commands. The command-based library provides several types of command compositions for teams to use, and users may write their own. As command compositions are commands themselves, they may be used in a recursive composition. That is to say - one can create a command compositions from multiple command compositions. This provides an extremely powerful way of building complex robot actions from simple components.

6.4 Command Based Programming

Command Based Programming is a programming structure used by FRC to organize how the code is setup and run in a way similar to function calling. The main difference between the two is that a command is a completely seperate file that gets called in something called a scheduler. With this style though, you can easily run multiple commands, set commands to run as a default state, and even cancel commands. This is a very powerful tool that can be used to make your robot do many things at once.

Basic Terminology

Command

A command is a file that contains a set of instructions that can be called by the scheduler. This is the main part of the command based programming structure. Commands can be run in parallel, run as a default state, or even canceled.

Scheduler

The scheduler is a part of the command based programming structure that runs the commands. It is the main part of the command based programming structure. The scheduler is what runs the commands and makes sure that they are running correctly. This process runs about every 20 milliseconds and checks for mapped button presses, joystick movements, and other inputs.

Subsystem

A subsystem is a part of the robot that is controlled by a command. This can be the drive train, the intake, or even the shooter. Subsystems are the main part of the command based programming structure. Subsystems are what the commands control given functions created inside of them and contain all of the setup for components (such as motors for wheels in a Drive Train).

RobotContainer

The robot container is a file that contains all of the commands and subsystems. This is the main part of the command based programming structure. The robot container is what the scheduler runs. This file is where you will map all of the buttons and joysticks to the commands and subsystems, along with all of the other requirements that should be pre-written when a command based project is created.

How to Use Command Based Programming

Creating a Command

To create a command, you need to create a new file in the commands folder. The file should be named after the command. For example, if you were to create a command that drives the robot forward, you would name the file DriveForward. An example of a command is shown below.