Ajout de composants personnalisés

RobotBuilder fonctionne très bien pour la création de programmes de robots qui utilisent uniquement la WPILib pour les moteurs, les contrôleurs et les capteurs. Mais pour les équipes qui utilisent des classes personnalisées, RobotBuilder n’a pas de support pour ces classes, donc quelques étapes doivent être prises pour les utiliser dans RobotBuilder

Structure d’un composants personnalisé

../../../../../_images/custom-components-1.png

Les composants personnalisés vont tous dans ~/wpilib/YYYY/Robotbuilder/extensions où ~ est C:\Users\Public sous Windows et YYYY correspond à l’année de la saison FRC®.

Il y a sept fichiers et un dossier qui sont nécessaires pour un composant personnalisé. Le dossier contient les fichiers décrivant le composant et comment l’exporter. Il doit avoir le même nom que le composant (p. ex. »Kiwi Drive » pour une base pilotable de type kiwi, « Robot Drive 6 » pour une base pilotable à six moteurs, etc.). Les fichiers doivent avoir les mêmes noms et extensions que ceux indiqués ici. D’autres fichiers peuvent être dans le dossier en plus de ces sept, mais les sept doivent être présents pour que RobotBuilder reconnaisse le composant personnalisé.

PaletteDescription.yaml

../../../../../_images/custom-components-2.png

Ligne par ligne :

  • !Component : déclare le début d’un nouveau composant

  • name: Nom du composant. C’est ce qui s’affichera dans la palette/arbre - cela devrait également être le même que le nom du dossier contenant

  • type: le type du composant (ceux-ci seront expliqués en profondeur plus tard)

  • supports: une carte de la quantité de chaque type de composant qui peut prendre en charge. Les contrôleurs de moteurs de RobotBuilder sont tous des PIDOutputs, de sorte qu’une base kiwi peut prendre en charge trois PIDOutputs. Si un composant ne prend rien en charge (comme les capteurs ou les contrôleurs de moteurs), juste ignorer cette ligne

  • help: une chaîne de caractères concise qui affiche un message utile lorsqu’on passe le curseur sur l’un de ces composants

  • properties: liste des propriétés de ce composant. Dans cet exemple de base kiwi, il y a trois propriétés très similaires, une pour chaque moteur. Un ChildSelectionProperty permet à l’utilisateur de choisir un composant du type donné à partir des sous-composants de celui qui est en cours de modification (donc ici, s’afficherait une liste déroulante demandant un PIDOutput - c’est-à-dire un contrôleur de moteur - qui a été ajouté à la base kiwi)

Les types de composants que RobotBuilder prend en charge (ceux-ci sont sensibles à la casse):

  • Command

  • Subsystem

  • PIDOutput (contrôleur de moteur)

  • PIDSource (capteur qui implémente PIDSource, par exemple un potentiomètre analogique, un encodeur)

  • Sensor (capteur qui n’implémente pas PIDSource, par exemple un interrupteur de fin de course)

  • Controller (déplacement du robot, contrôleur PID, etc.)

  • Actuator (une sortie qui n’est pas un moteur, par exemple un solenoïde, un servo)

  • Joystick

  • Joystick Button

Propriétés

Propriétés pertinentes pour un composant personnalisé :

  • StringProperty: utilisé lorsqu’un composant a besoin d’une chaîne de caractères, par exemple le nom du composant

  • BooleanProperty: utilisé lorsqu’un composant a besoin d’une valeur booléenne, par exemple en mettant un bouton sur le SmartDashboard

  • DoubleProperty: utilisé lorsqu’un composant a besoin d’une valeur numérique, par exemple PID constantsChoicesProperty

  • ChildSelectionProperty: ce paramètre est utilisé lorsque vous devez choisir un composant enfant, par exemple des contrôleurs de moteurs dans un RobotDrive

  • TypeSelectionProperty: utilisé lorsque vous devez choisir n’importe quel composant du type donné de n’importe où dans le programme, par exemple l’entrée et la sortie pour une commande PID

Les champs de chaque propriété sont décrits ci-dessous :

../../../../../_images/custom-components-3.png

Validators.yaml

../../../../../_images/custom-components-4.png

Vous avez peut-être remarqué « KiwiDriveValidator » dans l’entrée validateurs de chacune des propriétés des moteurs dans PaletteDescription.yaml. Ce n’est pas un validateur intégré, il a donc dû être défini dans Validators.yaml. Cet exemple de validateur est très simple - il s’assure simplement que chacun des champs nommés a une valeur différente des autres.

Validateurs intégrés et types de validateurs

../../../../../_images/custom-components-5.png

Les validateurs intégrés sont très utiles (en particulier les UniqueValidators pour l’utilisation port/canal), mais parfois un validateur personnalisé est nécessaire, comme dans l’étape précédente

  • DistinctValidator: Garantit que les valeurs de chacun des champs donnés sont uniques

  • ExistsValidator: Garantit qu’une valeur a été définie pour la propriété à l’aide de ce validateur

  • UniqueValidator: S’assure que la valeur de la propriété est unique globalement pour les champs donnés

  • ListValidator: S’assure que toutes les valeurs d’une liste propriété sont valides

C++ Export.yaml

../../../../../_images/custom-components-6.png

Analyse du fichier ligne par ligne

  • Kiwi Drive: Le nom du composant exporté. Il s’agit du même nom que le nom défini dans PaletteDescription.yaml, et le nom du dossier contenant ce fichier

  • Defaults: fournit certaines valeurs par défaut pour les fichiers d’inclusion nécessaires à ce composant, le nom de la classe, un modèle de construction, et plus encore. Le CustomComponent par défaut ajoute une inclusion pour Custom/${ClassName}.h à chaque fichier généré qui utilise le composant (par exemple RobotDrive.h aurait #include Custom/KiwiDrive.h en haut du fichier)

  • ClassName: nom de la classe personnalisée que vous ajoutez.

  • Construction: une instruction sur la façon dont le composant doit être construit. Les variables seront remplacées par leurs valeurs (« ${ClassName} » sera remplacé par « KiwiDrive »), puis les macros seront évaluées (par exemple, #variable($Name) pourrait être remplacée par drivebaseKiwiDrive).

Cet exemple s’attend à une classe KiwiDrive avec le constructeur

KiwiDrive(SpeedController, SpeedController, SpeedController)

Si votre équipe utilise Java, ce fichier peut être laissé vide.

Java Export.yaml

../../../../../_images/custom-components-7.png

Très similaire au fichier d’exportation C++; la seule différence devrait être la ligne de construction. Cet exemple s’attend à une classe KiwiDrive avec le constructeur

KiwiDrive(SpeedController, SpeedController, SpeedController)

Si votre équipe utilise C++, ce fichier peut être laissé vide.

Utilisation de macros et de variables

Les macros sont des fonctions simples que RobotBuilder utilise pour transformer des variables en texte qui seront insérées dans le code généré. Ils commencent toujours par le Symbole « # », et ont une syntaxe similaire aux fonctions : <macro_name>( arg0, arg1, arg2, ...). La seule macro que vous aurez probablement besoin d’utiliser est #variable( component_name )

#variable accepte une chaîne de caractères, généralement la variable définie quelque part (c.-à-d. « Name » est le nom donné au composant dans RobotBuilder, tel que « Arm Motor »), et le transforme en nom d’une variable définie dans le code généré. Par exemple,``#variable(« Arm Motor »)`` se traduit par la chaîne de caractères ArmMotor

Les variables sont référencées en plaçant un signe dollar (« $ ») devant le nom de la variable, qui peut optionnellement être placé à l’intérieur des accolades pour distinguer facilement la variable d’un autre texte dans le fichier. Lorsque le fichier est analysé, le signe dollar, le nom de la variable et les accolades sont remplacés par la valeur de la variable (p. ex. ${ClassName} est remplacé par KiwiDrive).

Les variables sont soit des propriétés de composants (p. ex. « Motor 1 », « Motor 2 », « Motor 3 » dans l’exemple de l’entraînement kiwi), soit l’un des suivants :

  1. Short_Name: le nom donné au composant dans le panneau d’édition de RobotBuilder

  2. Name: le nom complet du composant. Si le composant se trouve dans un sous-système, il s’agit d’un version écourtée du nom ajoutée au nom du sous-système

  3. Export: Le nom du fichier dans lequel ce composant doit être créé, le cas échéant. Cela doit être « RobotMap » pour les composants comme les actionneurs, les contrôleurs et les capteurs; ou « OI » pour des composants comme les gamepads ou d’autres composants OI personnalisés. Notez que le défaut « CustomComponent » s’exportera vers le RobotMap.

  4. Import: Les fichiers qui doivent être inclus ou importés pour que ce composant puisse être utilisé.

  5. Declaration: une instruction, similaire à Construction, pour savoir comment déclarer une variable de ce type de composant. Ceci est pris en charge par la valeur par défaut « None »

  6. Construction: une instruction montrant comment créer une nouvelle instance de ce composant

  7. LiveWindow: une instruction montrant comment ajouter ce composant au LiveWindow

  8. Extra: les instructions relatives à toutes les fonctions ou méthodes exigent que ce composant se fonctionne correctement, tels que les encodeurs qui doivent définir le type d’encodage.

  9. Prototype (C++ uniquement) : Le prototype pour la création d’une fonction dans le fichier dans lequel le composant est déclaré, généralement un getter de la classe OI

  10. Function : Une fonction à créer dans le fichier dans lequel le composant est déclaré, généralement un getter dans la classe OI

  11. PID : Une instruction montrant la façon d’obtenir la sortie PID du composant, si elle en a une (p. ex. #variable($Short_Name)->PIDGet())

  12. ClassName: Le nom de la classe que représente le composant (p. ex. “”KiwiDrive”” ou “”Joystick””)

Si vous avez des variables avec des espaces dans le nom (tels que »Motor 1 », « Right Front Motor », etc.), les espaces doivent être remplacés par des soulignements lors de leur utilisation dans les fichiers d’exportation.

help.html

../../../../../_images/custom-components-8.png

Un fichier HTML donnant des informations sur le composant. Il est préférable qu’il soit aussi détaillé que possible, mais il n’est certainement pas nécessaire si le programmeur (s) est ou sont assez familier.s avec le composant, ou si c’est si simple qu’il inutile d’avoir une description détaillée.

config.txt

../../../../../_images/custom-components-9.png

Un fichier de configuration pour contenir diverses informations sur le composant. Actuellement, il y a que la section de la palette pour contenir le composant

Les sections de la palette (celles-ci sont sensibles à la casse) :

  • Subsystems

  • Controllers

  • Sensors

  • Actuators

  • Pneumatics

  • OI

  • Commands

icon.png

L’Icône qui apparaît dans la palette et la page d’aide. Il devrait être un fichier 64x64 .png.

It should use the color scheme and general style of the section it’s in to avoid visual clutter, but this is entirely optional. Photoshop .psd files of the icons and backgrounds are in src/main/icons/icons and png files of the icons and backgrounds are in src/main/resources/icons.