KO S3 HUD - ajouatom/openpilot GitHub Wiki

CARROT S3 Wi-Fi HUD 설치 설명서

일반 사용자는 NAS 설치 페이지를 여세요. PC Chrome/Edge에서 보드를 선택하고 설치할 수 있습니다. 개발 환경은 필요 없습니다. 펌웨어·설명서 ZIP · 검증값

준비물과 지원 범위

준비물	확인할 내용
ESP32-S3 N16R8	Flash 16MB, Octal PSRAM 8MB, UART/USB 두 USB-C 포트가 있는 DevKitC-1 형태
안테나	보드 끝에 안테나가 붙은 제품 권장. 외장 안테나형은 별도 안테나 필요하며 이번 검증 대상 아님
USB 화면	TURZX 9.2인치 1920×462, USB ID `1cbe:0092`
전원형 USB 허브	본체 연결용 케이블 + USB 데이터 포트 + 외부 전원 입력. 모든 허브의 호환성을 보장하지 않음
전원·케이블	화면/허브 요구 전력을 충족하는 USB 전원, 데이터 지원 USB 케이블

ESP32, S2, C3, N8R2, PSRAM 없는 보드는 이 펌웨어 대상이 아닙니다. HDMI 또는 USB-C DP Alt Mode 모니터로 영상 신호를 내보내는 장치가 아닙니다.

연결

PC 또는 C4 ── S3 UART 포트 (BOOT 버튼 쪽): 설치·최초 등록
                 S3 USB 포트 (RESET 버튼 쪽)
                         │
                 허브 본체 연결용 케이블
                         │
                    전원형 허브 ── USB 화면 (데이터 포트)
                         │
                     USB 전원 입력

보드의 좌우보다 UART / USB 인쇄를 확인하세요. 시험 보드는 USB 포트에서 화면용 전원을 공급하지 못해 전원형 허브가 필요했습니다. 전원을 받은 화면이 제조사 로고를 보여도 USB 데이터 통신이 된다는 뜻은 아닙니다. 등록 전 대기 화면은 소등될 수 있으며, 설정 모드를 열면 설정 안내가 나옵니다.

1. 펌웨어 설치 또는 업데이트

S3 UART 포트를 데이터 케이블로 PC에 연결합니다.
PC Chrome/Edge에서 NAS 설치 페이지를 엽니다.
새 보드는 처음 설치, 기존 CARROT 보드는 업데이트를 선택합니다.
보드 확인란을 선택하고 설치 버튼을 눌러 CP210x / USB Serial 포트를 고릅니다.
완료 메시지까지 기다립니다. S3가 재시작합니다.

업데이트는 기존 파티션을 검사한 뒤 앱만 교체합니다. 처음 설치도 전체 지우기를 하지 않습니다. 설치 전후 등록 저장 영역을 비교해 Wi-Fi·등록 정보 보존을 확인합니다. 처음 설치는 보드의 기존 프로그램을 CARROT으로 교체합니다.

포트가 없으면 데이터 케이블/UART 포트를 확인하고, 필요 시 Silicon Labs CP210x 드라이버를 설치합니다. 다른 UART 칩 보드는 해당 칩의 드라이버가 필요합니다. 자동 연결에 실패하면 BOOT를 누른 채 RESET을 한 번 누르고 두 버튼을 뗀 뒤 재시도하세요. 다른 시리얼 모니터는 닫아 두세요. 실패 시 같은 설치를 다시 실행할 수 있습니다.

2-A. C4 USB로 등록 (권장)

C4에 최신 carrot-nav/carrot-wip가 설치돼 있어야 합니다. C4를 사용할 2.4GHz Wi-Fi/폰 핫스팟에 연결한 뒤 S3의 UART 포트를 C4에 연결하세요. C4 웹 터미널 또는 SSH 터미널에서 실행합니다. 시동을 꺼도 등록할 수 있습니다.

cd /data/openpilot
python3 tools/esp32s3_display/provision.py --auto

현재 Wi-Fi 이름과 암호를 S3에 저장하고 C4 등록까지 마칩니다. 지원 UART가 한 개일 때만 자동 선택하며 S3 응답을 확인한 뒤 저장합니다. 여러 포트가 있으면 실제 S3를 확인해 --auto 대신 --port /dev/ttyUSB0처럼 지정하세요. Wi-Fi 암호를 읽을 권한이 없으면 sudo -E로 실행하거나 --ssid를 사용합니다. 케이블을 꽂는 것만으로 등록되지는 않습니다.

2-B. 폰으로 설정

첫 설치 또는 부팅 후 BOOT 3초로 설정 화면을 엽니다. 전원을 넣을 때 BOOT를 누르고 있으면 다운로드 모드가 되므로 부팅이 끝난 뒤 누르세요.
폰에서 Wi-Fi CARROT-HUD, 암호 12345678에 접속합니다.
**http://192.168.4.1**을 엽니다. 시간 초과 시 “인터넷 없이 연결 유지”를 선택하고 모바일 데이터를 잠깐 끕니다. setup closed면 BOOT 3초로 다시 엽니다.
차에서 사용할 2.4GHz Wi-Fi 이름·암호를 입력하고 Wi-Fi 저장을 누릅니다. 설정은 약 15초 뒤 닫힙니다. 미저장 설정 창은 10분 후 닫힙니다.
첫 C4 등록이면 처음 C4 연결: 등록 파일 받기를 누릅니다. 매번 다른 이름의 JSON이 다운로드됩니다. Wi-Fi만 바꾸는 경우에는 다운로드가 필요 없습니다.
JSON을 WinSCP/SFTP 등으로 C4의 /data/carrot-s3.json에 복사하고 아래를 실행합니다. 파일 전송이 어렵다면 USB 등록(2-A)을 선택하세요.

cd /data/openpilot
python3 tools/esp32s3_display/provision.py --import-pairing /data/carrot-s3.json

등록 파일은 해당 화면에 접근할 수 있는 키입니다. 공개하거나 다른 사람에게 보내지 마세요. 핫스팟 폰이 Wi-Fi 접속을 동시에 못 하면 다른 폰으로 설정 후 핫스팟을 켭니다. 아이폰 핫스팟은 호환성 최대화, 안드로이드는 2.4GHz를 선택하세요.

3. 사용

C4 설정에서 외부 HUD (ClusterHud) → 9.2인치를 선택합니다.
C4와 S3를 같은 Wi-Fi/핫스팟에 연결합니다. 기기 간 통신을 차단하는 게스트망은 사용할 수 없습니다. 차량에서는 PC·USB 테더링이 필요 없습니다.
시동 ON에서 표시하고 OFF에서 소등합니다. 대기 중 화면 시험은 ClusterHudDebug를 사용하고 시험 후 0으로 되돌립니다.

밝기·방향·미러·카메라는 기존 HUD 설정을 사용합니다. Wi-Fi는 기본 최대 15fps, eGPU 사용 중 최대 10fps입니다. 실제 속도는 화면 내용과 무선 환경에 따라 달라지며 광학 패널 FPS 보장이 아닙니다. 직접 USB 연결의 기존 5fps 정책은 별도입니다.

보드 LED로 상태 확인 (펌웨어 1.1.1 이상)

전원 LED와 별도로 보드 가운데 RGB LED를 약하게 켭니다.

RGB LED	상태
파란색 점멸	처음 Wi-Fi에 연결하는 중
빨간색 점멸	Wi-Fi 연결 또는 IP를 잃어 재연결 대기 중
초록색 계속 켜짐	Wi-Fi에서 IP를 받았고 USB 화면 연결이 확인됨
초록색이 짧게 꺼졌다 켜짐	최근 2초 안에 화면 데이터를 USB로 정상 전송함
빨간색 두 번씩 점멸	Wi-Fi IP는 있지만 USB 화면이 없거나 USB 통신 오류
보라색 점멸	폰 설정 모드가 열려 있음

초록색만으로 C4 연결이나 인터넷 통신까지 보장하지는 않습니다. 설정 모드가 열려 있으면 보라색 표시가 우선합니다. 시동 OFF로 화면이 꺼져도 S3 전원이 있으면 LED는 상태를 계속 표시합니다. RGB LED 핀이 GPIO38인 일부 보드에서는 기본 GPIO48 빌드의 LED가 켜지지 않을 수 있습니다. 이 경우 아래 README의 빌드 설정을 확인하세요.

다음에 바꿀 때

SSID/암호: BOOT 3초 → 폰에서 저장, 또는 새 Wi-Fi에 연결된 C4에서 USB 등록 명령 재실행. 같은 보드의 등록 키는 유지되어 다시 JSON을 옮길 필요가 없습니다.
펌웨어: NAS 설치 페이지의 업데이트. 일반적인 C4 화면 변경마다 다시 설치할 필요는 없지만 S3 자체 버그 수정은 재설치가 필요할 수 있습니다. OTA는 없습니다.
직접 USB로 복귀: C4 등록 파일 /data/carrot/cluster_wifi.json을 별도 위치로 옮기고 HUD를 재시작합니다. 나중에 복원하려면 등록 파일을 보관하세요.

화면이 안 나오거나 꺼지지 않을 때

제조사 로고만 보이면 허브 본체 케이블이 S3의 USB에 연결됐는지 확인합니다. 전원이 들어오는 것과 데이터 연결은 다릅니다. 다른 허브로 비교할 수 있습니다.
설정 Wi-Fi는 보이는데 설정 화면이 안 보이면 화면/허브 연결부터 확인합니다.
대기 중 꺼짐은 정상입니다. 시동 ON에서도 안 보이면 C4 등록과 동일 네트워크를 확인합니다.
지연이 크면 안테나를 금속·허브에서 떨어뜨리고 다른 2.4GHz 핫스팟과 비교합니다.
시동 OFF인데 계속 켜지면 Debug 0, C4 최신 코드, S3 1.1.0 이상을 확인합니다. 1.1.0은 소등 명령 응답을 확인하고 실패 시 재시도합니다. 통신이 끊겨도 마지막 정상 영상 약 2초 후 자체 소등하며 USB 타임아웃이 추가될 수 있습니다. 대기 중 30초마다 소등을 재확인합니다. 설정 안내 중에는 켜져 있습니다.

소등은 백라이트 끄기이며 USB 전원 차단은 아닙니다.

고급 사용자: 파일로 설치

ZIP에는 bootloader.bin, partition-table.bin, carrot-s3.bin, release.json, SHA256SUMS.txt, 설명서, 검증된 빌드 설정이 있습니다. esptool 4.11 사용 예:

python -m esptool --chip esp32s3 --port COM14 --baud 460800 write_flash --flash_mode dio --flash_freq 80m --flash_size 16MB 0x0 bootloader.bin 0x8000 partition-table.bin 0x10000 carrot-s3.bin

COM14는 예시이며 실제 포트를 선택합니다. 기존 CARROT 앱만 업데이트할 때는 마지막 0x10000 carrot-s3.bin만 기록합니다. erase_flash는 실행하지 마세요. 0x9000–0xEFFF의 NVS에는 개인 Wi-Fi/등록 정보가 있습니다. 배포 ZIP에는 이 영역이나 개인 설정이 포함되지 않습니다. ESP-IDF 5.4.0 소스 빌드는 개발자 README를 참고하세요.