﻿TiVo Touch 2.0 · 설치 및 자동 실행 설명서
TiVo Stream 4K · USB 0712:000a · Android 12 · 2026-10-24

먼저 manual.html을 브라우저에서 열면 목차와 명령 복사 버튼을 사용할 수 있습니다.

========================================================================
1. 배포본과 작동 방식
========================================================================

TiVo Stream 4K의 USB 터치 입력을 보완하는 배포본입니다. 최초 한 번 PC의 ADB로 APK와 보조 파일을 설치하고 승인하면, 이후 TiVo 부팅 시 자동으로 터치 드라이버를 실행합니다.

v2.0 APK만 별도로 설치하면 드라이버 파일이 복사되지 않습니다. 최초 설치에는 ZIP 전체와 아래 설치 절차를 사용하세요. 현재 작동하던 APK·드라이버를 그대로 묶었으며 이번 배포를 위해 APK를 새로 수정하지 않았습니다.

앱은 TiVo 안의 127.0.0.1:5555로 연결합니다. 앱 전용 키는 TiVo의 앱 비공개 저장소에서 생성하며, PC의 ADB 개인 키를 복사하지 않습니다. 부팅 수신기가 서비스를 시작하고, 서비스는 드라이버가 종료되면 약 30초 간격으로 재실행합니다. 연결 실패 시 약 3초 간격으로 재시도합니다.

커널 설정에서 HID 멀티터치가 비활성인 환경을 대상으로, USB 보고서를 읽어 uinput 터치스크린으로 전달합니다. 시스템 파티션 수정이나 루팅 없이 동작하며 PC의 시작프로그램 등록은 필요하지 않습니다.

========================================================================
2. 확인된 호환 범위
========================================================================

항목 | 확인된 환경
장치 / OS | TiVo Stream 4K / Android 12, API 31
커널 | 4.9.269-ab1272, CONFIG_INPUT_UINPUT=y
CPU | armeabi-v7a, 32비트 ARM 드라이버
터치 컨트롤러 | USB VID 0712 / PID 000a, hotlotus · normal Elan
화면 | 1920×1080 가로 화면
앱 | TiVo Touch 2.0 / local.tivo.touch / targetSdk 31 / minSdk 26
필수 접근 | ADB shell에서 /dev/uinput 쓰기와 USB 장치 접근이 가능한 펌웨어

한 손가락 탭, 길게 누르기, 드래그 및 가장자리 제스처를 지원합니다. 두 손가락 확대·축소는 지원하지 않습니다. 프로그램은 USB ID 0712:000a만 선택하므로 다른 터치 컨트롤러는 별도의 대응이 필요합니다. 같은 ID라도 보고서 형식이 다르면 추가 검증이 필요합니다.

USB 포트 번호를 고정하지 않고 장치 ID로 찾습니다. 분리 후 재연결을 감지하도록 구현했지만, 실제 포트 이동 및 케이블 분리·재연결 시험은 수행하지 않았습니다. 다른 Android 버전, 제조사, 보안 정책에 대한 호환성은 확인하지 않았습니다. 설치 스크립트는 확인된 모델·API·ABI와 /dev/uinput 접근을 먼저 검사합니다.

========================================================================
3. 준비물과 파일 구성
========================================================================

파일 / 준비물 | 용도
TiVo-Touch-2.0.apk | 부팅 수신기, 유지 서비스, 로컬 ADB 인증 및 터치 시험 화면
tivo-touch-bridge.jar | USB 터치 보고서 해석과 제스처 처리
libtivo_touch.so | 32비트 ARM용 가상 입력 장치 생성
start-touch.sh / stop-touch.sh | TiVo 내부 드라이버 시작 / 중지
Install-TiVoTouch.ps1 | 파일 검사, 설치, 설정, 로컬 키 승인 시도 및 실행 확인
SHA256SUMS.txt | 배포 파일의 SHA-256 목록
manual.html / README-ko.txt | 브라우저용 설명서 / 텍스트 설명서
Windows PC와 공식 Android SDK Platform-Tools | adb.exe 및 같은 폴더의 DLL이 필요하며 ZIP에는 포함하지 않음
TiVo 리모컨과 터치용 USB 데이터 케이블 | 최초 디버깅 승인 및 USB 터치 신호 연결

HDMI는 화면을 전달하며 터치 데이터는 USB로 전달됩니다. 모니터의 USB 터치 데이터 선을 TiVo의 USB 호스트에 연결하세요. PC와 TiVo는 최초 설정 때 같은 네트워크에 연결합니다. 이후의 터치 실행은 PC와 공유기 IP에 의존하지 않지만, TiVo의 로컬 ADB 5555 포트는 계속 활성화되어 있어야 합니다.

========================================================================
4. 개발자 옵션과 ADB 연결
========================================================================

TiVo 설정의 정보 화면에서 Android TV OS 빌드 항목을 여러 번 눌러 개발자 옵션을 활성화하고 USB 디버깅을 켭니다. 메뉴 이름과 위치는 펌웨어에 따라 다를 수 있습니다. 네트워크 설정에서 TiVo의 IP를 확인하세요. 이 설명서의 192.168.1.100은 예시이며 실제 주소로 바꿔야 합니다.

ZIP을 모두 압축 해제한 폴더에서 PowerShell을 엽니다. 아래 명령은 Windows PowerShell 문법입니다. CMD 창에 그대로 붙여 넣지 마세요. 일반 사용자 PowerShell에서 실행할 수 있습니다.

TiVo에 연결하고 승인 상태 확인
# ZIP을 압축 해제한 폴더에서 PowerShell을 엽니다.
$adb = "C:\platform-tools\adb.exe"       # 실제 adb.exe 위치로 변경
$tivo = "192.168.1.100:5555"             # 실제 TiVo IP로 변경
& $adb connect $tivo
& $adb devices -l
& $adb -s $tivo get-state
# 마지막 결과가 device여야 합니다.

TiVo 화면에 USB 디버깅 승인 창이 뜨면 리모컨으로 항상 허용을 선택하세요. 이 단계에서는 터치가 아직 작동하지 않을 수 있습니다. unauthorized이면 승인 후 다시 연결하고, offline이면 장치 및 네트워크 상태를 확인합니다.

5555 포트에 접속되지 않으면 개발자 옵션, USB 디버깅, 네트워크 및 펌웨어의 TCP ADB 지원을 확인해야 합니다. 이미 승인된 USB ADB 연결이 있을 때는 다음 명령으로 TCP ADB를 켤 수 있습니다. ADB 연결 자체가 전혀 없는 상태에서는 이 명령을 보낼 수 없습니다.

필요한 경우에만: 기존 USB ADB에서 TCP ADB 켜기
# 이미 USB ADB로 연결하고 디버깅을 승인한 장치에서만 가능한 명령입니다.
# USB_SERIAL은 adb devices -l에 표시된 해당 장치의 일련번호로 바꾸세요.
& $adb -s "USB_SERIAL" tcpip 5555
& $adb connect $tivo

========================================================================
5. 권장 설치: 스크립트 한 번 실행
========================================================================

파일만 먼저 검증하기
# ADB에 연결하지 않고 파일 5개의 SHA-256만 검증합니다.
powershell -NoProfile -ExecutionPolicy Bypass -File .\Install-TiVoTouch.ps1 -ValidateOnly

실제 설치
powershell -NoProfile -ExecutionPolicy Bypass -File .\Install-TiVoTouch.ps1 -Device $tivo -AdbPath $adb

설치 중 TiVo의 디버깅 승인 창이 다시 뜨면 앱 전용 연결에 대해 항상 허용을 선택하세요. 스크립트는 펌웨어가 허용하면 공개 키 자동 승인도 한 번 시도합니다. 자동 승인이 거부되면 리모컨으로 승인하면 됩니다. 기본 대기 시간은 120초이며, 승인하지 못하면 재실행하거나 설명서의 수동 명령을 사용할 수 있습니다.

스크립트는 파일 해시와 기기 환경을 확인하고, 변경 전 ADB 키 유효기간을 install-records 폴더에 저장합니다. APK 설치 뒤 앱과 기존 드라이버를 중지한 다음 보조 파일을 복사합니다. 기존 드라이버가 살아 있으면 .so 파일을 덮어쓰지 않고 중단합니다.

터치 드라이버 프로세스 실행 확인이라는 메시지가 나오면 TiVo Touch 화면에서 실제로 눌러 보고 드래그하세요. WAITING_FOR_USB는 드라이버가 해당 USB 장치를 기다리는 상태이며 터치 성공을 뜻하지 않습니다. 실제 터치가 확인되면 홈으로 돌아가 앱을 사용하면 됩니다. APK나 파일 서명 오류가 나면 기존 앱을 바로 삭제하지 말고 배포본 버전과 해시를 먼저 확인하세요.

========================================================================
6. 수동 설치용 ADB 명령
========================================================================

5번 스크립트 대신 직접 실행하려는 경우에만 사용합니다. 4번에서 $adb와 $tivo를 설정하고 연결을 승인한 상태여야 합니다. 각 단계가 성공했는지 확인한 뒤 다음 단계로 진행하세요. 업데이트할 때도 실행 중인 .so와 JAR를 먼저 덮어쓰면 안 됩니다.

6-1. APK 설치 후 기존 앱과 드라이버 중지
# ZIP을 압축 해제한 폴더에서 실행합니다. 각 명령이 실패하면 다음 단계로 진행하지 마세요.
& $adb -s $tivo install --no-streaming --no-incremental -r .\TiVo-Touch-2.0.apk
if ($LASTEXITCODE -ne 0) { throw "APK 설치 실패" }
& $adb -s $tivo shell am force-stop local.tivo.touch
if ($LASTEXITCODE -ne 0) { throw "앱 중지 실패" }
& $adb -s $tivo push .\stop-touch.sh /data/local/tmp/stop-touch.sh
if ($LASTEXITCODE -ne 0) { throw "중지 스크립트 복사 실패" }
& $adb -s $tivo shell sh /data/local/tmp/stop-touch.sh
if ($LASTEXITCODE -ne 0) { throw "기존 드라이버 중지 실패" }
& $adb -s $tivo shell pidof tivo-touch
if ($LASTEXITCODE -ne 1) { throw "중지 여부를 확인하지 못했습니다. 파일 복사를 중단합니다." }

6-2. TiVo에 보조 파일 복사
foreach ($file in @("tivo-touch-bridge.jar", "libtivo_touch.so", "start-touch.sh")) {
    & $adb -s $tivo push ".\$file" "/data/local/tmp/$file"
    if ($LASTEXITCODE -ne 0) { throw "파일 복사 실패: $file" }
}
& $adb -s $tivo push .\TiVo-Touch-2.0.apk /data/local/tmp/tivo-touch-auto-config.apk
if ($LASTEXITCODE -ne 0) { throw "설정 도우미 복사 실패" }

6-3. 키 만료 해제와 최초 앱 실행
# 변경 전 값을 메모합니다. null이면 별도 값이 설정되어 있지 않은 상태입니다.
& $adb -s $tivo shell settings get global adb_allowed_connection_time
# 승인된 ADB 키의 자동 만료를 해제합니다. 이 기기의 승인된 키 전체에 적용됩니다.
& $adb -s $tivo shell settings put global adb_allowed_connection_time 0
if ($LASTEXITCODE -ne 0) { throw "ADB 키 유효기간 설정 실패" }
# 최초 한 번 앱을 열어 부팅 시 자동 실행할 수 있는 상태로 만듭니다.
& $adb -s $tivo shell am start -W -n local.tivo.touch/.TouchActivity

TiVo에 뜨는 앱 전용 디버깅 승인 창에서 항상 허용을 선택합니다. PC의 기존 승인과 앱 자체의 로컬 ADB 승인은 별개입니다. 다음 도우미 명령은 해당 펌웨어가 허용하는 경우에만 성공합니다.

6-4. 선택 사항: 앱 전용 공개 키 승인 도우미
# 디버깅 승인 창에서 허용하기 어려울 때 선택적으로 시도할 수 있는 도우미입니다.
& $adb -s $tivo shell "CLASSPATH=/data/local/tmp/tivo-touch-auto-config.apk app_process /system/bin ConfigureTouchApp"
# 성공하면 DEDICATED_LOCAL_ADB_KEY_AUTHORIZED가 표시됩니다.
# 권한 오류가 나면 TiVo의 승인 창에서 리모컨으로 항상 허용을 선택하세요.

========================================================================
7. 시작프로그램 등록과 재부팅 확인
========================================================================

자동 실행에 필요한 부팅 수신기는 APK에 들어 있습니다. 보조 파일과 디버깅 승인을 마친 뒤 am start -n local.tivo.touch/.TouchActivity로 앱을 한 번 열면 됩니다. Windows 시작프로그램 폴더에 넣을 항목은 없습니다.

APK의 RECEIVE_BOOT_COMPLETED 선언과 BOOT_COMPLETED / LOCKED_BOOT_COMPLETED 수신기가 서비스를 시작합니다. am start는 최초 실행과 강제 중지 상태 해제에 사용합니다. 매번 재부팅할 때 이 명령을 보낼 필요는 없습니다. 앱을 강제 중지하거나 USB 디버깅을 끄거나 ADB 승인을 취소하면 자동 실행이 멈출 수 있습니다.

현재 실행 상태 읽기
& $adb -s $tivo shell pidof local.tivo.touch
& $adb -s $tivo shell pidof tivo-touch
& $adb -s $tivo shell tail -n 20 /data/local/tmp/tivo-touch.log
& $adb -s $tivo logcat -d -s TivoTouchBoot

TiVo를 실제 재부팅하고 자동 실행 검증
# 작업을 저장한 뒤 실행합니다. TiVo 자체가 재부팅됩니다.
& $adb -s $tivo reboot
# TiVo 화면에서 부팅 완료를 기다린 뒤, 아래 명령으로 상태만 읽습니다.
# IP가 바뀌었다면 $tivo 값을 바꾸세요.
& $adb connect $tivo
& $adb -s $tivo shell getprop sys.boot_completed
& $adb -s $tivo shell pidof local.tivo.touch
& $adb -s $tivo shell pidof tivo-touch
# start-touch.sh 또는 TiVo Touch 실행 명령 없이 실제 손가락으로 터치해 보세요.

sys.boot_completed가 1이고 local.tivo.touch와 tivo-touch의 PID가 표시되는지 확인합니다. 가장 중요한 확인은 PC에서 시작 명령을 보내지 않은 상태로 실제 화면을 누르고 드래그하는 것입니다. 재부팅 뒤 5555 포트가 꺼지는 다른 펌웨어라면 현재 방식의 자동 실행은 보장되지 않습니다.

========================================================================
8. 일상 사용과 제스처
========================================================================

동작 | 사용법
일반 터치 | 한 번 누르기, 길게 누르기, 한 손가락 드래그
뒤로가기 | 왼쪽 또는 오른쪽 끝 약 20px 안에서 시작해 안쪽으로 약 100px 밀고 손 떼기
홈 | 화면 아래 끝 약 20px 안에서 시작해 위로 약 100px 밀고 손 떼기
일반 스크롤 | 가장자리를 벗어난 화면 안쪽에서 드래그 시작
확대·축소 | 두 손가락 멀티터치는 미지원. 앱의 확대·축소 버튼 사용

위 픽셀 값은 검증한 1920×1080 화면 기준의 근사값입니다. 제스처는 1.5초 안에 완료해야 합니다. 화면 가운데에서 시작한 드래그를 그대로 앱에 전달하며, 가장자리 탭이나 다른 방향의 드래그는 일반 입력으로 넘깁니다. 뒤로/홈 동작은 Android 키 입력이므로 사용 중인 앱을 벗어날 수 있습니다.

========================================================================
9. 문제 해결
========================================================================

증상 | 확인 및 조치
APK만 설치했는데 터치가 안 됨 | v2.0은 보조 파일 설치도 필요합니다. ZIP의 설치 스크립트나 6번 전체 절차를 실행하세요.
연결 대기 / Connection refused | USB 디버깅 및 TiVo의 127.0.0.1:5555 ADB 사용 가능 여부 확인. 로그에서 원인 확인.
unauthorized / authentication 오류 | PC와 앱 전용 승인을 각각 확인하고 리모컨으로 항상 허용. 승인 취소나 앱 데이터 삭제 후에는 재승인 필요.
WAITING_FOR_USB 0712:000a | 터치 데이터 USB 선과 컨트롤러 ID 확인. 다른 VID/PID의 장치는 현재 드라이버 대상이 아닙니다.
Permission denied / /dev/uinput 오류 | 펌웨어의 ADB shell 권한과 SELinux 정책이 확인 환경과 다를 수 있습니다. 임의의 chmod나 SELinux 해제로 해결하려고 진행하지 마세요.
재부팅하면 터치만 안 됨 | 앱 강제 중지 여부, 부팅 후 ADB 5555 유지 여부, 승인 키 유효기간, 앱/드라이버 PID 및 TivoTouchBoot 로그 확인.
INSTALL_FAILED_UPDATE_INCOMPATIBLE | 설치된 앱과 서명 키가 다릅니다. 같은 서명의 APK를 사용하세요. 삭제 후 재설치는 앱 전용 키도 바뀌므로 재승인 필요.
드라이버 파일이 사라짐 | /data/local/tmp가 정리되거나 초기화되면 파일 복사가 다시 필요합니다. 이 APK에는 자동 재복사 기능이 없습니다.

진단에 사용할 상태 및 로그 명령
& $adb -s $tivo shell pidof local.tivo.touch
& $adb -s $tivo shell pidof tivo-touch
& $adb -s $tivo shell tail -n 20 /data/local/tmp/tivo-touch.log
& $adb -s $tivo logcat -d -s TivoTouchBoot

========================================================================
10. 자동 실행 중지, 재개, APK 삭제
========================================================================

중지는 자동 실행 앱을 먼저 강제 중지하고, 다음으로 터치 드라이버를 중지하는 순서입니다. 드라이버만 중지하면 유지 서비스가 약 30초 안에 다시 켤 수 있습니다. 중지 후에는 리모컨이나 PC로 조작해야 합니다.

자동 실행 앱과 드라이버 중지
& $adb -s $tivo shell am force-stop local.tivo.touch
if ($LASTEXITCODE -ne 0) { throw "자동 실행 앱 중지 실패" }
& $adb -s $tivo shell sh /data/local/tmp/stop-touch.sh
if ($LASTEXITCODE -ne 0) { throw "터치 드라이버 중지 실패" }
& $adb -s $tivo shell pidof tivo-touch
if ($LASTEXITCODE -ne 1) { throw "드라이버 중지를 확인하지 못했습니다. 삭제를 중단하세요." }

중지만 한 뒤 다시 켜기
# 중지만 한 경우 다시 시작합니다.
& $adb -s $tivo shell am start -W -n local.tivo.touch/.TouchActivity

앱 제거
# 위의 중지 명령을 먼저 성공시킨 뒤 실행합니다.
& $adb -s $tivo uninstall local.tivo.touch
# APK만 제거합니다. /data/local/tmp의 보조 파일은 비활성 상태로 남습니다.

설치 스크립트를 사용했다면 install-records 폴더의 JSON에 변경 전 키 유효기간이 기록되어 있습니다. TiVo 주소가 달라져 스크립트를 다시 실행하면 기록이 추가될 수 있으므로 최초 기록을 확인하세요. 수동 설치했다면 6-3에서 메모한 값을 사용합니다.

필요한 경우 ADB 키 유효기간 원상 복원
# 최초 설치 당시 기록한 값으로 복원합니다. 아래 둘 중 해당하는 한 줄만 실행하세요.
# 원래 값이 null이었다면:
& $adb -s $tivo shell settings delete global adb_allowed_connection_time
# 원래 숫자 값이 있었다면, 예: 604800000 = 7일:
& $adb -s $tivo shell settings put global adb_allowed_connection_time 604800000

adb_allowed_connection_time=0은 이 앱뿐 아니라 TiVo에 승인된 ADB 키 전체의 자동 만료를 해제합니다. 자동 실행을 제거할 때는 기존 값을 복원하세요. 이 배포본은 ADB 인증을 끄거나 PC의 개인 키를 TiVo로 복사하지 않습니다.

========================================================================
11. 검증 기록과 배포 확인
========================================================================

검사 | 확인 범위
실제 USB 터치 | 현재 TiVo와 0712:000a에서 사용자가 터치·드래그 작동을 확인
부팅 자동 실행 | TiVo 실제 OS 재부팅 뒤 PC의 시작 명령 없이 앱·드라이버 실행 및 사용자 터치 확인
제스처 | 분류기 테스트와 가상 입력 장치의 실제 Android 뒤로/홈 이동 확인. 손가락 제스처 확인은 별도
배포 APK | 기존 작동 APK와 바이트 일치, APK v2/v3 서명 검증
보조 파일 | 기존 작동 JAR/.so/스크립트와 바이트 일치, DEX 및 ARM ELF 형식 확인
이번 패키지 | 문서 JSON 검증, 오프라인 HTML 생성, PowerShell 구문 및 배포 파일 해시 검사
수행하지 않은 시험 | 다른 TiVo의 신규 설치, 새 설치 스크립트의 실제 기기 실행, 전원 차단, 실제 USB 포트 이동

자동 실행 재부팅 확인은 기존 v2.0 앱과 당시 터치 구성에서 수행했습니다. 이후 추가한 제스처 및 런처를 포함한 전체 구성에 대한 추가 재부팅 시험은 하지 않았습니다. 이 배포물은 현재 확인한 APK와 최신 드라이버 파일을 묶었습니다. 배포 ZIP에는 PC ADB 인증 키, 앱 서명용 키 저장소, 기기의 비공개 저장소나 개인 화면 캡처가 포함되지 않습니다.

========================================================================
12. 공식 참고 자료
========================================================================

Android SDK Platform-Tools 다운로드: https://developer.android.com/tools/releases/platform-tools
  공식 adb.exe 및 Windows용 DLL
Android Debug Bridge 명령 안내: https://developer.android.com/tools/adb
  장치 연결, APK 설치, TCP ADB 및 shell 명령
Android 부팅 수신과 포그라운드 서비스 조건: https://developer.android.com/develop/background-work/services/fgs/restrictions-bg-start
  BOOT_COMPLETED 등 백그라운드 시작 예외와 버전별 제약
