ProffieBoard V2 / ProffieOS 개발자 가이드

1. 적용 범위 및 버전 관리

본 문서는 Arduino IDE, ProffieOS, config.h 파일, SD 카드 콘텐츠, Preset 및 Blade Styles를 중심으로 한 ProffieBoard V2 개발 워크플로를 설명합니다.

최신 ProffieOS에서도 기본적인 개발 절차는 동일합니다. Arduino 지원 환경을 설치하고 ProffieOS를 준비한 다음, 대상 보드에 맞는 설정 파일을 작성하고 CONFIG_FILE을 통해 해당 파일을 지정합니다. 이후 펌웨어를 컴파일하여 업로드하고, 필요에 따라 설정을 반복적으로 수정하고 테스트합니다.

문서 및 소스의 우선순위

1. 보드별 소스 및 설정: 실제 대상 보드에 적용되는 ProffieOS 소스와 보드별 configuration을 가장 우선적으로 확인하십시오.
2. 최신 공식 문서: ProffieOS 공식 Documentation을 참고하십시오.
3. 보드 레퍼런스: ProffieBoard V2 공식 reference documentation을 확인하십시오.
4. Repository 변경 이력: 버전별 동작 차이가 있는 경우 GitHub commit 및 release notes를 함께 확인하십시오.

2. 펌웨어 아키텍처 및 기준 데이터 구조

SUPERNEOX Proffie 기반 라이트세이버는 다음과 같은 계층 구조의 시스템으로 이해하는 것이 좋습니다: 하드웨어 배선 → 보드별 설정 → ProffieOS 기능 정의 → Blade 정의 → Preset / Style / Prop → SD 카드 리소스.

특정 계층의 문제가 다른 계층의 문제처럼 나타날 수 있습니다. 따라서 문제를 진단할 때는 가장 낮은 의존 계층인 하드웨어와 배선부터 순차적으로 확인하는 것이 권장됩니다.

3. ProffieBoard V2 하드웨어

ProffieBoard V2는 고급 펌웨어 커스터마이징을 지원하는 오픈소스 라이트세이버 컨트롤러입니다. 전원, 버튼, 주소 지정형 LED, 디스플레이, 모션 센서, 디버깅 인터페이스 및 추가 주변 장치를 연결할 수 있습니다.

3.1 핵심 하드웨어

• ProffieBoard V2/V2.2 컨트롤러
• 3.7V Li-ion 배터리
• 스피커
• 주소 지정형 Blade 또는 지원되는 LED 하드웨어
• 개발용 Micro-USB 연결
• Sound Font 및 리소스 저장용 microSD 카드

3.2 주요 핀

3.3 배선 시 고려 사항

대부분의 신호선은 상대적으로 가는 전선을 사용할 수 있지만, 배터리 및 LED 전원 경로는 예상되는 최대 전류에 맞는 적절한 굵기의 전선을 사용해야 합니다.

4. 개발 환경

4.1 필수 소프트웨어

• Arduino IDE
• ProffieBoard Arduino 플러그인
• ProffieOS 소스 패키지
• 필요한 경우 USB 드라이버
• Configuration 편집용 일반 텍스트 / 코드 에디터

4.2 Arduino 보드 선택

ProffieBoard V2를 사용하는 경우 해당 보드 타깃을 선택하십시오:

Tools → Board → Proffieboard V2

5. ProffieOS 설치

5.1 ProffieOS 준비

SUPERNEOX 라이트세이버의 안정적인 펌웨어 설정 및 컴파일을 위해 ProffieOS 5.9를 사용하십시오. 다운로드한 ProffieOS 파일은 Documents 또는 Desktop과 같은 쓰기 권한이 있는 사용자 폴더에 압축을 해제하는 것을 권장합니다. Windows의 권한 제한으로 인해 컴파일 문제가 발생할 수 있으므로 Program Files와 같은 보호된 시스템 폴더나 시스템에서 관리하는 애플리케이션 디렉터리에는 소스 코드를 저장하지 마십시오.

소스 트리에는 메인 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. Config 파일 생성 및 선택

6.1 Configuration 파일 생성

1. ProffieOS의 config/ 디렉터리를 엽니다.
2. 기존 configuration 템플릿을 복사합니다.
3. 용도를 쉽게 식별할 수 있는 이름으로 변경합니다.
4. 일반 텍스트 또는 코드 에디터에서 configuration을 수정합니다.
5. 파일을 저장합니다.

6.2 CONFIG_FILE을 사용하여 Configuration 선택

ProffieOS.ino를 열고 정확히 하나의 configuration 파일만 활성화하십시오:

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

#define CONFIG_FILE "config/my_saber_config.h"

사용하지 않는 configuration 정의는 반드시 주석 처리된 상태로 유지하십시오.

7. Config 구성 이해하기

ProffieOS configuration 파일은 여러 개의 컴파일 타임 설정 영역으로 구성됩니다.

8. 핵심 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. Blade Configuration (* 참고: 현재 SUPERNEOX 라이트세이버에서는 지원되지 않습니다.)

Blade Configuration은 실제 LED 하드웨어, Blade 감지 방식 및 논리적 Blade 동작을 정의합니다.

9.1 단일 Blade 예제

BladeConfig blades[] = {

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

};

첫 번째 값은 Blade 감지에 사용되는 Blade ID 저항값입니다. Blade ID에 따른 선택이 필요하지 않은 경우 일반적으로 0을 사용할 수 있습니다.

9.2 여러 Blade Configuration

여러 개의 BladeConfig 항목을 사용하면 Blade 식별 정보를 통해 서로 다른 물리적 하드웨어 구성을 선택할 수 있습니다.

9.3 SubBlade

SubBlade를 사용하면 주소 지정형 LED를 여러 개의 논리적 영역으로 분할할 수 있습니다. 예를 들어 Crossguard, Crystal Chamber, Accent Pixel 등의 영역을 각각 독립적으로 구성할 수 있습니다.

10. Preset Configuration

하나의 Preset은 다음 요소를 결합합니다:

• Sound Font
• Music Track
• Blade Style
• Preset 이름

Preset presets[] = {

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

};

11. SD 카드 및 Sound Font 관리

microSD 카드는 ProffieOS에서 사용하는 런타임 리소스를 저장합니다. 여기에는 Sound Font, Track, Configuration 리소스 및 선택적 디스플레이 리소스 등이 포함될 수 있습니다.

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 Configuration에서는 해당 디렉터리 이름을 참조합니다.

Preset presets[] = {

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

};

12. 버튼 및 Prop

버튼은 사용자의 물리적인 입력을 담당하며, Prop 시스템은 버튼 조합과 입력 동작을 해석하여 실제 라이트세이버 기능으로 변환합니다.

12.1 주요 동작

정확한 동작은 선택된 Prop과 버튼 Configuration에 따라 달라집니다. ProffieOS에는 일반적인 Prop부터 고급 버튼 및 기능을 지원하는 여러 가지 Saber Prop이 포함되어 있습니다. 따라서 현재 사용 중인 모든 ProffieOS Prop의 버튼 맵이 동일하다고 가정해서는 안 됩니다.

12.2 Prop Configuration

선택된 Prop은 다음과 같은 동작을 정의합니다:

• 버튼 입력 시간 및 Timing
• 제스처 해석 방식
• 메뉴 동작
• 특수 기능

#include "props/saber.h"

특정 하드웨어 또는 제품별 컨트롤 방식을 구현해야 하는 경우 Custom Prop을 직접 작성할 수도 있습니다.

13. Serial Monitor 디버깅

기존 매뉴얼에서는 다음과 같은 명령어를 일반적으로 사용합니다.

13.1 Serial 출력 활성화

#define ENABLE_SERIAL

13.2 일반적인 디버깅 정보

• 부팅 메시지
• SD 카드 감지 상태
• Blade 초기화 상태
• Preset 로딩 상태
• 모션 센서 상태
• 버튼 입력 이벤트

14. Blade Styles

Blade Style은 ProffieOS에서 Blade의 시각적 동작을 정의하는 핵심 메커니즘입니다. 색상, 애니메이션, Ignition, Retraction, Clash 반응, Blaster 효과, Lockup, Drag, Transition 및 기타 인터랙티브 효과를 제어할 수 있습니다.

14.1 기본 Style 예제

StyleNormalPtr<RED>()

기본 Style은 Blade의 기본적인 외관을 정의합니다. 보다 고급 Configuration에서는 중첩된 Style 함수와 Effect Layer를 조합하여 복잡한 애니메이션을 구현할 수 있습니다.

14.2 StylePtr 구조

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

StylePtr은 완성된 Blade Style을 할당할 때 일반적으로 사용됩니다. 복잡한 효과는 여러 Function, Layer 및 Transition을 조합하여 구현합니다.

14.3 RGB 색상

Rgb<255, 50, 0>

RGB 각 채널의 값은 0에서 255 사이입니다. 지원되는 경우 RED, GREEN, BLUE, WHITE, CYAN과 같은 이름이 지정된 색상도 사용할 수 있습니다.

14.4 주요 Effect Function

14.5 고급 Style 구성

고급 사용자는 Function, Layer, Transition 및 Random Effect를 조합하여 완전히 커스터마이징된 Blade 동작을 구현할 수 있습니다.

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

14.6 여러 Blade 및 Accent Pixel

하나의 Preset에는 여러 개의 논리적 Blade 정의에 대응하는 복수의 Blade Style을 구성할 수 있습니다. 이를 통해 Main Blade, Quillon, Crystal Chamber, Accent Strip 또는 기타 설정된 Pixel Group에 각각 독립적인 Style을 적용할 수 있습니다.

14.7 Style 편집 리소스

• ProffieOS Homepage - 참고: SUPERNEOX 라이트세이버에서는 ProffieOS 5.9를 사용하십시오.
• SD Configuration File
• ProffieOS Documentation
• The Crucible Support Forum
• Fett263 Style Resources
• Blade Configuration Documentation

15. 고급 통합

15.1 디스플레이

지원되는 디스플레이 모듈을 사용하면 다음과 같은 정보를 표시할 수 있습니다:

• 배터리 정보
• Preset 선택
• 메뉴 탐색
• 런타임 상태

15.2 추가 주변 장치

고급 하드웨어 구성에서는 다음과 같은 장치를 통합할 수 있습니다:

• Accent LED
• Crystal Chamber
• Crossguard Lighting
• Custom Sensor
• External Controller

15.3 제품 개발 및 생산 워크플로 권장 사항

16. 문제 해결

17. 개발자 레퍼런스

• 공식 설치 가이드
• ProffieOS GitHub Repository
• V2 Board Configuration Source
• ProffieOS 공식 페이지
• ProffieOS.ino / CONFIG_FILE Entry Point