SUPERNEOX 開発者向けヘルプセンター

ProffieBoard V2 / ProffieOS 開発者ガイド

ProffieBoard V2/V2.2およびProffieOSを搭載したSUPERNEOXライトセーバーを対象とした、ファームウェア開発者、設定エンジニア、製品技術者、上級インテグレーター向けの技術リファレンスです。

ドキュメント情報：日本語開発者向け / 技術資料 ProffieBoard V2/V2.2 ProffieOS

バージョンによって仕様が異なる場合があります。 ProffieOSは継続的に開発・更新されています。そのため、設定ファイルの構文、Props、Style、メニュー、シリアルコマンド、対応ハードウェアなどは、バージョンによって変更される場合があります。ファームウェアをビルドする際は、使用するProffieOSの正確なバージョンおよび対応する公式ドキュメントを最終的な参照先としてください。

1. 対象範囲とバージョン管理

本ガイドでは、ProffieBoard V2を使用した開発環境を前提に、 Arduino IDE、ProffieOS、config.h、 SDカードのデータ、プリセット、Blade Stylesを使用した基本的なワークフローを説明します。

現在のProffieOSでも基本的な開発フローは同様です。 Arduinoのサポート環境をセットアップし、ProffieOSを取得したうえで、対象ボードに合わせた設定ファイルを作成します。その後、CONFIG_FILEで設定を指定し、コンパイルと書き込みを行いながら設定を調整していきます。

信頼できる参照先

ボード固有のソースコード / 設定： 使用する対象ボードに対応したProffieOSのソースコードおよびボード設定。
最新の公式ドキュメント： ProffieOS公式ドキュメント。
ハードウェアリファレンス： ProffieBoard V2のリファレンスドキュメント。
リポジトリの履歴： バージョンによって動作が異なる場合は、 GitHubのコミット履歴およびリリースノートを確認してください。

2. ファームウェア構成と基本的な考え方

Proffieを搭載したSUPERNEOXライトセーバーは、次のような複数のレイヤーから構成されるシステムとして考えることができます。

ハードウェア配線 → ボード固有の設定 → ProffieOSの機能定義 → ブレード定義 → プリセット / Style / Props → SDカードのリソース

あるレイヤーの問題が、別のレイヤーの不具合として現れることがあります。そのため、トラブルシューティングでは、最も基本となる依存レイヤーから順番に確認してください。

ハードウェアレイヤー

バッテリー、スピーカー、ボタン、NeoPixelのデータ・電源、ブレードID、SDカード、ディスプレイ、アクセントLED、その他のオプション周辺機器。

ビルドレイヤー

Arduino IDE、ボードパッケージ / プラグイン、 ProffieOSソースコード、および選択したCONFIG_FILE。

ランタイムレイヤー

BladeConfig、プリセット、Style、Props、モーション・オーディオ動作、メニュー、保存状態など。

リソースレイヤー

SDカード上のSound Font、トラック、設定ファイル、画像、ディスプレイ用データ、その他の実行時リソース。

推奨される開発・管理方法： 製品として出荷するライトセーバーごとに、使用したProffieOSの正確なリリース / コミット、完全な設定ファイル、SDカードのリソース一式、配線仕様、正常動作が確認されたビルドを保存・管理してください。

3. ProffieBoard V2 ハードウェア

ProffieBoard V2は、ライトセーバー向けのオープンソースコントローラーです。高度なファームウェアカスタマイズに対応しており、電源、ボタン、アドレサブルLED、ディスプレイ、モーションセンサー、デバッグ用インターフェース、その他の周辺機器を接続できます。

3.1 主なハードウェア

ProffieBoard V2/V2.2 コントローラー
3.7V Li-ionバッテリー
スピーカー
アドレサブルブレードまたは対応LEDハードウェア
開発用Micro-USB接続
Sound Fontおよび各種リソース用microSDカード

3.2 主要ピン

接続	用途
`BATT+`	ボードへのバッテリー入力。
`BATT-`	LED電源のリターンおよび大電流回路のリターン。
`GND`	ボードのグランド接続。
`Button 1/2/3`	物理ボタン入力。
`Data 1 / ID`	ブレードIDの検出および/または最初のアドレサブルLED用データ出力。
`Data 2 / Data 3`	追加のアドレサブルLED用データ出力。
`Data4 / DAC`	設定に応じて、追加のデータ出力またはオーディオDACとして使用。
`LED 1-6`	対応するLEDチャンネル用の接続。
`SDA / SCL`	モーションセンサーや周辺機器とのI²C通信。
`SWDIO / SWDCLK`	ST-LINKデバッグインターフェース。

電源および極性に関する注意： 逆極性保護によりボード自体は保護されますが、バッテリーの極性を誤ると、接続されているNeoPixelなどの LEDハードウェアが損傷する可能性があります。

3.3 配線に関する注意

信号線の多くは比較的細い線を使用できますが、バッテリーおよびLEDの電源ラインについては、想定される最大電流に合わせて適切な線径を選択してください。

4. 開発環境

4.1 必要なソフトウェア

Arduino IDE
ProffieBoard用Arduinoプラグイン
ProffieOSソースパッケージ
必要に応じてUSBドライバー
設定ファイル編集用のテキストエディター / コードエディター

4.2 Arduino IDEでのボード選択

ProffieBoard V2を使用する場合は、対応するボードを選択してください。


ツール → ボード → Proffieboard V2

Arduino設定	推奨値
Board	Proffieboard V2
USB Type	Serial + WebUSB + Mass Storage（対応している場合）
DOSFS	SDCARD (SPI)
CPU Speed	80 MHz
Optimize	Smallest Code、Fast、Faster、Fastestのいずれかを、設定内容およびリソース要件に応じて選択
Port	接続されているボードのCOMポート

5. ProffieOSのインストール

5.1 ProffieOSの入手

SUPERNEOXライトセーバーのファームウェアを安定して設定・コンパイルするため、 ProffieOS 5.9を使用してください。ダウンロード後、ProffieOSのソースファイルを「ドキュメント」や「デスクトップ」など、書き込み可能なユーザーフォルダに展開してください。

Program Filesなどの保護されたシステムフォルダや、システムによって管理されている場所にはソースコードを保存しないでください。 Windowsのアクセス権限によってファイルへのアクセスが制限され、コンパイルエラーが発生する場合があります。

ソースツリーには、メインのArduinoスケッチが含まれています。


ProffieOS/ProffieOS.ino

主なディレクトリには以下のようなものがあります。


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

5.2 Arduinoスケッチを開く

以下のファイルを開きます。


ProffieOS/ProffieOS.ino

5.3 V2 Configuratorを使用する

ProffieOS公式ドキュメントでは、使用するProffieBoardのバージョンに対応したConfiguratorの利用が推奨されています。 ProffieBoard V2.xを搭載したSUPERNEOXライトセーバーでは、以下のConfiguratorを使用してください。

ProffieBoard V2.x Configurator

Configuratorで生成されたコードは、実際のライトセーバーの配線、搭載されているハードウェア、および使用する機能に合わせて調整してください。 Configuratorは信頼できる初期設定を作成するためのツールですが、高度な構成やカスタムハードウェアでは、生成後に手動でコードを編集する必要があります。

6. 設定ファイルの作成と選択

6.1 設定ファイルを作成する

ProffieOSのconfig/ディレクトリを開きます。
既存の設定テンプレートをコピーします。
用途が分かる名前に変更します。
テキストエディターで設定を編集します。
ファイルを保存します。

Microsoft Wordは使用しないでください。 設定ファイルはソースコードであるため、プレーンテキスト形式で保存する必要があります。

6.2 CONFIG_FILEで設定を指定する

ProffieOS.inoを開き、使用する設定ファイルを1つだけ有効にします。


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

#define CONFIG_FILE "config/my_saber_config.h"

使用しない設定ファイルの定義は、コメントアウトした状態にしてください。

7. 設定セクションについて

ProffieOSの設定ファイルには、コンパイル時に使用される複数のセクションがあります。

`CONFIG_TOP`

ハードウェア全体の設定、機能スイッチ、ブレード数、ボタン、オーディオ、モーション、SDカードなどを定義します。

`CONFIG_STYLES`

ProffieOS 7.x以降で利用可能です。再利用可能なStyleテンプレートやエイリアスを定義します。

`CONFIG_PRESETS`

プリセット、Sound Font、トラック、Style、プリセット名などを定義します。

`CONFIG_PROP`

Propsの動作やカスタム操作を定義します。

8. 主要な設定パラメータ


#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

パラメータ	用途
`NUM_BLADES`	ブレード定義の数。
`NUM_BUTTONS`	設定されている物理ボタンの数。
`VOLUME`	デフォルトの音量レベル。
`maxLedsPerStrip`	LEDの最大数。
`CLASH_THRESHOLD_G`	Clash検出のしきい値。一般的に値を小さくすると、 Clash検出の感度が高くなります。
`ENABLE_AUDIO`	オーディオ機能を有効にします。
`ENABLE_MOTION`	モーション検出を有効にします。
`ENABLE_WS2811`	一般的なNeoPixel構成で使用されるWS2811 / アドレサブルLED機能を有効にします。
`ENABLE_SD`	SDカードのサポートを有効にします。
`SAVE_STATE`	対応する設定の状態保存機能を有効にします。

9. ブレード設定（※現在、SUPERNEOXのライトセーバーではサポートされていません。）

ブレード設定では、物理LEDハードウェア、ブレード検出、および論理的なブレード動作を定義します。

9.1 シングルブレードの例


BladeConfig blades[] = {

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

};

最初の値は、ブレード検出に使用されるBlade ID抵抗値です。ブレードIDによる選択が必要ない場合は、通常0を使用します。

9.2 複数ブレードの設定

複数のBladeConfigエントリを使用すると、 Blade IDに応じて異なる物理構成を選択できます。

9.3 SubBlade

SubBladeを使用すると、アドレサブルLEDを複数の論理ゾーンに分割できます。たとえば、クロスガード、クリスタルチャンバー、アクセントピクセルなどを個別のゾーンとして扱うことができます。

10. プリセット設定

1つのプリセットには、以下の要素が含まれます。

Sound Font
音楽トラック
Blade Style
プリセット名


Preset presets[] = {

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

};

項目	意味
Sound Font	サウンドファイルが格納されているディレクトリ。
Track	音楽ファイルのパス。
Style	ブレードの視覚的な動作。
Name	プリセットとして表示される名前。

11. SDカードとSound Fontの管理

microSDカードには、ProffieOSが実行時に使用する各種リソースが保存されます。 Sound Font、トラック、設定リソース、オプションのディスプレイ用データなどが含まれます。

11.1 推奨されるSDカード構成


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ディレクトリ

各Sound Fontは、それぞれ専用のディレクトリに保存します。ディレクトリ名はプリセット設定から参照されます。

例：


Preset presets[] = {

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

};

ファイル名は重要です。 ProffieOSは決められた名前のサウンドファイルを検索します。ファイル名が正しくない場合や必要なファイルが存在しない場合、音が出ない、または一部のエフェクトが動作しないことがあります。

12. ボタンとProps

ボタンはユーザー操作を定義します。 Propsシステムはボタン操作や組み合わせを解釈し、ライトセーバーの各種アクションに変換します。

12.1 主な操作

操作	一般的な入力
点灯	Power / Activationボタンを短く押します。
消灯	ブレード点灯中にPower / Activationボタンを短く押します。
サイレント点灯	Powerボタンを2回押します。
次のプリセット	ブレード消灯中にAUXを短く押します。
前のプリセット	AUXを押したままPowerを押します。
Clash	ブレード点灯中にブレードへ衝撃を与えます。
Lockup	Powerを押したまま、Clashを発生させます。
Drag	ライトセーバーの先端を下向きにしてLockupジェスチャーを行います。
Force Effect	AUXを長押しします。
Blaster Block	ブレード点灯中にAUXを短く押します。
カラー変更	AUXを押したままPowerを素早く押し、その後ハンドルを回転させます。
音量 / メニュー操作	ボタンの長押しや組み合わせ操作によって、設定や各種調整メニューにアクセスします。

実際の操作方法は、選択しているPropおよびボタン設定によって異なります。 ProffieOSには、標準的なボタン操作に対応したPropや、より高度な機能を備えたPropなど、複数の実装が存在します。すべてのProffieOS Propで同じボタン操作が使用されるとは限りません。

12.2 Propの設定

選択したPropによって、以下の項目が定義されます。

ボタン入力のタイミング
ジェスチャーの判定方法
メニューの動作
特殊機能


#include "props/saber.h"

専用ハードウェアや製品独自の操作方法に対応するため、カスタムPropを作成することもできます。

13. シリアルモニターによるデバッグ

以下は、提供されているマニュアルで説明されている主なコマンドです。

コマンド	機能
`battery_voltage`	バッテリー電圧を確認します。
`get_volume`	現在の音量を確認します。
`pow`	電源状態を切り替えます。
`on`	電源をオンにします。
`off`	電源をオフにします。
`set_volume 500`	音量を設定します。
`play`	デフォルトのトラックを再生 / 停止します。
`force`	Forceサウンドを再生します。
`drag`	Dragサウンドを再生します。
`blast`	Blasterサウンドを再生します。

13.1 シリアル出力を有効にする


#define ENABLE_SERIAL

13.2 主なデバッグ情報

起動メッセージ
SDカードの検出状態
ブレードの初期化
プリセットの読み込み
モーションセンサーの状態
ボタン操作イベント

推奨デバッグ手順： 製品版ライトセーバーのトラブルシューティングを行う際は、ファームウェア設定を変更する前に、起動時のシリアルログを最初から最後まで保存してください。

14. Blade Styles

Blade Stylesは、ProffieOSでブレードの視覚的な動作を定義するための中心的な仕組みです。色、アニメーション、点灯、消灯、Clash時の反応、 Blasterエフェクト、Lockup、Drag、トランジション、その他のインタラクティブなエフェクトを制御できます。

14.1 基本的なStyleの例


StyleNormalPtr<RED>()

基本的なStyleでは、ブレードの標準的な外観を定義します。より高度な設定では、Style関数や複数のエフェクトレイヤーを組み合わせ、複雑なアニメーションを作成できます。

14.2 StylePtrの構造


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

StylePtrは、ブレード全体のBlade Styleを割り当てるために使用されます。複雑なエフェクトは、複数の関数、レイヤー、トランジションを組み合わせて作成します。

14.3 RGBカラー


Rgb<255, 50, 0>

RGBの各チャンネル値は0～255の範囲で指定します。また、対応している場合は、 RED、GREEN、BLUE、 WHITE、CYANなどの色名も使用できます。

14.4 主なエフェクト関数

関数	説明
`InOutHelper<base, extension, retraction, offColor>`	ブレードの点灯・消灯時の伸長 / 収納アニメーションを制御し、消灯時のカラーも指定します。
`AudioFlicker<A, B>`	2色の間で音に反応するちらつきを生成し、エネルギーが不安定に揺らいでいるような表現を作ります。
`OnSpark<base, spark, duration>`	ブレード点灯時にスパークアニメーションを追加します。
`SimpleClash<base, clash, duration>`	ブレードが衝撃を検出した際にフラッシュエフェクトを生成します。
`Lockup<base, lockup>`	Lockup中の継続的なブレード動作とカラー反応を定義します。
`Blast<base, blast>`	Blaster攻撃を受けた際のフラッシュエフェクトとカラーを定義します。

14.5 高度なStyleの組み合わせ

上級ユーザーは、関数、レイヤー、トランジション、ランダムエフェクトなどを組み合わせることで、完全にカスタマイズされたブレード動作を作成できます。


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

14.6 複数ブレード / アクセントピクセル

1つのプリセットに複数のBlade Styleを設定し、複数の論理ブレード定義に対応させることができます。これにより、メインブレード、クイロン、クリスタルチャンバー、アクセントLEDなどを個別に制御できます。

14.7 Style編集用リソース

ProffieOS Homepage - 注意：SUPERNEOXライトセーバーではProffieOS 5.9を使用してください。
SD設定ファイル
ProffieOS Documentation
The Crucible Support Forum
Fett263 Style Resources
Blade Configuration Documentation

15. 高度な統合

15.1 ディスプレイ

対応するディスプレイモジュールを使用すると、以下の情報を表示できます。

バッテリー情報
プリセット選択
メニュー操作
リアルタイムの動作状態

15.2 追加の周辺機器

高度な構成では、以下のようなハードウェアを統合できます。

アクセントLED
クリスタルチャンバー
クロスガード照明
カスタムセンサー
外部コントローラー

15.3 製品開発・量産時の推奨ワークフロー

ハードウェアのリビジョンを確定する。
配線図を保存する。
使用したProffieOSのバージョンを保存する。
設定ファイルを保存する。
SDカードの内容を保存する。
代表的な実機でファームウェアをテストする。
量産用パッケージとしてリリースする。

16. トラブルシューティング

症状	考えられる原因	対処方法
ボードが認識されない	ドライバー、USBケーブル、ブートローダー、またはポートの問題。	USB接続、ドライバー、Arduino IDEで選択しているポートを確認してください。
コンパイルに失敗する	ProffieOSのバージョンが不適切、設定ファイルが不足している、または構文エラー。	`CONFIG_FILE`、ボード設定、設定ファイルの構文を確認してください。
音が出ない	SDカード上のファイル不足、 Sound Fontディレクトリの設定ミス、または音量設定の問題。	SDカードの構成、Sound Font名、オーディオ設定を確認してください。
ブレードが点灯しない	ブレード設定の誤り、または配線上の問題。	`BladeConfig`、 LEDデータ接続、電源経路を確認してください。
モーションエフェクトが使用できない	モーション機能が無効になっている、またはセンサーに問題がある。	`ENABLE_MOTION`およびセンサーのハードウェア接続を確認してください。

ファームウェアを書き換える前に： 必ず正常動作している設定ファイルとSDカードのバックアップを保存してください。ファームウェアの更新によって、カスタム設定や動作が上書きされる場合があります。

17. 開発者向けリファレンス

技術メモ： 量産用ライトセーバーを開発する場合は、ファームウェア、設定ファイル、ハードウェアリビジョン、 SDカードのリソースをまとめてバージョン管理することを推奨します。

注意：
ProffieBoardおよびProffieOSはオープンソースプロジェクトです。本ドキュメントは、提供されたマニュアルおよび公開されているProffieOSのドキュメントをもとに作成した技術リファレンスであり、ProffieOSプロジェクトの公式ドキュメントではありません。
量産用ビルドを作成する際は、実際に使用するProffieOSのバージョンおよびハードウェアリビジョンに対して、必ず動作を検証してください。

1. 対象範囲とバージョン管理

信頼できる参照先

2. ファームウェア構成と基本的な考え方

ハードウェアレイヤー

ビルドレイヤー

ランタイムレイヤー

リソースレイヤー

3. ProffieBoard V2 ハードウェア

3.1 主なハードウェア

3.2 主要ピン

3.3 配線に関する注意

4. 開発環境

4.1 必要なソフトウェア

4.2 Arduino IDEでのボード選択

5. ProffieOSのインストール

5.1 ProffieOSの入手

5.2 Arduinoスケッチを開く

5.3 V2 Configuratorを使用する

6. 設定ファイルの作成と選択

6.1 設定ファイルを作成する

6.2 CONFIG_FILEで設定を指定する

7. 設定セクションについて

CONFIG_TOP

CONFIG_STYLES

CONFIG_PRESETS

CONFIG_PROP

8. 主要な設定パラメータ

9. ブレード設定 （※現在、SUPERNEOXのライトセーバーではサポートされていません。）

9.1 シングルブレードの例

9.2 複数ブレードの設定

9.3 SubBlade

10. プリセット設定

11. SDカードとSound Fontの管理

11.1 推奨されるSDカード構成

11.2 Sound Fontディレクトリ

12. ボタンとProps

12.1 主な操作

12.2 Propの設定

13. シリアルモニターによるデバッグ

13.1 シリアル出力を有効にする

13.2 主なデバッグ情報

14. Blade Styles

14.1 基本的なStyleの例

14.2 StylePtrの構造

14.3 RGBカラー

14.4 主なエフェクト関数

14.5 高度なStyleの組み合わせ

14.6 複数ブレード / アクセントピクセル

14.7 Style編集用リソース

15. 高度な統合

15.1 ディスプレイ

15.2 追加の周辺機器

15.3 製品開発・量産時の推奨ワークフロー

16. トラブルシューティング

17. 開発者向けリファレンス

`CONFIG_TOP`

`CONFIG_STYLES`

`CONFIG_PRESETS`

`CONFIG_PROP`

9. ブレード設定（※現在、SUPERNEOXのライトセーバーではサポートされていません。）