버튼 8 × 바인딩 가능한 제스처 2 = 16 슬롯. 펌웨어 0.9.4 · 설정 앱 0.15.0. 배선은 wiring.html을 보세요.
앱이 없어도 키패드는 동작합니다. 펌웨어만 올리면 평범한 USB HID 키보드/마우스이고, PC 앱은 키 편집·녹음·동기화할 때만 켭니다. 설정이 끝나면 꺼도 됩니다.
Pro Micro는 리셋 버튼이 없습니다. RST–GND를 빠르게 두 번 단락시켜
부트로더(8초)를 띄운 직후에 업로드하세요. 항상 compile --upload로
한 번에 올리세요(upload만 하면 예전 빌드가 올라갈 수 있습니다).
arduino-cli compile --upload --fqbn SparkFun:avr:promicro:cpu=16MHzatmega32U4 \
-p /dev/ttyACM0 firmware여기까지만 해도 키 8개가 Ctrl+Alt+Shift+1~8을 보냅니다. 앱은 선택입니다.
# 개발
python3 -m venv .venv && source .venv/bin/activate
python -m pip install -r requirements.txt
python main.py
# 배포용 단일 실행 파일 (Linux → releases/linux/macrokey)
./build_release.sh일반 사용은 PyInstaller GUI 실행 파일만 있으면 됩니다.
Wayland에서 녹음이 안 되면 첫 실행 안내에 따라 관리자 비밀번호로 input
권한을 한 번 허용하세요. 이 권한은 계정의 프로그램이 비밀번호를 포함한 모든 키보드·마우스
입력을 읽을 수 있으므로, macroKey는 빨간 녹화 표시가 켜진 동안에만 입력 장치를 엽니다.
포트가 안 보이면
sudo usermod -aG dialout $USER 후 재로그인.
| 제스처 | 동작 | 발화 시점 | 주로 넣는 것 |
|---|---|---|---|
| TAP | 짧게 눌렀다 뗌 | 뗄 때 즉시 | 기본 단축키 |
| DOUBLE | 250 ms 안에 두 번 | 두 번째 탭 | 되돌리기 어려운 동작 |
| HOLD | 3초 단독 유지 | 3초 도달 | 바인딩 불가 — 녹음 진입점 |
DOUBLE을 안 쓰는 키는 느려지지 않습니다. 해당 키의 DOUBLE 슬롯이 비어 있으면 TAP을 떼는 즉시 내보내고, 채워져 있을 때만 250 ms를 기다립니다. 자주 쓰는 키에는 DOUBLE을 비워 두세요.
HOLD에는 아무것도 바인딩할 수 없습니다. 키 하나를 단독으로 3초 누르는 것이 녹음을 여는 방법이기 때문입니다. 그래서 바인딩 가능한 슬롯은 키당 TAP · DOUBLE 두 개, 전부 16개입니다.
녹음은 패드에서 시작하고 끝냅니다. 키를 단독으로 3초 누르면 픽셀이 빨갛게 맥동하며 녹음이 시작되고, 같은 키를 다시 3초 누르면 저장됩니다. 탭한 뒤 곧바로 다시 눌러 3초 유지하면 DOUBLE 슬롯에 녹음되고 픽셀은 분홍입니다.
레이어와 코드(chord)는 제거되었습니다. 레이어는 보이지 않는 모드와 외워야 하는 진입 방법을 만들었고, 코드는 편집 수단이 없어 채울 방법이 없었습니다. 두 영역이 쓰던 EEPROM은 지금 매크로 레코드가 씁니다.
| 키 · 제스처 | 동작 |
|---|---|
| 1–8 TAP | ctrl+alt+shift+1 … 8 |
| 1–8 DOUBLE | 비어 있음 — 탭 후 250 ms 안에 다시 눌러 3초 홀드 |
미디어 키는 기본 빌드에서 나가지 않습니다. AVR 코어의 Keyboard에는
consumer page가 없어 펌웨어가 시리얼로 보고만 합니다. 쓰려면
arduino-cli lib install "HID-Project" 후 Config.h의
MK_USE_HID_PROJECT를 1로 바꿔 다시 올리세요.
python main.py 또는 배포 바이너리로 편집기를 엽니다.
키 8행 × 제스처 2열 격자로 16슬롯이 화면에 있습니다. 칸을 클릭 → 단축키를 누르거나
녹음. 연결 시 장치 프로필과 다르면 Pull / Push / Cancel을 묻습니다. Cancel 뒤에는
Sync needed가 계속 보이고, 어느 쪽이 이길지 정할 때까지 로컬 편집이 패드를 덮어쓰지
않습니다.
Save·Write 버튼은 없습니다. 편집이나 녹음이 끝나면 그 자리에서 저장되고 키패드에 기록됩니다. 단, 프로필 충돌을 Cancel한 동안은 로컬에만 저장합니다. Profile 메뉴에서 가져오기·내보내기·직전 버전 복구를 할 수 있습니다.
| Action | Value | 실행 | 예 |
|---|---|---|---|
| key | 단축키 문자열 | 장치 | ctrl+shift+p |
| consumer | 미디어 키 이름 | 장치 | volume_up |
| mouse_button | left · right · middle | 장치 | middle |
| mouse_wheel | up · down | 장치 | 현재 포인터에서 스크롤 |
| sequence | 매크로 슬롯 | 장치 | 녹음이 만듦 |
| none | — | — | 비우기 |
호스트 전용 액션(클립보드·셸·daemon)은 없습니다. 장치에 안 들어가면 저장이 거절됩니다.
단축키 문법 — 수식키를 +로 잇고 마지막에 일반 키 하나. 순서 무관.
ctrl(control) · alt(option) · shift ·
gui(win·cmd·super) · rctrl ralt rshift rgui(오른쪽).
미디어 키 이름 — volume_up volume_down mute play_pause stop
next_track prev_track brightness_up brightness_down
패드에서 직접 합니다. 키 하나를 단독으로 3초 누르면 녹음이 시작되고, 같은 키를 다시 3초 누르면 저장됩니다. 앱은 켜져 있어야 하지만(캡처는 PC가 합니다) 창을 볼 필요는 없습니다. 녹화 시작·종료 홀드는 그 키의 기본 바인딩을 실행하지 않습니다.
| 동작 | 들어가는 슬롯 | 픽셀 |
|---|---|---|
| 홀드 3초 | TAP | 빨강 맥동 |
| 탭 → 250 ms 안에 다시 눌러 홀드 3초 | DOUBLE | 분홍 맥동 |
| 저장 성공 | — | 초록 플래시 |
| 저장 실패·빈 캡처 | — | 빨강 플래시 |
캡처된 스텝은 창에 목록으로 뜨고 ~/.config/macrokey/macrokey.log에도 남습니다.
앱이 자동으로 정리합니다: 수식키 접기 · 지연 양자화 · 연속 문자 병합 · 패드 자신 HID 제외 ·
비밀번호로 보이는 구간 제거.
재생은 녹음보다 빠릅니다. 연속 타자는 text로 합쳐지고 패드의
Typing(글자당 ms) 속도로 칩니다. 값은 프로필에 저장되므로 앱을 꺼도 패드가
그 속도로 재생합니다.
마우스는 기본적으로 현재 포인터 기준으로 재생합니다. 단순 클릭·휠은 현재 위치에서,
이동·드래그는 현재 위치로부터 상대적으로 실행됩니다. 화면의 같은 좌표가 필요할 때만
실험 기능인 Fixed screen을 켜세요. 이 모드는 녹음과 재생 전에 패드 USB
마우스로 좌상단에 홈하지만, 모니터 배치·해상도·배율·포인터 속도/가속·창 위치가 같아야
합니다. 긴 이동은 짧은 시간 조각으로 저장해 가속 오차를 줄이지만 절대 좌표 HID는 아닙니다.
위험한 버튼을 누르는 고정 위치 매크로는 안전한 대상에서 먼저 시험하세요.
패드는 USB HID로 혼자 동작합니다. PC 앱은 편집·녹음·동기화용이며 끝나면 꺼도 됩니다.
배포 바이너리는 GUI만 포함합니다. 소스 트리에서는:
| 명령 | 하는 일 |
|---|---|
| python main.py | 편집기 (권장) |
| python -m macrokey ports | 시리얼 포트 목록 |
| python -m macrokey info | 장치 정보 · 동기화 여부 |
| python -m macrokey push / pull | 프로필 쓰기 · 읽기 |
| python -m macrokey monitor | 이벤트 실시간 출력 |
| python -m macrokey record --key N | CLI 녹음 |
| 상황 | 픽셀 |
|---|---|
| 키 탭 | 흰색 짧은 플래시 |
| 빈 슬롯 | 어두운 빨강 |
| 녹음 중 (TAP / DOUBLE) | 빨강 / 분홍 맥동 |
| 매크로(시퀀스) 실행 중 | 시안 펄스 |
| 매크로 완료 · 저장 성공 | 초록 플래시 |
| 앱 없음 / 녹음 거절 | 주황 또는 빨강 플래시 |
밝기는 툴바 슬라이더(0–255). AgentPet 상시 LED 연동은 제거되었습니다.
| 플랫폼 | 경로 |
|---|---|
| Linux | ~/.config/macrokey/ |
| macOS | ~/Library/Application Support/MaduinosMacroKey/ |
| Windows | %APPDATA%\MaduinosMacroKey\ |
profile.json(키맵 · 장치 매크로 · LED 색)과
settings.json. 저장할 때마다 직전 프로필을 권한 0600의
profile.json.bak로 남깁니다. 편집기의 Profile → Restore previous version으로
복구하거나, 장치 EEPROM에서 python -m macrokey pull --save로 되찾을 수 있습니다.
| 기능 | 현재 상태 |
|---|---|
| 호스트 액션 · 셸 · 클립보드 이미지 | 제거됨. 장치 HID만 |
| 미디어 키 (consumer) | MK_USE_HID_PROJECT=1로 다시 빌드해야 동작 |
| 마우스 이동 · 드래그 | 녹음으로만. 클릭·휠은 편집기에서 직접 지정 가능 |
| 절대 좌표 마우스 | 상대 마우스만. 선택형 좌상단 홈은 실험 기능 |
| PC 단축키로 매크로 실행 | 트리거는 패드뿐 |