Guide développeur ProffieBoard V2 / ProffieOS

1. Périmètre et gestion des versions

Le présent guide décrit un workflow ProffieBoard V2 basé sur Arduino IDE, ProffieOS, un fichier config.h, le contenu de la carte SD, les presets et les Blade Styles.

La documentation actuelle de ProffieOS conserve le même principe de fonctionnement : installer le support Arduino, récupérer ProffieOS, créer une configuration adaptée à la carte, la sélectionner via CONFIG_FILE, compiler et téléverser le firmware, puis itérer sur la configuration.

Références faisant autorité

1. Code source / configuration spécifique à la carte : le code source de ProffieOS et la configuration correspondant exactement au matériel cible.
2. Documentation officielle à jour : documentation ProffieOS.
3. Référence matérielle : documentation de référence du ProffieBoard V2.
4. Historique du dépôt : commits GitHub et notes de version lorsque le comportement diffère selon les versions.

2. Architecture du firmware et modèle de référence

Un sabre SUPERNEOX basé sur Proffie doit être considéré comme un système à plusieurs couches : câblage matériel → configuration spécifique à la carte → définitions des fonctionnalités ProffieOS → définitions des lames → presets/styles/props → ressources de la carte SD.

Une défaillance au niveau d'une couche peut se manifester comme un problème situé sur une autre couche. Le diagnostic doit donc commencer par le niveau de dépendance le plus bas et remonter progressivement vers les couches supérieures.

3. Matériel ProffieBoard V2

Le ProffieBoard V2 est un contrôleur open source pour sabres laser, conçu pour permettre une personnalisation avancée du firmware. Il dispose de connexions pour l'alimentation, les boutons, les LED adressables, les écrans, les capteurs de mouvement, le débogage et différents périphériques supplémentaires.

3.1 Matériel principal

• Contrôleur ProffieBoard V2/V2.2
• Batterie Li-ion 3,7 V
• Haut-parleur
• Lame adressable ou matériel LED compatible
• Connexion Micro-USB pour le développement
• Carte microSD pour les sound fonts et autres ressources

3.2 Broches importantes

3.3 Considérations relatives au câblage

La plupart des connexions de signal peuvent utiliser des fils de section réduite. En revanche, les lignes d'alimentation de la batterie et des LED doivent être dimensionnées en fonction du courant maximal attendu.

4. Environnement de développement

4.1 Logiciels requis

• Arduino IDE
• Plugin Arduino pour ProffieBoard
• Package source ProffieOS
• Pilotes USB lorsque cela est nécessaire
• Éditeur de texte brut ou éditeur de code pour modifier la configuration

4.2 Sélection de la carte dans Arduino IDE

Pour un ProffieBoard V2, sélectionnez la cible correspondant à la carte :

Outils → Type de carte → Proffieboard V2

5. Installation de ProffieOS

5.1 Télécharger ProffieOS

Pour garantir une configuration et une compilation stables du firmware des sabres SUPERNEOX, utilisez ProffieOS 5.9. Après téléchargement, extrayez les fichiers source de ProffieOS dans un dossier utilisateur accessible en écriture, par exemple Documents ou Bureau. Évitez de placer le code source dans des emplacements protégés tels que Program Files ou d'autres répertoires gérés par le système : les restrictions de permissions de Windows peuvent empêcher l'accès aux fichiers et provoquer des erreurs de compilation.

L'arborescence source contient notamment le sketch Arduino principal :

ProffieOS/ProffieOS.ino

Les répertoires courants comprennent notamment :

config/
blades/
styles/
props/
sound/
motion/
functions/

5.2 Ouvrir le sketch Arduino

Ouvrez :

ProffieOS/ProffieOS.ino

5.3 Utiliser le configurateur V2

La documentation officielle de ProffieOS recommande d'utiliser le configurateur correspondant à la version exacte de votre ProffieBoard. Pour les sabres SUPERNEOX équipés d'un ProffieBoard V2.x, utilisez le configurateur suivant : Configurateur ProffieBoard V2.x

Configurez ensuite le code généré en fonction du câblage réel du sabre, des composants matériels installés et des fonctionnalités utilisées. Le configurateur constitue un point de départ fiable, mais les configurations avancées ou personnalisées peuvent nécessiter des modifications manuelles supplémentaires après génération.

6. Créer et sélectionner un fichier de configuration

6.1 Créer le fichier de configuration

1. Ouvrez le répertoire config/ de ProffieOS.
2. Copiez un modèle de configuration existant.
3. Renommez-le avec un nom explicite.
4. Modifiez la configuration avec un éditeur de texte brut.
5. Enregistrez le fichier.

6.2 Sélectionner la configuration avec CONFIG_FILE

Ouvrez ProffieOS.ino et activez exactement un fichier de configuration :

// #define CONFIG_FILE "config/example.h"

#define CONFIG_FILE "config/my_saber_config.h"

Toutes les autres définitions de configuration inutilisées doivent rester commentées.

7. Comprendre les sections de configuration

Un fichier de configuration ProffieOS contient plusieurs sections évaluées lors de la compilation.

8. Principaux paramètres de configuration

#ifdef CONFIG_TOP

#include "proffieboard_v2_config.h"

#define NUM_BLADES 1
#define NUM_BUTTONS 2
#define VOLUME 1000

const unsigned int maxLedsPerStrip = 144;

#define CLASH_THRESHOLD_G 1.0

#define ENABLE_AUDIO
#define ENABLE_MOTION
#define ENABLE_WS2811
#define ENABLE_SD
#define SAVE_STATE

#endif

9. Configuration de la lame (* Remarque : cette fonction n'est actuellement pas prise en charge sur les sabres SUPERNEOX.)

La configuration de la lame définit le matériel LED physique, la détection de la lame et son comportement logique.

9.1 Exemple avec une seule lame

BladeConfig blades[] = {

 {
  0,
  WS2811BladePtr<144>(),
  CONFIGARRAY(presets)
 }

};

La première valeur correspond à la résistance d'identification de la lame utilisée pour sa détection. Une valeur de 0 est généralement utilisée lorsqu'aucune sélection par identification de lame n'est nécessaire.

9.2 Configurations avec plusieurs lames

Plusieurs entrées BladeConfig permettent de sélectionner différentes configurations physiques grâce à l'identification de la lame.

9.3 SubBlade

SubBlade permet de diviser les LED adressables en plusieurs zones logiques, par exemple pour les quillons, les chambres de cristal ou les pixels auxiliaires.

10. Configuration des presets

Un preset regroupe :

• Sound font
• Piste audio
• Blade Style
• Nom du preset

Preset presets[] = {

 {
  "TeensySF",
  "tracks/theme.wav",
  StyleNormalPtr<CYAN>(),
  "cyan"
 }

};

11. Gestion de la carte SD et des Sound Fonts

La carte microSD stocke les ressources utilisées par ProffieOS pendant l'exécution, notamment les sound fonts, les pistes audio, les ressources de configuration et, selon la configuration, les ressources d'affichage.

11.1 Structure recommandée de la carte SD

SD CARD

├── SOUND/
│
├── TRACKS/
│
├── CONFIG/
│
├── FONT DIRECTORY 1/
│   ├── hum.wav
│   ├── swingl.wav
│   ├── swingh.wav
│   ├── clash.wav
│   └── blst.wav
│
└── FONT DIRECTORY 2/

11.2 Répertoire d'une Sound Font

Chaque sound font est stockée dans son propre répertoire. Le nom du répertoire est référencé dans la configuration du preset.

Exemple :

Preset presets[] = {

 {
  "DarkLord",
  "tracks/theme.wav",
  StyleNormalPtr<RED>(),
  "Dark Lord"
 }

};

12. Boutons et Props

Les boutons définissent les interactions avec l'utilisateur. Le système de props interprète les combinaisons de boutons et les convertit en actions du sabre.

12.1 Actions courantes

Le comportement exact dépend du prop sélectionné et de la configuration des boutons. ProffieOS propose plusieurs props pour sabres laser, notamment des implémentations standard et avancées de la gestion des boutons et des fonctionnalités. Ne partez pas du principe que tous les props actuels utilisent la même affectation des boutons.

12.2 Configuration du Prop

Le prop sélectionné définit notamment :

• Le temps de détection des appuis sur les boutons
• L'interprétation des gestes
• Le comportement des menus
• Les fonctions spéciales

#include "props/saber.h"

Des props personnalisés peuvent être créés pour du matériel spécifique ou des commandes propres à un produit.

13. Débogage avec le Moniteur série

Le manuel fourni documente les commandes couramment utilisées suivantes :

13.1 Activer la sortie série

#define ENABLE_SERIAL

13.2 Informations de diagnostic courantes

• Messages de démarrage
• Détection de la carte SD
• Initialisation de la lame
• Chargement des presets
• État du capteur de mouvement
• Événements liés aux boutons

14. Blade Styles

Les Blade Styles constituent le mécanisme principal utilisé par ProffieOS pour définir le comportement visuel de la lame. Ils permettent notamment de contrôler : la couleur, les animations, l'allumage, l'extinction, la réaction aux impacts, les effets de tirs de blaster, le lockup, le drag, les transitions et d'autres effets interactifs.

14.1 Exemple de style simple

StyleNormalPtr<RED>()

Les styles simples définissent l'apparence par défaut de la lame. Les configurations plus avancées utilisent des fonctions de style imbriquées et différentes couches d'effets afin de créer des animations complexes.

14.2 Structure StylePtr

StylePtr<
  InOutHelper<GREEN, 300, 800, BLACK>()
>()

StylePtr est couramment utilisé pour attribuer un Blade Style complet. Les effets complexes sont créés en combinant plusieurs fonctions, couches et transitions.

14.3 Couleurs RGB

Rgb<255, 50, 0>

Les valeurs des canaux RGB sont comprises entre 0 et 255. Des couleurs nommées telles que RED, GREEN, BLUE, WHITE et CYAN peuvent également être utilisées lorsqu'elles sont prises en charge.

14.4 Fonctions d'effets courantes

14.5 Composition avancée des styles

Les utilisateurs avancés peuvent combiner fonctions, couches, transitions et effets aléatoires afin de créer des comportements de lame entièrement personnalisés.

Layers<
 RED,
 AudioFlicker<RED,WHITE>,
 Clash
>()

14.6 Lames multiples / Pixels auxiliaires

Un preset peut contenir plusieurs Blade Styles correspondant à plusieurs définitions logiques de lame. Cela permet de définir indépendamment le style de la lame principale, des quillons, des chambres de cristal, des bandes de pixels auxiliaires ou d'autres groupes de pixels configurés.

14.7 Ressources pour modifier les styles

• ProffieOS Homepage - Remarque : utilisez ProffieOS 5.9 pour les sabres SUPERNEOX.
• Fichier de configuration SD
• Documentation ProffieOS
• Forum d'assistance The Crucible
• Ressources de styles Fett263
• Documentation de configuration des lames

15. Intégration avancée

15.1 Écrans

Les modules d'affichage compatibles peuvent fournir notamment :

• Informations sur la batterie
• Sélection des presets
• Navigation dans les menus
• État du système en temps réel

15.2 Périphériques supplémentaires

Les configurations avancées peuvent intégrer :

• LED auxiliaires
• Chambres de cristal
• Éclairage des quillons
• Capteurs personnalisés
• Contrôleurs externes

15.3 Workflow recommandé pour la production

16. Dépannage

17. Références pour les développeurs

• Guide officiel d'installation
• Dépôt GitHub ProffieOS
• Code source de configuration de la carte V2
• Page officielle ProffieOS
• ProffieOS.ino / point d'entrée CONFIG_FILE