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 suivants comme plugins.

  • 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

Les plug-ins nécessitent l’utilisation de la librairie Shuffleboard API Library. Ces dépendances peuvent être résolues dans le fichier build.gradle ou en utilisant Apache Maven-un outil d’automatisation de construction utilisé principalement pour les projets Java. Les dépendances seraient les suivantes:

Pour Gradle:

repositories {
   mavenCentral()
   maven{ url "https://frcmaven.wpi.edu:443/artifactory/release" }
}

dependencies {
   compileOnly("edu.wpi.first.shuffleboard", "api", "2020.+")
   compileOnly("edu.wpi.first.shuffleboard.plugin", "networktables", "2020.+")
}

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", "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

Afin de charger un plugin dans le Shuffleboard, vous devrez générer un fichier .jar du plugin et le placer dans le dossier ~/Shuffleboard/plugins. Cela peut être fait automatiquement à partir de Gradle, comme indiqué:

Le chemin vers votre dossier de plugins Shuffleboard sera probablement ~/Shuffleboard/plugins.

La tâche deployPlugin prend quatre paramètres, le paramètre type: Copy fait que la tâche implémente l’interface CopySpec spécifiant quoi copier. Les paramètres de groupe et de description spécifient l’ID de groupe du plugin et une brève description de ce que fait le plugin.

Dans le corps, le champ from spécifie d’où le fichier doit être copié, suivi du champ into spécifiant la destination vers laquelle le fichier doit être copié. Enfin, le champ include garantit que tous les fichiers avec l’extension .jar sont également copiés.

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.

En exécutant gradle deployPlugin à partir de la ligne de commande, le fichier .jar sera automatiquement placé dans le dossier du plugin Shuffleboard.

Ajout manuel d’un Plugin

L’autre façon d’ajouter un plugin au Shuffleboard est de le compiler dans un fichier jar et de l’ajouter à partir du Shuffleboard. Tout d’abord, compilez votre plugin dans un fichier .jar à l’aide de Maven ou Gradle. Ensuite, ouvrez le Shuffleboard, cliquez sur l’onglet File en haut à gauche, puis choisissez Plugins dans le menu déroulant.

Manually adding custom plugins

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