ADB 연결
Android 디바이스를 ADB로 Aurora에 연결하는 방법 — USB·Wi-Fi·디바이스 별칭·트러블슈팅 정리.
Android 명령어는 ADB(Android Debug Bridge) 로 연결된 디바이스에서 동작합니다. 이 페이지는 디바이스 준비부터 Aurora가 인식하기까지의 전 과정을 정리합니다.
ADB가 디바이스를 인식하지 못하면 Touch in Android 같은 모든 Android 명령어가 실패합니다. 명령어를 사용하기 전에 이 페이지의 절차를 한 번씩 점검하세요.
사전 준비
연결 전에 디바이스에서 다음 두 가지를 활성화해야 합니다.
1. 개발자 옵션 활성화
- 설정 → 휴대전화 정보 → 빌드 번호 를 7번 연속 탭
- "개발자가 되었습니다" 메시지 확인
2. USB 디버깅 활성화
- 설정 → 시스템 → 개발자 옵션 진입
- USB 디버깅 토글 ON
- (Wi-Fi 연결 시) 무선 디버깅(Wireless debugging) 도 ON
무선 디버깅은 Android 11 이상에서 지원됩니다. 이전 버전은 USB 연결 후 adb tcpip 명령으로 전환해야 합니다.
USB 연결
가장 간단하고 안정적인 방법입니다.
- USB 케이블로 PC와 디바이스 연결
- 디바이스 화면에 "USB 디버깅을 허용하시겠습니까?" 팝업 → 항상 허용 체크 후 확인
- 연결 확인:
adb devices
device 상태로 표시되면 성공입니다.
List of devices attached
3a8c91e2 device
unauthorized 로 나오면 디바이스 화면의 디버깅 허용 팝업을 못 본 것입니다. 케이블을 뽑았다 다시 연결하면 팝업이 다시 뜹니다.
Wi-Fi(TCP/IP) 연결
USB 케이블 없이 같은 네트워크에서 연결하는 방법입니다.
Android 11 이상 — 무선 디버깅
- 디바이스 설정 → 개발자 옵션 → 무선 디버깅 진입
- 페어링 코드로 디바이스 페어링 선택 — 6자리 코드와
IP:포트표시 - PC 터미널에서:
adb pair <IP>:<페어링_포트>
# 6자리 페어링 코드 입력
adb connect <IP>:<디버깅_포트>
Android 10 이하 — adb tcpip
- USB 연결 상태에서:
adb tcpip 5555
adb connect <디바이스_IP>:5555
- USB 케이블 분리 후
adb devices로 무선 연결 상태 확인
같은 Wi-Fi 네트워크여도 회사·공용 Wi-Fi 는 디바이스 격리(client isolation) 정책으로 ADB가 막히는 경우가 있습니다. 가능하면 개인 라우터나 모바일 핫스팟을 사용하세요.
Aurora에서 디바이스 별칭 등록
모든 Android 명령어는 첫 번째 인자로 디바이스 별칭(Device alias) 을 받습니다. 이는 ADB 시리얼 번호에 사람이 알아보기 쉬운 이름을 매핑한 것입니다.
| ADB serial | 디바이스 별칭 예 |
|---|---|
3a8c91e2 | pixel-7 |
192.168.1.42:5555 | tablet-wifi |
명령어 실행 시 이 별칭으로 어떤 디바이스에 보낼지를 구분합니다.
Touch in Android (alias=pixel-7, x=540, y=1200)
별칭은 Aurora 프로젝트에 저장되므로, 같은 프로젝트를 다른 PC에서 열 때 별칭 매핑은 다시 등록해야 합니다. ADB 시리얼은 PC 환경별로 다르기 때문입니다.
연결 확인 체크리스트
명령어가 실패할 때 다음 순서로 점검합니다.
| 증상 | 확인 항목 | 해결 |
|---|---|---|
adb devices 에 안 뜸 | USB 케이블이 데이터 케이블인지 (충전 전용 ✗) | 다른 케이블로 교체 |
unauthorized | 디바이스 디버깅 허용 팝업 | 케이블 재연결 후 항상 허용 |
offline | ADB 데몬 충돌 | adb kill-server && adb start-server |
| Wi-Fi 연결 끊김 | 디바이스 슬립 / 네트워크 변경 | adb connect 재시도, 슬립 해제 |
| 명령어 좌표가 빗나감 | 화면 회전·해상도 변경 | resource-id / 텍스트 기반 명령으로 전환 |
| Accessibility Service 미동작 | 일부 키 입력·텍스트 조회 실패 | 디바이스의 Aurora Accessibility 권한 ON |
다음 단계
- 식별 방법별 명령어는 Android 명령어 개요의 입력 방식 표를 참고하세요.
- 좌표 의존을 줄이는 안정적인 방법은
Touch by resource-id in Android입니다. - 텍스트 라벨로 식별하려면
Touch by text in Android를 사용하세요.