Changements apportés lors de la réécriture de 2020

This article provides a summary of changes from the original command-based framework to the 2020 rewrite. This summary is not necessarily comprehensive - for rigorous documentation, as always, refer to the API docs (Java, C++).

Emplacement du package

The new command-based framework is located in the wpilibj2 package for Java, and in the frc2 namespace for C++. The new framework must be installed using the instructions: Librairies des commandes WPILib.

Changements architecturaux majeurs

Dans l’ensemble, la structure du cadre d’application orienté commande est restée la même. Il y a toutefois certains changements architecturaux majeurs dont les utilisateurs doivent être conscients :

Commandes et sous-systèmes en tant qu’interfaces

Command (Java, C++) and Subsystem (Java, C++) are both now interfaces as opposed to abstract classes, allowing advanced users more potential flexibility. CommandBase and SubsystemBase abstract base classes are still provided for convenience, but are not required. For more information, see Commandes and Les sous-systèmes.

Plusieurs classes de groupes de commandes

The CommandGroup class no longer exists, and has been replaced by a number of narrower classes that can be recursively composed to create more-complicated group structures. For more information see Command Compositions.

Définitions de commandes en une seule ligne

Previously, users were required to write a subclass of Command in almost all cases where a command was needed. Many of the new commands are designed to allow inline definition of command functionality, and so can be used without the need for an explicit subclass. For more information, see Included Command Types.

Injection des dépendances des commandes

Bien qu’il ne s’agisse pas d’un réel changement au niveau de la programmation de la bibliothèque, le patron recommandé pour utiliser le nouveau cadre d’application orienté commande est l’injection des sous-systèmes dépendants dans les commandes, ce qui ne requiert plus de déclarer les sous-systèmes comme variables globales. Il s’agit d’un patron beaucoup plus clair, maintenable et réutilisable que la déclaration globale des sous-systèmes, ce qui était anciennement recommandé. Pour plus d’informations, consultez Structurer un projet de robot orienté commande.

Propriété des commandes (seulement en C++)

L’ancien cadre d’application orienté commande requérait l’utilisation de pointeurs primitifs (raw pointers) pour toutes les commandes, ce qui entraînait presque inévitablement des fuites de mémoire dans tous les projets C++ qui utilisaient des commandes. De plus, ces pointeurs rendaient également possibles certaines erreurs courantes telles que la double allocation de commandes dans des groupes de commandes.

Le nouveau cadre d’application offre la gestion de la propriété pour toutes les commandes. Les commandes par défaut et les commandes liées à des boutons sont généralement la propriété du CommandScheduler, et les commandes faisant partie d’un groupe de commandes sont la propriété du groupe qui les encapsule. Par conséquent, les utilisateurs ne devraient presque jamais allouer une commande avec new à moins d’avoir une très bonne raison de le faire.

Le transfert de propriété se fait par transfert parfait ou perfect forwarding, ce qui signifie que les rvalues seront déplacées et que les lvalues seront copiées (en anglais :explication des *rvalues* et des *lvalues*).

Changements à la classe Scheduler

  • Scheduler has been renamed to CommandScheduler (Java, C++).

  • L’interruptibilité des commandes est maintenant la responsabilité du CommandScheduler, et non des commandes, ce qui peut être spécifié lors de l’appel à la méthode schedule.

  • Les utilisateurs peuvent à présent passer au CommandScheduler des actions qui seront exécutées chaque fois qu’une commande est programmée, interrompue ou complétée normalement. Cela est très utile pour, par exemple, la journalisation d’événements.

Changements à la classe Subsystem

Note

Pour plus d’informations sur les sous-systèmes, consultez Les sous-systèmes.

  • As noted earlier, Subsystem is now an interface (Java, C++); the closest equivalent of the old Subsystem is the new SubsystemBase class. Many of the Sendable-related constructor overloads have been removed to reduce clutter; users can call the setters directly from their own constructor, if needed.

  • La méthode initDefaultCommand a été supprimée; les sous-systèmes n’ont plus besoin de « connaître » leurs commandes par défaut. Celles-ci sont plutôt configurées directement avec le CommandScheduler. La nouvelle méthode setDefaultCommand encapsule simplement l’appel vers le CommandScheduler.

  • Les sous-systèmes n’ont plus besoin de « connaître » les commandes qui les requièrent à tout moment; cela est géré exclusivement par le CommandScheduler. Cependant, une méthode qui encapsule l’appel vers le CommandScheduler est fournie.

Changements à la classe Command

Note

Pour plus d’informations sur les commandes, consultez Commandes.

  • As noted earlier, Command is now an interface (Java, C++); the closest equivalent of the old Command is the new CommandBase class. Many of the Sendable-related constructor overloads have been removed to reduce clutter; users can call the setters directly from their own constructor, if needed.

  • Les commandes ne gèrent plus l’état de leur planification; il s’agit maintenant la responsabilité de la classe CommandScheduler.

  • La méthode interrupted() a été intégrée dans la méthode end(), qui reçoit désormais un paramètre spécifiant si la commande a été interrompue (false si elle s’est terminée normalement).

  • La méthode requires() s’appelle maintenant addRequirement().

  • void setRunsWhenDisabled(boolean disabled) has been replaced by an overridable runsWhenDisabled method.

  • void setInterruptible(boolean interruptible) has been replaced by an overridable getInterruptionBehavior method.

  • Several « decorator » methods have been added to allow easy inline modification of commands (e.g. adding a timeout).

  • (C++ only) In order to allow the decorators to work with the command ownership model, a CRTP is used via the CommandHelper class. Any user-defined Command subclass Foo must extend CommandHelper<Foo, Base> where Base is the desired base class.

Changements aux classes PIDSubsystem et PIDCommand

Note

Pour plus d’informations, consultez Contrôle PID via PIDSubsystems et PIDCommands, and Contrôle PID dans WPILib.

  • Suite aux changements apportés à PIDController, ces classes fonctionnent désormais de manière synchrone à partir de la boucle principale du robot (et non dans un processus séparé).

  • Le PIDController est à présent injecté dans le constructeur, ce qui a permis la suppression de plusieurs méthodes faisant le lien avec le contrôleur. Après l’appel du constructeur, celui-ci peut être modifié en utilisant la méthode getController().

  • PIDCommand est destiné en grande partie à une utilisation en inline, comme le montre l’exemple GyroDriveCommands (Java, C++).

  • Si les utilisateurs souhaitent utiliser PIDCommand de façon plus « traditionnelle », la redéfinition des méthodes protégées returnPIDInput() et usePIDOutput(double output) a été remplacée par la modification des attributs protégés m_measurement et m_useOutput. De même, plutôt que d’appeler la méthode setSetpoint(), les utilisateurs peuvent modifier l’attribut protégé m_setpoint.