================================================================
 PoseLab Core (pio) — PlatformIO 빌드 가이드
================================================================

대상 보드 : ESP32-S3-WROOM-1 N16R8 (16MB flash, 8MB OPI PSRAM)
USB-UART  : CH343P (CDC, 드라이버리스) — COM 포트로 인식
전송      : UART0 @ 2,000,000 baud, 50fps, 96-byte AnalyzedFrame 패킷
            (86 바이트 + 온디바이스 추론 블록 10 바이트)

----------------------------------------------------------------
 1. 준비물
----------------------------------------------------------------
- VS Code + PlatformIO IDE 확장
  (또는 CLI 단독: pip install platformio)
- 플랫폼/라이브러리는 platformio.ini 에 명시되어 있어
  첫 빌드 시 자동으로 내려받습니다. 수동 설치는 필요 없습니다.
    platform : espressif32 6.11.0  (arduino-esp32 2.0.17)
    lib_deps : Chirale_TensorFLowLite 2.0.0  ← 온디바이스 추론 (TFLite Micro)
               Adafruit NeoPixel     ^1.12.0
               ArduinoJson           ^7.1.0  ← v6 아님, 반드시 v7

----------------------------------------------------------------
 2. 프로젝트 열기
----------------------------------------------------------------
- 이 폴더(PoseLabCore-pio/)를 PlatformIO 프로젝트로 엽니다.
  platformio.ini 가 있는 폴더가 프로젝트 루트입니다.
- 소스는 src/ 하위에 트리로 들어 있습니다
  (board/ sense/ calib/ proto/ tinyml/ model/ ...).
- 진입점은 src/main.cpp 입니다.

----------------------------------------------------------------
 3. 빌드 / 업로드 / 모니터
----------------------------------------------------------------
    pio run                 빌드 (env:n16r8 — 유일한 env)
    pio run -t upload       업로드
    pio run -t monitor      시리얼 모니터 (2,000,000 baud)

- 포트는 platformio.ini 에 COM7 로 고정되어 있습니다.
  다른 포트라면 upload_port / monitor_port 를 바꾸거나 실행 시 지정하세요:
    pio run -t upload --upload-port COM12

----------------------------------------------------------------
 4. platformio.ini 핵심 설정 (★ 건드리지 말 것)
----------------------------------------------------------------
  board                        : esp32-s3-devkitc-1
  build_flags
    -DARDUINO_USB_CDC_ON_BOOT=0  ← 중요. Serial = UART0 (CH343P 브리지).
                                   1이면 데이터가 나오지 않습니다
    -I src                       ← "board/pins.h" 같은 하위 폴더 include 해석용
    -DBOARD_HAS_PSRAM            ← PSRAM 사용 선언
  board_build.partitions       : partitions-16mb.csv
                                 ← ★ 커스텀 파티션. fit NVS 파티션과
                                   models SPIFFS 파티션이 들어 있습니다.
                                   기본 파티션이면 교정값과 업로드한 모델이
                                   영속 저장되지 않습니다
  board_build.flash_size       : 16MB
  board_build.arduino.memory_type : qio_opi   ← 8MB OPI PSRAM 활성
  upload_speed                 : 921600
  monitor_speed                : 2000000

  ※ MUX EN 핀은 GPIO35~37을 절대 사용하지 않습니다 (PSRAM 예약).
     그래서 PSRAM 을 켜도 충돌이 없습니다.
     핀 배정은 src/board/pins.h 에 있습니다.

  ※ 여기서 PSRAM 은 선택이 아닙니다. 업로드된 모델은 SPIFFS 에 쓰기 전에
     PSRAM 에 통째로 모았다가 한 번에 씁니다. PSRAM 이 동작하지 않는 보드는
     모델 업로드를 받지 못합니다.

----------------------------------------------------------------
 5. 업로드 & 확인
----------------------------------------------------------------
- pio run -t monitor 로 2,000,000 baud 연결합니다.
- 부팅 배너 예시:
    ==== PoseLab Core ====
    Chip       : ESP32-S3 ... Flash 16MB, PSRAM 8189KB   ← PSRAM 인식 확인
    FIT calib loaded: USER params                         ← 교정값 영속 확인
    PUMP- ENTER ...                                        ← 스트리밍 시작
- 부팅 시 WS2812C LED 무지개 시퀀스 → 앰버가 유지되면 정상입니다.
- 모델이 올라가 있으면 배너에 로딩한 모델과 셀프테스트 줄이 함께 나옵니다.
  모델이 없으면 추론만 꺼진 상태(패킷의 appId = 0x00)로 나머지는 정상 동작합니다.

----------------------------------------------------------------
 6. 시리얼 명령
----------------------------------------------------------------
  STOP / RESTART           50fps 스트림 정지 / 재개
  FITWR / FITRD / FITCLR   "fit" NVS 파티션의 채널별 교정값
  MDLWR / MDLRD / MDLCLR   SPIFFS 의 .plmodel 업로드 / 확인 / 삭제

- MDLWR 은 전송 동안 스트리밍을 스스로 끄고, 전송이 끝나면 다시 켭니다.
  오류나 타임아웃으로 끝나는 경우에도 마찬가지입니다.
- 업로드 시 디바이스는 재부팅하지 않습니다. 새로 올린 모델은 다음 부팅부터
  적용됩니다 — 인터프리터를 시작할 때 한 번만 만들기 때문입니다.
- 모델 전송은 브라우저가 대신 해줍니다. MLP 랩 페이지에 On-Device 패널이
  있습니다. 직접 도구를 만드시려면 SDK 프로토콜 문서의 프레이밍을 보세요.

----------------------------------------------------------------
 7. 참고
----------------------------------------------------------------
- Arduino IDE 로 빌드하시려면 PoseLabCore-adv 패키지를 사용하세요
  (진입점이 .ino, include 가 "src/..." 접두). 런타임 동작은 동일합니다 —
  adv 는 이 소스에서 생성됩니다.
- 86-byte 프로토콜은 폐기되었습니다. 이 펌웨어는 96 바이트만 내보냅니다.
- 문의: support@poselab.app
