rzeldent/esp32-cam-ai

ESP32-CAM을 강력하고 원격 제어가 가능한 AI 지원 카메라 시스템으로 변환하세요!

이 프로젝트는 ESP32-CAM을 이미지를 캡처하고, LED를 제어하며, 플래시 조명을 관리하고, 시스템 진단을 제공할 수 있는 원격 제어 가능한 MCP (Model Context Protocol) 서버로 변환합니다. 이 서버는 Model Context Protocol을 통해 이러한 기능들을 노출하여, AI 어시스턴트 및 자동화 시스템과 쉽게 통합할 수 있도록 합니다.

요약: Copilot 또는 VSCode의 AI-Toolkit, Home Assistant (HA), Node-Red와 같은 다른 AI 디지털 어시스턴트를 사용하여 ESP32-CAM을 활용하고, 정보(카메라, wifi 또는 시스템 상태)를 얻거나 GPIO(led, flash)를 설정하세요.

LED 제어: ESP32-CAM의 내장 LED를 켜거나 끕니다
플래시 제어: 설정 가능한 지속 시간(5-100ms)으로 카메라 플래시를 트리거합니다
카메라 캡처: 선택적 플래시 지원을 포함하여 사진을 촬영합니다 (<4KB base64에 최적화됨)
실시간 제어: MCP 도구 호출에 즉각적으로 응답합니다

WiFi 상태: 네트워크 연결 정보, 신호 강도, IP 주소
시스템 상태: 메모리 사용량, 업타임 (uptime), CPU 주파수, SDK 버전
하드웨어 정보: 플래시 저장소, 스케치 크기, 리셋 원인

WiFi 자동 재연결: 자동 복구 기능을 갖춘 견고한 연결 관리
mDNS 지원: 로컬 네트워크에서의 쉬운 장치 발견
OTA 업데이트: 무선 펌웨어 업데이트 (Over-the-air updates)
워치독 타이머 (Watchdog Timer): 시스템 신뢰성 및 충돌 복구
CORS 지원: 웹 브라우저 호환성을 위한 교차 출처 리소스 공유 (Cross-Origin Resource Sharing) 헤더

표준 준수: 완전한 MCP 2024-11-05 프로토콜 구현
도구 스키마 (Tool Schema): 모든 도구에 대한 적절한 JSON 스키마 검증
오류 처리: 적절한 코드를 포함한 포괄적인 오류 보고
알림: notifications/initialized 지원

AI-Thinker ESP32-CAM(주요 대상)

• ESP32-CAM TTGO T-Series
• ESP32-CAM M5Stack
• ESP32-CAM Wrover Kit

Camera (카메라): OV2640 센서 (내장)
LED: 내장 LED (설정 가능한 GPIO)
Flash (플래시): 내장 플래시 LED (설정 가능한 GPIO)
Power (전원): USB를 통한 5V 또는 외부 공급
Programming (프로그래밍): FTDI USB-to-Serial 어댑터 또는 ESP32-CAM 메인보드 (초기 업로드용)

Important (중요): 최적의 이미지 캡처를 위해, 플래시 LED가 아래를 향하도록 ESP32-CAM을 배치하십시오. 이 방향은 다음과 같은 효과를 제공합니다:

• 피사체에 적절한 조명 방향 제공
• 플래시 반사 문제 방지
• 사진에서 자연스러운 조명 보장
• 대부분의 사용 사례에서 기대되는 관점(perspective)과 일치

카메라 렌즈는 피사체를 향해야 하며, 작은 플래시 LED(보통 렌즈 옆에 위치)는 촬영 대상이 되는 표면이나 피사체를 향해 아래를 가리켜야 합니다.

• PlatformIO IDE 또는 CLI
• Visual Studio Code (권장)
• ESP32 개발 프레임워크 (development framework)

ArduinoJson

• JSON 파싱 (parsing) 및 생성

ESP32 Camera

• 카메라 기능 (ESP32 SDK에 포함됨)

Base64

• 이미지 인코딩 (Arduino core에 포함됨)

• 커스텀 MCP 라이브러리 (포함됨)

git clone https://github.com/yourusername/esp32-cam-ai.git
cd esp32-cam-ai

프로젝트 루트 디렉토리에 WiFi 자격 증명을 포함한 .env 파일을 생성하십시오:

WIFI_SSID=YourWiFiNetwork
WIFI_PASSWORD=YourPassword

Important (중요): 프로젝트가 성공적으로 빌드(build)되려면 .env 파일이 반드시 필요합니다. 빌드 시스템은 컴파일(compilation) 중에 이 자격 증명을 자동으로 읽어 펌웨어(firmware)에 전달합니다.
.env.template 템플릿 파일이 제공되므로, 이를 .env로 복사하여 자격 증명을 업데이트할 수 있습니다.

Note (참고): 보안상의 이유로 .env 파일은 버전 관리 시스템(version control)에 커밋(commit)해서는 안 됩니다. 반드시 .gitignore 파일에 포함되어 있는지 확인하십시오.

pio run --target upload

pio device monitor

시리얼 출력에서 IP 주소를 찾으십시오:

Local IP address: 192.168.1.132
or
mDNS hostname: esp32-7c9ebdf16a10.local

IP 주소를 찾는 다른 방법은

• DHCP 서버에서 IP 예약 (IP reservation) 확인
• avahi를 사용하여 _jsonrpc에 대한 80번 포트 mDNS 체크 수행

이 프로젝트는 include/camera_config.h에 여러 카메라 설정(camera configurations)을 포함하고 있습니다.

:

// AI-Thinker ESP32-CAM을 위한 현재 설정
constexpr camera_config_t esp32cam_aithinker_settings = {
.pin_pwdn = 32,
...

현재는 AI-Thinker만 활성화되어 있습니다. 이는 향후 다른 카메라로 확장될 수 있습니다.

빌드 플래그(build flags)에서 LED 및 플래시(Flash) 핀을 설정하십시오:

build_flags =
-DLED_GPIO=33 # 내장 LED 핀
-DLED_ON_LEVEL=LOW # 켜짐(On)을 위한 GPIO 레벨
...

ESP32-CAM의 내장 LED 상태를 제어합니다.

매개변수 (Parameters):

state

(필수): "on"

또는 "off"

예시 (Example):

{
"jsonrpc": "2.0",
"method": "tools/call",
...

지정된 시간 동안 카메라 플래시를 트리거합니다.

매개변수 (Parameters):

duration

(선택 사항): 밀리초(ms) 단위의 지속 시간 (5-100ms, 기본값: 50ms)

예시 (Example):

{
"jsonrpc": "2.0",
"method": "tools/call",
...

ESP32-CAM 센서로부터 사진을 캡처합니다.

매개변수 (Parameters):

flash

(선택 사항): "on"

또는 "off"

• 캡처 중에 플래시 사용

응답 (Response):

• 텍스트 상태 메시지
• Base64로 인코딩된 JPEG 이미지 데이터 (4KB 미만으로 최적화됨)
• 이미지 메타데이터 (크기, MIME 타입)

예시 (Example):

{
"jsonrpc": "2.0",
"method": "tools/call",
...

현재 네트워크 연결 정보를 반환합니다.

필요한 매개변수 없음.

응답 포함 내용:

• IP 주소
• 신호 강도 (dBm)
• MAC 주소
• 게이트웨이(Gateway) IP
• DNS 서버

포괄적인 시스템 진단 및 상태 모니터링을 제공합니다.

필요한 매개변수 없음.

응답 포함 내용:

하드웨어 정보 (Hardware Information):

CPU 주파수 (CPU Frequency): MHz 단위의 동작 주파수 (통상 240 MHz)
플래시 크기 (Flash Size): 바이트 단위의 총 플래시 메모리 (통상 4MB)
플래시 속도 (Flash Speed): Hz 단위의 플래시 메모리 클럭 속도 (통상 40MHz)

메모리 통계 (Memory Statistics):

Free Heap: 현재 사용 가능한 RAM (byte 단위)Min Free Heap: 부팅 이후 최소 여유 힙 (메모리 압박 지표)Max Alloc Heap: 사용 가능한 최대 연속 메모리 블록Sketch Size: 컴파일된 펌웨어 크기 (byte 단위)Free Sketch Space: 펌웨어 업데이트를 위한 여유 공간

시스템 정보 (System Information):

Uptime: 마지막 부팅 이후 경과 시간 (초 단위)SDK Version: ESP-IDF 프레임워크 버전Reset Reason: 시스템이 마지막으로 재시작된 이유 (1=전원 켜짐, 2=외부 리셋, 3=소프트웨어 리셋, 12=브라운아웃 (brownout), 14=워치독 (watchdog))Internal Temperature: ESP32 칩 온도 (Celsius 단위)

장치 상태 (Device Status):

Camera Initialized: 카메라 준비 상태 (실패 시 에러 코드 포함)

온도 모니터링 가이드라인 (Temperature Monitoring Guidelines):

• 정상: 40-60°C | 부하 높음: 60-75°C | 경고: >75°C | 위험: >85°C

메모리 상태 지표 (Memory Health Indicators):

• 양호: 여유 메모리 >100KB | 보통: 50-100KB | 압박 높음: <50KB | 위험: <30KB

# 플래시를 사용하여 이미지 캡처
$body = '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "capture", "arguments": {"flash": "on"}}}'
Invoke-RestMethod -Uri "http://192.168.1.132/" -Method Post -Body $body -ContentType "application/json"

MCP 서버는 Model Context Protocol을 지원하는 AI 어시스턴트와 통합할 수 있습니다:

MCP 클라이언트 설정 (Configure MCP Client) (mcp.json):

{
"servers": {
"esp32-cam-ai": {
...

자연어 명령 사용 (Use Natural Language Commands):

• "ESP32-CAM으로 사진을 찍어줘"
• "LED를 켜줘"
• "WiFi 상태를 확인해줘"
• "카메라 플래시를 터뜨려줘"

VSCode의 AI-Toolkit: 프롬프트를 생성하고 커스텀 MCP를 사용합니다. https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio
Home Assistant: 카메라 캡처에 의해 트리거되는 자동화를 생성합니다
Node-RED: 카메라 및 LED 제어를 포함한 시각적 워크플로우를 구축합니다
커스텀 애플리케이션 (Custom Applications): 표준 HTTP 요청을 통해 통합합니다

┌───────────────────┐ ┌───────────────────┐ ┌───────────────────┐
│ MCP Protocol │────│ Tool Handlers │────│ Hardware Layer │
│ │ │ │ │
...

esp32-cam-ai/
├── src/
│ └── main.cpp # 메인 애플리케이션 코드
...

자동 재연결 (Auto-reconnection): 지수 백오프 (Exponential backoff)를 이용한 자동 재시도
연결 모니터링 (Connection monitoring): 5초마다 주기적인 상태 확인
복구 메커니즘 (Recovery mechanisms): 최대 실패 횟수 도달 시 시스템 재시작
이벤트 핸들링 (Event handling): 적절한 WiFi 이벤트 관리

워치독 타이머 (Watchdog Timer): 10초 타임아웃으로 시스템 멈춤 (Hang) 방지
메모리 관리 (Memory Management): 카메라 프레임 버퍼 (Frame buffer)의 적절한 정리
에러 핸들링 (Error Handling): 포괄적인 에러 코드 및 메시지
OTA 지원 (OTA Support): 유지보수를 위한 원격 펌웨어 업데이트

초기화 체크 (Initialization Checks): 동작 전 카메라 검증
프레임 버퍼 관리 (Frame Buffer Management): 적절한 할당 및 정리
플래시 타이밍 (Flash Timing): 플래시와 캡처 타이밍 동기화
품질 설정 (Quality Settings): 구성 가능한 해상도 및 압축률

// 시리얼 출력에서 카메라 초기화 확인
Camera init failed with error 0x[code]

해결 방법 (Solutions):

• 카메라 연결 상태 확인
• 전원 공급 확인 (충분한 전류 확보)
• 다른 카메라 설정 시도

// WiFi 자격 증명 및 네트워크 확인
Failed to connect to WiFi. Error code: [code]

해결 방법 (Solutions):

• .env 파일 내 SSID 및 비밀번호 확인
• 프로젝트 루트 디렉토리에 .env 파일이 존재하는지 확인
• 2.4GHz 네트워크 사용 가능 여부 확인 (ESP32는 5GHz를 지원하지 않음)
• 충분한 신호 강도 확보
• .env 파일 형식이 올바른지 확인 (= 주변에 공백 없음)

WIFI_SSID is not defined. Please define it in your environment variables or in the code.
WIFI_PASSWORD is not defined. Please define it in your environment variables or in the code.

해결 방법 (Solutions):

• 프로젝트 루트 디렉토리에 .env 파일 생성
• .env 파일에 올바른 형식으로 WiFi 자격 증명 추가:

WIFI_SSID=YourNetworkName
WIFI_PASSWORD=YourPassword

• = 기호 주변에 공백이 없는지 확인
• 특수 문자나 공백을 포함하는 값은 따옴표로 감싸기

// 힙 (Heap) 사용량 모니터링
Free Heap: [bytes] bytes

해결 방법 (Solutions):

• 4KB 제한을 넘지 않도록 이미지 품질/해상도(resolution)를 낮춤
• 프레임 버퍼(frame buffer) 개수를 늘림
• 메모리 누수(memory leaks) 확인

진단 정보를 위해 시리얼 출력(serial output)을 모니터링하세요:

CPU Freq: 240 MHz
Free heap: 189092 bytes
WiFi got IP address: 192.168.1.132
...

특정 요구 사항에 맞춰 camera_config.h를 수정하세요:

// 고품질 설정 (4KB 제한을 초과할 수 있음)
.frame_size = FRAMESIZE_SVGA, // 800x600
.jpeg_quality = 8, // 더 높은 품질
...

추가 도구(tools)로 MCP 서버를 확장하세요:

도구 정의 추가 (handle_tools_list() 내)

도구 핸들러(tool handler) 구현

handle_tools_call()에 등록

import requests
import base64
import json
...

const axios = require('axios');
const fs = require('fs');
async function captureImage(esp32IP, useFlash = false) {
...

저장소(repository) 포크(Fork)

기능 브랜치(feature branch) 생성: git checkout -b feature/new-tool

변경 사항 커밋(Commit): git commit -am 'Add new MCP tool'

브랜치에 푸시(Push): git push origin feature/new-tool

풀 리퀘스트(Pull Request) 생성

• 기존 코드 스타일 및 패턴을 따를 것
• 새로운 기능에 대해 적절한 에러 처리(error handling)를 추가할 것
• 새로운 도구에 대한 문서를 업데이트할 것
• 실제 하드웨어에서 철저히 테스트할 것

이 프로젝트는 MIT License 라이선스 하에 배포됩니다 - 자세한 내용은 LICENSE 파일을 참조하세요.

ESP32 Community: 우수한 카메라 라이브러리 제공
Model Context Protocol: 사양(specification) 작성자
PlatformIO: 우수한 개발 환경 제공
ArduinoJson: 효율적인 JSON 처리를 위한 라이브러리

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: 이 README 및 코드 내 주석

이미지 캡처(Image Capture): QVGA (320x240) JPEG 기준 약 2-3초
도구 응답 시간(Tool Response Time): LED/플래시(Flash) 제어 기준 500ms 미만
WiFi 재연결(WiFi Reconnection): 복구 시간 약 10-15초
메모리 사용량(Memory Usage): 정상 작동 중 약 200KB의 여유 힙(free heap)
네트워크 지연 시간(Network Latency): 로컬 네트워크 요청 기준 100ms 미만

Flash Storage (플래시 저장소): 컴파일된 펌웨어(compiled firmware) 기준 약 1.2MB
RAM Usage (RAM 사용량): 기본 기능 및 카메라 버퍼(camera buffers)를 위해 약 100KB
CPU Usage (CPU 사용량): 유휴(idle) 상태 시 5% 미만, 이미지 캡처(image capture) 중 약 30%
Network Bandwidth (네트워크 대역폭): 이미지당 약 50KB (QVGA 품질 12, base64 기준 4KB 미만)

JPEG 품질 낮추기 (Lower JPEG Quality): 파일 크기 및 캡처 시간 감소
프레임 크기 축소 (Smaller Frame Size): 성능 및 메모리 사용량 개선
프레임 버퍼 개수 감소 (Reduce Frame Buffer Count): 메모리를 절약하지만 안정성에 영향을 줄 수 있음
WiFi 전력 관리 (WiFi Power Management): 성능과 전력 소비 사이의 균형 조절

Open HTTP Server (개방형 HTTP 서버): 내장된 인증 기능 없음 (필요 시 사용자 정의 인증 추가)
로컬 네트워크 액세스 (Local Network Access): 모든 네트워크 클라이언트가 장치에 접속 가능
암호화되지 않은 통신 (Unencrypted Communication): 민감한 배포 환경의 경우 HTTPS 고려 필요
IP 주소 노출 (IP Address Exposure): 네트워크 스캔 시 장치 IP가 노출됨

카메라 배치 (Camera Placement): 의도한 모니터링을 위해 장치를 적절한 위치에 배치
액세스 제어 (Access Control): 장치 및 프로그래밍 핀(programming pins)에 대한 물리적 접근 보안
전원 공급 (Power Supply): 데이터 손상을 방지하기 위해 안정적인 전원 확보
SD 카드 (SD Card): 사용 시 무단 접근으로부터 보호