Agregar componentes personalizados

RobotBuilder funciona muy bien para crear programas de robots que solo usan WPILib para motores, controladores y sensores. Pero para los equipos que usan clases personalizadas, RobotBuilder no tiene ningún soporte para esas clases, por lo que se deben seguir algunos pasos para usarlas en RobotBuilder.

Estructura de componentes personalizada

Todos los componentes personalizados van en ~/wpilib/YYYY/Robotbuilder/extensions donde ~ es C:\Users\Public en Windows y YYYY es el año de FRC®.

Hay siete archivos y una carpeta que se necesitan para un componente personalizado. La carpeta contiene los archivos que describen el componente y cómo exportarlo. Debe tener el mismo nombre que el componente (por ejemplo, «Kiwi Drive» para un controlador de unidad de kiwi, «Robot Drive 6» para un controlador de unidad de seis motores, etc.). Los archivos deben tener los mismos nombres y extensiones que los que se muestran aquí. Otros archivos pueden estar en la carpeta junto con estos siete, pero los siete deben estar presentes para que RobotBuilder reconozca el componente personalizado.

PaletteDescription.yaml

Linea por linea:

• !Component: declara el comienzo de un nuevo componente

• name: El nombre del componente. Esto es lo que se mostrará en la paleta/árbol; también debe ser el mismo que el nombre de la carpeta que lo contiene.

• type: el tipo de componente (se explicarán en profundidad más adelante)

• supports: un mapa de la cantidad de cada tipo de componente que puede soportar. Los controladores de motor en RobotBuilder son todos PIDOutputs, por lo que una unidad de kiwi puede admitir tres PIDOutputs. Si un componente no admite nada (como sensores o controladores de motor), simplemente deje esta línea fuera

• help: una cadena corta que da un mensaje útil cuando se coloca el cursor sobre uno de estos componentes

• properties: una lista de las propiedades de este componente. En este ejemplo de unidad de kiwi, hay tres propiedades muy similares, una para cada motor. Una ChildSelectionProperty permite al usuario elegir un componente del tipo dado de los subcomponentes del que se está editando (por lo que aquí, mostrarían un menú desplegable solicitando una PIDOutput, es decir, un controlador de motor, que se ha agregado a la unidad de kiwi)

Los tipos de componentes que admite RobotBuilder (distinguen entre mayúsculas y minúsculas):

• Comando

• Subsistema

• PIDOutput (controlador de motor)

• PIDSource (sensor que implementa PIDSource, por ejemplo, potenciómetro analógico, encoder)

• Sensor (sensor que no implementa PIDSource, por ejemplo, interruptor de límite)

• Controlador (unidad de robot, controlador PID, etc.)

• Actuador (una salida que no es un motor, por ejemplo, solenoide, servo)

• Joystick

• Botón de joystick

Propiedades

Las propiedades relevantes para un componente personalizado:

• StringProperty: se utiliza cuando un componente necesita una cadena, p. Ej. el nombre del componente

• BooleanProperty: se usa cuando un componente necesita un valor booleano, p. Ej. poner un botón en el SmartDashboard

• DoubleProperty: se utiliza cuando un componente necesita un valor numérico, p. Ej. Constantes PIDChoicesProperty

• ChildSelectionProperty: se usa cuando necesita elegir un componente secundario, p. ej. controladores de motor en un RobotDrive

• TypeSelectionProperty: se usa cuando necesita elegir cualquier componente del tipo dado desde cualquier lugar del programa, p. entrada y salida para un comando PID

Los campos de cada propiedad se describen a continuación:

Validators.yaml

Es posible que haya notado «KiwiDriveValidator» en la entrada de los validadores de cada una de las propiedades del motor en PaletteDescription.yaml. No es un validador integrado, por lo que tuvo que definirse en Validators.yaml. Este validador de ejemplo es muy simple: solo se asegura de que cada uno de los campos nombrados tenga un valor diferente al de los demás.

Validadores integrados y tipos de validador

Los validadores integrados son muy útiles (especialmente los UniqueValidators para uso de puertos / canales), pero a veces se necesita un validador personalizado, como en el paso anterior

• DistinctValidator: se asegura de que los valores de cada uno de los campos dados sean únicos

• ExistsValidator: se asegura de que se haya establecido un valor para la propiedad usando este validador

• UniqueValidator: se asegura de que el valor de la propiedad sea único globalmente para los campos dados

• ListValidator: se asegura de que todos los valores de una propiedad de lista sean válidos

C++ Export.yaml

Un desglose línea por línea del archivo:

• Kiwi Drive: el nombre del componente que se exporta. Este es el mismo que el nombre establecido en PaletteDescription.yaml y el nombre de la carpeta que contiene este archivo

• Valores predeterminados: proporciona algunos valores predeterminados para las inclusiones que necesita este componente, el nombre de la clase, una plantilla de construcción y más. El CustomComponent predeterminado agrega una inclusión para``Custom/${ClassName}.h`` a cada archivo generado que usa el componente (por ejemplo, RobotDrive.h tendría #include "Custom/KiwiDrive.h la parte superior del archivo)

• ClassName: el nombre de la clase personalizada que está agregando.

• Construcción: una instrucción sobre cómo se debe construir el componente. Las variables se reemplazarán con sus valores («${ClassName}» se reemplazará con «KiwiDrive»), luego se evaluarán las macros (por ejemplo, #variable($Name) se puede reemplazar con drivebaseKiwiDrive).

Este ejemplo espera una clase KiwiDrive con el constructor

KiwiDrive(SpeedController, SpeedController, SpeedController)

Si su equipo usa Java, este archivo puede estar vacío.

Java Export.yaml

Muy similar al archivo de exportación de C++; la única diferencia debería ser la línea de Construcción. Este ejemplo espera una clase KiwiDrive con el constructor

KiwiDrive(SpeedController, SpeedController, SpeedController)

Si su equipo usa C++, este archivo puede estar vacío.

Usar macros y variables

Las macros son funciones simples que utiliza RobotBuilder para convertir variables en texto que se insertará en el código generado. Siempre comienzan con el símbolo «#» y tienen una sintaxis similar a las funciones: <macro_name>( arg0, arg1, arg2, ...). La única macro que probablemente necesitará usar es #variable( component_name )

#variable toma una cadena, generalmente una variable definida en algún lugar (es decir, «Name» es el nombre que se le da al componente en RobotBuilder, como «Arm Motor»), y lo convierte en el nombre de una variable definida en el código generado. Por ejemplo, #variable("Arm Motor") da como resultado la cadena ArmMotor

Se hace referencia a las variables colocando un signo de dólar («$») delante del nombre de la variable, que opcionalmente se coloca entre llaves para distinguir fácilmente la variable de otro texto en el archivo. Cuando se analiza el archivo, el signo de dólar, el nombre de la variable y las llaves se reemplazan por el valor de la variable (por ejemplo, ${ClassName} is replaced with KiwiDrive).

Las variables son propiedades de los componentes (por ejemplo, «Motor 1», «Motor 2», «Motor 3» en el ejemplo de la unidad de kiwi) o una de las siguientes:

1. Short_Name: el nombre que se le da al componente en el panel del editor en RobotBuilder

2. Name: el nombre completo del componente. Si el componente está en un subsistema, este será el nombre corto adjunto al nombre del subsistema

3. Export: el nombre del archivo en el que se debe crear este componente, si lo hubiera. Debe ser «RobotMap» para componentes como actuadores, controladores y sensores; o «OI» para cosas como gamepads u otros componentes personalizados de OI. Tenga en cuenta que el valor predeterminado «CustomComponent» se exportará a RobotMap.

4. Import: archivos que deben incluirse o importarse para que este componente pueda utilizarse.

5. Declaration: instrucción, similar a Construction, sobre cómo declarar una variable de este tipo de componente. Esto se soluciona con el valor predeterminado «None»

6. Construction: una instrucción sobre cómo crear una nueva instancia de este componente

7. LiveWindow: una instrucción sobre cómo agregar este componente a LiveWindow

8. Extra: instrucciones para cualquier función adicional o llamadas a métodos para que este componente se comporte correctamente, como los codificadores que necesitan establecer el tipo de codificación.

9. Prototype (solo C++): el prototipo de una función que se creará en el archivo en el que se declara el componente, generalmente un captador en la clase OI

10. Function: una función que se creará en el archivo en el que se declara el componente, normalmente un captador en la clase OI

11. PID: Una instrucción sobre cómo obtener la salida PID del componente, si tiene una (por ejemplo, #variable($Short_Name)->PIDGet())

12. ClassName: el nombre de la clase que representa el componente (por ejemplo, KiwiDrive o Joystick)

Si tiene variables con espacios en el nombre (como «Motor 1», «Right Front Motor», etc.), los espacios deben reemplazarse por guiones bajos cuando los use en los archivos de exportación.

help.html

Un archivo HTML que proporciona información sobre el componente. Es mejor que esto sea lo más detallado posible, aunque ciertamente no es necesario si los programadore(s) están lo suficientemente familiarizados con el componente, o si es tan simple que no tiene mucho sentido una descripción detallada.

config.txt

Un archivo de configuración para contener información diversa sobre el componente. Actualmente, esto solo tiene la sección de la paleta para colocar el componente.

Las secciones de la paleta (distinguen entre mayúsculas y minúsculas):

• Subsistemas

• Controladores

• Sensores

• Actuadores

• Neumática

• OI

• Comandos

icon.png

El icono que aparece en la paleta y la página de ayuda. Debe ser un archivo``.png`` de 64x64.

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.