Macbook
183 lines
5.9 KiB
Markdown
183 lines
5.9 KiB
Markdown
# JUC500 / JUC700 File Transfer (Apple Silicon ↔ Windows 11)
|
||
|
||
j5create **JUC500** / **JUC700** USB 3.0 Wormhole 케이블로 **Apple Silicon Mac**과 **Windows 11** 사이 파일을 직접 전송하는 오픈 구현입니다.
|
||
|
||
## 지원 케이블
|
||
|
||
| 모델 | USB ID | 비고 |
|
||
|------|--------|------|
|
||
| **JUC500** | `0711:7500` | Mac ↔ Windows, Smart Data Link |
|
||
| **JUC700** | `0711:7000`–`700F` | Windows DSS(화면 공유) 포함, **데이터 링크는 동일 IF5** |
|
||
|
||
케이블 종류는 **USB로 자동 감지**됩니다. GUI 상단에 `JUC500` 또는 `JUC700`이 표시됩니다. 별도 선택 설정은 필요 없습니다.
|
||
|
||
> JUC700의 화면 미러/확장(DSS) 기능은 공식 Wormhole 앱 전용이며, 본 프로그램은 **파일 전송·입력공유**만 IF5 bulk 프로토콜로 제공합니다.
|
||
|
||
## 왜 공식 앱이 Silicon Mac에서 안 되나
|
||
|
||
실측/분석 결과:
|
||
|
||
| 항목 | 내용 |
|
||
|------|------|
|
||
| USB ID | `0711:7500` (JUC500) · `0711:700x` (JUC700) / Product: **Smart Data Link** |
|
||
| 가상 CD | `WORMHOLE` (FAT12, 공식 설치본 포함) |
|
||
| 번들/공식 Mac 앱 (2024, v1.0.1463.47) | **x86_64 전용**, Apple Silicon 네이티브 **arm64 없음** |
|
||
| USB 스택 | deprecated `IOUSBDevice` API (`kIOUSBDeviceInterfaceID500`) |
|
||
| 핵심 라이브러리 | KaiJet / OTi `OTiTransfer.framework` — bounding·alive·XML UPipe |
|
||
|
||
Intel Mac에서는 Rosetta 없이(구버전) 또는 Rosetta로 동작할 수 있으나, Apple Silicon + 최신 macOS에서는 공식 Wormhole 경로가 깨집니다. 이 프로젝트는 **libusb로 Vendor/CDC 인터페이스를 직접 열고**, 자체 프레임 프로토콜로 파일을 보냅니다.
|
||
|
||
공식 Windows Wormhole과 호환되지 않습니다. **양쪽 모두 이 프로그램을 실행**해야 합니다.
|
||
|
||
## 장치 인터페이스 (요약)
|
||
|
||
```
|
||
IF0 CDC Comm INT 0x81
|
||
IF1 CDC Data BULK 0x02 / 0x83
|
||
IF2 Mass Storage WORMHOLE CD (OS 점유 — 건드리지 않음)
|
||
IF3 HID mouse (KM — OS 점유)
|
||
IF4 HID keyboard (KM — OS 점유)
|
||
IF5 Vendor BULK 0x08/0x89 (데이터) + 0x0A/0x8B (keepalive)
|
||
```
|
||
|
||
## 요구 사항
|
||
|
||
### macOS (Apple Silicon)
|
||
|
||
- Python 3.10+
|
||
- libusb: `brew install libusb`
|
||
- (선택) 공식 Wormhole 앱이 떠 있으면 종료
|
||
|
||
```bash
|
||
cd /path/to/juc500
|
||
python3 -m venv .venv
|
||
source .venv/bin/activate
|
||
pip install -r requirements.txt
|
||
python -m juc500_xfer info
|
||
```
|
||
|
||
### Windows 11
|
||
|
||
**폐쇄망/오프라인:** `vendor/` 에 Python embeddable·wheel·libusb 가 포함되어 있습니다.
|
||
복사 후 `scripts\setup_windows.bat` → `.\start.bat` (자세한 절차: [`docs/OFFLINE-WINDOWS.md`](docs/OFFLINE-WINDOWS.md)).
|
||
|
||
1. (온라인 PC면) Python 3.10+ 선택 설치 — 없어도 `vendor\python-windows` 사용
|
||
2. 이 저장소 `vendor/libusb-1.0.dll` + `vendor/wheels` 사용 (PyPI 불필요)
|
||
3. **Zadig**로 `Smart Data Link` 복합 장치의
|
||
- **Interface 5** (Vendor Specific)
|
||
- **Interface 1** (CDC Data, 권장)
|
||
에 **WinUSB** 드라이버 설치
|
||
4. 공식 j5create Wormhole / 자동실행 소프트웨어는 **종료·제거** (같은 인터페이스를 점유함)
|
||
|
||
```bat
|
||
cd juc500
|
||
scripts\setup_windows.bat
|
||
.\start.bat
|
||
```
|
||
|
||
**장치가 안 보이면:**
|
||
|
||
```powershell
|
||
# libusb DLL 복사 (필수)
|
||
copy vendor\libusb-1.0.dll .venv\Scripts\libusb-1.0.dll
|
||
python -m juc500_xfer doctor
|
||
```
|
||
|
||
Zadig로 **Interface 5 (MI_05)** 에 WinUSB 설치 여부를 확인하세요.
|
||
케이블 가상 CD의 공식 **Wormhole**가 IF5를 점유하면 Access denied가 납니다.
|
||
GUI **Wormhole 종료** 버튼 또는 `python -m juc500_xfer kill-wormhole` 로 종료할 수 있습니다 (연결·실행 시에도 자동 종료).
|
||
|
||
## 사용법
|
||
|
||
### GUI (권장)
|
||
|
||
**macOS**
|
||
|
||
```bash
|
||
# 최초 1회
|
||
./scripts/setup_macos.sh
|
||
|
||
# 이후
|
||
./start.sh
|
||
```
|
||
|
||
**Windows 10/11** (Git Bash)
|
||
|
||
```bash
|
||
# 최초 1회 (PowerShell/CMD)
|
||
scripts\setup_windows.bat
|
||
|
||
# 이후 (Git Bash)
|
||
./start.sh
|
||
```
|
||
|
||
인자를 넘기면 CLI로 동작합니다: `./start.sh doctor`, `./start.sh kill-wormhole` 등.
|
||
|
||
양쪽 PC에 케이블을 꽂고, **먼저 수신 쪽**, 이어서 송신 쪽을 실행합니다.
|
||
|
||
**Windows (수신 예)**
|
||
|
||
```bash
|
||
./start.sh recv --dest "$USERPROFILE/Downloads" -y
|
||
```
|
||
|
||
**Mac (송신 예)**
|
||
|
||
```bash
|
||
./start.sh send ~/Desktop/archive.zip
|
||
```
|
||
|
||
## Windows 설치파일
|
||
|
||
산출물:
|
||
|
||
| 파일 | 용도 |
|
||
|------|------|
|
||
| `JUC500-Setup-win64.exe` | Inno Setup 설치 프로그램 |
|
||
| `JUC500-portable.exe` | 단일 실행 포터블 EXE |
|
||
| `JUC500-win64-portable.zip` | 폴더형 포터블 (+ `setup.bat`) |
|
||
|
||
**Mac(Apple Silicon)에서 빌드:**
|
||
|
||
```bash
|
||
./build-installer-windows.sh --ci
|
||
# → dist-windows/ 에 위 파일 다운로드 (GitHub Actions)
|
||
```
|
||
|
||
**Windows PC에서 빌드:**
|
||
|
||
```bat
|
||
build-installer-windows.bat
|
||
```
|
||
|
||
(Inno Setup 6 필요 시 Setup.exe 생성. 없어도 portable exe/zip 은 생성됩니다.)
|
||
|
||
사용 전 Win11에서 Zadig WinUSB 설정이 필요합니다 (`docs/WINDOWS.md`).
|
||
|
||
## GUI
|
||
|
||
fileShare와 동일한 **듀얼 패널(이 PC | 전송 | 상대 PC)** 웹 UI입니다.
|
||
|
||
```bash
|
||
python -m juc500_xfer gui
|
||
# → http://127.0.0.1:8765/
|
||
```
|
||
|
||
양쪽 PC에서 GUI를 실행한 뒤 **연결**을 누르세요.
|
||
|
||
**입력공유(가장자리 제어권):** 양쪽 모두 동일 소스 + `pynput` 설치 후 「입력공유 켜기」.
|
||
상대 PC를 오른쪽에 둔다고 가정합니다. 마우스 오른쪽 끝 → 상대 제어, 왼쪽 끝(또는 Ctrl+Shift+←) → 이 PC 복귀.
|
||
macOS는 **손쉬운 사용** 권한이 필요합니다.
|
||
|
||
Windows 설치본은 `JUC500.exe` / `JUC500-portable.exe` 더블클릭으로 동일 GUI가 열립니다.
|
||
|
||
## 프로토콜
|
||
|
||
Vendor BULK(`0x08`/`0x89`) 위에 길이·CRC 프레임(`J5FX` 매직)을 올리고 `HELLO` 핸드셰이크로 연결을 만듭니다. 보조 파이프(`0x0A`/`0x8B`)로 keepalive를내어 링크를 유지합니다. 파일은 SHA-256으로 무결성을 검증합니다.
|
||
|
||
공식 OTi XML / bounding 프로토콜은 재구현하지 않았습니다.
|
||
|
||
## 분석 메모
|
||
|
||
자세한 USB·바이너리 분석은 [`docs/ANALYSIS.md`](docs/ANALYSIS.md) 를 참고하세요.
|