ai-passport 딥다이브
— 작은 웨어러블로 배우는 C 펌웨어의 설계와 수명 관리

1프로젝트 한줄 요약

ai-passport는 FoloToy의 작은 웨어러블 기기에서 화면·버튼·오디오·배터리·무선·절전 기능을 재사용하도록 만든 ESP-IDF 기반 C 펌웨어와 개발 자료 모음입니다. 제품 소개는 docs/README.md에 있고, 프로그램의 시작점은 main/main.c의 app_main()입니다.

이 저장소에서 배울 핵심은 AI 모델 호출법보다, 여러 하드웨어 기능이 같은 메모리와 시간을 나눠 쓰는 방법입니다. 기본 브랜치의 빌드 대상에는 LLM 추론 엔진이나 대화 서버가 없습니다. AI 코딩 도구가 읽을 지침과 스킬은 있지만, 그것과 기기 안에서 돌아가는 AI 모델은 다른 구성 요소입니다.

기본 프로그램에서 직접 제공하는 일

main/main.c의 DEMOS[]에 위 7개 페이지가 등록됩니다. Wi-Fi는 인터넷에 연결하거나 자격 증명을 저장하지 않고, BLE는 사용자 데이터를 주고받는 GATT 앱을 구현하지 않습니다. 범위를 정확히 잡아야 이후 추가할 기능도 정확해집니다.

2왜 주목받는가

2026-10-23 GitHub Trending C Daily에서 9위로 선정되었고, 같은 날 GitHub 기준 스타는 706개, 포크는 281개입니다. 생성일은 2026-07-31입니다. 다만 이 숫자와 순위만으로 유입 경로나 인기의 원인을 확정할 수는 없습니다. 아래는 저장소의 구성에서 추론할 수 있는 관심 요인입니다.

2-1. AI 개발 지침이 실제 하드웨어 경계까지 내려옵니다

AGENTS.md는 핀 배치의 근거, LVGL 잠금, 버튼 콜백의 제한, 작업 종료 순서, 검증 결과의 구분을 명시합니다. skills/README.md에는 개발·환경 준비·빌드·기기 테스트·디버깅을 담당하는 5개 핵심 스킬과 배포 후 경험을 정리하는 스킬이 등록되어 있습니다.

초보자가 AI에게 “타이머 만들어 줘”라고 말할 때 빠뜨리기 쉬운 것이 메모리·버스·수명 제약입니다. 자연어 요구사항을 보드의 제약과 검증 항목에 연결하는 지침이 코드와 함께 있다는 점이 이 저장소의 특징입니다. 이는 지침의 존재에서 확인되는 장점이며, 모든 AI 도구가 같은 품질로 구현한다는 성능 검증은 아닙니다.

2-2. 시작하기 쉬운 구성과, 숨길 수 없는 제약이 함께 있습니다

화면·마이크·스피커·세 버튼이 한 기기에 모여 있어 별도 주변장치를 하나씩 연결하는 부담을 줄일 수 있습니다. 반면 8 MB Flash와 PSRAM 부재는 이미지·소리·화면 버퍼를 무제한으로 늘릴 수 없게 만듭니다. 그래서 작은 기능도 메모리 예산과 종료 절차를 생각하게 하는 학습 재료가 됩니다.

이 표는 개발 구성의 비교입니다. 가격·배터리 시간·처리 속도를 측정한 경쟁 제품 벤치마크는 아닙니다. 같은 크기의 하드웨어라도 원하는 앱이 음성 대화인지, 오프라인 도구인지에 따라 적합성이 달라집니다.

2-3. 커뮤니티 결과물과 기본 코드의 거리를 배울 수 있습니다

docs/reference/README.md에는 음성 키체인, 게임, 독서기, 음성 메모 등의 응용 사례와 메모리·폰트·BLE 경험 글이 정리되어 있습니다. 이는 참고 문서에 소개된 프로젝트입니다. 그 기능이 전부 현재 main/CMakeLists.txt의 빌드에 포함된다는 뜻은 아닙니다.

최근 커밋도 실제 기기 운용과 맞닿아 있습니다. 006c227은 500 mAh 배터리 프로필 수정 PR #110을 병합한 커밋이며, 코드에는 제조사 프로필 80바이트의 일치 검사와 읽기 검증이 있습니다. 눈에 띄는 UI뿐 아니라 기기별 보정 데이터도 소프트웨어 품질의 일부라는 사례입니다.

3기술 스택 전체 지도

이 프로젝트에는 웹 백엔드·브라우저 프론트엔드·데이터베이스 서버 조합이 없습니다. 대신 제어 계층은 C와 ESP-IDF, 화면 계층은 LVGL, 빌드·검증 계층은 CMake·Python·셸·GitHub Actions입니다. package.json, Cargo.toml, pyproject.toml, go.mod, Dockerfile은 커밋 기준 저장소에 없습니다.

3-1. 백엔드에 해당하는 제어 계층

FreeRTOS의 1,000 Hz 설정은 스케줄링의 틱 단위가 1 ms라는 뜻입니다. 모든 작업이 1 ms 안에 끝난다는 보장은 아닙니다. 녹음과 재생은 블로킹 I/O를 포함하므로 별도 태스크에서 진행합니다.

3-2. 프론트엔드에 해당하는 기기 화면

설치 가능한 버전 범위와 현재 고정된 버전을 나눠 읽어야, 같은 소스의 동작을 다시 재현할 수 있습니다. 참고 문서에 다른 LVGL 버전의 경험이 등장하더라도 기본 펌웨어의 버전은 이 잠금 파일로 판단합니다.

3-3. 인프라·빌드·검증

루트 CMakeLists.txt는 cmake_minimum_required(VERSION 3.16)과 project(FoloToy-AI-Passport)를 선언합니다. 여기서 3.16은 최소 요구값이지 설치된 CMake의 확정 버전이 아닙니다. main/CMakeLists.txt는 12개 C 파일을, BSP의 CMake 파일은 8개 C 파일을 등록합니다.

독립적인 Dockerfile은 없지만 펌웨어 CI는 espressif/esp-idf-ci-action을 사용합니다. .github/workflows/build-firmware.yml에는 태그 push 시 릴리스를 만드는 설정이 있습니다. 릴리스 자동화 코드가 존재하는 것과 2026-10-23에 게시된 최신 릴리스가 없는 것은 모순이 아닙니다.

여기서 테스트 개수는 tools/validate.sh가 실행하도록 구성된 대상 수입니다. 테스트가 작성되어 있다는 사실과 특정 환경에서 실행해 통과했다는 사실은 구분해야 합니다.

4아키텍처 심화 분석

4-1. 시스템 구조를 한 장으로 보기

화살표는 호출 또는 데이터 전달 관계입니다. 모든 블록이 동시에 독립적으로 실행되는 것은 아닙니다. 기본 메뉴는 한 페이지를 활성화하며, Wi-Fi·BLE는 해당 페이지의 시작·종료 함수가 자원을 관리합니다. enter()·exit()은 호출자가 LVGL 잠금을 잡고, key()는 각 함수 내부에서 UI 접근 시 잠금을 잡습니다.

설계 ① 계층 분리와 자원 소유권

bsp_i2c_init()은 정적 핸들 s_bus가 이미 있으면 ESP_OK를 반환합니다. bsp_audio_init()과 bsp_battery_init()은 이 버스를 공유합니다. 앱은 SDA/SCL을 다시 설정하기보다 공개 BSP 함수를 이용합니다.

중요한 것은 파일을 나눈 모양보다 누가 생성하고, 누가 정리하는가입니다. I2C 버스는 components/bsp/src/bsp_i2c.c, 버튼의 ADC와 보정 핸들은 components/bsp/src/bsp_button.c, 페이지 객체는 각 main/demo_*.c가 소유합니다. 버튼 드라이버의 정리가 실패하면 ADC를 먼저 지우지 않는 것도 이 소유권을 지키기 위해서입니다.

상수의 중심은 components/bsp/include/bsp_pins.h입니다. 화면 크기 240×320, SPI 80 MHz, 버튼 임계 전압, I2C 주소를 여기서 가져옵니다. 다른 보드로 옮길 때도 핀만 바꾸면 충분하다고 가정하면 안 됩니다. 디스플레이 초기화와 칩별 동작 계약까지 함께 검토해야 합니다.

설계 ② 이벤트 큐와 순수 상태 머신

버튼 콜백은 공유 esp_timer 태스크에서 호출됩니다. 그 자리에서 3초 녹음을 수행하면 같은 타이머 태스크의 다른 작업도 늦어집니다. on_key()는 깨움 입력 보호와 준비 상태를 확인한 뒤 짧은 이벤트만 큐로 보냅니다.

// main/main.c: on_key()의 큐 전달 부분
if (!s_input_ready || !s_input_queue) return;
const input_event_t input = { .btn = btn, .event = ev };
(void)xQueueSend(s_input_queue, &input, 0);

// input_task(): 실제 입력 처리는 다른 태스크에서
if (xQueueReceive(s_input_queue, &input, portMAX_DELAY) == pdTRUE) {
    process_input(&input);
}

전송 대기값 0은 큐에 공간이 생길 때까지 기다리지 않겠다는 뜻입니다. INPUT_QUEUE_DEPTH는 8이고 전송 반환값은 버립니다. 따라서 큐가 꽉 차면 이벤트가 유실될 수 있습니다. 이는 콜백 지연을 줄이는 대신 감수하는 경계이며, 입력이 반드시 보존되어야 하는 앱은 유실 횟수와 처리 정책을 설계해야 합니다.

메뉴의 선택 규칙은 demo_navigation_handle()로 분리됩니다. 이 함수는 화면을 그리지 않고 REFRESH, ENTER, EXIT, FORWARD 같은 다음 행동을 반환합니다.

// main/demo_navigation.c: 첫 항목에서 위를 누르면 마지막으로 순환
navigation->selected = (navigation->selected + navigation->count - 1)
                     % navigation->count;

// 활성 페이지에서 OK 길게 누르기: 종료 요청만 반환
result.action = input == DEMO_NAV_INPUT_OK_LONG
              ? DEMO_NAV_ACTION_EXIT
              : DEMO_NAV_ACTION_FORWARD;

tests/test_demo_navigation.c는 종료 요청 직후에도 active가 유지됨을 검사합니다. 실제 정리가 성공한 뒤 demo_navigation_complete_exit()가 호출되어야 메뉴 상태로 돌아갑니다. “종료하고 싶다”와 “종료가 끝났다”를 구분한 것입니다.

설계 ③ 페이지 수명과 작업 종료 확인

main/demo.h의 demo_entry_t는 함수 포인터로 페이지의 공통 인터페이스를 정의합니다. 객체 지향 언어의 메서드 표처럼 쓸 수 있지만, C에서는 함수 호출 순서와 자원 수명을 직접 지켜야 합니다.

// main/demo.h: 주석을 풀어 쓴 인터페이스
typedef struct {
    const char *name;
    void (*enter)(void);    // LVGL 잠금 안에서 화면 생성
    void (*exit)(void);     // 작업 정리가 끝난 뒤 화면 삭제
    void (*key)(bsp_btn_t btn, bsp_btn_ev_t ev);
    esp_err_t (*start)(void); // 잠금 밖에서 느린 서비스 시작
    esp_err_t (*stop)(void);  // 잠금 밖에서 작업 중단 확인
} demo_entry_t;

오디오의 demo_audio_stop()은 취소 플래그를 세우고 종료 명령을 보낸 뒤, 최대 2000 ms 동안 세마포어를 기다립니다. 작업은 PCM 청크 사이에서 취소를 확인하고, 더 이상 공유 상태나 UI를 건드리지 않는 시점에 xSemaphoreGive()로 알립니다.

화면 삭제의 조건은 종료 명령을 보냈다는 사실이 아니라, 그 화면을 만질 작업이 멈췄다는 확인입니다. 응답이 시간 안에 오지 않으면 process_input()은 화면을 유지합니다. 재시도할 수 있도록 태스크 핸들도 남겨 둡니다.

설계 ④ 메모리 예산에 맞춘 화면 경계 처리

bsp_lvgl_init()은 40행 단일 버퍼를 설정하며 double_buffer=false, buff_dma=true, swap_bytes=true를 사용합니다. 화면 전체를 두 장 잡아 빠르게 그리는 방향보다 오디오·무선에 남길 내부 RAM을 고려한 구성입니다.

// components/bsp/src/bsp_display_lvgl.c
#define BSP_LVGL_DRAW_BUFFER_LINES 40
.buffer_size   = (uint32_t)BSP_LCD_W * BSP_LVGL_DRAW_BUFFER_LINES,
.double_buffer = false,
.flags = { .buff_dma = true, .swap_bytes = true },

// RGB565는 한 픽셀에 2바이트
// 부분 버퍼: 240 × 40 × 2 = 19,200바이트 = 18.75 KiB
// 전체 화면: 240 × 320 × 2 = 153,600바이트 = 150 KiB

둥근 화면 모서리는 전체 화면을 별도 투명 레이어로 합성하지 않고, LV_EVENT_FLUSH_START의 rounded_flush_event()에서 최종 RGB565 버퍼의 바깥 픽셀을 검게 만듭니다. 반경은 BSP_LVGL_SCREEN_RADIUS=30입니다.

bsp_display_rounded_row_span()은 각 행에서 보이는 x 좌표 범위를 계산합니다. 실제 메모리 접근은 행의 stride를 사용합니다. 버퍼가 항상 화면 너비와 정확히 같은 간격이라고 가정하지 않는다는 점도 살펴볼 만합니다. 기하 계산은 별도 C 파일에 있어 호스트 테스트로 확인할 수 있습니다.

부팅과 배터리 초기화도 같은 관점으로 읽기

app_main()은 깨움 원인 확인 → I2C 준비·검색 → 화면·LVGL 초기화 → 입력 처리·버튼 → 오디오 → 배터리 → 메뉴 순으로 진행합니다. 화면이 실패하면 메뉴를 만들 수 없어 반환하지만, 오디오나 배터리 실패는 해당 항목을 [FAIL]로 표시하여 다른 기능을 남깁니다. Wi-Fi·BLE·절전은 페이지 안에서 시작 실패를 표시할 수 있습니다.

배터리의 bsp_battery_init()은 VERSION 응답을 확인하고, cw_profile_matches()로 업데이트 플래그와 80바이트 전체를 비교합니다. 다르면 cw_update_profile()이 절전 전환 → 쓰기 → 전체 읽기 검증 → 플래그 설정 → 재시작 순서를 수행합니다. 플래그 하나만 보고 데이터 전체가 맞다고 가정하지 않습니다.

이 로직은 assets/battery/wanli-500mah-profile2-xil40x-20261020.txt의 제조사 데이터와 연결됩니다. _Static_assert는 배열 길이 80을 확인하고, tests/test_battery_profile.py는 원본·해석된 바이트의 해시와 C 배열 일치를 검사하도록 작성되어 있습니다. 프로필 쓰기의 성공과 실제 잔량 정확도는 별도 검증 대상입니다.

5디렉토리 구조 해부

파일 수와 줄 수를 범위별로 보기

커밋 기준 추적 파일은 총 351개입니다. 위 집계는 .git/을 제외한 물리적 줄 수이며 빈 줄과 주석도 포함합니다. 관리형 의존성의 다운로드 결과나 ESP-IDF 전체 코드는 포함하지 않습니다. “C 프로젝트”라는 분류만으로 소스의 대부분이 기기에서 실행된다고 생각하지 않도록 범위를 나눠 보세요.

새 기능을 설계할 때의 질문도 이 트리에서 나옵니다. “다른 앱에서도 필요한 칩 동작인가?”라면 BSP, “우리 앱의 메뉴·상태·표시인가?”라면 main/, “칩 없이 검사할 수 있는 계산인가?”라면 순수 로직 파일과 호스트 테스트가 적절합니다.

6학습 포인트 (기술별)

6-1. C: 포인터 문법을 수명과 연결하기

demo_entry_t는 함수 포인터를 저장하고, DEMOS[]는 구현을 등록합니다. const, 구조체 초기화, 배열 크기 계산을 실제 용도로 볼 수 있습니다. lv_obj_t *나 태스크 핸들은 숫자처럼 복사할 수 있어도, 가리키는 대상이 언제까지 유효한지는 별도 문제입니다.

• 읽을 곳: main/demo.h, main/main.c, main/demo_audio.c.
• 작은 실습: 페이지 진입부터 종료까지 생성되는 화면·태스크·세마포어를 각각 표시하고, 삭제 주체를 적습니다.
• 완료 기준: 생성 실패 또는 종료 타임아웃 뒤에도 남아 있어야 하는 핸들을 설명할 수 있습니다.

demo_audio_stop()이 s_task를 지역 변수에 복사하는 이유와, 작업 스스로 핸들을 지우지 않는 이유를 살펴보세요. “포인터에 NULL을 대입했다”는 사실만으로 다른 실행 흐름의 접근이 끝나지는 않습니다.

6-2. FreeRTOS: 짧은 콜백과 긴 작업 나누기

입력에는 큐, 오디오 명령에는 태스크 알림, 종료 확인에는 이진 세마포어가 쓰입니다. 큐는 여러 이벤트를 담고, eSetValueWithOverwrite 알림은 알림값을 덮어씁니다. 그러므로 오디오 알림을 “명령이 순서대로 무한히 쌓이는 목록”으로 이해하면 안 됩니다.

• 읽을 곳: on_key(), input_task(), audio_task().
• 작은 실습: 큐 깊이 8과 알림값 1개의 차이를 그림으로 표현합니다.
• 완료 기준: 연속 입력에서 무엇이 대기하고 무엇이 덮어써지거나 유실될 수 있는지 말할 수 있습니다.

6-3. LVGL: 화면을 그리는 순간과 보내는 순간 구분하기

main/ui_pixel.c는 위젯을 만들고, components/bsp/src/bsp_display_lvgl.c는 그 결과를 LCD에 보내는 경로를 연결합니다. rounded_flush_event()가 다루는 것은 버튼이나 레이블 객체가 아니라 최종 픽셀 버퍼입니다. 그래서 모든 페이지에 동일한 모서리 마스크를 적용할 수 있습니다.

• 읽을 곳: bsp_lvgl_init(), rounded_flush_event(), bsp_display_rounded_row_span().
• 작은 실습: 첫 행·중앙 행·마지막 행의 가시 x 범위를 계산하고 좌우 대칭을 확인합니다.
• 완료 기준: 전체 화면 레이어와 행 단위 마스크가 요구하는 메모리의 차이를 설명합니다.

성능 관점에서는 main/demo_battery.c도 읽어 보세요. 현재 tick()은 LVGL 타이머에서 bsp_battery_soc()와 bsp_battery_mv()를 동기 호출합니다. 각각의 I2C 전송 제한시간은 100 ms이므로, 버스 이상 시 화면 작업을 오래 붙잡을 여지가 있습니다. 모든 I/O가 별도 작업으로 옮겨진 예제라고 일반화하지 말고, 느린 환경에서는 읽기와 표시를 나누는 개선을 생각해 볼 수 있습니다.

6-4. 오디오: 바이트 예산과 시간 예산을 함께 계산하기

// main/demo_audio.c의 설정으로 계산
// 초당 바이트 = 샘플레이트 × 샘플당 바이트 × 채널 수
16000 × 2 × 1 = 32000 바이트/초
32000 × 3     = 96000 바이트   // 3초 전체 녹음 버퍼
512 × 2       = 1024 바이트    // 한 번의 PCM 청크
512 / 16000   = 0.032초        // 청크의 오디오 길이

components/bsp/src/bsp_audio.c의 I2S DMA는 6개 디스크립터·240프레임 설정입니다. 16 kHz에서 모두 차 있을 때 시간 길이는 6 × 240 ÷ 16000 = 0.09초입니다. 실제 여유는 현재 채워진 양에 따라 줄어듭니다. 90 ms라는 숫자는 모든 지연을 흡수한다는 보증이 아닙니다.

임베디드의 메모리 부족은 총 남은 양뿐 아니라, 필요한 크기의 연속 공간을 확보할 수 있는가의 문제입니다. 96,000바이트를 한 번에 요구하는 녹음과 1,024바이트 단위의 전송을 비교하면, 긴 녹음에 순환 버퍼나 스트리밍이 필요한 이유가 드러납니다.

6-5. 드라이버: 쓰기 성공과 상태 확인 분리하기

components/bsp/src/bsp_es8311_sleep_check.c의 bsp_es8311_sleep_check_matches()는 읽은 레지스터에 마스크를 적용합니다. REG0E는 쓰기값 0xFF와 달리 검증 마스크·기대값이 0x7F입니다. 정의되지 않은 비트까지 일치시켜 거짓 실패를 만들지 않으려는 구현입니다.

// 실제 검증식: 검사 대상 비트만 비교
return (actual & check->mask) == (check->value & check->mask);

// REG0E에서 actual=0xFF와 actual=0x7F는 모두 통과
// actual=0x3F는 검사 대상 비트가 달라 실패

또한 components/bsp/src/bsp_audio.c는 audio_track_error()와 감싼 제어·데이터 인터페이스로 첫 하위 오류를 보존합니다. 소스 주석은 esp_codec_dev 1.6.2가 일부 오류를 버리거나 뒤의 성공으로 덮을 수 있음을 이유로 듭니다. 상위 반환값 하나만 믿기 어려울 때 공개 인터페이스 경계에서 오류를 관찰하는 사례로 읽을 수 있습니다.

6-6. 테스트: 정상 동작보다 복구 계약에 주목하기

tests/test_demo_audio_runtime.c는 태스크 생성 실패, 늦은 종료 응답, 첫·중간 녹음 실패, 재생 실패, 취소를 다룹니다. tests/test_bsp_battery.c는 가짜 I2C 동작으로 초기화·프로필 갱신·SOC 및 전압 오류 경로를 검사합니다. 이런 테스트는 물리적 음질이나 SOC 정확도를 대신하지 않지만, 실패 후 코드가 어떤 상태여야 하는지는 빠르게 확인할 수 있습니다.

7하드웨어 / 시스템 요구사항

7-1. 대상 보드의 명시된 사양

제품 사양은 docs/hardware-design/specifications.md, 펌웨어의 핀·주파수·주소는 components/bsp/include/bsp_pins.h 기준입니다. 소비 전류, 실제 배터리 사용 시간, 부하별 최고 프레임률은 코드 상수만으로 확정할 수 없습니다.

7-2. 같은 핀을 두 용도로 쓸 수 없는 이유

CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG=y에는 이 배경이 있습니다. 콘솔 출력 방법을 바꾸는 설정 하나가 화면 밝기 제어와 충돌할 수 있습니다. “범용 ESP32 예제에서 쓰는 핀”보다 이 보드의 실제 배치를 먼저 확인해야 합니다.

버튼 전압 범위는 [0,150), [150,447), [447,1900) mV입니다. button_level()은 반열린 구간으로 비교해 경계에서 두 버튼이 동시에 일치하지 않게 합니다. 이 수치는 이 회로의 기준이며, 다른 저항·보드에서는 실측 분포를 확인해야 합니다.

7-3. Flash와 RAM 예산은 별개의 표입니다

partitions.csv의 기본 레이아웃입니다. 사용자 앱이 다른 유효한 배치를 설계할 수 있지만, 현재 테이블에는 OTA 슬롯이나 별도 파일시스템 파티션이 예약되어 있지 않습니다.

앞의 세 항목만 합쳐도 139,776바이트입니다. 이는 같은 시점에 녹음 버퍼가 존재한다고 가정한 부분 합계이며 전체 RAM 사용량이나 최소 필요 RAM 수치가 아닙니다. 전체 여유와 가장 큰 연속 블록, LVGL 자체 풀의 최고 사용량을 각각 확인하는 편이 좋습니다.

7-4. 개발 컴퓨터와 도구

개발 안내는 Linux·macOS·Windows·WSL2를 다룹니다. 기준 SDK는 ESP-IDF 5.5.3이며, Python·CMake·Ninja와 ESP32-C3용 도구 체인이 필요합니다. Windows에서는 ESP-IDF가 준비한 터미널을 사용하고, WSL2의 USB 접근은 별도로 준비해야 합니다.

호스트 검증에는 Python 3, C 컴파일러, actionlint와 관련 다운로드·해시 도구가 쓰입니다. Python의 독립적인 프로젝트 버전 핀은 없습니다. 펌웨어 빌드 환경은 ESP-IDF의 요구사항을 따라야 하며, 저장소는 개발 PC의 최소 RAM·디스크 용량을 별도 보증값으로 명시하지 않습니다.

8직접 해볼 수 있는 실습 과제

앞의 두 과제는 소스를 읽고 계산하는 것만으로 진행할 수 있습니다. 구현 과제는 자신의 학습용 브랜치에서 진행하세요. 보드용 앱을 만든다면 AGENTS.md의 규칙에 따라 기존 테스트 메뉴를 복제하지 않고 자신의 화면을 설계합니다. BSP와 비 UI 로직은 재사용할 수 있습니다.

실습 결과를 화면이 나왔다는 감상 대신, 입력·기대 상태·실패 조건이 있는 기록으로 남겨 보세요. 각 과제의 완료 기준은 이후 테스트 항목으로 바꿀 수 있습니다.

// main/key_guard.h를 읽으며 추적할 호출 예
key_guard_t g = {0};
key_guard_arm(&g, 1000, 10LL * 1000 * 1000);  // 시각 단위: 마이크로초, 제한: 10초
key_guard_sync_released(&g, true);
// 드라이버 관측 전에 버튼을 놓았어도 즉시 보호 해제
// 다음 key_guard_consume()은 false: 이벤트 정상 전달

구현 단계의 검증은 저장소가 정의한 tools/validate.sh의 정적·펌웨어 게이트와 실기기 관찰을 구분해서 기록합니다. 호스트 테스트를 통과했더라도 마이크 입력이 실제로 잡히는지, 전원 상태가 목표에 도달했는지는 별개의 증거가 필요합니다.

9관련 기술 심화 학습 로드맵

처음부터 음성 AI 앱 전체를 만들기보다, 한 주에 하나의 경계를 익히는 구성이 좋습니다. 입력과 상태를 먼저 검증하고, 그 위에 화면·작업·하드웨어를 하나씩 연결하면 고장의 원인을 좁히기 쉽습니다. 진도가 느리면 주차를 늘리되 산출물은 유지해 보세요.

로드맵의 마지막에서 읽을 이미지 검증 코드

verify_flash_images()는 flash_args에 적힌 각 이미지가 존재하고 비어 있지 않은지, Flash 범위 안에 들어가는지, 서로 겹치지 않는지 확인합니다. 이어 병합 파일의 해당 위치가 원본 이미지 바이트와 같은지 비교합니다. 파일 이름이 맞는 것보다 더 강한 검증입니다.

verify_firmware_layout()은 파티션 테이블의 MD5 표식·중복 라벨·겹침을 검사하고, 앱 시작 주소가 실제 앱 파티션에 맞는지, 앱 크기가 그 파티션 안에 들어가는지 확인합니다. verify_extra_image_partitions()는 추가 이미지도 한 파티션 안에 완전히 들어가도록 검사합니다.

다음 확장 방향은 한 가지씩 선택하기

• UI 중심: 자신만의 화면, 한글 폰트 서브셋, 긴 문자열의 줄바꿈과 최악 화면의 메모리 사용량.
• 오디오 중심: 순환 버퍼, 지연 측정, 녹음 취소, 재생과 Flash 저장이 겹칠 때의 끊김 관찰.
• 연결 중심: Wi-Fi 연결 또는 BLE GATT 프로토콜을 하나 선택하고 인증·재연결·버퍼 상한 설계.
• 전원 중심: 주변장치 종료 순서, 버튼 해제 경쟁 조건, 상태별 전류 측정과 깨움 후 복구.

폰트 안내의 대상은 중국어지만, UTF-8 디코딩·글리프 포함 여부·폰트 선택·레이아웃을 따로 확인하라는 접근은 한글에도 적용됩니다. 중국어용 서브셋을 켜는 것만으로 한글까지 지원된다고 가정하지 마세요.

10핵심 키워드 사전

비슷해 보이는 용어를 쌍으로 구분하면 소스 읽기가 쉬워집니다. Flash와 RAM, 광고와 연결, 종료 요청과 종료 완료, 빌드 성공과 기기 검증을 각각 다른 항목으로 생각해 보세요.

11참고 링크

공식 저장소와 프로젝트 문서

• FoloToy/ai-passport 공식 저장소 · 분석 기준 커밋의 전체 트리
• 제품 소개와 문서 색인 · 기본 브랜치는 하드웨어 테스트 기준선이라는 설명
• AI 개발 지침 · 보드·잠금·작업 수명·파생 앱 UI 규칙
• 제품 사양 · 크기·배터리·무선·수동 NFC
• 하드웨어 개발 가이드 · 버퍼 크기는 본문에서 설명한 코드와의 차이 주의
• 빌드·테스트 안내 · 환경 준비 안내
• Flash 배치와 저장 데이터 · 병합 이미지·분할 기록의 차이
• AI 스킬 목록 · 응용 사례와 경험 기록

본문의 핵심 구현을 다시 읽는 링크

• main/main.c · app_main(), on_key(), process_input()
• main/demo.h · 페이지 수명 인터페이스
• main/demo_navigation.c · main/key_guard.h · 보드 없이 이해할 상태 로직
• main/demo_audio.c · 오디오 실패·종료 테스트
• components/bsp/src/bsp_display_lvgl.c · 행별 모서리 계산
• components/bsp/src/bsp_battery.c · 배터리 프로필의 원본·해시·C 배열 검사
• main/demo_low_power.c · 주변장치 정리와 깨움 순서
• tools/verify_firmware.py · 이미지 범위·바이트·파티션 검사
• 의존성 명세 · 버전 잠금 파일 · 기본 SDK 설정

관련 기술의 공식 자료

• ESP-IDF 5.5.3 · ESP32-C3 공식 문서
• ESP-IDF I2S 문서 · DMA와 Flash 동작 중 인터럽트 제약을 이어서 학습
• LVGL 9.5 폰트 공식 문서 · 공식 폰트 변환 도구
• LVGL v9.5.0 소스 · 잠금 버전에 맞춰 구현 확인
• esp_lvgl_port 공식 소스 · 이 프로젝트의 잠금 버전은 2.9.0
• FreeRTOS 공식 문서 · 태스크·큐·동기화의 기초
• actionlint 공식 저장소 · 워크플로 정적 검사

현재 상태 (2026-10-23 GitHub 기준)