ESP32 BLE가 검색·연결되지 않을 때 — 증상별 점검 순서

증상부터 나눕니다

같은 증상도 원인이 여러 개일 수 있습니다. 한 번에 한 항목만 바꾸고 결과를 기록해야 원인을 좁힐 수 있습니다.

거리가 짧으면 실제 적용된 출력을 확인합니다

송신 출력의 기본값을 추측하지 말고, 사용 중인 칩·스택의 설정·조회 API로 광고·스캔·연결 출력이 어떻게 적용됐는지 읽어 봅니다. 출력 값과 함께 안테나 위치, 케이스·금속 차폐, 전원, 상대 기기도 같이 봅니다.

열거형 상수를 #ifdef로 검사하면 매크로가 있는지만 확인하게 됩니다. 상수가 있어도 같은 이름의 매크로가 없으면 조건이 거짓이 되므로 헤더 정의를 직접 확인합니다.

연결 직후 끊기면 콜백을 짧게 만듭니다

연결 콜백 안에서 저장 같은 긴 작업을 하면 연결 과정과 겹칠 수 있습니다. 콜백은 상태 기록이나 큐 전달만 하고 끝내고, 긴 작업은 다른 태스크로 옮겨 전후를 비교합니다.

이때 작업 시간과 연결 해제 사유를 함께 남깁니다. 저장 자체가 항상 끊김을 일으키는 것은 아니므로 로그로 확인한 뒤 판단합니다.

이름이 안 보이면 광고 데이터 크기를 계산합니다

레거시 BLE의 광고 데이터와 스캔 응답은 각각 최대 31바이트입니다. 기기 이름 외에 플래그·서비스 UUID 같은 필드도 이 공간을 씁니다. 한글 완성형 음절은 UTF-8에서 보통 3바이트이므로 “한글 몇 자까지”로 고정하지 말고 실제 바이트 수를 계산합니다.

이름을 스캔 응답으로 옮기거나 다른 식별 정보로 기기를 찾는 방법도 있습니다. 확장 광고는 별도 기능이므로 칩과 스택의 지원 여부를 먼저 확인합니다.

끊긴 뒤 안 보이면 광고 재시작을 확인합니다

NimBLE-Arduino 2.x는 연결이 해제된 뒤 광고를 기본으로 다시 시작하지 않습니다. 서버의 advertiseOnDisconnect(true)를 쓰거나 해제 콜백에서 직접 다시 시작하는 방식 중 설계에 맞는 쪽을 고릅니다.

// NimBLE-Arduino 2.x — 연결 해제 후 광고를 자동으로 다시 시작
NimBLEServer* server = NimBLEDevice::createServer();
server->advertiseOnDisconnect(true);

NimBLEAdvertising::start()의 반환값과 isAdvertising() 상태를 확인하고, 실패했을 때의 재시도 간격도 정해 둡니다. 다른 스택이라면 해당 API의 반환형과 완료 이벤트를 따릅니다.

USB가 사라지면 USB 방식과 절전을 봅니다

보드가 칩 내장 USB Serial/JTAG를 쓰는지, 외부 USB-UART 변환 칩을 쓰는지부터 구분합니다. ESP32-S3의 내장 USB Serial/JTAG는 Light-sleep 중 사용에 제한이 있으므로 절전 설정과 보드·소프트웨어 버전을 함께 확인합니다. 포트 복구와 프로그램 기록은 해당 보드의 공식 안내를 따릅니다.

제품으로 만들 때는 재연결까지 시험합니다

개발 책상에서 한 번 연결되는 것과 설치된 자리에서 매일 다시 연결되는 것은 다릅니다. 테크브릭은 모듈로 기능을 시험할 때 실제 케이스와 설치 위치에서 연결·해제·재연결을 반복해 보고, 보드·칩·SDK·라이브러리 버전과 재현 순서를 함께 기록합니다.

명령 처리·동시 연결·멈춤 복구까지 보는 안정성 기준 →