example 앱 iOS 실기기 설치 트러블슈팅

example/ 앱을 실제 iPhone 에 설치할 때 자주 마주치는 오류와 해결 절차를 정리합니다.

실행 명령은 항상 example/ 디렉터리에서:

cd example
npm run ios -- --device

1. No code signing certificates are available to use.

원인

Apple Developer 계정 / 서명 인증서가 Xcode 에 설정되지 않은 상태에서 실기기 빌드를 시도할 때 발생. 시뮬레이터 빌드에서는 발생하지 않음.

해결 절차

1) Xcode 에 Apple ID 등록 (최초 1 회)

1. Xcode 실행
2. 메뉴 Xcode → Settings… → Accounts 탭
3. 좌측 하단 + 클릭 → Apple ID 선택 → 로그인
4. 등록되면 Personal Team (무료 계정) 또는 가입된 Apple Developer Program 팀이 표시됨

2) 프로젝트에 Team 지정

프로젝트 루트에서:

npm run open:ios

→ Xcode 가 example/ios/bootnemonicprinterexample.xcworkspace 를 자동으로 엽니다.

1. 좌측 Navigator 최상단 bootnemonicprinterexample 프로젝트 선택
2. TARGETS → bootnemonicprinterexample 타겟 선택
3. Signing & Capabilities 탭 열기
4. Automatically manage signing 체크 유지
5. Team 드롭다운에서 등록한 계정 선택
6. Xcode 가 provisioning profile 을 자동 생성할 때까지 잠시 대기

3) Bundle Identifier 충돌 시

net.eventboot.nemonicprinter.example 가 이미 다른 사람의 계정에 등록돼 있으면 빨간 오류가 표시됨. 본인만 쓰는 식별자로 변경:

• example/app.json 의 ios.bundleIdentifier 를 net.eventboot.nemonicprinter.example.<이니셜> 등으로 수정
• 이후 example/ 에서 npx expo prebuild --platform ios --clean 으로 ios/ 재생성 (또는 Xcode 의 Bundle Identifier 필드를 직접 수정)

4) 무료 계정으로 설치 시 — 기기에서 "신뢰" 설정

첫 설치 후 iPhone 에서 앱 실행 시 "신뢰할 수 없는 개발자" 경고가 뜨면:

• iPhone → 설정 → 일반 → VPN 및 기기 관리 → 본인 Apple ID 선택 → 신뢰

5) 다시 빌드

cd example
npm run ios -- --device

2. The developer disk image could not be mounted on this device.

원인

iOS 17+ 부터 Apple 은 Developer Disk Image (DDI) 를 Xcode 가 인터넷에서 자동 다운로드해 마운트합니다. 첫 연결 시, 또는 iOS / Xcode 업데이트 직후 자주 실패합니다.

버전 호환 확인: xcodebuild -version 의 Xcode 메이저 버전이 iPhone 의 iOS 메이저 버전 이상이어야 함. (예: iOS 26.x 디바이스에는 Xcode 26.x 이상 필요)

해결 절차

1) 기본 점검

• Mac 이 인터넷에 연결돼 있는지 확인 (DDI 다운로드용)
• iPhone 잠금을 해제하고 그대로 유지 (잠기면 마운트가 중단됨)

2) 케이블 재연결 + 신뢰 재확인

• iPhone 케이블 분리 → 재연결
• iPhone 에 "이 컴퓨터를 신뢰하시겠습니까?" 가 뜨면 신뢰 → 암호 입력

3) Xcode 의 디바이스 준비 완료 대기 (가장 중요)

• Xcode 메뉴 Window → Devices and Simulators (단축키 ⇧⌘2)
• 좌측 사이드바에서 본인 iPhone 선택
• 우측 상단에 다음과 같은 진행 표시가 나타남:
  • Preparing iPhone for development…
  • Fetching debug symbols
• 5 ~ 15 분 소요 (첫 연결 시 특히 오래 걸림). 끝까지 기다릴 것
• 완료되면 디바이스 이름 옆 노란 경고 표시가 사라지고 Connected via … 만 남음

⚠️ 이 단계가 완료되기 전에 빌드를 시도하면 그대로 developer disk image 오류가 발생합니다.

4) Platforms 다운로드 상태 확인

• Xcode → Settings → Platforms 탭
• 본인 iPhone 의 iOS 메이저 버전 (예: iOS 26.x) 항목이 표시되고 다운로드 완료 상태인지 확인
• 누락돼 있으면 Get 클릭 후 다운로드

5) 위 절차 후에도 실패 시

# Xcode 종료 후 DerivedData 삭제
rm -rf ~/Library/Developer/Xcode/DerivedData/*

추가로:

• iPhone 재부팅 (전원 끄고 30 초 후 재시작)
• Mac 재부팅
• Xcode 재실행 → Window > Devices and Simulators 로 다시 준비 대기

6) 재시도

cd example
npm run ios -- --device

3. print() 결과가 -64 로 떨어짐 (iOS / Android 공통)

증상

BLE 연결 후 인쇄를 호출하면 프린터에서는 라벨이 정상 출력되지만 JS 측에는 짧은 시간 안에 -64 가 반환됨:

[NemonicPrintTimer-JS] #7 T+5118ms ◀ native print() resolved (result=-64)

iOS, Android 모두 동일하게 재현됨.

원인

-64 = NemonicSdk 의 NResult.TIMEOUT. SDK 가 한 페이지 인쇄 후 프린터의 완료 ACK 를 기다리다 시간을 초과하면 이 값을 반환.

example/App.tsx 가 과거에 connect 직후 setPrintTimeout(false, 100) 으로 ACK 대기 시간을 100ms 로 짧게 강제하던 워크어라운드를 사용해서, 실제 프린터 ACK 가 도착하기 전에 SDK 가 타임아웃 처리하면서 -64 를 반환했음. BLE 로 데이터는 이미 전송됐기 때문에 프린터에서는 출력이 끝까지 진행되지만 JS 입장에서는 성공/실패 구분이 불가능했음.

추가로, 짧은 타임아웃은 onPrintComplete 이벤트도 timeout 시점에 발화시켜 "프린터 완료 신호로 인쇄 버튼 활성화" 같은 게이팅이 실제 인쇄 끝과 어긋나는 문제도 일으킴.

해결

iOS / Android(BLE) 는 충분히 긴 타임아웃 (30 초), Android USB 는 3 초 로 분기 — 이 example 코드에는 이미 적용돼 있음:

// example/App.tsx connect() 내부
const isAndroidUsb = Platform.OS === 'android' && transport === 'usb';
const PRINT_TIMEOUT_MS = isAndroidUsb ? 3000 : 30000;
BootNemonicPrinter.setPrintTimeout(false, PRINT_TIMEOUT_MS);

| 환경 | manualTime | 동작 | | --- | --- | --- | | iOS (BLE) | 30000 (30 초) | ACK 받고 진짜 결과 코드 반환 (OK / -81 / -101 / ...) | | Android (BLE) | 30000 (30 초) | 동일 | | Android (USB) | 3000 (3 초) | SDK 가 ACK 못 받아 항상 timeout 발생 — 짧게 잡아 UX 보호. result=-64 지만 인쇄는 정상 |

Android USB 의 특수 사항

Android + USB 조합은 SDK 가 인쇄 완료 ACK 를 받지 못해 setPrintTimeout 으로 설정한 시간만큼 무조건 대기 후 -64 를 반환. BLE 처럼 "ACK 도착 즉시 반환" 이 동작하지 않음.

SDK 가 클로즈드 소스라 추정 원인:

• BLE 는 GATT notification 으로 프린터가 인쇄 완료 신호를 양방향 publish → SDK 가 즉시 인지
• USB 는 SDK 의 IN endpoint 응답 처리가 없거나 프린터 펌웨어가 USB 모드에서 상태 응답을 보내지 않음 → SDK 는 timeout 까지 대기

모듈/앱 코드 레벨에서 우회 불가 — setPrintTimeout 값을 줄여 대기 시간만 단축하는 게 현실적 해결책.

이 때문에 USB 에서는 다음 점도 인지하고 설계할 것:

• print() 결과로 성공/실패 판정 불가 — 항상 -64
• onPrintComplete 이벤트도 timeout 시점 (3 초) 에 발화 — 실제 인쇄 끝과 시간이 다를 수 있음
• 정확한 완료 시점이 필요하면 별도 메커니즘 필요 (예: 사용자 확인 버튼 등)

자기 앱에 적용할 때 가이드 (BLE 기준)

• 인쇄 성공/실패 판정 + 완료 신호 게이팅이 중요 (기본 권장) → 10000 ~ 30000ms 로 길게 설정. await print() 가 한 페이지당 수 초 블로킹되므로 UI 로딩 상태/취소를 별도로 관리.
• 빠른 연속 인쇄가 우선이고 결과 코드 정밀도가 덜 중요하면 짧은 값도 가능 — 단 -64 를 "전송 성공, ACK 미수신" 으로 해석 만 하면 됨. (Android SDK 일부 버전에서 큰 timeout 값이 다음 print 호출을 늦추는 부작용이 보고된 적 있음. 본인 환경에서 확인 후 결정.)

참고 — 다른 음수 결과 코드

| 코드 | 의미 | | --- | --- | | -64 | TIMEOUT (위 설명) | | -81 | UNAVAILABLE_CARTRIDGE (카트리지 미장착/미인식) | | -101 | BLUETOOTH_DISABLED | | -301 | NOT_CONNECTED |

전체 목록은 ios/Frameworks/NemonicSdk.framework/Headers/NemonicSdk-Swift.h 의 NResult enum, 또는 src/BootNemonicPrinter.types.ts 의 NResult 참고.

빠른 체크리스트

실기기 빌드 전:

• [ ] Xcode 에 Apple ID 등록 완료
• [ ] 타겟의 Signing & Capabilities 에 Team 지정 완료
• [ ] Bundle Identifier 가 본인 계정에서 사용 가능한 값
• [ ] iPhone 이 신뢰된 상태로 연결 + 잠금 해제
• [ ] Xcode Devices and Simulators 에서 Preparing iPhone for development 완료
• [ ] Xcode Settings → Platforms 에서 iPhone 의 iOS 버전 다운로드 완료
• [ ] setPrintTimeout 값이 충분히 길게(예: 30000ms) 잡혀 있는지 확인 — iOS / Android 공통 (3 번 참고)