Structurer un projet de robot orienté commande
Alors que les utilisateurs sont libres d’utiliser les bibliothèques orientées commande comme ils le veulent (et les utilisateurs avancés sont encouragés à le faire), les nouveaux utilisateurs pourraient avoir besoin de conseils sur la manière de structurer un projet de robot orienté commande de base.
A standard template for a command-based robot project is included in the WPILib examples repository (Java, C++). This section will walk users through the structure of this template.
Le package/répertoire racine contient généralement quatre classes :
Main, qui est l’application principale du robot (Java seulement). Les nouveaux utilisateurs ne devraient pas toucher à cette classe. Robot, qui est responsable du flux de contrôle principal du code robot. RobotContainer, qui contient des sous-systèmes et des commandes du robot, et c’est là que l’essentielle de la configuration déclarative du robot (par exemple la liaison des boutons avec les commandes) est effectuée. Constants, qui renferme des constantes accessibles globalement, donc à utiliser dans l’ensemble du programme du robot.
Le répertoire racine contiendra aussi deux sous-packages/sous-répertoires : Subsystems contiendra toutes les classes sous-systèmes définies par l’utilisateur. Commands contiendra tout les classes commandes définies par l’utilisateur.
Robot
As Robot (Java, C++ (Header), C++ (Source)) is responsible for the program’s control flow, and command-based is an declarative paradigm designed to minimize the amount of attention the user has to pay to explicit program control flow, the Robot class of a command-based project should be mostly empty. However, there are a few important things that must be included
21 /**
22 * This function is run when the robot is first started up and should be used for any
23 * initialization code.
24 */
25 public Robot() {
26 // Instantiate our RobotContainer. This will perform all our button bindings, and put our
27 // autonomous chooser on the dashboard.
28 m_robotContainer = new RobotContainer();
29 }
In Java, an instance of RobotContainer should be constructed during the Robot constructor - this is important, as most of the declarative robot setup will be called from the RobotContainer constructor.
En C++, ce n’est pas nécessaire, car RobotContainer est un membre valeur et va être construit durant la construction de Robot.
31 /**
32 * This function is called every 20 ms, no matter the mode. Use this for items like diagnostics
33 * that you want ran during disabled, autonomous, teleoperated and test.
34 *
35 * <p>This runs after the mode specific periodic functions, but before LiveWindow and
36 * SmartDashboard integrated updating.
37 */
38 @Override
39 public void robotPeriodic() {
40 // Runs the Scheduler. This is responsible for polling buttons, adding newly-scheduled
41 // commands, running already-scheduled commands, removing finished or interrupted commands,
42 // and running subsystem periodic() methods. This must be called from the robot's periodic
43 // block in order for anything in the Command-based framework to work.
44 CommandScheduler.getInstance().run();
45 }
11/**
12 * This function is called every 20 ms, no matter the mode. Use
13 * this for items like diagnostics that you want to run during disabled,
14 * autonomous, teleoperated and test.
15 *
16 * <p> This runs after the mode specific periodic functions, but before
17 * LiveWindow and SmartDashboard integrated updating.
18 */
19void Robot::RobotPeriodic() {
20 frc2::CommandScheduler::GetInstance().Run();
21}
L’inclusion de l’appel CommandScheduler.getInstance().run() dans la méthode robotPeriodic() est essentielle; sans cela, le planificateur n’exécutera pas les commandes programmées. Puisque TimedRobot s’exécute à la fréquence de la boucle principale (50Hz par défaut), c’est la fréquence à laquelle les commandes périodiques et les méthodes de sous-systèmes s’exécuteront. Il n’est pas recommandé pour les utilisateurs novices d’appeler cette méthode ailleurs dans leur code.
54 /** This autonomous runs the autonomous command selected by your {@link RobotContainer} class. */
55 @Override
56 public void autonomousInit() {
57 m_autonomousCommand = m_robotContainer.getAutonomousCommand();
58
59 // schedule the autonomous command (example)
60 if (m_autonomousCommand != null) {
61 m_autonomousCommand.schedule();
62 }
63 }
32/**
33 * This autonomous runs the autonomous command selected by your {@link
34 * RobotContainer} class.
35 */
36void Robot::AutonomousInit() {
37 m_autonomousCommand = m_container.GetAutonomousCommand();
38
39 if (m_autonomousCommand) {
40 m_autonomousCommand->Schedule();
41 }
42}
La méthode autonomousInit() planifie une commande autonome retournée par l’instance de RobotContainer. La logique pour sélectionner quelle commande autonome sera exécutée peut être gérée à l’intérieur de RobotContainer.
69 @Override
70 public void teleopInit() {
71 // This makes sure that the autonomous stops running when
72 // teleop starts running. If you want the autonomous to
73 // continue until interrupted by another command, remove
74 // this line or comment it out.
75 if (m_autonomousCommand != null) {
76 m_autonomousCommand.cancel();
77 }
78 }
46void Robot::TeleopInit() {
47 // This makes sure that the autonomous stops running when
48 // teleop starts running. If you want the autonomous to
49 // continue until interrupted by another command, remove
50 // this line or comment it out.
51 if (m_autonomousCommand) {
52 m_autonomousCommand->Cancel();
53 }
54}
La méthode teleopInit() annulera toutes les commandes du mode autonome qui sont en train d’être exécutées. C’est généralement une bonne pratique.
Les utilisateurs avancés peuvent ajouter du code additionnel aux méthodes init et periodic comme ils l’entendent; cependant, il faut noter que le fait d’inclure de grandes quantités de code robot impératif dans Robot.java va à l’encontre de la philosophie de conception déclarative du paradigme orienté commande, et peut entraîner un code structuré de manière confuse/désorganisée.
RobotContainer
This class (Java, C++ (Header), C++ (Source)) is where most of the setup for your command-based robot will take place. In this class, you will define your robot’s subsystems and commands, bind those commands to triggering events (such as buttons), and specify which command you will run in your autonomous routine. There are a few aspects of this class new users may want explanations for:
23 private final ExampleSubsystem m_exampleSubsystem = new ExampleSubsystem();
32 ExampleSubsystem m_subsystem;
Notez que les sous-systèmes sont déclarés comme des champs privés dans RobotContainer. Ceci est en contraste notable avec l’incarnation précédente du cadre orienté commande, mais est beaucoup plus aligné sur les meilleures pratiques orientées objet convenues. Si les sous-systèmes sont déclarés comme des variables globales, cela permet à l’utilisateur d’y accéder n’importe où dans le code. Alors que cela peut faciliter certaines choses (par exemple, il n’y aurait pas besoin de passer les sous-systèmes aux commandes pour que ces commandes puissent y avoir accès), cela rend aussi le flux de contrôle du programme beaucoup plus difficile à suivre, car on ne peut pas voir immédiatement quelles parties du code pourraient changer ou pourraient être changées par d’autres parties du code. Cela peut également empêcher le système de gestion de ressources de faire son travail, car la facilité d’accès rend facile pour un utilisateur de faire un appel à une méthode de sous-systèmes hors des commandes gérées par les ressources.
61 return Autos.exampleAuto(m_exampleSubsystem);
34 return autos::ExampleAuto(&m_subsystem);
Puisque les sous-systèmes sont déclarés comme des membres privés, ils doivent être passés explicitement aux commandes (un modèle nommé « dependency injection ») pour que les commandes puissent appeler leurs méthodes. Cela est fait ici avec ExampleCommand, qui se fait passer un pointeur vers un ExampleSubsystem.
35 /**
36 * Use this method to define your trigger->command mappings. Triggers can be created via the
37 * {@link Trigger#Trigger(java.util.function.BooleanSupplier)} constructor with an arbitrary
38 * predicate, or via the named factories in {@link
39 * edu.wpi.first.wpilibj2.command.button.CommandGenericHID}'s subclasses for {@link
40 * CommandXboxController Xbox}/{@link edu.wpi.first.wpilibj2.command.button.CommandPS4Controller
41 * PS4} controllers or {@link edu.wpi.first.wpilibj2.command.button.CommandJoystick Flight
42 * joysticks}.
43 */
44 private void configureBindings() {
45 // Schedule `ExampleCommand` when `exampleCondition` changes to `true`
46 new Trigger(m_exampleSubsystem::exampleCondition)
47 .onTrue(new ExampleCommand(m_exampleSubsystem));
48
49 // Schedule `exampleMethodCommand` when the Xbox controller's B button is pressed,
50 // cancelling on release.
51 m_driverController.b().whileTrue(m_exampleSubsystem.exampleMethodCommand());
52 }
19void RobotContainer::ConfigureBindings() {
20 // Configure your trigger bindings here
21
22 // Schedule `ExampleCommand` when `exampleCondition` changes to `true`
23 frc2::Trigger([this] {
24 return m_subsystem.ExampleCondition();
25 }).OnTrue(ExampleCommand(&m_subsystem).ToPtr());
26
27 // Schedule `ExampleMethodCommand` when the Xbox controller's B button is
28 // pressed, cancelling on release.
29 m_driverController.B().WhileTrue(m_subsystem.ExampleMethodCommand());
30}
As mentioned before, the RobotContainer() constructor is where most of the declarative setup for the robot should take place, including button bindings, configuring autonomous selectors, etc. If the constructor gets too « busy, » users are encouraged to migrate code into separate subroutines (such as the configureBindings() method included by default) which are called from the constructor.
54 /**
55 * Use this to pass the autonomous command to the main {@link Robot} class.
56 *
57 * @return the command to run in autonomous
58 */
59 public Command getAutonomousCommand() {
60 // An example command will be run in autonomous
61 return Autos.exampleAuto(m_exampleSubsystem);
62 }
63}
32frc2::CommandPtr RobotContainer::GetAutonomousCommand() {
33 // An example command will be run in autonomous
34 return autos::ExampleAuto(&m_subsystem);
35}
Finalement, la méthode getAutonomousCommand() fournit un moyen pratique à l’utilisateur pour envoyer sa commande autonome sélectionnée à la classe Robot principale (qui a besoin d’y accèder pour la planifier au début de la période autonome).
Constants
The Constants class (Java, C++ (Header)) (in C++ this is not a class, but simply a header file in which several namespaces are defined) is where globally-accessible robot constants (such as speeds, unit conversion factors, PID gains, and sensor/motor ports) can be stored. It is recommended that users separate these constants into individual inner classes corresponding to subsystems or robot modes, to keep variable names shorter.
En Java, toutes les constantes devraient être déclarées public static final pour qu’elles soient accessibles globalement et ne puissent pas être changées. En C++, toutes les constantes devraient être constexpr.
Pour des exemples plus illustratifs de ce à quoi devrait ressembler une classe Constants en pratique, voir les classes des projets exemples orientés commande :
En java, il est recommandé que les constantes soient utilisées à partir d’autres classes par l’importation statique de la classe intérieure nécessaire. Une déclaration import static importe l’espace de nom statique d’une classe dans la classe dans laquelle vous travaillez pour que les constantes static puissent être référencées directement comme si elles étaient définies dans cette classe. En C++, la même chose peut être faite avec using namespace:
import static edu.wpi.first.wpilibj.templates.commandbased.Constants.OIConstants.*;
using namespace OIConstants;
Subsystems
Les sous-systèmes définis par l’utilisateur devraient entrer dans ce package/répertoire.
Commands
Les commandes définies par l’utilisateur devraient entrer dans cet package/répertoire.