ProffieBoard V2 / ProffieOS Entwicklerhandbuch

1. Geltungsbereich und Versionierung

Das vorliegende Handbuch beschreibt einen ProffieBoard-V2-Workflow, der auf Arduino IDE, ProffieOS, einer config.h-Datei, SD-Karteninhalten, Presets und Blade Styles basiert.

Die aktuelle ProffieOS-Dokumentation folgt weiterhin demselben grundlegenden Ablauf: Arduino-Unterstützung installieren, ProffieOS beziehen, eine boardspezifische Konfiguration erstellen, diese über CONFIG_FILE auswählen, kompilieren und auf das Board übertragen und anschließend die Konfiguration weiter anpassen.

Maßgebliche Dokumentationsquellen

1. Boardspezifischer Quellcode / Konfiguration: Der ProffieOS-Quellcode und die Board-Konfiguration für das konkret verwendete Zielsystem.
2. Aktuelle offizielle Dokumentation: Die offizielle ProffieOS-Dokumentation.
3. Board-Referenz: Die Referenzdokumentation für ProffieBoard V2.
4. Repository-Historie: GitHub-Commits und Release Notes, wenn sich das Verhalten zwischen verschiedenen Versionen unterscheidet.

2. Firmware-Architektur und Modell der maßgeblichen Datenquelle

Ein SUPERNEOX Lichtschwert auf Proffie-Basis sollte als mehrschichtiges System betrachtet werden: Hardware-Verkabelung → boardspezifische Konfiguration → ProffieOS-Funktionsdefinitionen → Blade-Definitionen → Presets/Styles/Props → SD-Karten-Assets.

Ein Fehler auf einer Ebene kann sich als Problem auf einer anderen Ebene bemerkbar machen. Bei der Fehlersuche sollte daher grundsätzlich von der untersten Abhängigkeitsebene nach oben vorgegangen werden.

3. ProffieBoard V2 Hardware

Das ProffieBoard V2 ist ein Open-Source-Controller für Lichtschwerter, der für eine weitreichende Anpassung der Firmware ausgelegt ist. Es bietet Anschlüsse für die Stromversorgung, Tasten, adressierbare LEDs, Displays, Bewegungssensoren, Debugging sowie zusätzliche Peripheriegeräte.

3.1 Zentrale Hardware-Komponenten

• ProffieBoard V2/V2.2 Controller
• 3,7-V-Li-Ionen-Akku
• Lautsprecher
• Adressierbares Blade oder unterstützte LED-Hardware
• Micro-USB-Anschluss für die Entwicklung
• microSD-Karte für Sound Fonts und weitere Ressourcen

3.2 Wichtige Anschlüsse

3.3 Hinweise zur Verkabelung

Für die meisten Signalleitungen können Kabel mit geringerem Querschnitt verwendet werden. Die Leitungen für Batterie- und LED-Stromversorgung müssen jedoch entsprechend der zu erwartenden Stromstärke dimensioniert werden.

4. Entwicklungsumgebung

4.1 Benötigte Software

• Arduino IDE
• ProffieBoard Arduino Plugin
• ProffieOS-Quellcode
• USB-Treiber bzw. erforderliche Treibersoftware
• Text- bzw. Code-Editor zur Bearbeitung der Konfiguration

4.2 Auswahl des Arduino-Boards

Wählen Sie für ProffieBoard V2 das entsprechende Board-Ziel aus:

Tools → Board → Proffieboard V2

5. ProffieOS installieren

5.1 ProffieOS beziehen

Für eine stabile Firmware-Konfiguration und Kompilierung von SUPERNEOX Lichtschwertern verwenden Sie ProffieOS 5.9. Entpacken Sie die ProffieOS-Quelldateien nach dem Download in einen Ordner mit Schreibzugriff, beispielsweise in „Dokumente“ oder auf den Desktop. Speichern Sie den Quellcode nicht in geschützten Verzeichnissen wie „Programme“ oder anderen systemverwalteten Anwendungsverzeichnissen, da Windows-Berechtigungen den Dateizugriff einschränken und dadurch Kompilierungsfehler verursachen können.

Der Quellcode enthält das zentrale Arduino-Sketch:

ProffieOS/ProffieOS.ino

Zu den häufig verwendeten Verzeichnissen gehören:

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

5.2 Arduino-Sketch öffnen

Öffnen Sie:

ProffieOS/ProffieOS.ino

5.3 V2-Konfigurator verwenden

Die offizielle ProffieOS-Dokumentation empfiehlt, den für die jeweilige ProffieBoard-Version vorgesehenen Konfigurator zu verwenden. Für SUPERNEOX Lichtschwerter mit ProffieBoard V2.x verwenden Sie den folgenden Konfigurator: ProffieBoard V2.x Configurator

Passen Sie den erzeugten Code an die tatsächliche Verkabelung, die verbauten Hardware-Komponenten und die aktivierten Funktionen des jeweiligen Lichtschwerts an. Der Konfigurator bietet eine zuverlässige Ausgangsbasis. Bei erweiterten Konfigurationen oder individuellen Hardware-Aufbauten können jedoch nach der Generierung zusätzliche manuelle Anpassungen erforderlich sein.

6. Konfigurationsdatei erstellen und auswählen

6.1 Konfigurationsdatei erstellen

1. Öffnen Sie das Verzeichnis config/ von ProffieOS.
2. Kopieren Sie eine vorhandene Konfigurationsvorlage.
3. Vergeben Sie einen aussagekräftigen Dateinamen.
4. Bearbeiten Sie die Konfiguration mit einem Text- bzw. Code-Editor.
5. Speichern Sie die Datei.

6.2 Konfiguration mit CONFIG_FILE auswählen

Öffnen Sie ProffieOS.ino und aktivieren Sie genau eine Konfigurationsdatei:

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

#define CONFIG_FILE "config/my_saber_config.h"

Alle nicht verwendeten Konfigurationsdefinitionen müssen auskommentiert bleiben.

7. Konfigurationsbereiche verstehen

Eine ProffieOS-Konfigurationsdatei enthält mehrere Bereiche, die beim Kompilieren ausgewertet werden.

8. Zentrale Konfigurationsparameter

#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. Blade-Konfiguration (* Hinweis: Derzeit nicht von SUPERNEOX Lichtschwertern unterstützt.)

Die Blade-Konfiguration definiert die physische LED-Hardware, die Blade-Erkennung und das logische Verhalten des Blades.

9.1 Beispiel für ein einzelnes Blade

BladeConfig blades[] = {

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

};

Der erste Wert gibt den Blade-ID-Widerstand an, der für die Blade-Erkennung verwendet wird. Der Wert 0 wird üblicherweise verwendet, wenn keine Auswahl über eine Blade-ID erforderlich ist.

9.2 Mehrere Blade-Konfigurationen

Mehrere BladeConfig-Einträge ermöglichen die Auswahl unterschiedlicher physischer Konfigurationen anhand der Blade-Identifikation.

9.3 SubBlade

Mit SubBlade können adressierbare LEDs in mehrere logische Bereiche unterteilt werden, beispielsweise für Crossguards, Kristallkammern oder zusätzliche Accent-Pixel.

10. Preset-Konfiguration

Ein Preset kombiniert:

• Sound Font
• Musik-Track
• Blade Style
• Preset-Name

Preset presets[] = {

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

};

11. SD-Karte und Sound-Font-Verwaltung

Die microSD-Karte speichert die von ProffieOS verwendeten Laufzeitressourcen. Dazu gehören Sound Fonts, Tracks, Konfigurationsressourcen und optionale Display-Assets.

11.1 Empfohlene SD-Kartenstruktur

SD CARD

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

11.2 Sound-Font-Verzeichnis

Jeder Sound Font wird in einem eigenen Verzeichnis gespeichert. Der Name dieses Verzeichnisses wird in der Preset-Konfiguration referenziert.

Beispiel:

Preset presets[] = {

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

};

12. Tasten und Props

Die Tasten steuern die Benutzerinteraktion. Das Prop-System interpretiert Tastenkombinationen und wandelt diese in Aktionen des Lichtschwerts um.

12.1 Häufig verwendete Funktionen

Das genaue Verhalten wird durch den ausgewählten Prop und die konfigurierte Tastenbelegung bestimmt. ProffieOS enthält mehrere Saber-Props, darunter Standard- und erweiterte Implementierungen für Tasten und Funktionen. Es sollte daher nicht davon ausgegangen werden, dass alle aktuellen ProffieOS-Props dieselbe Tastenbelegung verwenden.

12.2 Prop-Konfiguration

Der ausgewählte Prop definiert:

• Tasten-Timing
• Interpretation von Gesten
• Menüverhalten
• Sonderfunktionen

#include "props/saber.h"

Individuelle Props können für spezielle Hardware oder produktspezifische Bedienelemente erstellt werden.

13. Debugging über den seriellen Monitor

Das bereitgestellte Handbuch dokumentiert die folgenden häufig verwendeten Befehle:

13.1 Serielle Ausgabe aktivieren

#define ENABLE_SERIAL

13.2 Typische Debug-Informationen

• Boot-Meldungen
• Erkennung der SD-Karte
• Initialisierung der Klinge
• Laden von Presets
• Status des Bewegungssensors
• Tastenereignisse

14. Blade Styles

Blade Styles bilden den zentralen Mechanismus von ProffieOS zur Definition des visuellen Verhaltens einer Klinge. Sie steuern unter anderem Farbe, Animationen, Zündung, Einfahren, Reaktionen auf Clash-Ereignisse, Blaster-Effekte, Lockup, Drag, Übergänge und weitere interaktive Effekte.

14.1 Einfaches Style-Beispiel

StyleNormalPtr<RED>()

Einfache Styles definieren das Standard-Erscheinungsbild einer Klinge. Für komplexere Konfigurationen werden verschachtelte Style-Funktionen und Effekt-Layer kombiniert, um umfangreiche Animationen und dynamische Effekte zu erzeugen.

14.2 Struktur von StylePtr

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

Mit StylePtr wird üblicherweise ein vollständiger Blade Style zugewiesen. Komplexe Effekte entstehen durch die Kombination mehrerer Funktionen, Layer und Übergänge.

14.3 RGB-Farben

Rgb<255, 50, 0>

Die Werte der einzelnen RGB-Kanäle liegen zwischen 0 und 255. Sofern unterstützt, können auch benannte Farben wie RED, GREEN, BLUE, WHITE und CYAN verwendet werden.

14.4 Häufig verwendete Effektfunktionen

14.5 Erweiterte Style-Komposition

Fortgeschrittene Anwender können Funktionen, Layer, Übergänge und Zufallseffekte miteinander kombinieren, um das Verhalten der Klinge vollständig individuell anzupassen.

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

14.6 Mehrere Klingen / Accent Pixels

Ein Preset kann mehrere Blade Styles enthalten, die unterschiedlichen logischen Klingendefinitionen zugeordnet sind. Dadurch lassen sich Hauptklinge, Quillons, Kristallkammern, Accent-Strips oder andere konfigurierte Pixelgruppen unabhängig voneinander steuern.

14.7 Ressourcen zur Bearbeitung von Blade Styles

• ProffieOS Homepage – Hinweis: Für SUPERNEOX-Sabers bitte ProffieOS 5.9 verwenden.
• SD-Konfigurationsdatei
• ProffieOS-Dokumentation
• The Crucible Support Forum
• Fett263 Style Resources
• Blade Configuration Documentation

15. Erweiterte Integration

15.1 Displays

Unterstützte Display-Module können beispielsweise folgende Informationen und Funktionen bereitstellen:

• Batterieinformationen
• Preset-Auswahl
• Menünavigation
• Betriebsstatus

15.2 Zusätzliche Peripheriegeräte

Bei fortgeschrittenen Hardware-Konfigurationen können unter anderem folgende Komponenten integriert werden:

• Accent-LEDs
• Kristallkammern
• Crossguard-Beleuchtung
• Benutzerdefinierte Sensoren
• Externe Controller

15.3 Empfehlung für den Produktionsablauf

16. Fehlerbehebung

17. Entwickler-Referenzen

• Offizieller Installationsleitfaden
• ProffieOS GitHub Repository
• Quellcode der V2-Board-Konfiguration
• Offizielle ProffieOS-Seite
• ProffieOS.ino / CONFIG_FILE-Einstiegspunkt