모델	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 앱이 떠 있으면 종료

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).

(온라인 PC면) Python 3.10+ 선택 설치 — 없어도 vendor\python-windows 사용
이 저장소 vendor/libusb-1.0.dll + vendor/wheels 사용 (PyPI 불필요)
Zadig로 Smart Data Link 복합 장치의
- Interface 5 (Vendor Specific)
- Interface 1 (CDC Data, 권장)
  에 WinUSB 드라이버 설치
공식 j5create Wormhole / 자동실행 소프트웨어는 종료·제거 (같은 인터페이스를 점유함)

cd juc500
scripts\setup_windows.bat
.\start.bat

장치가 안 보이면:

# 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

# 최초 1회
./scripts/setup_macos.sh

# 이후
./start.sh

Windows 10/11 (Git Bash)

# 최초 1회 (PowerShell/CMD)
scripts\setup_windows.bat

# 이후 (Git Bash)
./start.sh

인자를 넘기면 CLI로 동작합니다: ./start.sh doctor, ./start.sh kill-wormhole 등.

양쪽 PC에 케이블을 꽂고, 먼저 수신 쪽, 이어서 송신 쪽을 실행합니다.

Windows (수신 예)

./start.sh recv --dest "$USERPROFILE/Downloads" -y

Mac (송신 예)

./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)에서 빌드:

./build-installer-windows.sh --ci
# → dist-windows/ 에 위 파일 다운로드 (GitHub Actions)

Windows PC에서 빌드:

build-installer-windows.bat

(Inno Setup 6 필요 시 Setup.exe 생성. 없어도 portable exe/zip 은 생성됩니다.)

사용 전 Win11에서 Zadig WinUSB 설정이 필요합니다 (docs/WINDOWS.md).

GUI

fileShare와 동일한 듀얼 패널(이 PC | 전송 | 상대 PC) 웹 UI입니다.

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 를 참고하세요.

README.md Unescape Escape

JUC500 / JUC700 File Transfer (Apple Silicon ↔ Windows 11)

지원 케이블