# 자주 발생하는 문제와 해결법

> 막혔을 때 **순서대로** 확인하세요. 80%는 이 문서로 해결됩니다.

---

## A. ESP32-CAM이 켜지지 않음

| 증상 | 점검 |
|---|---|
| 빨간 LED 미점등 | 5V 전원 공급 확인, USB 케이블 교체 |
| 부팅 루프 (계속 재시작) | 전원 부족 → **2A 이상** 어댑터 사용 |
| 시리얼 모니터에 글자 깨짐 | 통신속도(baud rate) `115200` 설정 |

---

## B. 펌웨어 업로드 실패

```
Failed to connect to ESP32: Timed out waiting for packet header
```

1. **GPIO 0 → GND** 점프(다운로드 모드 진입) 후 RESET 버튼 누르기
2. FTDI 케이블 점검 (TX↔RX 교차 연결)
3. 드라이버 설치 (CP2102, CH340 등)
4. 다른 USB 포트 시도

---

## C. Wi-Fi 연결 안 됨

### 시리얼 모니터에 IP가 안 뜸
1. SSID·비밀번호 오타 확인 (대소문자 구분)
2. 학교 Wi-Fi는 **WPA2-Enterprise**(ID/PW 다중 입력) 필요 → ESP32는 미지원
3. **휴대폰 핫스팟**으로 전환 (가장 빠른 해결)
4. 5GHz Wi-Fi는 ESP32 미지원 → **2.4GHz** 사용

### IP는 떴는데 브라우저 접속 안 됨
1. 같은 Wi-Fi 네트워크인지 확인
2. 핸드폰 LTE/데이터로 PC 핫스팟 한 경우, PC와 ESP32 모두 같은 핫스팟에 연결
3. PC 방화벽 임시 해제 후 테스트
4. `ping [ESP32_IP]` 실행 → 응답 없으면 네트워크 문제

---

## D. 영상 스트림이 안 나옴

| 증상 | 원인·해결 |
|---|---|
| 화면이 회색·검은색 | 카메라 케이블 헐거움 → 다시 꽂기 |
| 화면이 깨짐 | 전원 부족 → 5V 2A 이상 |
| `imshow` 창이 안 뜸 | OpenCV 미설치: `pip install opencv-python` |
| `Stream connection failed` | **다른 클라이언트가 연결 중** → 브라우저 탭 닫기 |
| 영상이 거꾸로/좌우반전 | `cv2.flip(frame, 1)` 또는 `cv2.rotate()` 추가 |

---

## D-2. 단계 3 폰 조종 / 자율 모드 / HC-SR04

| 증상 | 원인·해결 |
|---|---|
| 거리 뱃지 항상 `📏 ∞` | HC-SR04 미장착, VCC=3.3V(IO4·IO2 옆) 또는 5V로, TRIG=GPIO4, ECHO=GPIO2 확인. 새 배선은 PSRAM 비활성화 불필요 |
| 거리값이 들쭉날쭉 (3.3V VCC) | 일부 HC-SR04 모듈은 3.3V에서 약함. 5V로 분기해서 공급 |
| **HC-SR04 연결 시 부팅 무한 루프** (시리얼에 `rst:0x1 (POWERON_RESET)` 반복, "모터·서보 초기화..." 직전·직후에서 끊김) | **GND 핀 위치를 IO0 옆 GND로 변경**. ESP32-CAM은 GND 핀이 3개인데 위치마다 보드 내부 라우팅이 달라 전압 강하/노이즈 차이가 큼. **5V 바로 옆 GND**가 가장 흔한 함정 — 모터 리턴 전류와 라우팅이 겹쳐 HC-SR04 idle 전류만으로도 전압이 무너짐. **IO0 바로 옆 GND**로 옮기면 즉시 해결됨 |
| 자율 모드 토글해도 직진만 함 | 거리 999 → "장애물 없음"으로 인식. HC-SR04 배선부터 점검 |
| 자율 모드 K-턴 좌·우 반대 | 펌웨어 `startAvoid()`의 `turnLeft` 인자나 서보 방향 확인 |
| 안드로이드 크롬 기울기 "신호 없음" | 진단 라인 탭 → 도움말 모달 → `chrome://flags` → "Insecure origins treated as secure"에 `http://192.168.4.1` Enabled → Relaunch |
| iOS 기울기 권한 팝업이 안 뜸 | 설정 > Safari > 고급 > 모션 및 방향 액세스 ON. HTTP에선 권한 자체가 거부될 수 있음 |
| 직진이 한쪽으로 쏠림 | 화면의 `조향 중심` `−`/`+`로 트림 (70~110, localStorage 저장) |
| 영상은 나오는데 명령 끊김 | 포트 80과 81을 분리했음에도 끊기면 폰 Wi-Fi 신호 약함. 차량과 가까이 |
| `/stop` 호출했는데 자율 모드가 계속됨 | `/stop`은 즉시 수동 모드로 복귀시키도록 펌웨어 동작. 페이지 새로고침 |

---

## E. UDP 명령이 안 먹힘

1. 시리얼 모니터에 `Received: ...` 로그가 뜨는지 확인
2. 안 뜨면: 포트 번호 일치하는지 (`udp_port: 4210`)
3. JSON 형식 확인: `{"speed": 100, "steering": 90}` (따옴표·콜론 정확히)
4. ESP32와 PC가 같은 네트워크인지 (위 C번 다시 확인)

---

## F. 모터가 안 돌아감

| 증상 | 점검 |
|---|---|
| 아무 반응 없음 | L298N 5V LED 점등 확인, IN1·IN2 결선 확인 |
| 한쪽으로만 돌아감 | IN1·IN2 둘 다 HIGH 또는 둘 다 LOW → 전진/후진 둘 다 0 |
| 약하게 돌다가 멈춤 | 전류 부족 → 배터리 충전 또는 모터용 별도 전원 |
| 소리만 나고 안 돌아감 | PWM duty 너무 낮음 → speed 100 이상 시도 |

---

## G. 서보가 떨림 / 이상 동작

| 증상 | 원인·해결 |
|---|---|
| 계속 떨림 | 전원 노이즈 → ESP32와 서보 사이 전원 분리 |
| 한 방향으로 끝까지 가서 멈춤 | 각도 범위(0~180) 초과 → 코드의 min/max 확인 |
| 처음에 큰 소리 | 정상(초기화 동작), 이후 안정되면 OK |

---

## H. 차선이 안 잡힘

1. **조명** 충분한지 (어두우면 흰색 차선이 회색으로 인식)
2. **HSV 튜닝 모드(`t` 키)**에서 흰색 마스크가 차선 부분만 흰색이 되도록 슬라이더 조정
3. 차선의 폭이 너무 가는지 (실제 자전거용 도로 표지테이프 권장 폭 5cm)
4. ROI가 너무 좁은지 (`config.json`의 `roi_y_start` 조정)

---

## I. 자율주행 시 비틀거림

| 증상 | 조정 |
|---|---|
| 좌우로 진동 | `Kp` 너무 큼 → 감소 (`-` 키) |
| 반응 느려서 차선 이탈 | `Kp` 증가 (`+` 키) |
| 직진은 OK, 곡선에서 이탈 | `k_angle` 증가 (`a` 키) |
| 곡선은 OK, 직진에서 흔들림 | `k_position` 감소 (`v` 키) |
| 전반적으로 너무 빠름 | `base_speed` 감소 (`x` 키) |

---

## J. Python 환경 문제

```
ModuleNotFoundError: No module named 'cv2'
```
→ `pip install opencv-python`

```
ModuleNotFoundError: No module named 'ultralytics'
```
→ `pip install ultralytics` (단계 9에서만 필요)

```
PermissionError
```
→ VSCode·터미널을 **관리자 권한**으로 실행

```
한글 깨짐
```
→ `chcp 65001` 후 다시 실행 (Windows)

---

## K. 그래도 안 될 때

1. **사진/영상 캡처** + **에러 메시지 전체 복사**
2. 어떤 단계에서, 무엇을 했고, 무엇이 안 됐는지 기록
3. 교사 또는 동료에게 도움 요청
4. 해결되면 **이 문서에 사례 추가** (다음 학생을 위해)

---

## L. 재부팅·초기화 절차

상황이 꼬였을 때 **모든 것을 다시 시작**:

1. Python 프로그램 종료 (`q` 키 또는 `Ctrl+C`)
2. ESP32-CAM 전원 차단 → 5초 대기 → 재인가
3. 시리얼 모니터에서 IP 재확인
4. 브라우저 탭 모두 닫기
5. Python 프로그램 다시 실행