Création d’un plugin

Aperçu

Les plugins offrent la possibilité de créer des widgets personnalisés, des mises en page, des sources/types de données et des thèmes personnalisés. Shuffleboard fournit les éléments plugins intégrés suivants.

  • Plugin NetworkTables: pour se connecter aux données publiées sur NetworkTables

  • Base Plugin: Pour afficher des types de données FRC® personnalisés dans des gadgets personnalisés

  • Plugin CameraServer: pour afficher les flux du CameraServer

Astuce

Un exemple de plugin Shuffleboard personnalisé qui crée un type de données personnalisé et un widget simple pour l’afficher peut être trouvé ici.

Créer un plugin personnalisé

Afin de définir un plugin, la classe de plugin doit être une sous-classe de edu.wpi.first.shuffleboard.api.Plugin ou l’une de ses sous-classes. Un exemple de classe plugin serait le suivant.

import edu.wpi.first.shuffleboard.api.plugin.Description;
import edu.wpi.first.shuffleboard.api.plugin.Plugin;

@Description(group = "com.example", name = "MyPlugin", version = "1.2.3", summary = "An example plugin")
public class MyPlugin extends Plugin {

}

Des explications supplémentaires sur la façon dont ces attributs sont utilisés, y compris les numéros de version, peuvent être trouvées ici.

Notez que l’annotation @Description est nécessaire pour indiquer au chargeur de plug-in les propriétés de la classe de plug-in personnalisée. Les classes de plugins sont autorisées à avoir un constructeur par défaut mais il ne peut accepter aucun argument.

Construction d’un plugin

The easiest way to build plugins is to utlize the example-plugins folder in the shufflebloard source tree. Clone Shuffleboard with git clone https://github.com/wpilibsuite/shuffleboard.git, and checkout the version that corresponds to the WPILib version you have installed (e.g. 2023.2.1). git checkout v2023.2.1

Put your plugin in the example-plugins\PLUGIN-NAME directory. Copy the custom-data-and-widget.gradle from example-plugins\custom-data-and-widget and rename to match your plugin name. Edit settings.gradle in the shuffleboard root directory to add include "example-plugins:PLUGIN-NAME"

Les plugins sont autorisés à avoir des dépendances avec d’autres plugins et librairies, cependant, ils doivent être inclus correctement dans le fichier de construction Maven ou Gradle. Lorsqu’un plugin dépend d’autres plugins, il est recommandé de définir ces dépendances afin que le plugin ne se charge pas lorsque les dépendances ne se chargent pas également. Cela peut être fait en utilisant l’annotation @Requires comme indiqué ci-dessous:

@Requires(group = "com.example", name = "Good Plugin", minVersion = "1.2.3")
@Requires(group = "edu.wpi.first.shuffleboard", name = "Base", minVersion = "1.0.0")
@Description(group = "com.example", name = "MyPlugin", version = "1.2.3", summary = "An example plugin")
public class MyPlugin extends Plugin {

}

La minVersion spécifie la version minimale autorisée du plugin qui peut être chargée. Par exemple, si la minVersion est 1.4.5 et que le plugin avec la version 1.4.7 est chargé, il sera autorisé à le faire. Cependant, si le plugin avec la version 1.2.4 est chargé, il ne sera pas autorisé à le faire car il est inférieur à la minVersion.

Déploiement du plugin au Shuffleboard

In order to load a plugin in Shuffleboard, you will need to generate a jar file of the plugin and put it in the ~/Shuffleboard/plugins folder. This can be done automatically by running from the shuffleboard root gradlew :example-plugins:PLUGIN-NAME:installPlugin

Après le déploiement, le Shuffleboard mettra en cache le chemin du plugin afin qu’il puisse être automatiquement chargé lors du prochain chargement du Shuffleboard. Il peut être nécessaire de cliquer sur Clear Cache dans le menu des plugins pour supprimer un plugin ou recharger un plugin dans le Shuffleboard.

Ajout manuel d’un Plugin

The other way to add a plugin to Shuffleboard is to compile it to a jar file and add it from Shuffleboard. The jar file is located in example-plugins\PLUGIN-NAME\build\libs after running gradlew build in the shuffleboard root Open Shuffleboard, click on the file tab in the top left, and choose Plugins from the drop down menu.

Ajout manuel de plugins personnalisés

Dans la fenêtre des plugins, choisissez le bouton « Load plugin » en bas à droite et sélectionnez votre fichier .jar.