Openterface KeyMod란?
Openterface KeyMod는 TechXArtisan Studio에서 출시한 100% 오픈소스 USB + 블루투스 HID 에뮬레이터입니다. 핵심 기능은 스마트폰을 휴대용 키보드와 터치패드로 변환하는 것입니다. KeyMod를 대상 기기의 USB 포트에 꽂고, 스마트폰 앱(KeyCmd)을 통해 대상 컴퓨터, 광고용 디스플레이, 스마트 TV 또는 키오스크를 제어할 수 있습니다.
전용 펌웨어에 의존하는 상용 KVM 스위치와 달리, KeyMod는 하드웨어 회로도, PCB 설계, 펌웨어 소스 코드, 모바일 앱까지 모두 오픈소스로 제공됩니다. 이 프로젝트는 AGPL-3.0 소프트웨어 라이선스와 CERN-OHL-S-2.0 하드웨어 오픈소스 라이선스를 따르며, OSHWA 오픈소스 하드웨어 인증(UID CN000015)을 획득했습니다.
KeyMod는 Openterface 제품군에 속하며, 해당 제품군에는 다음 제품들도 포함됩니다:
| 제품 | 포지셔닝 | 오픈소스 저장소 Stars |
|---|---|---|
| Mini-KVM | 휴대용 BIOS 수준 KVM 제어 | 299(하드웨어) + 162(데스크톱) |
| KVM-GO | 강화된 휴대용 KVM | 21(하드웨어) |
| KeyMod 시리즈 | USB + BLE HID 키보드/터치패드 | 본 글의 주제 |
| uConsole KVM 확장 | uConsole 휴대용 KVM 확장 보드 | 5(하드웨어) |
제품 형태: Mini와 Plus 두 가지 버전
KeyMod는 동일한 핵심 기능을 공유하는 두 가지 하드웨어 버전으로 제공됩니다:
| 특성 | KeyMod Mini | KeyMod Plus |
|---|---|---|
| USB 인터페이스 | USB-C 수 커넥터 | USB-A 수 커넥터 + USB-C 암 포트 |
| 사용 시나리오 | 최신 기기(USB-C) | 레거시 기기 + 패스스루 충전 |
| 블루투스 | BLE HID | BLE HID |
| 스마트폰 연결 | USB / BLE | USB / BLE |
| 크기 | 초소형 EDC | 약간 더 큼, 패스스루 포트 포함 |
연결 흐름은 다음과 같습니다: 스마트폰(KeyCmd 앱) → KeyMod(USB 또는 블루투스) → 대상 기기. 대상 기기에는 어떤 소프트웨어도 설치할 필요가 없습니다. KeyMod는 진정한 하드웨어 수준의 HID 에뮬레이션입니다.
핵심 하드웨어 솔루션: CH32V208
KeyMod의 핵심 마스터 컨트롤 칩은 WCH CH32V208로, RISC-V 아키텍처 기반의 중국산 마이크로컨트롤러입니다. CH32V208은 CH9329 호환 프로토콜을 내장하여 USB HID 키보드/마우스 에뮬레이션을 직접 구현할 수 있으며, 대상 기기에 드라이버를 설치할 필요가 없습니다.
하드웨어 설계 하이라이트
┌─────────────────────────────────────────────┐
│ KeyMod PCB │
│ │
│ ┌──────────┐ ┌──────────┐ │
│ │ CH32V208 │ │ BLE 모듈 │ │
│ │ RISC-V │◄──►│ 블루투스 5.x │ │
│ │ MCU │ │ │ │
│ └────┬─────┘ └──────────┘ │
│ │ │
│ ┌────┴─────┐ │
│ │ USB │ → 대상 기기 연결(HID 키보드/마우스)│
│ │ 인터페이스│ │
│ └──────────┘ │
│ │
│ ┌──────────┐ │
│ │ 프로그래밍│ 프로그래밍 가능한 버튼 │
│ │ 가능한 │ (사용자 정의 매크로/전환) │
│ │ 버튼 │ │
│ └──────────┘ │
└─────────────────────────────────────────────┘
주요 하드웨어 구성 요소:
- 마스터 컨트롤 칩: CH32V208(RISC-V, CH9329 호환 프로토콜)
- 무선 연결: BLE 블루투스(HID 키보드/마우스)
- USB 인터페이스: Mini 버전 USB-C 수 커넥터 / Plus 버전 USB-A 수 커넥터 + USB-C 암 포트
- 프로그래밍 가능한 버튼: 사용자 정의 매크로 명령 및 구성 전환 지원
- 인증: CE, UKCA, RoHS, WEEE
왜 CH32V208을 선택했는가?
CH32V208은 일반적인 RP2040이나 ESP32 솔루션에 비해 몇 가지 독특한 장점이 있습니다:
- 네이티브 CH9329 프로토콜 호환: USB HID 디스크립터를 처음부터 구현할 필요 없이 즉시 사용 가능
- RISC-V 아키텍처: 오픈소스 명령어 세트로, 프로젝트의 오픈소스 철학과 일치
- 저비용: 중국산 칩으로, BOM 비용 통제 가능
- 저전력: 휴대용 EDC 기기에 적합
- 소형 패키지: 초소형 하드웨어 설계 구현에 유리
KeyCmd 앱: 기능이 풍부한 스마트폰 제어 단말기
KeyMod의 companion 앱은 KeyCmd라는 이름으로, Android와 iPadOS(iOS 포함)를 지원합니다. KeyCmd는 단순한 키보드/터치패드가 아니라, 기능이 풍부한 HID 제어 플랫폼입니다.
기능 매트릭스
| 기능 모듈 | 설명 |
|---|---|
| 키보드 & 마우스(기본) | 전체 화면 키보드 + 길게 눌러 반복 + 키 미리보기 + 숫자 키패드 |
| 키보드 & 마우스 Pro | 복합 레이아웃 + Shortcut Hub 단축키 바 + 분할 키보드 + IME 입력 |
| 프레젠테이션 모드 | 슬라이드 리모컨 + 타이머(Google Slides 등 지원) |
| 게임패드 | 가상 게임패드 + 사용자 정의 프리셋 레이아웃 + 멀티 터치 |
| Shortcut Hub | 프로필 기반 단축키(Blender, KiCAD, Photoshop, VS Code) |
| 매크로 명령 | 프로그래밍 가능한 키 시퀀스 + 딜레이 제어 |
| 음성 입력 | Whisper API 기반 음성-키보드 변환 |
| 터미널 | 블루투스 SSH 원격 명령 접근 |
| Agent | AI 기반 HID/SSH 명령 직접 제어 |
Shortcut Hub 상세
Shortcut Hub는 KeyCmd의 가장 특징적인 기능 중 하나입니다. 사용자가 다양한 전문 소프트웨어를 위한 단축키 구성 파일을 생성, 가져오기, 내보내기할 수 있게 해줍니다:
Shortcut Hub 구성 파일 예시
├── Blender.json # 3D 모델링 단축키
├── KiCAD.json # PCB 설계 단축키
├── Photoshop.json # 이미지 편집 단축키
├── VS Code.json # 코드 편집 단축키
└── Custom.json # 사용자 정의 구성
개발자가 자주 사용하는 도구를 위한 전용 구성을 만들고, 커뮤니티를 통해 공유할 수 있습니다.
Agent 모드: AI 기반 HID 제어
KeyCmd의 Agent 모드는 미래 지향적인 기능입니다. AI를 통해 HID 또는 SSH 명령을 직접 생성하여 대상 컴퓨터를 제어합니다. 즉, 자연어로 작업을 설명하면 AI가 이를 구체적인 키보드/마우스 입력 시퀀스로 변환합니다.
GitHub 저장소 구조
Openterface 프로젝트는 GitHub에서 다중 저장소 조직 방식을 채택하고 있으며, TechxArtisanStudio에서 관리합니다:
핵심 저장소 개요
| 저장소 | Stars | 내용 | 라이선스 |
|---|---|---|---|
| Openterface | 124 | 공식 웹사이트(GitHub Pages) | — |
| Openterface_Mini-KVM_Hardware | 299 | 하드웨어 설계, 회로도, BOM | CERN-OHL-S-2.0 |
| Openterface_QT | 162 | Windows/Linux 데스크톱 | AGPL-3.0 |
| Openterface_MacOS | 62 | macOS 데스크톱 | AGPL-3.0 |
| Openterface_Android | 39 | Android 앱 | AGPL-3.0 |
| Openterface_WebExtension | 6 | Chrome/Firefox 브라우저 확장 | AGPL-3.0 |
| Openterface_KVM-GO_Hardware | 21 | KVM-GO 하드웨어 설계 | CERN-OHL-S-2.0 |
| Openterface_KVM_Ext_Hardware | 5 | uConsole KVM 확장 보드 하드웨어 | CERN-OHL-S-2.0 |
저장소 디렉토리 구조(Mini-KVM Hardware 예시)
Openterface_Mini-KVM_Hardware/
├── docs/ # 하드웨어 문서
├── hardware/ # KiCad PCB 설계 파일
│ ├── schematics/ # 회로도
│ ├── pcb/ # PCB 레이아웃
│ └── gerber/ # 생산 파일
├── models/ # 3D 모델(외관)
├── part/ # 부품 자료
├── LICENSE # CERN-OHL-S-2.0
└── README.md
데스크톱 코드 구조(Openterface_QT)
Openterface_QT/
├── CMakeLists.txt # CMake 빌드 구성
├── src/
│ ├── main.cpp # 진입점
│ ├──mainwindow.cpp # 메인 윈도우
│ ├── video/ # HDMI 비디오 캡처
│ ├── hid/ # USB HID 통신
│ └── ui/ # Qt UI 컴포넌트
├── packaging/ # 데스크톱 통합 파일
└── docs/
└── BUILD.md # 빌드 가이드
오픈소스 라이선스 해설
Openterface는 이중 라이선스 전략을 채택하고 있습니다:
소프트웨어: AGPL-3.0
모든 소프트웨어 코드(데스크톱, Android, 펌웨어)는 GNU Affero General Public License v3.0을 사용합니다:
- 자유롭게 사용 가능: 개인 및 상업적 사용 모두 가능
- 수정 시 오픈소스 필수: 파생 저작물은 동일한 라이선스로 배포해야 함
- 네트워크 사용 조항: 네트워크를 통한 서비스 제공(SaaS)의 경우에도 소스 코드를 공개해야 함
- 적합 시나리오: 커뮤니티의 개선이 프로젝트에 환원되도록 보장
하드웨어: CERN-OHL-S-2.0
하드웨어 설계 파일은 CERN Open Hardware License — Strongly Reciprocal을 사용합니다:
- 자유롭게 제작 가능: 설계 파일을 기반으로 PCB를 직접 생산할 수 있음
- 수정 및 배포 가능: 수정된 설계는 동일한 라이선스로 배포해야 함
- 상업적 사용 가능: 오픈소스 설계를 기반으로 제품을 판매할 수 있음
- 문서화 필수: 원본 설계 파일과 수정 사항을 첨부해야 함
실전: 소스 코드로 데스크톱 빌드하기
Openterface_QT(Windows/Linux 데스크톱)를 예시로, 소스 코드에서 빌드하는 방법을 보여줍니다:
환경 준비(Ubuntu/Debian)
# 의존성 설치
sudo apt install cmake build-essential qt6-base-dev \
qt6-multimedia-dev libusb-1.0-0-dev libfftw3-dev
# 저장소 클론
git clone https://github.com/TechxArtisanStudio/Openterface_QT.git
cd Openterface_QT
컴파일 단계
mkdir build && cd build
cmake .. \
-DCMAKE_BUILD_TYPE=Release \
-DUSE_SHARED_FFMPEG=ON
make -j$(nproc)
Fedora 주의사항
Fedora에서 컴파일할 때는 FFmpeg 공유 라이브러리 경로 문제에 주의해야 합니다. BUILD.md의 해결 방법을 참조하세요:
cmake .. -DFFMPEG_PREFIX=/usr/local/ffmpeg
일반적인 문제
| 문제 | 해결 방법 |
|---|---|
undefined symbol: vaMapBuffer2 |
시스템 FFmpeg와 번들 VA 라이브러리를 혼용하지 마세요 |
| CMake은 성공했으나 바이너리가 없음 | 추가로 make를 실행해야 합니다 |
| 데스크톱 카테고리 오류 | Categories=Utility;를 사용하세요 |
사용 시나리오 실전
시나리오 1: 야외 광고판 유지보수
야외 LED 광고판은 현장 구성이 필요한 경우가 많지만, 키보드를 휴대하기는 불편합니다:
1. KeyMod Mini를 광고판의 USB-C 포트에 꽂습니다
2. 스마트폰에서 KeyCmd를 실행하고 BLE로 KeyMod와 연결합니다
3. 스마트폰 화면 키보드로 구성 명령을 입력합니다
4. 유지보수 완료 후 KeyMod를 뽑습니다
시나리오 2: 키오스크 디버깅
1. KeyMod Plus를 키오스크의 USB-A 포트에 꽂습니다
2. 스마트폰을 USB로 KeyMod와 연결합니다(더 안정적)
3. Shortcut Hub로 키오스크 전용 구성을 로드합니다
4. 디버깅 명령을 빠르게 입력합니다
시나리오 3: 개발자 워크플로우 가속
1. KeyMod를 개발 머신에 꽂습니다
2. KeyCmd에서 VS Code Shortcut Hub 구성을 로드합니다
3. 매크로 명령으로 반복 작업을 빠르게 실행합니다
4. Agent 모드로 자연어를 사용해 복잡한 작업을 수행합니다
기여 방법
Openterface는 활발한 오픈소스 커뮤니티이며, 모든 형태의 기여를 환영합니다:
Issue 제출
- 버그 리포트: 문제 설명, 재현 단계, 펌웨어 버전
- 기능 제안: 사용 시나리오와 기대 동작 설명
- 하드웨어 문제: 해당 저장소의 Issue 라벨 사용
Pull Request 제출
# 1. 저장소 Fork
# 2. 기능 브랜치 생성
git checkout -b feature/your-feature
# 3. 개발 및 테스트
# 4. main 브랜치로 PR 제출
문서 개선
문서 저장소 Openterface/Openterface는 MkDocs로 구축되었으며, 다국어(중국어, 영어, 일본어, 한국어, 프랑스어, 독일어, 이탈리아어, 포르투갈어, 루마니아어)를 지원합니다. 번역 PR을 매우 환영합니다.
커뮤니티 채널
- Discord: openterface.com/discord — 실시간 소통
- GitHub Discussions: 기능 토론 및 기술 Q&A
- 포럼: openterface.com/forum — 장기 토론
- YouTube: TechxArtisan — 제품 데모 및 튜토리얼
다른 오픈소스 HID 솔루션과의 비교
| 특성 | Openterface KeyMod | TinyUSB HID | Arduino HID | BluePill HID |
|---|---|---|---|---|
| 마스터 컨트롤 | CH32V208 (RISC-V) | 멀티 플랫폼 | AVR/ARM | STM32F103 |
| 블루투스 | ✅ BLE | ❌ 외부 모듈 필요 | ❌ 외부 모듈 필요 | ❌ 외부 모듈 필요 |
| 스마트폰 앱 | ✅ KeyCmd | ❌ 직접 개발 | ❌ 직접 개발 | ❌ 직접 개발 |
| 오픈소스 하드웨어 | ✅ CERN-OHL | ❌ 펌웨어만 | ❌ 펌웨어만 | ✅ 부분적 |
| 플러그 앤 플레이 | ✅ 드라이버 불필요 | ✅ 드라이버 불필요 | ✅ 드라이버 불필요 | ✅ 드라이버 불필요 |
| 제품화 수준 | 양산 제품 | 개발 프레임워크 | 개발 프레임워크 | DIY 솔루션 |
| AI 통합 | ✅ Agent 모드 | ❌ | ❌ | ❌ |
자주 묻는 질문
KeyMod와 전통적 KVM 스위치의 차이점은 무엇입니까?
전통적 KVM 스위치는 여러 컴퓨터 간에 하나의 키보드/마우스/모니터를 전환하는 데 사용됩니다. KeyMod의 포지셔닝은 다릅니다. 스마트폰을 키보드와 터치패드로 변환하여, 입력 장치가 없는 단일 대상 기기를 제어하는 데 사용됩니다. 야외 광고판, 키오스크, 스마트 TV 등의 시나리오에 적합합니다.
KeyMod는 대상 기기에 소프트웨어 설치가 필요합니까?
아니요. KeyMod는 진정한 하드웨어 수준의 HID 에뮬레이션으로, 대상 기기가 표준 USB 키보드와 마우스로 인식합니다. 어떤 드라이버나 소프트웨어도 필요하지 않습니다.
KeyMod를 직접 제작할 수 있습니까?
네. 하드웨어 설계 파일이 CERN-OHL-S-2.0 라이선스로 오픈소스 제공되므로, Gerber 파일을 다운로드하여 PCB를 직접 생산하고, BOM에 따라 부품을 조달하여 조립할 수 있습니다.
KeyCmd 앱은 어떤 플랫폼을 지원합니까?
현재 Android와 iPadOS(iOS)를 지원합니다. 데스크톱 버전(Windows/macOS)은 Openterface 생태계에 이미 QT 및 macOS 네이티브 앱이 존재합니다.
오픈소스 라이선스가 상업적 사용에 어떤 제한을 둡니까?
소프트웨어는 AGPL-3.0을 사용하며, 상업적 사용은 가능하지만 수정된 코드는 오픈소스로 공개해야 합니다. 하드웨어는 CERN-OHL-S-2.0을 사용하며, 오픈소스 설계를 기반으로 제품을 생산하고 판매할 수 있지만, 수정된 설계 역시 오픈소스로 공개해야 합니다.
요약
Openterface KeyMod는 오픈소스 하드웨어와 소프트웨어의 협업 개발 모범 사례를 보여줍니다:
- 100% 오픈소스: 하드웨어 설계, 펌웨어, 앱 모두 공개, OSHWA 인증 획득
- 실용적 도구: 야외 기기 유지보수, 키오스크 디버깅, 워크플로우 가속 등 실제 시나리오 해결
- 기술적先进性: CH32V208 RISC-V 마스터 컨트롤 + BLE + AI Agent 모드
- 활발한 커뮤니티: 다중 저장소 협업, 다국어 문서, Discord 실시간 소통
RISC-V 임베디드 개발을 배우고 싶든, USB HID 프로토콜을 이해하고 싶든, 실용적인 휴대용 입력 도구가 필요하든, Openterface KeyMod는 깊이 주목할 만한 가치가 있습니다.
관련 링크: - GitHub 조직: github.com/TechxArtisanStudio - 공식 문서: docs.openterface.com/products/keymod - 공식 웹사이트: openterface.com - Discord 커뮤니티: openterface.com/discord - 관련 튜토리얼: Openterface Mini-KVM 심층 분석