ADB / Android Debug Bridge
Macro Deck에 포함USB나 Wi-Fi로 Android 스마트폰이나 태블릿을 제어하세요. 화면 깨우기, 앱 시작, 탭, 입력, 스크린샷까지.
설정에서 ADB를 켜라는 알림이 있는 ADB / Android Debug Bridge 연동의 개요 탭
- 연결된 Android 기기 깨우기, 잠그기, 다시 시작
- 기기에서 앱 시작 또는 강제 종료, 링크 열기
- 키, 탭, 스와이프, 텍스트 보내기
- 기기 화면의 스크린샷을 폴더에 저장
- 배터리, 화면, 포그라운드 앱에 대한 기기 이벤트와 변수
ADB 연동은 Android 개발자가 쓰는 것과 같은 도구인 Android Debug Bridge(ADB)로 Android 스마트폰과 태블릿을 제어합니다. Macro Deck은 adb 프로그램을 찾아 ADB 서버를 실행하고, USB로 연결되었거나 Wi-Fi로 연결된 기기를 추적합니다. 공식 Android platform-tools를 대신 내려받을 수도 있습니다.
모든 액션은 액션에서 고른 기기에서 동작하며, 기기를 비워 두면 기본 기기에서 동작합니다. 기본 기기는 설정 > ADB에서 기본값으로 설정으로 고른 기기이며, 아무것도 고르지 않았다면 연결된 유일한 기기입니다.
할 수 있는 일
- 화면과 전원: 기기를 깨우거나, 화면을 끄거나(Android는 이렇게 기기를 잠급니다), Android, 복구 모드, 부트로더로 다시 시작합니다.
- 앱과 링크:
com.spotify.music같은 패키지 이름으로 앱을 시작하거나 강제 종료하고, 기기가 고르는 앱으로 링크를 엽니다. - 입력: Home, Back, Volume Up, Media Play Pause 같은 키를 보내고, 화면의 한 지점을 탭하고, 한 지점에서 다른 지점으로 스와이프하고, 포커스된 필드에 텍스트를 입력합니다.
- 스크린샷: 화면을 컴퓨터의 폴더에 PNG 파일로 캡처하며, 파일 경로를 변수에 쓸 수도 있습니다.
활용 예:
- 책상 위 태블릿을 깨우고 음악 앱을 시작하는 버튼.
- 스마트폰에 Media Play Pause를 보내는 버튼.
- 태블릿을 연결하자마자 대시보드 페이지를 여는 기기 연결됨 자동화.
실시간 상태
이 연동은 기기가 연결되거나, 연결이 해제되거나, 인증되거나, 인증이 해제되거나, 오프라인이 되거나, 다시 온라인이 될 때 알려 주므로 흐름과 버튼이 반응할 수 있습니다. 변수에는 연결된 기기 수와 인증된 기기 수, 그리고 기본 기기의 모델, 제조사, 배터리 수준, 화면이 켜져 있는지, 잠금 화면이 표시되는지, 어떤 앱이 맨 앞에 있는지가 담깁니다. 인증된 각 기기도 모델 이름을 딴 고유한 변수를 가집니다. 연동이 켜져 있는 동안에는 각 Android 기기의 배터리가 배터리 위젯에도 나타납니다.
기본 액션(키, 탭, 스와이프, 텍스트, 앱, 링크, 다시 시작, 스크린샷)은 Macro Deck이 잠겨 있는 동안에도 동작하므로, 이런 액션을 지정한 버튼은 컴퓨터가 잠겨 있어도 동작합니다.
준비물
- Windows, macOS 또는 Linux의 Macro Deck 3
- Developer options에서 USB debugging을 켠 Android 기기
- 데이터 전송이 되는 USB 케이블, 또는 Wi-Fi 연결을 위한 무선 디버깅
- Android platform-tools(adb). Macro Deck이 설정 > ADB에서 내려받을 수 있음
- Linux에서는 사용자가 USB 기기에 접근할 수 있는 권한, 보통 udev 규칙으로 부여
설정하기
1단계: ADB 연동 켜기
사이드바에서 연동을 클릭한 다음 ADB / Android Debug Bridge를 클릭하세요. 오른쪽 위의 스위치를 켜기 전까지는 연동이 꺼져 있습니다. 연동을 켜면 다음 단계에서 ADB를 켤 때까지 페이지에 ADB가 꺼져 있습니다가 표시됩니다.
2단계: Macro Deck에서 ADB 사용
설정 > ADB를 열고 ADB 사용을 켜세요. ADB 프로그램에 찾을 수 없음이 표시되면 platform-tools 다운로드를 클릭하세요. 기존 Android SDK나
PATH에 있는adb는 자동으로 찾으며, 실행 파일 경로로 다른 위치를 지정할 수 있습니다.3단계: 기기에서 USB 디버깅 켜기
스마트폰이나 태블릿에서 Settings > About phone을 열고 Build number를 일곱 번 탭해 Developer options를 켜세요. 그런 다음 Settings > Developer options에서 USB debugging을 켜세요. 정확한 위치는 제조사마다 조금씩 다릅니다.
4단계: 기기 연결 및 인증
USB 케이블로 기기를 연결하고 기기 화면에서 **Allow USB debugging?**을 확인하세요. 다시 묻지 않도록 Always allow from this computer를 체크하세요. 그러면 기기가 설정 > ADB의 기기 아래에 준비됨으로 나타납니다. Wi-Fi로 연결하려면 Wi-Fi로 연결에 기기의 IP 주소와 포트를 입력하세요. 예:
192.168.1.20:5555.5단계: 기본 기기 고르기
기기가 여러 대 연결되어 있다면, 기기를 비워 두었을 때 액션이 사용할 기기 옆의 기본값으로 설정을 클릭하세요. 기기가 하나뿐이면 자동으로 사용됩니다.
6단계: 버튼에 ADB 액션 추가
덱 페이지에서 덱의 잠금이 해제되어 있는지 확인하고(오른쪽 위 버튼에 잠금이라고 표시됨) 버튼을 클릭하세요. 짧게 누르기가 선택된 상태로 편집기가 열립니다. + 액션 추가를 클릭하고 액션 추가 대화 상자 왼쪽에서 ADB / Android Debug Bridge를 선택한 다음 액션을 고르세요. 예: 기기 깨우기, 앱 시작. 앱 시작의 패키지 같은 필드를 채우고, 기본 기기를 사용하려면 기기를 비워 두세요. 이 카테고리는 연동이 켜져 있을 때만 나타납니다.
7단계: 버튼 누르기
저장을 클릭하고 덱에서 버튼을 누르세요. 아무 일도 일어나지 않으면 연동에 연결된 기기가 없습니다나 인증이 필요한 기기 같은 알림이 있는지 확인하세요.
액션11
버튼에 넣거나 흐름에서 실행하세요.
- 기기 깨우기
- 기기 화면을 깨웁니다.
- 절전 / 화면 잠금
- 기기 화면을 끕니다. Android는 이렇게 기기를 잠급니다.
- 앱 시작
- 패키지 이름으로 앱을 실행하거나 앞으로 가져옵니다.
- 앱 강제 종료
- 패키지 이름으로 앱을 강제 종료합니다.
- 링크 열기
- 링크를 탭한 것처럼 기기에서 URI를 엽니다.
- 텍스트 입력
- 기기에서 현재 포커스된 필드에 텍스트를 입력합니다.
- 키 보내기
- Home, Back, Volume Up, Media Next 같은 Android 키 이벤트 하나를 보냅니다.
- 탭
- 지정한 X, Y 좌표에서 화면을 탭합니다.
- 스와이프
- 정한 시간 동안 한 지점에서 다른 지점으로 화면을 스와이프합니다.
- 기기 다시 시작
- 기기를 일반, 복구 또는 부트로더 모드로 다시 시작합니다.
- 스크린샷 찍기
- 기기 화면을 캡처해 폴더에 PNG 파일로 저장하며, 경로를 변수에 쓸 수도 있습니다.
트리거6
버튼이나 흐름이 이 이벤트에 반응할 수 있습니다.
- 기기 연결됨
- Android 기기가 연결되었거나 Macro Deck이 처음 인식했습니다.
- 기기 연결 해제됨
- Android 기기의 연결이 해제되었거나 Macro Deck이 추적을 놓쳤습니다.
- 기기 인증됨
- 기기에서 인증 요청이 수락되었습니다.
- 기기 인증 해제됨
- 이전에 인증된 기기에서 인증 요청을 다시 수락해야 합니다.
- 기기 온라인 상태가 됨
- 인증된 기기에 다시 접속할 수 있게 되었습니다.
- 기기 오프라인 상태가 됨
- 접속할 수 있던 기기에 더 이상 접속할 수 없습니다.
변수11
버튼과 위젯에 이 값을 표시하거나 조건에 사용하세요.
adb_connected_device_count- 연결된 Android 기기의 수입니다.
adb_authorized_device_count- 온라인이며 인증된 기기의 수입니다.
adb_device_connected- 기본 기기가 연결되어 있는지 여부입니다.
adb_device_authorized- 기본 기기가 이 컴퓨터를 인증했는지 여부입니다.
adb_device_model- 기본 기기의 모델입니다.
adb_device_manufacturer- 기본 기기의 제조사입니다.
adb_device_battery_level- 기본 기기의 배터리 잔량(퍼센트)입니다.
adb_device_screen_on- 기본 기기의 화면이 켜져 있는지 여부입니다.
adb_device_locked- 기본 기기에 잠금 화면이 표시되어 있는지 여부입니다.
adb_device_foreground_app- 기본 기기에서 맨 앞에 있는 앱의 패키지 이름입니다.
adb_device_<device>_connected,adb_device_<device>_authorized,adb_device_<device>_model,adb_device_<device>_battery_level- 인증된 각 기기의 연결 여부, 인증 여부, 모델, 배터리 잔량입니다.
<device>는 기기 모델을 소문자, 숫자, 밑줄로 바꾼 이름이며, 같은 모델의 기기가 더 있으면_2,_3등이 붙습니다.
자주 묻는 질문
Android Studio나 Android SDK가 필요한가요?
아니요. Macro Deck에는 Android platform-tools의 adb 프로그램만 있으면 됩니다. 설정 > ADB에서 platform-tools 다운로드를 클릭하면 Macro Deck이 자체적으로 사용할 공식 패키지(약 15MB)를 Google에서 내려받습니다. 기존 설치는 자동으로 찾습니다.
Wi-Fi로 기기를 제어할 수 있나요?
네. 기기에서 무선 디버깅을 켜고 설정 > ADB의 Wi-Fi로 연결에 IP 주소와 포트를 입력하세요. Macro Deck은 직접 기기를 페어링하지 않습니다. Android 11 이상에서는 먼저 기기를 이 컴퓨터와 페어링하거나, USB로 연결한 상태에서 adb tcpip로 네트워크 디버깅으로 전환하세요. 그렇지 않으면 기기가 연결을 거부합니다.
기기를 찾을 수 없다며 액션이 실패하는 이유는 무엇인가요?
기기를 비워 두면 액션은 기본 기기를 사용합니다. 기본 기기를 고르지 않았고 기기가 여러 대 연결되어 있으면 기본 기기가 없으므로, 액션에서 기기를 고르거나 설정 > ADB에서 기본값으로 설정을 클릭하세요. 기기가 승인되지 않음이 아니라 준비됨으로 표시되는지도 확인하세요.
별도의 잠금 액션이 있나요?
아니요. Android에는 별도의 잠금 명령이 없습니다. 절전 / 화면 잠금은 화면을 끄며, 전원 버튼과 같은 방식으로 기기를 잠급니다.
ADB 연동이 ADB를 쓰는 다른 프로그램에 영향을 주나요?
Macro Deck은 일반 ADB 서버를 사용하므로 Android Studio 같은 프로그램과 서버를 공유합니다. 설정 > ADB의 ADB 서버 다시 시작은 그 프로그램들의 기기 연결도 잠시 끊습니다. Macro Deck 종료 시 ADB 서버 중지를 켜지 않으면 Macro Deck이 종료될 때 서버는 계속 실행됩니다.
기기에 "이 기기에 접근할 권한이 없습니다"가 표시되는 이유는 무엇인가요?
컴퓨터에 USB로 기기와 통신할 권한이 없습니다. Linux에서는 platform-tools udev 규칙을 설치하고, Windows에서는 기기 제조사의 USB 드라이버를 설치하세요.
