문제 해결
자주 겪는 문제를 증상별로 해결합니다. 서버, 페어링, 오프라인이 되는 폰, 권한, 찾지 못하는 요소, 입력, 스크린샷, 설정 앱 레시피를 다룹니다.
번역된 페이지입니다. 영어 문서와 내용이 다르면 영어 문서가 기준입니다. English
문제를 살펴볼 때는 항상 이 두 명령부터 실행하세요. doctor는 설정을 점검하고, serve --verbose는 접속 시도를 일어나는 그대로 모두 보여 줍니다.
droidline doctor
droidline serve --verbose
아래에서 해당하는 증상을 찾으세요. 내 Wi-Fi를 벗어났을 때만 생기는 문제는 연결 문제 해결에 있습니다.
코드에서 서버가 실행 중이 아니라고 나올 때
SERVER_NOT_RUNNING(Python에서는 ServerNotRunningError)은 클라이언트 주소에서 아무것도 응답하지 않았다는 뜻입니다. 바꾸지 않았다면 이 주소는 127.0.0.1:8780입니다.
droidline serve를 실행하고 창을 열어 두세요. 창을 닫으면 서버가 멈춥니다.config.toml의client.listen을 바꿨다면,droidline명령은 0.1.9부터 그 주소를 따라가지만 SDK는 설정 파일을 읽지 않습니다. 스크립트에는DROIDLINE_PORT(필요하면DROIDLINE_HOST도)를 같은 주소로 지정하세요.- CLI의 에러는 시도한 주소를 함께 보여 줍니다. 예:
(nothing answered at 127.0.0.1:8780) droidline doctor는 시도한 주소와, 에이전트 포트가 비어 있는지를 보여 줍니다.
서버가 시작되지 않을 때
"address already in use" 같은 에러는 다른 프로그램이 Droidline의 포트 중 하나를 쓰고 있다는 뜻입니다. 포트는 폰용 8779, 내 코드용 8780, Wi-Fi 탐색용 8778입니다.
- 다른 창이나 서비스로
droidline serve가 이미 실행 중일 수 있습니다. 먼저 그것을 멈추세요. - 다른 포트를 쓰려면 config.toml에서
agent.listen,client.listen,discovery.listen을 바꾸세요. 폰은 다음에 페어링할 때 새 에이전트 포트를 알게 됩니다. - Windows에서는 아무 프로그램도 쓰지 않는데 포트를 못 여는 경우가 있습니다. Windows가 Hyper-V, WSL, Docker 등을 위해 포트 범위를 통째로 예약하기 때문입니다. 0.1.10부터
droidline doctor가 Droidline의 포트 세 개를 이 범위와 비교하고,config.toml에 넣을 빈 포트를 제안합니다. 예약 범위를 직접 보려면netsh interface ipv4 show excludedportrange protocol=tcp를 실행하세요(탐색 포트는protocol=udp).
폰이 PC를 찾지 못할 때
이 Wi-Fi에서 페어링을 누르면 "응답한 PC가 없습니다"가 나오거나, 페어링한 뒤에도 폰이 전혀 접속하지 않는 경우입니다.
-
두 기기가 같은 Wi-Fi 네트워크에 있는지 확인하세요. 게스트 네트워크와 일부 메시 시스템은 기기끼리 통신하지 못하게 막습니다. 기본 네트워크를 쓰세요.
-
Windows에서는 네트워크를 개인 네트워크로 설정하세요. 설정, 네트워크 및 인터넷, Wi-Fi, 사용 중인 네트워크, 네트워크 프로필 유형: 개인 네트워크 순서입니다. Windows는 공용 네트워크에서 들어오는 연결을 막습니다.
-
개인 네트워크에서
droidline이 방화벽을 통과하도록 허용하세요. 허용 여부를 묻는 창을 닫아 버렸다면 Windows 보안, 방화벽 및 네트워크 보호, 방화벽에서 앱 허용을 차례로 열고droidline의 개인에 체크하세요. 또는 관리자 권한 PowerShell에서 다음을 실행합니다.New-NetFirewallRule -DisplayName "Droidline" -Direction Inbound -Action Allow -Profile Private -Program "C:\Tools\droidline\droidline.exe" -
macOS에서는 시스템 설정, 네트워크, 방화벽, 옵션을 차례로 열고
droidline에 대해 들어오는 연결을 허용하세요. -
PC에서 VPN이 실행 중이면 로컬 네트워크에서 PC가 보이지 않을 수 있습니다. 페어링하는 동안 VPN을 잠시 멈추거나, PC 주소가 담긴 QR 코드로 페어링하세요.
-
6자리 코드 방식은 8778번 포트의 UDP 브로드캐스트로 PC를 찾습니다. 일부 공유기와 방화벽은 폰의 TCP 연결은 통과시키면서 이 브로드캐스트만 버립니다. 그러면 폰이 PC에 접속할 수는 있는데 PC를 찾지는 못합니다. QR 코드는 이 단계를 거치지 않습니다.
그래도 6자리 코드 방식이 안 되면 대개 QR 코드는 됩니다. droidline pair를 실행하고 QR 코드를 스캔하세요.
페어링이 실패할 때
- PC에서
PAIRING_FAILED가 나오면 그 코드로 기다리는 폰이 없다는 뜻입니다. 코드는 5분 뒤 만료됩니다. 이 Wi-Fi에서 페어링을 다시 눌러 새 코드를 받으세요. - QR 코드는 10분 동안 유효하고 폰 한 대만 페어링합니다. 다음 폰은
droidline pair를 다시 실행하세요. - 앱에 PC가 이 폰을 알아보지 못한다고 나오면,
droidline revoke로 폰이 제거됐거나 서버의 설정 폴더가 지워졌거나 옮겨진 것입니다. 다시 페어링하세요.
화면이 꺼지면 폰이 오프라인이 될 때
안드로이드와 많은 폰 제조사는 배터리를 아끼려고 백그라운드 앱을 멈춥니다. Droidline은 연결을 계속 열어 두어야 합니다.
-
Droidline의 설정 탭에서 배터리 최적화를 제한 없음으로 설정합니다.
-
제조사가 따로 두는 백그라운드 앱 설정을 찾아, 각각에서 Droidline을 허용합니다. 보통 다음과 같은 곳에 있습니다.
제조사 찾아볼 곳 Samsung 설정, 배터리, 백그라운드 사용 제한: 절전 앱과 초절전 앱에서 Droidline을 빼거나, 절전 예외 앱에 추가 Xiaomi, Redmi, POCO 앱 정보, Autostart 켜기, Battery saver: No restrictions OPPO, OnePlus, realme 앱 정보, 배터리 사용량, Allow background activity와 Allow auto launch vivo 설정, 배터리, Background power consumption management: Droidline 허용 Huawei, Honor 설정, 배터리, App launch: Droidline을 Manage manually로 바꾸고 스위치를 모두 켜기 메뉴 이름은 버전마다 다릅니다. 이름이 다르면 설정에서 "배터리"나 "백그라운드"로 검색하세요.
-
사람이 지켜보지 않는 폰이라면 계속 충전해 두세요.
앱의 상태 탭에 연결 상태와 사용 중인 경로가 나옵니다. 앱이 잠든 것인지 네트워크 문제인지 구분할 때 도움이 됩니다.
접근성 스위치가 회색으로 비활성화될 때
Android 13 이상에서는 파일로 설치한 앱은 제한된 설정을 허용하기 전까지 접근성을 쓸 수 없습니다.
- 설정, 앱, Droidline을 차례로 엽니다(또는 Droidline 앱의 설정 탭에서 앱 정보를 누릅니다).
- 오른쪽 위의 점 세 개 메뉴를 누르고 제한된 설정 허용을 고릅니다.
- 접근성 설정으로 돌아가 Droidline을 켭니다.
메뉴 항목이 없다면 먼저 접근성 설정을 한 번 열어 안드로이드가 시도를 기록하게 한 다음, 다시 찾아보세요.
접근성이 자꾸 저절로 꺼질 때
이때 명령은 NO_ACCESSIBILITY로 실패합니다. 일부 폰은 앱이 업데이트된 뒤, 앱이 비정상 종료된 뒤, 또는 절전 기능이 앱을 종료했을 때 접근성 서비스를 끕니다.
- 설정 탭에서 다시 켜세요.
- 위의 배터리 관련 단계를 적용하세요. 대부분은 이것으로 막을 수 있습니다.
- Droidline 앱 업데이트를 설치한 뒤에는 설정 탭을 한 번 확인하세요.
눈에 보이는 요소를 명령이 찾지 못할 때
요소가 화면에 있는데도 NOT_FOUND가 나오는 경우입니다. 요소 찾기의 점검 목록을 차례로 확인하세요. 흔한 원인은 다음과 같습니다.
- 텍스트가 조금 다릅니다. 대소문자, 끝에 붙은 공백, 다른 언어 등입니다. 값은
droidline dump에서 복사하세요. - 요소가 권한 대화상자 같은 시스템 창에 있습니다.
all_windows=True로 dump하세요. - 화면에 요소가 전혀 없습니다(게임, 지도, 캔버스로 그린 페이지). 좌표와 함께
tap을 쓰세요.
입력이 안 될 때
NO_IME: Droidline 키보드가 켜져 있지 않거나 선택되어 있지 않습니다. 설정 탭에서 켜고 선택하세요.- 텍스트는 들어가는데 앱이 반응하지 않습니다. 예를 들어 Enter를 기다리는 검색창입니다.
input다음에sendkey("enter")를 호출하세요. input이 남겨 두고 싶던 텍스트를 바꿔 버렸습니다.append=True를 넘기세요.
Android 9나 10에서 스크린샷이 실패할 때
Android 11 이전에는 스크린샷을 찍으려면 안드로이드의 화면 캡처 권한이 필요합니다. 처음 screenshot을 호출하면 폰에 확인 창이 뜹니다. 지금 시작을 누르세요. 누군가 허용하기 전까지 screenshot은 NO_PERMISSION으로 실패하고, droidline devices의 MISSING에 capture가 나옵니다.
설정 앱 레시피가 내 폰에서 동작하지 않을 때
강제 종료, 데이터 삭제, 네트워크 전환을 위한 설정 앱 레시피는 안드로이드 설정 앱의 버튼을 누릅니다. 설정 앱은 제조사, Android 버전, 언어마다 다릅니다. 레시피는 한국어로 설정한 삼성 폰에서 확인했습니다.
- 화면이 켜져 있고 잠금이 풀려 있는지 확인하세요. 먼저
wake()를 호출하세요. NOT_FOUND는 찾지 못한 이름을 알려 줍니다. 폰에서 같은 설정 화면을 열고dump나droidline inspect로 실제 이름을 본 뒤, 레시피의 패턴을 고치세요.- 확인 대화상자가 닫히지 않는다면: 레시피는 안드로이드 대화상자의 표준 확인 버튼인
android:id/button1을 누릅니다. 내 폰의 대화상자가 다른 버튼을 쓴다면 버튼의 텍스트로 고르세요. intent가BAD_ARGS로 실패한다면: 이 폰에는 그 액션을 처리하는 화면이 없거나, 다른 앱이 열 수 없는 화면입니다.clear_data가 권한device_owner와 함께NO_PERMISSION으로 답한다면: 기기 소유자 모드에서만 동작합니다. 이 모드가 아니면 설정 화면을 거치는 레시피를 쓰세요.
여러 폰이 온라인이고 명령이 실패할 때
DEVICE_AMBIGUOUS는 온라인인 폰이 둘 이상인데 명령이 어느 폰인지 지정하지 않았다는 뜻입니다. connect("shelf-01"), --device shelf-01, /devices/shelf-01/...로 폰을 지정하거나 DROIDLINE_DEVICE를 설정하세요.
명령이 AGENT_RESTARTED로 실패할 때
명령을 처리하는 도중에 폰의 Droidline 앱이 재시작돼서, 명령이 실행됐는지 Droidline이 알 수 없는 상태입니다. 화면을 확인한 다음, 다시 실행해도 안전한지 판단하세요. 재시작이 잦다면 대개 위의 배터리 설정이 원인입니다.
그래도 해결되지 않으면
GitHub에 이슈를 열어 주세요. droidline doctor 출력, 폰 모델과 Android 버전, 문제를 재현하는 가장 짧은 스크립트를 함께 적어 주세요. 토큰, 비밀번호, 개인 정보는 빼세요.