ProffieBoard V2.2 Developer Guide

1. Scope and Versioning

The supplied manual documents a ProffieBoard V2 workflow centered on Arduino IDE, ProffieOS, a config.h file, SD-card content, presets, and Blade Styles.

Current ProffieOS documentation retains the same fundamental workflow: install the Arduino support, obtain ProffieOS, create a board-specific configuration, select it through CONFIG_FILE, compile and upload, then iterate on the configuration.

Documentation authority

1. Board-specific source/config: The ProffieOS source tree and board configuration for the exact target.
2. Current official documentation: ProffieOS Documentation.
3. Board reference: ProffieBoard V2 reference documentation.
4. Repository history: GitHub commit and release notes when behavior differs between versions.

2. Firmware Architecture and Source-of-Truth Model

A SUPERNEOX Proffie-based saber should be treated as a layered system: hardware wiring → board-specific configuration → ProffieOS feature definitions → blade definitions → presets/styles/props → SD-card assets.

A failure at one layer can present as a failure at another, so diagnosis should begin from the lowest dependency layer upward.

3. ProffieBoard V2 Hardware

The ProffieBoard V2 is an open-source lightsaber controller designed for advanced firmware customization. It provides connections for power, buttons, addressable LEDs, displays, motion sensors, debugging, and additional peripherals.

3.1 Core Hardware

• ProffieBoard V2/V2.2 controller
• 3.7V Li-ion battery
• Speaker
• Addressable blade or supported LED hardware
• Micro-USB connection for development
• microSD card for sound fonts and resources

3.2 Important Pins

3.3 Wiring Considerations

Most signal connections can use smaller gauge wire, but battery and LED power paths must be sized according to expected current requirements.

4. Development Environment

4.1 Required Software

• Arduino IDE
• ProffieBoard Arduino plugin
• ProffieOS source package
• USB driver tools where required
• Plain-text/code editor for configuration editing

4.2 Arduino Board Selection

For ProffieBoard V2, select the corresponding board target:

Tools → Board → Proffieboard V2

5. Installing ProffieOS

5.1 Obtain ProffieOS

To ensure stable firmware configuration and compilation for SUPERNEOX lightsabers, use ProffieOS 5.9. After downloading, extract the ProffieOS source files to a writable user folder, such as Documents or Desktop. Do not store the source code inside protected locations such as Program Files or other system-managed application directories, as Windows permissions may restrict file access and cause compilation issues.

The source tree contains the main Arduino sketch:

ProffieOS/ProffieOS.ino

Common directories include:

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

5.2 Open Arduino Sketch

Open:

ProffieOS/ProffieOS.ino

5.3 Use the V2 Configurator

The official ProffieOS documentation recommends using the configurator designed for your specific ProffieBoard version. For SUPERNEOX lightsabers equipped with ProffieBoard V2.x, use the following configurator: ProffieBoard V2.x Configurator

Configure the generated code according to the saber’s actual wiring, hardware components, and installed features. The configurator provides a reliable starting point, but advanced builds or custom setups may require additional manual editing after generation.

6. Creating and Selecting a Config File

6.1 Create Configuration File

1. Open the ProffieOS config/ directory.
2. Copy an existing configuration template.
3. Rename it with a meaningful name.
4. Edit the configuration using a plain-text editor.
5. Save the file.

6.2 Select Configuration with CONFIG_FILE

Open ProffieOS.ino and enable exactly one configuration file:

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

#define CONFIG_FILE "config/my_saber_config.h"

All unused configuration definitions must remain commented.

7. Understanding Config Sections

A ProffieOS configuration file contains several compile-time sections.

8. Core Configuration Parameters

#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 Configuration (* Note: Not currently supported on SUPERNEOX sabers.)

Blade configuration defines physical LED hardware, blade detection, and logical blade behavior.

9.1 Single Blade Example

BladeConfig blades[] = {

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

};

The first value is the Blade ID resistance used for blade detection. A value of 0 is commonly used when no blade-ID selection is required.

9.2 Multiple Blade Configurations

Multiple BladeConfig entries allow different physical configurations to be selected through blade identification.

9.3 SubBlade

SubBlade allows addressable LEDs to be divided into multiple logical zones such as crossguards, crystal chambers, and accent pixels.

10. Preset Configuration

A preset combines:

• Sound font
• Music track
• Blade Style
• Preset name

Preset presets[] = {

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

};

11. SD Card and Sound Font Management

The microSD card stores runtime assets used by ProffieOS, including sound fonts, tracks, configuration resources, and optional display assets.

11.1 Recommended SD Card Structure

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 Directory

Each sound font is stored inside an individual directory. The directory name is referenced by the preset configuration.

Preset presets[] = {

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

};

12. Buttons and Props

Buttons determine user interaction. The prop system interprets button combinations and converts them into saber actions.

12.1 Common Actions

Exact behavior is determined by the selected prop and button configuration. ProffieOS includes multiple saber props, including standard and advanced button/feature implementations. Do not assume that every current ProffieOS prop uses the same button map.

12.2 Prop Configuration

The selected prop defines:

• Button timing
• Gesture interpretation
• Menu behavior
• Special functions

#include "props/saber.h"

Custom props can be created for specialized hardware or product-specific controls.

13. Serial Monitor Debugging

The supplied manual documents the following commonly used commands:

13.1 Enable Serial Output

#define ENABLE_SERIAL

13.2 Typical Debug Information

• Boot messages
• SD card detection
• Blade initialization
• Preset loading
• Motion sensor status
• Button events

14. Blade Styles

Blade Styles are the core mechanism used by ProffieOS to define blade visual behavior. They control color, animation, ignition, retraction, clash response, blaster effects, lockup, drag, transitions, and other interactive effects.

14.1 Basic Style Example

StyleNormalPtr<RED>()

Basic styles define the default appearance of a blade. More advanced configurations use nested style functions and effect layers to create complex animations.

14.2 StylePtr Structure

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

StylePtr is commonly used to assign a complete Blade Style. Complex effects are created by combining multiple functions, layers, and transitions.

14.3 RGB Colors

Rgb<255, 50, 0>

RGB channel values range from 0 to 255. Named colors such as RED, GREEN, BLUE, WHITE, and CYAN can also be used where supported.

14.4 Common Effect Functions

14.5 Advanced Style Composition

Advanced users can combine functions, layers, transitions, and random effects to create fully customized blade behavior.

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

14.6 Multiple Blades / Accent Pixels

A preset can contain multiple Blade Styles corresponding to multiple logical blade definitions. This allows independent styles for a main blade, quillons, crystal chambers, accent strips, or other configured pixel groups.

14.7 Style Editing Resources

• ProffieOS Homepage - Note: Use ProffieOS 5.9 for SUPERNEOX sabers.
• SD Configuration File
• ProffieOS Documentation
• The Crucible Support Forum
• Fett263 Style Resources
• Blade Configuration Documentation

15. Advanced Integration

15.1 Displays

Supported display modules can provide:

• Battery information
• Preset selection
• Menu navigation
• Runtime status

15.2 Additional Peripherals

Advanced builds may integrate:

• Accent LEDs
• Crystal chambers
• Crossguard lighting
• Custom sensors
• External controllers

15.3 Production Workflow Recommendation

16. Troubleshooting

17. Developer References

• Official Installation Guide
• ProffieOS GitHub Repository
• V2 board configuration source
• ProffieOS Official Page
• ProffieOS.ino / CONFIG_FILE entry point