ESP32-CAM 자율주행 자동차 — 사용 설명서

main.py · 차선을 인식해 스스로 달리는 자율주행 프로그램

영상 수신 → 차선 인식 → 제어 계산 → ESP32로 명령 전송 순서로 동작합니다.

1. 준비물과 사전 점검

• ESP32-CAM 자동차가 켜져 있고 같은 와이파이(Auto_Car_01)에 접속되어 있어야 합니다.
• 노트북도 같은 네트워크에 있어야 합니다. (단계 4~9는 STA 모드, UDP 포트 4210)
• 파이썬 환경에 opencv-python(GUI 버전)과 numpy가 설치되어 있어야 합니다.
• YOLO 객체 감지(단계 9)를 쓰려면 pip install ultralytics가 추가로 필요합니다. 없어도 차선주행(단계 6~8)은 정상 동작합니다.

2. 실행 방법

방법 A — 더블클릭 권장

자율주행_실행.bat 파일을 더블클릭합니다. 검은 콘솔 창이 열립니다.

방법 B — 명령어

python opencv/python/main.py

실행 후 IP 입력

• 콘솔에 ESP32-CAM IP 끝자리를 입력하세요 가 나오면 자동차의 IP 끝자리 숫자를 입력하고 Enter를 누릅니다.
• 그냥 Enter만 누르면 config의 기본값(현재 74)을 사용합니다.
• 연결에 성공하면 연결 완료! 와 함께 영상 창(Autonomous Car)이 뜹니다.

3. 화면 구성

영상 창은 위쪽에 카메라 영상(차선 인식 표시), 아래쪽에 정보 패널 3칸으로 되어 있습니다.

• 왼쪽 (STATUS / CONTROL) — 모드, FPS, 지연시간, 속도, 조향각, 중립값(Neutral), 차선 각도 등.
• 가운데 (HSV VALUES) — 흰색/노란색 차선 인식 색 범위. 아래에 START HERE 안내 박스(처음 사용자용).
• 오른쪽 (CONTROLS) — 키 목록을 DRIVE / VISION / SYSTEM 으로 묶어 표시.

화면 글자는 OpenCV 제약으로 영어로 표시됩니다. (콘솔 출력은 한글)

4. 두 가지 주행 모드

모드	진입	설명
자동 (AUTO)	s 로 시작/정지	차선을 인식해 스스로 조향·주행. 평소 사용하는 모드.
수동 (MANUAL)	m 으로 전환	키보드로 직접 운전. 조향 중립 맞추기·테스트에 사용.

• 처음에는 자동 모드(정지 상태)로 시작합니다. s 를 누르면 달리기 시작합니다.
• 위험하면 언제든 Space(긴급 정지)를 누릅니다.

5. 전체 조작키

공통

키	기능
s	자동주행 시작 / 정지
m	수동 ↔ 자동 모드 전환
Space	긴급 정지
h	도움말(콘솔 출력)
q	프로그램 종료
p	키 코드 디버그 모드(방향키 코드 확인)

주행 제어 (자동)

키	기능
w / x	기본 속도 증가 / 감소
+ / -	Kp 증가 / 감소
a / d	k_angle 증가 / 감소 (커브 대응)
z / v	k_position 증가 / 감소 (좌우 위치 복귀)
e / r	조향 중립 트림 ← / → (캘리브레이션, 자동 저장)

수동 운전 (m 으로 진입 후)

키	기능
i / k (또는 ↑ / ↓)	속도 증가 / 감소
j / l (또는 ← / →)	좌회전 / 우회전
n	조향 중립으로 리셋

영상·차선 인식

키	기능
1 / 2 / 3	차선 색 선택 (1=흰색, 2=검정, 3=주황)
t	HSV 튜닝 모드 켜기/끄기 (끄면 자동 저장)
c	HSV 설정 저장(튜닝 모드일 때)
[ / ]	검출(초록) ROI를 위로 확장 / 축소
, / .	흰색 밝기 최소값 낮춤 / 높임
; / '	흰색 채도 최대값 높임 / 낮춤
f / g	프레임 스킵 증가 / 감소 (지연 줄이기)
y / u	YOLO 실행 주기 증가 / 감소 (단계 9)

6. 제어 게인 이해 — k_position 과 k_angle

조향은 다음 식으로 계산됩니다.

조향 보정 = k_position × 위치오차 + k_angle × 각도오차
조향각   = 중립(steering_neutral) + 보정

• k_position — 가까운 차선이 화면 중심에서 좌우로 얼마나 벗어났는지(위치)에 반응합니다. 차를 차로 가운데로 끌어당깁니다.
• k_angle — 먼 차선과 가까운 차선을 잇는 선의 기울기(방향·커브)에 반응합니다. 커브를 미리 따라가게 합니다.

7. 조향 중립(직진) 캘리브레이션

앞바퀴가 정지 상태에서 똑바로 직진하지 않으면 중립값을 맞춰야 합니다.

1. m 으로 수동 모드에 들어갑니다.
2. e(왼쪽) / r(오른쪽) 키로 앞바퀴가 정확히 직진이 되는 지점을 찾습니다.
3. 누를 때마다 config.json 에 자동 저장되어 다음 실행부터 그대로 적용됩니다.

화면 왼쪽 패널의 Neutral: NN 으로 현재 중립값을 확인할 수 있습니다.

8. ROI(인식 영역) 조정

• 검출 영역(초록)은 화면에서 차선을 찾는 범위입니다. 시작값은 세로로 가장 크게(위 30% 지점부터 바닥까지), 가로 중앙 80%로 설정되어 있습니다.
• 주행 중 [(위로 확장) / ](축소)로 세로 길이를 조절합니다.
• 더 넓게/좁게 고정하려면 config/config.json 의 lane_detection 에서 roi_far_y(작을수록 위로 큼), roi_near_y, roi_x_ratio(가로 비율)를 바꿉니다.

9. 차선 색 선택과 HSV 튜닝

흰색 HSV 미세 튜닝

조명이나 차선 색에 따라 인식이 잘 안 되면 색 범위를 조정합니다.

1. t 를 눌러 튜닝 모드를 켭니다. 슬라이더 창이 뜹니다.
2. White Brightness Min(흰색 밝기 최소), White Saturation Max(흰색 채도 최대), Yellow Hue/Brightness 를 조정합니다.
3. 다시 t 를 누르면 저장하며 종료, c 는 저장만 합니다.

권장값 — White Brightness Min 200~240, White Saturation Max 30~80, Yellow Hue 15~35.

10. 문제 해결

증상	원인 / 해결
영상 창이 안 뜨고 GUI: NONE / function is not implemented	headless OpenCV 문제. pip uninstall -y opencv-python-headless 후 pip install opencv-python.
시작하자마자 No module named 'ultralytics' 로 종료	보통은 자동 비활성화되지만, 단계 9를 쓰려면 pip install ultralytics.
영상 스트림 연결 실패 / 창이 안 뜸	ESP32 전원·와이파이 확인, IP 끝자리 재확인, 같은 네트워크인지 확인.
한글이 콘솔에서 깨짐	bat은 chcp 65001 적용됨. 직접 실행 시 콘솔을 UTF-8로 두거나 bat 사용.
수동 조향이 반대로 돈다	j/l 은 하드웨어에 맞춰 이미 조정됨. 그래도 반대면 서보 배선 확인.
자동 주행이 차선 반대로 꺾인다	수동과 별개 원인(제어 부호/서보 배선). 담당자에게 문의.
화면이 끊기고 지연이 크다	f 로 프레임 스킵을 늘리거나, u 로 YOLO 주기를 늘림.

11. 현재 기본 설정값 (config/config.json)

항목	값	설명
base_speed	220	기본 속도 (w/x)
kp	1.4	비례 상수
k_position	1.0	위치 복귀 게인 (z/v)
k_angle	2.5	커브 대응 게인 (a/d)
steering 범위	30 ~ 150	조향 최소~최대
steering_neutral	90	직진 중립 (e/r 로 조정)
roi_far_y	0.30	ROI 위 경계(작을수록 위로 큼)
roi_near_y	0.90	ROI 아래/근거리 경계
roi_x_ratio	0.8	ROI 가로 비율(중앙 기준)
lane_color	white	차선 색 (1/2/3 로 선택, white/black/orange)