WPILibC++ 2024.3.2
Subsystem.h
Go to the documentation of this file.
1// Copyright (c) FIRST and other WPILib contributors.
2// Open Source Software; you can modify and/or share it under the terms of
3// the WPILib BSD license file in the root directory of this project.
4
5#pragma once
6
7#include <concepts>
8#include <functional>
9#include <string>
10#include <utility>
11
12#include <wpi/FunctionExtras.h>
13
15
16namespace frc2 {
17class Command;
18class CommandPtr;
19/**
20 * A robot subsystem. Subsystems are the basic unit of robot organization in
21 * the Command-based framework; they encapsulate low-level hardware objects
22 * (motor controllers, sensors, etc) and provide methods through which they can
23 * be used by Commands. Subsystems are used by the CommandScheduler's resource
24 * management system to ensure multiple robot actions are not "fighting" over
25 * the same hardware; Commands that use a subsystem should include that
26 * subsystem in their GetRequirements() method, and resources used within a
27 * subsystem should generally remain encapsulated and not be shared by other
28 * parts of the robot.
29 *
30 * <p>Subsystems must be registered with the scheduler with the
31 * CommandScheduler.RegisterSubsystem() method in order for the
32 * Periodic() method to be called. It is recommended that this method be called
33 * from the constructor of users' Subsystem implementations. The
34 * SubsystemBase class offers a simple base for user implementations
35 * that handles this.
36 *
37 * This class is provided by the NewCommands VendorDep
38 *
39 * @see Command
40 * @see CommandScheduler
41 * @see SubsystemBase
42 */
43class Subsystem {
44 public:
45 virtual ~Subsystem();
46 /**
47 * This method is called periodically by the CommandScheduler. Useful for
48 * updating subsystem-specific state that you don't want to offload to a
49 * Command. Teams should try to be consistent within their own codebases
50 * about which responsibilities will be handled by Commands, and which will be
51 * handled here.
52 */
53 virtual void Periodic();
54
55 /**
56 * This method is called periodically by the CommandScheduler. Useful for
57 * updating subsystem-specific state that needs to be maintained for
58 * simulations, such as for updating simulation classes and setting simulated
59 * sensor readings.
60 */
61 virtual void SimulationPeriodic();
62
63 /**
64 * Gets the name of this Subsystem.
65 *
66 * @return Name
67 */
68 virtual std::string GetName() const;
69
70 /**
71 * Sets the default Command of the subsystem. The default command will be
72 * automatically scheduled when no other commands are scheduled that require
73 * the subsystem. Default commands should generally not end on their own, i.e.
74 * their IsFinished() method should always return false. Will automatically
75 * register this subsystem with the CommandScheduler.
76 *
77 * @param defaultCommand the default command to associate with this subsystem
78 */
79 template <std::derived_from<Command> T>
80 void SetDefaultCommand(T&& defaultCommand) {
82 this, std::forward<T>(defaultCommand));
83 }
84
85 /**
86 * Sets the default Command of the subsystem. The default command will be
87 * automatically scheduled when no other commands are scheduled that require
88 * the subsystem. Default commands should generally not end on their own, i.e.
89 * their IsFinished() method should always return false. Will automatically
90 * register this subsystem with the CommandScheduler.
91 *
92 * @param defaultCommand the default command to associate with this subsystem
93 */
94 void SetDefaultCommand(CommandPtr&& defaultCommand);
95
96 /**
97 * Removes the default command for the subsystem. This will not cancel the
98 * default command if it is currently running.
99 */
101
102 /**
103 * Gets the default command for this subsystem. Returns null if no default
104 * command is currently associated with the subsystem.
105 *
106 * @return the default command associated with this subsystem
107 */
109
110 /**
111 * Returns the command currently running on this subsystem. Returns null if
112 * no command is currently scheduled that requires this subsystem.
113 *
114 * @return the scheduled command currently requiring this subsystem
115 */
117
118 /**
119 * Registers this subsystem with the CommandScheduler, allowing its
120 * Periodic() method to be called when the scheduler runs.
121 */
122 void Register();
123
124 /**
125 * Constructs a command that runs an action once and finishes. Requires this
126 * subsystem.
127 *
128 * @param action the action to run
129 */
130 [[nodiscard]]
131 CommandPtr RunOnce(std::function<void()> action);
132
133 /**
134 * Constructs a command that runs an action every iteration until interrupted.
135 * Requires this subsystem.
136 *
137 * @param action the action to run
138 */
139 [[nodiscard]]
140 CommandPtr Run(std::function<void()> action);
141
142 /**
143 * Constructs a command that runs an action once and another action when the
144 * command is interrupted. Requires this subsystem.
145 *
146 * @param start the action to run on start
147 * @param end the action to run on interrupt
148 */
149 [[nodiscard]]
150 CommandPtr StartEnd(std::function<void()> start, std::function<void()> end);
151
152 /**
153 * Constructs a command that runs an action every iteration until interrupted,
154 * and then runs a second action. Requires this subsystem.
155 *
156 * @param run the action to run every iteration
157 * @param end the action to run on interrupt
158 */
159 [[nodiscard]]
160 CommandPtr RunEnd(std::function<void()> run, std::function<void()> end);
161
162 /**
163 * Constructs a DeferredCommand with the provided supplier. This subsystem is
164 * added as a requirement.
165 *
166 * @param supplier the command supplier.
167 * @return the command.
168 */
169 [[nodiscard]]
171};
172} // namespace frc2
This file provides a collection of function (or more generally, callable) type erasure utilities supp...
A state machine representing a complete action to be performed by the robot.
Definition: Command.h:41
A wrapper around std::unique_ptr<Command> so commands have move-only semantics.
Definition: CommandPtr.h:29
static CommandScheduler & GetInstance()
Returns the Scheduler instance.
void SetDefaultCommand(Subsystem *subsystem, T &&defaultCommand)
Sets the default command for a subsystem.
Definition: CommandScheduler.h:184
A robot subsystem.
Definition: Subsystem.h:43
void SetDefaultCommand(CommandPtr &&defaultCommand)
Sets the default Command of the subsystem.
virtual std::string GetName() const
Gets the name of this Subsystem.
void SetDefaultCommand(T &&defaultCommand)
Sets the default Command of the subsystem.
Definition: Subsystem.h:80
Command * GetCurrentCommand() const
Returns the command currently running on this subsystem.
void Register()
Registers this subsystem with the CommandScheduler, allowing its Periodic() method to be called when ...
virtual ~Subsystem()
CommandPtr RunOnce(std::function< void()> action)
Constructs a command that runs an action once and finishes.
CommandPtr RunEnd(std::function< void()> run, std::function< void()> end)
Constructs a command that runs an action every iteration until interrupted, and then runs a second ac...
void RemoveDefaultCommand()
Removes the default command for the subsystem.
virtual void SimulationPeriodic()
This method is called periodically by the CommandScheduler.
virtual void Periodic()
This method is called periodically by the CommandScheduler.
CommandPtr StartEnd(std::function< void()> start, std::function< void()> end)
Constructs a command that runs an action once and another action when the command is interrupted.
CommandPtr Defer(wpi::unique_function< CommandPtr()> supplier)
Constructs a DeferredCommand with the provided supplier.
Command * GetDefaultCommand() const
Gets the default command for this subsystem.
CommandPtr Run(std::function< void()> action)
Constructs a command that runs an action every iteration until interrupted.
unique_function is a type-erasing functor similar to std::function.
Definition: FunctionExtras.h:57
Definition: TrapezoidProfileSubsystem.h:12