SUPERNEOX 개발자 헬프 센터

ProffieBoard V2.2 사용자 가이드

SUPERNEOX ProffieBoard V2.2가 탑재된 라이트세이버를 ProffieOS 5.9에서 사용하고, 설정하고, 커스터마이즈하는 방법을 안내합니다. 이 가이드에서는 라이트세이버 사용자가 알아야 할 기본 설정부터 실용적인 커스터마이즈 방법까지 설명합니다.
고급 프로그래밍, 펌웨어 설정 및 개발자 수준의 커스터마이즈에 대한 자세한 내용은 ProffieBoard V2.2 개발자 가이드를 참조하십시오.

ProffieBoard V2.2 ProffieOS 5.9 펌웨어 설정 Blade Styles

버전 안내: 본 가이드는 주로 ProffieOS 5.9 및 ProffieBoard V2.x를 기준으로 작성되었습니다. 설정 문법과 사용 가능한 기능은 ProffieOS 버전에 따라 달라질 수 있습니다. 버전별 동작 방식은 반드시 해당 ProffieOS의 공식 문서와 소스 코드를 확인하십시오.

1. 버튼 조작

버튼 동작은 ProffieOS 설정과 라이트세이버에 정의된 버튼 수에 따라 결정됩니다. 아래 조작 방법은 최소 1개의 전원 버튼이 설정된 구성을 기준으로 하며, AUX 버튼을 사용하는 경우가 포함될 수 있습니다.

기능	버튼 조작
Blade 점등 / 소등	전원 버튼을 짧게 누르면 라이트세이버가 켜지거나 꺼집니다.
무음 상태로 켜기	전원 버튼을 두 번 누릅니다.
다음 Preset	Blade가 꺼진 상태에서 AUX 버튼을 짧게 누릅니다.
이전 Preset	AUX 버튼을 누른 상태에서 전원 버튼을 누릅니다.
Clash	Blade가 켜진 상태에서 Blade에 충격을 가합니다.
Lockup	Blade가 켜진 상태에서 전원 버튼을 누른 채 충격을 가합니다. 전원 버튼을 놓으면 Lockup이 종료됩니다.
Drag	Lockup과 유사한 방식으로 작동합니다. 전원 버튼을 누르고 효과를 실행하기 전에 라이트세이버를 거의 아래쪽으로 향하게 합니다.
Force	AUX 버튼을 길게 누릅니다.
사운드트랙 재생	전원 버튼을 길게 누릅니다.
Blaster Block	Blade가 켜진 상태에서 AUX 버튼을 짧게 누릅니다.
Color Change Mode	Blade가 켜진 상태에서 AUX 버튼을 누른 채 전원 버튼을 빠르게 누릅니다. 확인음이 들리면 힐트를 회전하여 색상을 변경합니다. Color Change Mode를 종료하려면 확인음이 들릴 때까지 전원 버튼을 길게 누릅니다.

개발자 참고: 버튼 동작은 설정된 버튼 정의와 ProffieOS의 prop/button 설정에 따라 달라집니다. 사용자 지정 버튼 레이아웃을 사용하는 경우, 버튼 동작을 문제 해결하기 전에 현재 활성화된 설정을 먼저 확인하십시오.

2. Serial Monitor 명령어

ProffieOS에서는 테스트, 진단, 설정 확인, 오디오 테스트 및 Preset 전환 등에 사용할 수 있는 Serial 명령어를 제공합니다.

명령어	설명
`battery_voltage`	현재 배터리 전압을 표시합니다.
`get_volume`	현재 볼륨 값을 표시합니다.
`pow`	라이트세이버를 켜거나 끕니다.
`on`	라이트세이버를 켭니다.
`off`	라이트세이버를 끕니다.
`set_volume <0-3000>`	볼륨 값을 설정합니다. 예: `set_volume 500`
`play`	기본 Preset의 사운드트랙을 재생합니다. 이미 재생 중인 경우 재생을 중지합니다.
`play_track tracks/<track name>.wav`	`tracks` 폴더에 있는 특정 트랙을 재생합니다. 예: `play_track tracks/venus.wav`
`stop_track tracks/<track name>.wav`	지정한 트랙의 재생을 중지합니다.
`force`	Force 사운드 효과를 재생합니다.
`drag`	Drag 사운드 효과를 재생합니다.
`blast`	Blaster 사운드 효과를 재생합니다.
`lock`	Lockup 사운드 효과를 재생합니다.
`clash`	Clash 사운드 효과를 재생합니다.
`reset`	ProffieBoard를 재부팅합니다.
`n`	다음 Preset으로 전환합니다.
`p`	이전 Preset으로 전환합니다.
`list_presets`	사용 가능한 모든 Preset을 목록으로 표시합니다.
`sdtest`	SD 카드 속도를 테스트합니다.
`scanid`	감지된 Blade ID 저항값을 표시합니다.

3. 소프트웨어 설치 및 설정

ProffieBoard의 펌웨어를 개발하고 업로드하려면 Arduino IDE, ProffieBoard Arduino 플러그인 및 적절한 USB 드라이버가 필요합니다.

권장 환경: 안정 버전의 Arduino IDE를 사용하십시오. SUPERNEOX ProffieBoard V2.2 라이트세이버의 경우, 본 가이드는 ProffieOS 5.9 환경을 기준으로 작성되었습니다.

3.1 필요한 소프트웨어

Arduino IDE

ProffieOS 펌웨어를 편집하고 컴파일하며 업로드하는 데 사용합니다.

ProffieBoard Plugin

Arduino IDE에 ProffieBoard 지원 기능과 보드 전용 업로드 옵션을 추가합니다.

Zadig

펌웨어 프로그래밍에 필요한 USB 드라이버 설정을 수행할 때 사용합니다.

USB 데이터 케이블

데이터 전송을 지원하는 Micro-USB 케이블이 필요합니다. 충전 전용 케이블은 펌웨어 프로그래밍에 사용할 수 없습니다.

3.2 Arduino IDE 설치

최신 안정 버전의 Arduino IDE를 설치하십시오. Beta 버전은 사용하지 마십시오.

Windows에서는 Arduino IDE를 Windows Store 앱으로 설치하는 것을 권장하지 않습니다. 애플리케이션이 보호된 디렉터리에 설치될 수 있으며, 이 경우 추가 플러그인이나 소프트웨어를 정상적으로 설치하지 못할 수 있습니다.

COM 포트 문제 해결: ProffieBoard가 사용 가능한 COM 포트로 표시되지 않는 경우 다른 USB 포트를 사용해 보고, 케이블이 데이터 전송을 지원하는지 확인하십시오. 필요한 경우 이전 안정 버전의 Arduino IDE를 사용해 보는 것도 좋습니다.

3.3 ProffieBoard Plugin 및 Zadig 설치

ProffieBoard Arduino Plugin과 Zadig를 각각의 설치 안내에 따라 설치하십시오.

3.4 Arduino IDE 보드 설정

Arduino IDE에서 다음 항목을 선택하십시오.

도구 → 보드 → Proffieboard V2

설정 항목	권장 값
Board	Proffieboard V2
USB Type	Serial + Mass Storage (또는 + WebUSB)
CPU Speed	80 MHz
Optimize	Smallest Code 또는 Fast / Faster / Fastest
DOSFS	SDCARD (SPI)
Port	연결된 ProffieBoard에 할당된 COM 포트

USB 데이터 케이블을 사용하여 ProffieBoard를 컴퓨터에 연결하십시오. 연결된 ProffieBoard에 할당된 COM 포트가 Port 메뉴에 표시됩니다.

4. 펌웨어 업로드 및 업데이트

1단계 — ProffieOS 및 SD 카드 파일 다운로드

ProffieOS 펌웨어 패키지와 해당 SD 카드 파일을 다운로드하십시오.

SUPERNEOX ProffieBoard V2.2 라이트세이버의 경우, 본 개발자 가이드는 ProffieOS 5.9를 기준 버전으로 사용합니다.

다음 파일을 압축 해제하십시오.

ProffieOS-v5.9.zip

Documents 또는 Desktop과 같은 일반적인 작업 디렉터리에 패키지를 압축 해제하십시오.

중요: ProffieOS를 Arduino 설치 디렉터리 또는 Windows의 Program Files 디렉터리에 압축 해제하지 마십시오.

압축 해제 후 다음과 같은 구조가 되어야 합니다.

ProffieOS-v5.9/

└── ProffieOS/

ProffieOS 디렉터리 내부의 폴더나 파일 이름을 변경하거나 다른 위치로 이동하지 마십시오.

2단계 — SD 카드 구성 파일 설치

다음 파일을 압축 해제하십시오.

ProffieOS_SD_Card.zip

압축 해제한 ProffieOS_SD_Card 폴더의 모든 파일을 ProffieBoard microSD 카드의 루트 디렉터리에 복사하십시오.

Windows 파일 확장명 설정

Windows 파일 탐색기에서 파일 이름 확장명을 활성화하여 .h와 같은 파일 확장명이 표시되도록 하십시오.

확장명을 중복해서 추가하지 마십시오. Windows에서 기존 확장명이 숨겨져 있는 경우 설정 파일 이름 뒤에 .h 확장명을 다시 추가하지 마십시오.

3단계 — 설정 파일 생성

다음 폴더를 엽니다.

ProffieOS/config/

이 디렉터리 안에 설정 파일을 생성하십시오.

권장 방법은 적절한 기본 설정 파일을 복사하여 다른 이름으로 저장한 다음, 복사한 파일의 내용을 해당 라이트세이버에 맞게 생성한 설정으로 교체하는 것입니다.

ProffieBoard V2.x의 경우 공식 ProffieBoard V2.x Configurator를 사용하십시오.

4단계 — 설정 파일 지정

다음 파일을 엽니다.

ProffieOS/ProffieOS.ino

CONFIG_FILE 정의를 찾습니다.

#define CONFIG_FILE "config/my_saber_config.h"

config 디렉터리에 여러 설정 파일이 있는 경우 컴파일할 설정 파일 하나만 활성화해야 합니다.

중요: 동시에 활성화된 CONFIG_FILE 정의는 하나만 존재해야 합니다.

여러 라이트세이버 설정 파일을 동일한 config 디렉터리에 보관할 수 있습니다. 활성화할 CONFIG_FILE을 변경하면 사용할 설정 파일을 전환할 수 있습니다.

5단계 — 보드 연결

데이터 전송을 지원하는 Micro-USB 케이블을 사용하여 ProffieBoard를 컴퓨터에 연결하십시오.

USB 케이블 주의사항: 충전 전용 USB 케이블은 펌웨어 프로그래밍에 사용할 수 없습니다.

6단계 — 컴파일 및 업로드

Arduino IDE에서 ProffieOS.ino를 엽니다.
올바른 ProffieBoard V2 보드와 COM 포트가 선택되어 있는지 확인합니다.
올바른 CONFIG_FILE이 활성화되어 있는지 확인합니다.
Upload를 클릭합니다.
컴파일과 업로드가 완료될 때까지 기다립니다.

업로드가 정상적으로 완료되면 진행률 표시가 100%에 도달합니다.

스피커가 연결되어 있다면 업로드가 정상적으로 완료된 후 ProffieBoard에서 부팅 사운드가 재생됩니다.

Serial + Mass Storage를 선택했고 ProffieBoard가 이동식 드라이브로 표시되는 경우 USB 케이블을 분리하기 전에 해당 드라이브를 안전하게 제거하십시오.

펌웨어 업로드 완료: 새로운 ProffieOS 펌웨어가 ProffieBoard에 설치되었습니다.

업로드 문제 해결

업로드에 실패한 경우 다음과 같은 일반적인 원인을 확인하십시오.

설정 헤더 파일에 문법 오류 또는 설정 오류가 있을 수 있습니다.
CONFIG_FILE의 파일 이름이 잘못되었을 수 있습니다.
설정 파일이 ProffieOS/config/ 디렉터리에 위치하지 않을 수 있습니다.
Windows 사용자 이름 또는 작업 디렉터리에 라틴 문자가 아닌 문자가 포함되어 있으면 툴체인에서 문제가 발생할 수 있습니다.
선택한 Board, USB Type, CPU Speed 또는 COM Port가 잘못되었을 수 있습니다.

5. SD 카드 구성

ProffieOS는 라이트세이버의 microSD 카드에 사운드 폰트, 설정 관련 파일 및 음악 트랙을 저장합니다.

Sound Fonts

지원되는 Sound Font 폴더를 microSD 카드의 루트 디렉터리에 복사하십시오.

기본 설정에서는 다음과 같은 일반적인 Sound Font 구조를 지원합니다.

Plecter

Plecter 호환 Sound Font 구조입니다.

NEC

NEC 호환 Sound Font 구조입니다.

SmoothSwing

SmoothSwing 호환 Sound Font 구조입니다.

지원되는 Sound Font 구조를 사용하는 경우 일반적으로 WAV 파일 이름을 변경할 필요가 없습니다.

음악 트랙

음악 트랙은 다음 폴더에 저장하십시오.

tracks/

예:

tracks/venus.wav

tracks/mars.wav
tracks/mercury.wav

파일 및 폴더 이름

호환성을 높이려면 Sound Font 폴더와 음악 트랙에 라틴 문자와 단순한 파일 이름을 사용하십시오.

다음과 같은 불필요한 특수 문자는 사용하지 않는 것이 좋습니다.

? , . | \ } { [ / -

각 Sound Font 폴더에는 다음과 같은 필수 설정 파일이 포함되어 있어야 합니다.

config.ini

smoothsw.ini

파일이 누락된 경우: 필수 파일이 없는 경우 임의의 대체 파일을 직접 생성하지 말고, 정상적으로 작동하는 기본 ProffieBoard Sound Font에서 해당 파일을 복사하십시오.

6. 설정 및 파라미터

ProffieBoard의 설정은 주로 다음 위치에 있는 C++ 설정 헤더 파일을 통해 관리됩니다.

ProffieOS/config/

설정 파일에서는 보드 구성, Blade 수, 버튼, 오디오 설정, 모션 기능, LED 설정, Clash 감도, Preset 및 Blade Styles 등을 정의합니다.

ProffieBoard V2 기본 설정

#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`	사용할 Blade 구성의 개수를 지정합니다.
`NUM_BUTTONS`	설정할 버튼 수를 지정합니다. 참조된 구성에서는 1~3개의 버튼을 지원합니다.
`VOLUME`	초기 볼륨 값을 설정합니다. 문서에 명시된 범위는 0~3000입니다.
`maxLedsPerStrip`	어드레서블 LED 스트립에 설정할 최대 LED 수를 지정합니다.
`CLASH_THRESHOLD_G`	Clash 감도를 설정합니다. 일반적으로 값을 낮추면 감도가 높아지고, 값을 높이면 감도가 낮아집니다.
`ENABLE_AUDIO`	오디오 기능을 활성화합니다.
`ENABLE_MOTION`	모션 감지 기능을 활성화합니다.
`ENABLE_WS2811`	WS2811 / 어드레서블 LED 기능을 활성화합니다.
`ENABLE_SD`	SD 카드 기능을 활성화합니다.
`SAVE_STATE`	선택한 볼륨, Preset, Blade 색상 등의 상태 정보를 보드에 저장할 수 있도록 합니다.

Clash 감도

권장되는 시작 값은 다음과 같습니다.

#define CLASH_THRESHOLD_G 1.0

일반적으로 값을 낮추면 Clash 감도가 높아지고, 값을 높이면 감도가 낮아집니다.

조정 팁: Clash 감도는 작은 단위로 조금씩 조정하십시오. 감도를 지나치게 높이면 일반적인 움직임에서도 오작동이 발생할 수 있으며, 감도를 너무 낮추면 실제 충격을 감지하지 못할 수 있습니다.

설정 파일 편집

C++ 설정 파일을 수정할 때는 일반 텍스트 편집기 또는 코드 편집기를 사용하십시오.

Microsoft Word를 사용하지 마십시오. 워드 프로세서는 서식 문자를 삽입하거나 소스 파일의 구조를 변경할 수 있습니다.

설정을 변경한 후 다음 순서로 진행하십시오.

설정 파일을 저장합니다.
ProffieOS.ino를 엽니다.
올바른 CONFIG_FILE이 활성화되어 있는지 확인합니다.
펌웨어를 컴파일합니다.
ProffieBoard에 펌웨어를 업로드합니다.

7. Preset 설정

Preset은 라이트세이버에서 사용할 Sound Font, 사운드트랙, Blade Style 및 사용자에게 표시되는 Preset 이름을 정의합니다.

기본 Preset 구조

일반적인 Preset은 CONFIG_PRESETS 섹션 안에서 정의합니다.

#ifdef CONFIG_PRESETS

Preset presets[] = {

{
"TeensySF",
"tracks/venus.wav",
StyleNormalPtr(),
"cyan"
}

};

#endif

Preset 구성 요소

구성 요소	설명
Sound Font 폴더	SD 카드에 저장된 Sound Font 폴더의 이름입니다.
Track 이름	음악 트랙의 경로입니다. 일반적으로 `tracks` 디렉터리 안에 저장합니다.
Blade Style	Blade의 시각적 동작과 효과를 정의합니다.
Preset 이름	Preset 시스템에서 사용하는 사용자 표시용 이름입니다.

Blade 설정

물리적인 Blade 구성은 BladeConfig blades[] 배열을 통해 선언합니다.

이 설정은 실제 LED/Blade 하드웨어와 Preset 설정을 연결합니다.

BladeConfig blades[] = {

{
0,
WS281XBladePtr<
144,
bladePin,
Color8::GRB,
PowerPINS
>(),
CONFIGARRAY(presets)
},

};

8. Blade Styles

ProffieOS에서는 Blade Styles를 사용하여 메인 Blade와 기타 설정된 LED의 시각적 동작을 정의합니다.

Color

기본 색상 및 사용자 지정 Blade 색상을 설정합니다.

Motion Effects

움직임, 스윙 및 기타 모션 입력에 반응하는 효과를 설정합니다.

Impact Effects

Clash, Blaster, Lockup 및 Drag 효과를 설정합니다.

Transitions

점등, 소등, 타이밍 및 전환 동작을 설정합니다.

Blade Style에서 설정할 수 있는 기능

기본 색상
색상 변경
Flickering
Clash 플래시
Blaster 효과
Lockup 효과
Drag 효과
점등 효과
소등 효과
타이밍
전환 동작

Blade Style Editor

기존 개발자 문서에서는 Blade Styles를 생성하고 수정할 때 Blade Style Editor를 사용하는 것을 권장합니다.

유용한 참고 자료:

Blade Style 구조

Blade Style은 일반적으로 StylePtr<...> 표현식 안에 작성합니다.

여러 효과를 중첩하여 구성할 수 있으며, 각 레이어는 하위 효과의 결과를 변경하거나 변환합니다.

InOutHelper

InOutHelper<base color, 200, 300, Black>

파라미터	의미
`base color`	기본 Blade 색상입니다.
`200`	Blade가 펼쳐지는 데 걸리는 시간 / 점등 시간(밀리초)입니다.
`300`	Blade가 수납되는 데 걸리는 시간 / 소등 시간(밀리초)입니다.
`Black`	Blade가 수납된 상태에서 표시되는 색상입니다.

Color 정의

일반적인 Blade 색상에는 미리 정의된 Color 상수를 사용할 수 있습니다.

WHITE
 

RED
GREEN
BLUE
PURPLE
CYAN
YELLOW
MAGENTA

사용자 지정 RGB 색상은 다음 형식으로 지정할 수 있습니다.

Rgb<R, G, B>

예:

Rgb<255, 50, 0>

각 RGB 채널에는 0부터 255까지의 값을 지정합니다.

0 = 해당 채널의 출력 없음
255 = 해당 채널의 최대 출력

AudioFlicker

AudioFlicker<"A" color, "B" color>

AudioFlicker는 라이트세이버의 오디오 또는 Hum 사운드에 반응하여 깜빡이는 Blade 효과를 생성합니다.

두 색상의 차이가 클수록 일반적으로 시각적인 변화도 더 크게 나타납니다.

OnSpark

OnSpark<base color, spark color, duration>

OnSpark는 Blade가 점등될 때 스파크 효과를 추가합니다. duration 값은 밀리초 단위로 지정합니다.

SimpleClash

SimpleClash<base color, clash color, 40>

Clash 플래시 효과를 추가합니다. 마지막 파라미터는 효과 지속 시간을 밀리초 단위로 지정합니다.

Lockup

Lockup<base color, lockup color>

Lockup 효과를 추가하고 효과가 실행되는 동안 사용할 색상 동작을 지정합니다.

Blast

Blast<base color, blast color>

Blaster 효과를 추가하고 효과에 사용할 색상을 지정합니다.

복합 Blade Style 예제

보다 고급 Blade Style에서는 여러 효과를 하나의 중첩 표현식으로 결합할 수 있습니다.

일반적인 복합 Style에는 다음과 같은 요소를 포함할 수 있습니다.

Green 기본 색상
Audio flicker
점등 시 스파크
Clash 효과
Blaster 효과
Lockup 효과
Drag 효과
점등 타이밍
소등 타이밍

개발자 참고: Blade Style 표현식은 매우 길어지거나 여러 단계로 깊게 중첩될 수 있습니다. 복잡한 Style을 디버깅할 때는 먼저 각 효과를 개별적으로 테스트한 후 단계적으로 결합하는 것이 좋습니다.

완성된 Blade Style은 Preset 내부의 적절한 StylePtr<...> 컨테이너에 삽입합니다.

9. 개발자 참고 자료

최신 ProffieOS 개발 정보, 설정 방법 및 보드별 정보는 본 SUPERNEOX 개발자 가이드와 함께 아래 공식 리소스를 참조하십시오.

SUPERNEOX SD 설정 파일

SUPERNEOX Proffie V2.2 기본 설정 파일입니다.

Google Drive 열기 →

ProffieOS 문서

ProffieOS의 기능, 설정 및 개발 개념을 다루는 공식 문서입니다.

문서 열기 →

ProffieOS GitHub

소스 코드, 릴리스, 설정 예제 및 개발 관련 정보를 확인할 수 있습니다.

GitHub 열기 →

ProffieBoard V2.x Configurator

ProffieBoard V2.x용 브라우저 기반 설정 도구입니다.

Configurator 열기 →

ProffieOS 지원 포럼

ProffieOS 및 ProffieBoard에 대한 커뮤니티 토론과 문제 해결 정보를 확인할 수 있습니다.

지원 포럼 열기 →

10. 문서 범위

문서 범위: 본 개발자 가이드는 제공된 ProffieBoard V2 기술 매뉴얼을 기반으로 작성되었으며, 기본 설정 개념, 명령어 참조, 펌웨어 작업 절차, Preset 구조 및 Blade Style 관련 용어를 그대로 유지합니다.

ProffieOS는 지속적으로 유지보수 및 업데이트되고 있습니다. 설정 문법, 사용 가능한 기능, 지원 하드웨어 및 동작 방식은 버전에 따라 달라질 수 있습니다.

반드시 버전별 동작을 확인하십시오. 실제 라이트세이버에 설정 또는 코드 예제를 적용하기 전에, 보드에 설치된 정확한 ProffieOS 버전에 해당하는 문서 및 소스 코드와 비교하여 확인하십시오.