juc500 정상동작

2026-07-21 21:04:25 +09:00
parent a423db0556
commit bb9874b931
2917 changed files with 708025 additions and 668 deletions
@@ -0,0 +1,64 @@
+# 입력공유 수동 검증 체크리스트
+
+양쪽 PC(Windows + Mac)에 **동일 커밋**을 받은 뒤:
+
+```bash
+# Mac
+./scripts/setup_macos.sh
+./start.sh
+
+# Windows
+scripts\setup_windows.bat
+.\start.bat
+```
+
+## 절차
+
+1. 케이블 연결 → 양쪽 GUI에서 **연결** (파일 패널이 떠야 함)
+2. **양쪽**에서 **입력공유 켜기** (기본은 꺼짐 — USB 연결만으로는 켜지지 않음. 한쪽만 켜면 핸드오프 불가)
+   - Mac: 손쉬운 사용에서 Python/Terminal 허용 후 다시 켜기
+3. A쪽 마우스를 **화면 오른쪽 끝**으로 밀어 잠시 대기
+   - A 상태: `상대 PC 제어` — 키보드·마우스 입력이 B로 전달
+   - B 상태: `상대가 조종 중` — 커서/클릭/키가 B에 적용
+4. 마우스를 **상대(B) 화면 왼쪽 끝**으로 이동
+   - A로 제어권 복귀 (`이 PC 제어`), 커서는 A 화면 오른쪽 안쪽에 놓임
+5. GUI의 [상대 PC] / [이 PC] 버튼으로도 전환되는지 확인 (입력공유 ON일 때만)
+6. **Esc** / 정상 종료 / 끊기 — 입력공유 해제 + 로컬 마우스·키보드 강제 복구
+7. 강제 종료 후에도 다음 실행 시 시작 단계에서 입력 상태를 복구하는지 확인
+8. 파일 전송 중에도 세션이 죽지 않는지 확인 (입력은 잠시 끊길 수 있음)
+
+## 레이아웃
+
+상대 PC를 **오른쪽**에 둔다고 가정합니다.
+
+현재 모니터 오른쪽 끝에 두고, **그 오른쪽에 다른 모니터가 없을 때** 상대 PC로 넘어갑니다.
+(다중 모니터면 맨 오른쪽 화면의 오른쪽 끝으로 밀어 주세요.)
+
+| 동작 | 결과 |
+|------|------|
+| 모니터 오른쪽 가장자리로 마우스 | 제어권 → 상대 PC (KM 캡처 → USB 전송) |
+| 상대 가상 커서 왼쪽 가장자리 | 제어권 → 이 PC (캡처 해제, 로컬 KM 복귀) |
+
+참고: 이 PC 커서는 ACK 수락 후 숨겨지고, 상대 PC 커서가 움직입니다.
+상대가 수락하지 않으면(입력공유 OFF 등) 약 1.5초 후 자동으로 이 PC로 복귀합니다.
+양쪽에 **동일 버전의** `inputshare.py` / `protocol.py`가 있어야 ACK(2)·NACK(3) 핸드셰이크가 동작합니다.
+
+## 파일 붙여넣기 (클립보드 → 상대 폴더)
+
+Finder / Explorer에서 파일을 복사한 뒤, JUC500으로 상대 폴더에 붙여넣을 수 있습니다.
+(OS 창을 넘나드는 진짜 드래그 앤 드롭은 지원하지 않습니다.)
+
+1. USB **연결** 후 JUC500 UI에서 **상대 대상 폴더**를 엽니다 (배지에 `붙여넣기 → …` 표시).
+2. Finder 또는 Explorer에서 파일/폴더를 **복사** (Cmd+C / Ctrl+C).
+3. JUC500 창에서 **Ctrl+Shift+V** 로 전송합니다.
+4. 전송 진행은 가운데 상태/프로그레스에 표시되고, 끝나면 상대 폴더 목록이 새로고침됩니다.
+
+대상 폴더를 열지 않은 경우 기본값은 상대 쪽 `Desktop` 상대 경로입니다. 가능하면 UI에서 폴더를 먼저 여세요.
+
+## 텍스트 붙여넣기 (상대 PC 제어 중)
+
+1. 이 PC에서 텍스트를 **복사** (Ctrl+C / Cmd+C).
+2. 마우스로 **상대 PC 제어**로 이동.
+3. 상대 앱에서 **Ctrl+V** (Mac에서는 Cmd+V도 가능) — 클립보드 텍스트가 상대로 동기화된 뒤 상대에서 붙여넣기됩니다.  
+   (파일 전송용 Ctrl+V 가로채기는 하지 않습니다.)
+
@@ -0,0 +1,79 @@
+# 폐쇄망 Windows 11 — 오프라인 빌드/실행
+
+이 저장소의 `vendor/` 에는 **인터넷 없이** 설치·실행할 수 있는 파일이 포함되어 있습니다.
+
+## 포함 내용
+
+- `vendor/wheels/*.whl` — pyusb, pynput, setuptools, pip, virtualenv 등
+- `vendor/libusb-1.0.dll` — libusb x64
+- `vendor/python-windows/` — Python 3.11.9 embeddable (시스템 Python 불필요)
+- `vendor/get-pip.py` — 오프라인 pip 설치
+- `vendor/tools/zadig.exe` — WinUSB 바인딩 (폐쇄망용, 오프라인)
+
+## 지원 케이블
+
+| 모델 | USB ID | 비고 |
+|------|--------|------|
+| **JUC500** | `0711:7500` | Interface 5 (MI_05) bulk 파일 전송 |
+
+## 대상 PC에서 **신규** 설치
+
+1. 소스 트리 전체를 USB 등으로 복사 (특히 `vendor/` 누락 금지)
+   - Mac에서 전체 zip: `./scripts/make_windows_bundle.sh` (`.venv` 제외, `vendor/` 포함)
+2. Git Bash (권장):
+
+```bash
+cd /c/dev/juc500
+./start_win.sh
+```
+
+첫 실행 시 `vendor/` 로 `.venv`·`libusb` 가 **자동 생성**됩니다.
+
+또는 CMD:
+
+```bat
+cd c:\dev\juc500
+scripts\setup_windows.bat
+.\start.bat
+```
+
+## 이미 설치된 PC에 **소스 업데이트만** (폐쇄망)
+
+Mac에서:
+
+```bash
+./scripts/make_offline_windows_update.sh
+```
+
+생성물:
+
+- `dist-offline/juc500-offline-update-*.zip`
+- 바탕화면 동일 zip
+- `vendor/tools/zadig.exe`, `vendor/wheels`, `juc500_xfer/*`, `apply_offline_update.bat` 포함
+
+Windows에서:
+
+1. zip을 USB로 복사·압축 해제  
+2. JUC500 GUI 종료  
+3. `apply_offline_update.bat` 실행 (기본 `C:\dev\juc500`)  
+4. `start.bat` 재실행 → 상단 빌드 태그가 `BUILD.txt`의 `XFER_BUILD`와 일치하는지 확인  
+
+인터넷·PyPI 불필요.
+
+## USB / WinUSB
+
+장치 Interface 5 는 **Zadig → WinUSB** 가 필요합니다.
+
+```
+vendor\tools\zadig.exe
+```
+
+Options → List All Devices → `Smart Data Link` (0711:7500) → **Interface 5 (MI_05)** → WinUSB.
+
+## 온라인 PC에서 vendor 갱신
+
+```bat
+python -m pip download -d vendor\wheels ^
+  pyusb==1.2.1 pynput==1.8.2 six==1.17.0 ^
+  "setuptools>=68" wheel packaging pip build virtualenv
+```
@@ -26,6 +26,14 @@ python -m juc500_xfer gui

 또는 `scripts\setup_windows.bat`

+설치 후 실행 (Git Bash):
+
+```bash
+./start.sh
+```
+
+CMD/탐색기에서는 `start.bat` 을 사용해도 됩니다.
+
 ## 설치파일 사용 (권장)

 1. `JUC500-Setup-win64.exe` 실행해 설치  
@@ -43,13 +51,46 @@ Mac에서 빌드 산출물 받기:

 1. [Zadig](https://zadig.akeo.ie/) 실행 (관리자)  
 2. Options → **List All Devices**  
-3. `Smart Data Link` 선택  
+3. `Smart Data Link` / `SmartKMLink` 선택  
 4. 하단에서 **Interface 5** 선택 → Driver: **WinUSB** → Replace Driver  
 5. 마찬가지로 **Interface 1** (CDC Data) 권장  
 6. Interface 2(Mass Storage), 3·4(HID) 는 그대로 두세요.

 공식 Wormhole가 설치돼 있으면 GUI의 **Wormhole 종료** 또는 `python -m juc500_xfer kill-wormhole` 후 Zadig를 실행하세요.

+### SmartKMLink가 목록에 하나만 보이고 MI_05가 없을 때
+
+OEM 드라이버가 **복합 장치 전체**를 한 덩어리로 붙잡고 있으면 Zadig에 `MI_00`…`MI_05` 하위 항목이 안 나옵니다. 아래 순서로 인터페이스를 분리하세요.
+
+**A. Zadig 옵션 확인**
+
+1. 관리자 실행  
+2. Options → **List All Devices** 체크  
+3. Options → **Ignore Hubs or Composite Parents** 체크 해제 후 목록을 다시 연다  
+4. 같은 이름이라도 USB ID가 `0EA0:7301` / `0EA0:7301 (MI_05)` 처럼 다른 항목이 있는지 확인  
+5. 장치 선택 후 창 하단 **Interface** 숫자(0~5)를 **5**로 바꿀 수 있으면 → WinUSB → Replace Driver  
+
+**B. 장치 관리자로 OEM 드라이버 제거 (권장, MI_xx 분리)**
+
+1. JUC500 / Wormhole 종료  
+2. `devmgmt.msc` → 보기 → **장치(연결)별** / **숨김 장치 표시**  
+3. **범용 직렬 버스 장치** · **휴대용 장치** · **디스크 드라이브** 등에서  
+   `SmartKMLink` / `WORMHOLE` / `j5create` / `0EA0` 관련 항목을 모두 찾는다  
+4. 각 항목 → 제거 → **이 장치의 드라이버 소프트웨어 삭제** 체크  
+5. 케이블 분리 → 5초 대기 → 다시 연결  
+6. Windows가 **USB 복합 장치(usbccgp)** + 자식 `MI_00`…`MI_05` 로 다시 잡히면  
+   Zadig List All Devices 에 Interface/MI_05 가 나타난다  
+7. **MI_05 (Interface 5)** 만 WinUSB 설치 (저장장치·HID MI는 건드리지 않음)
+
+**C. 그래도 MI_05가 없을 때 (최후 수단)**
+
+복합 부모(`USB Composite Device` / usbccgp, USB ID `0EA0:7301` 에 MI 없음)에  
+WinUSB를 씌우면 libusb로 IF5에 접근 가능해질 수 있다.  
+단, 같은 케이블의 CD롬/HID/가상 시리얼이 Windows에서 안 보일 수 있다.  
+파일 전송만 필요하면 이 방법으로 진행한 뒤 `start.bat` 로 연결을 확인한다.
+
+복구: 장치 관리자에서 해당 WinUSB 장치 제거(+드라이버 삭제) 후 케이블 재연결.
+
 ## 2. libusb DLL

 [libusb releases](https://github.com/libusb/libusb/releases) 에서 MS64/dll을 받아: