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.

Un modèle standard pour un projet de robot orienté commande est inclus dans le dépôt d’exemples WPILib (Java, C++). Cette section guidera les utilisateurs à travers la structure de ce modèle.

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

Alors que Robot (Java, C++ (En-tête), C++ (Source)) est responsable du flux de contrôle du programme et la programmation orientée commande est un paradigme déclaratif conçu pour minimiser l’attention que l’utilisateur doit porter au flux de contrôle du programme explicite, la classe Robot d’un projet orienté commande devrait être presque vide. Cependant, il y a quelques éléments importants qui doivent être inclus.

25
26
27
28
29
30
31
32
33
34
  /**
   * This function is run when the robot is first started up and should be used for any
   * initialization code.
   */
  @Override
  public void robotInit() {
    // Instantiate our RobotContainer.  This will perform all our button bindings, and put our
    // autonomous chooser on the dashboard.
    m_robotContainer = new RobotContainer();
  }

En Java, une instance de RobotContainer devrait être construite dans la méthode robotInit() - cela est important, car l’essentiel de la configuration déclarative du robot sera appelé depuis le constructeur RobotContainer.

En C++, ce n’est pas nécessaire, car RobotContainer est un membre valeur et va être construit durant la construction de Robot.

36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
  /**
   * This function is called every robot packet, no matter the mode. Use this for items like
   * diagnostics that you want ran during disabled, autonomous, teleoperated and test.
   *
   * <p>This runs after the mode specific periodic functions, but before
   * LiveWindow and SmartDashboard integrated updating.
   */
  @Override
  public void robotPeriodic() {
    // Runs the Scheduler.  This is responsible for polling buttons, adding newly-scheduled
    // commands, running already-scheduled commands, removing finished or interrupted commands,
    // and running subsystem periodic() methods.  This must be called from the robot's periodic
    // block in order for anything in the Command-based framework to work.
    CommandScheduler.getInstance().run();
  }

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.

63
64
65
66
67
68
69
70
71
72
73
74
  /**
   * This autonomous runs the autonomous command selected by your {@link RobotContainer} class.
   */
  @Override
  public void autonomousInit() {
    m_autonomousCommand = m_robotContainer.getAutonomousCommand();

    // schedule the autonomous command (example)
    if (m_autonomousCommand != null) {
      m_autonomousCommand.schedule();
    }
  }

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.

83
84
85
86
87
88
89
90
91
92
  @Override
  public void teleopInit() {
    // This makes sure that the autonomous stops running when
    // teleop starts running. If you want the autonomous to
    // continue until interrupted by another command, remove
    // this line or comment it out.
    if (m_autonomousCommand != null) {
      m_autonomousCommand.cancel();
    }
  }

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

Cette classe (Java, C++ (En-tête), C++ (Source)) est où la plupart de la configuration d’un robot orienté commande sera effectuée. Dans cette classe, on définit les sous-systèmes et commandes du robot, lie ces commandes aux événements déclencheurs (tels que les boutons), et spécifie quelle commande sera exécutée dans la routine autonome. Il y a quelques aspects de cette classe pour lesquels de nouveaux utilisateurs pourraient avoir besoin d’explications:

24
  private final ExampleSubsystem m_exampleSubsystem = new ExampleSubsystem();

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.

26
  private final ExampleCommand m_autoCommand = new ExampleCommand(m_exampleSubsystem);

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.

38
39
40
41
42
43
44
45
  /**
   * Use this method to define your button->command mappings.  Buttons can be created by
   * instantiating a {@link GenericHID} or one of its subclasses ({@link
   * edu.wpi.first.wpilibj.Joystick} or {@link XboxController}), and then passing it to a
   * {@link edu.wpi.first.wpilibj2.command.button.JoystickButton}.
   */
  private void configureButtonBindings() {
  }

Comme indiqué précédemment, le constructeur RobotContainer() est le lieu où l’essentiel de la configuration déclarative pour le robot devrait prendre place, incluant la liaison des boutons, la configuration des sélectionneurs autonome, etc. Si le constructeur devient trop « occupé », les utilisateurs sont encouragés à déplacer du code dans des sous-routines séparées (comme la méthode configureButtonBindings() incluse par défaut) qui sont appelées par le constructeur.

48
49
50
51
52
53
54
55
56
57
  /**
   * Use this to pass the autonomous command to the main {@link Robot} class.
   *
   * @return the command to run in autonomous
   */
  public Command getAutonomousCommand() {
    // An ExampleCommand will run in autonomous
    return m_autoCommand;
  }
}

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

La classe Constants (Java, C++ (En-tête)) (en C++, ce n’est pas une classe, mais simplement un fichier en-tête dans lequel plusieurs espaces de noms sont définis) est où les constantes du robot accessibles globalement (comme les vitesses, les facteurs de conversion d’unités, les gains PID, les ports de capteurs/moteurs, etc.) peuvent être stockées. Il est recommandé que les utilisateurs séparent ces constantes en classes internes individuelles qui correspondent aux sous-systèmes ou aux modes du robot pour garder le nom des variables le plus court possible.

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.*;

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.