브라우저가 블루투스를 인식하지 못할 때: Web Bluetooth API 실전 진단 가이드

온라인 미팅 5 분 전. IoT 데모를 보여주려는데 브라우저가 침묵합니다. 스피너만 돌고 기기는 nowhere. 당황스럽죠. 대부분의 개발자는 즉시 하드웨어 고장을 의심하거나, 복잡한 드라이버 재설치부터 시작합니다. 하지만 잠깐 멈추세요. 문제의 근본 원인은 종종 훨씬 단순한 권한 설정의 누락이나, 업데이트 후 달라진 브라우저의 보안 정책에 있습니다.

이 글에서는 'Web 블루투스 연결 및 스캔 테스트' 도구를 활용해, 하드웨어 결함과 소프트웨어 구성 오류를 신속하게 분리해내는 3 단계 프로세스를 공유합니다. 이론적 배경 설명은 생략합니다. 바로 작업台에 올려두고 쓸 수 있는 실질적인 진단법을 다룹니다.

1 단계: 환경 격리 및 기본 스캔 능력 검증

가장 먼저 수행해야 할 작업은 현재 브라우저 인스턴스가 블루투스 어댑터에 접근할 수 있는 최소한의 능력을 갖추었는지 확인하는 것입니다. 많은 경우, 문제는 기기 자체가 아니라 브라우저가 해당 프로토콜을 활성화하지 않은 상태에서 발생합니다.

테스트 도구를 실행하기 전에, 사용자가 HTTPS 환경에서 페이지를 로드했는지 반드시 점검해야 합니다. Web Bluetooth API 는 보안상의 이유로 비보안 컨텍스트 (HTTP) 에서의 사용을 명시적으로 차단합니다. 로컬호스트 (localhost) 는 예외적으로 허용되지만, 실제 배포 환경에서는 SSL 인증서 구성이 제대로 되어 있지 않으면 스캔 요청 자체가 던져지지 않습니다.

브라우저 주소창 자물쇠 아이콘을 클릭해 권한 상태를 살펴보세요. '블루투스' 항목이 '차단됨'으로 표시되어 있다면, 여기서 모든 시도는 무의미합니다. 사용자에게 권한 부여를 요청하는 프롬프트가 뜨지 않는다면, 이는 브라우저 설정深处에서 해당 기능이 비활성화되었거나, 운영체제 레벨에서 브라우저 프로세스에 대한 블루투스 접근이 제한되었을 가능성이 큽니다.

Chrome 의 경우 chrome://flags 에서 #enable-experimental-web-platform-features 플래그가 꺼져 있는지 확인하세요. 가끔씩 브라우저 업데이트 과정에서 실험적 기능이 초기화되면서 Web Bluetooth 지원이 사라지는 경우가 있습니다. 이런 사소한 구성 변화 하나가 전체 데모를 무산시킬 수 있습니다.

스캔 버튼을 누르는 순간 어떤 일이 일어나야 할까요? 브라우저는 운영체제의 블루투스 스택과 상호작용을 수행하며 주변 장치 목록을 조회합니다. 이 과정에서 아무런 반응이 없다면, 그것은 하드웨어 고장일 수도 있지만, 대부분은 브라우저가 OS 에게 질의를 보내는 과정 자체가 막혀있는 상태입니다.

2 단계: 필터링 로직과 서비스 UUID 정합성 분석

기기가 목록에 보이긴 하는데 원하는 타겟이 잡히지 않나요? 혹은 연결은 되는데 데이터 전송이 안 된다면, 문제는 스캔 범위를 좁히는 필터링 로직에 있을 확률이 높습니다. 개발자가 작성한 JavaScript 코드가 요구하는 서비스 UUID 가 실제 기기가 광고하는 UUID 와 정확히 부합하지 않는 경우가 빈번합니다.

Web Bluetooth API 는 보안을 위해 사용자가 명시적으로 선택한 기기만 연결하도록 강제합니다. 이때 requestDevice() 메서드에 전달되는 filters 옵션이 결정적인 역할을 수행합니다. 코드상에서 { services: ['battery_service'] } 처럼 잘 알려진 서비스 이름을 사용했다면 괜찮겠지만, 커스텀 펌웨어를 올린 IoT 기기라면 128 비트 UUID 를 직접 지정해야 합니다.

여기서 흔히 저지르는 실수는 대소문자 구분이나 하이픈 위치를 틀리는 것입니다. 0000180f-0000-1000-8000-00805f9b34fb 와 0000180F-0000-1000-8000-00805F9B34FB 는 문자열 비교 관점에서 완전히 다른 식별자입니다. 브라우저는 이러한 불일치를 묵시적으로 수정해주지 않습니다. 단순히 매칭되지 않는 것으로 처리할 뿐입니다.

테스트 도구를 활용해 기기가 실제로 어떤 서비스 UUID 를 광고하고 있는지 Raw 데이터를 확인하세요.很多时候, 제조사 문서에 적힌 UUID 와 실제 펌웨어가 브로드캐스팅하는 값이 다를 수 있습니다. 특히 프로토타입 단계의 하드웨어라면 더욱 그렇습니다. 문서만 믿고 코드를 작성했다가는 헛수고를 하게 됩니다.

필터 조건을 너무 엄격하게 설정하면 기기가 아예 목록에 나타나지 않습니다. 디버깅 단계에서는 { acceptAllDevices: true, optionalServices: [...] } 옵션을 활용해 모든 장치를 노출시킨 뒤, 필요한 서비스를 선택적으로 가져오는 방식으로 접근 범위를 넓혀보는 것이 현명합니다. 이렇게 하면 필터링 로직의 오류인지, 아니면 기기 자체의 광고 패킷 문제인지를 명확하게 구분할 수 있게 됩니다.

연결 성공 후에도 특정 characteristic 에 대한 읽기/쓰기 작업이 실패한다면, 해당 서비스가 optionalServices 배열에 포함되어 있는지 다시 한번 검토해야 합니다. 연결 시점에 명시적으로 요청하지 않은 서비스에 대해서는 이후 접근이 거부됩니다. 이는 API 설계상의 보안 정책이지 버그가 아닙니다.

3 단계: 데이터 전송 안정성 및 MTU 협상 검증

연결까지 성공했다면 이제 진짜 작업이 시작됩니다. 많은 개발자가 여기까지만 테스트하고 "된다"라고 판단하지만, 실제 현장에서의 문제는 대부분 데이터 전송 단계에서 발생합니다. 특히 대용량 펌웨어 업데이트나 실시간 센서 데이터 스트리밍 시나리오에서는 더더욱 그렇습니다.

블루투스 Low Energy (BLE) 는 기본적으로 작은 패킷 단위의 통신에 최적화되어 있습니다. 한 번에 보낼 수 있는 데이터 크기 (MTU, Maximum Transmission Unit) 는 기기와 중앙 장치 (브라우저가 실행되는 PC 또는 스마트폰) 간의 협상 과정을 통해 결정됩니다. 기본값은 종종 23 바이트로 매우 작습니다. 이를 고려하지 않고 긴 문자열이나 바이너리 데이터를 한꺼번에 전송하려 하면 데이터가 잘리거나 연결이 끊어집니다.

테스트 도구의 '데이터 전송 검증' 기능을 이용해 다양한 크기의 페이로드를 발송해 보세요. 10 바이트, 50 바이트, 그리고 512 바이트 이상으로 점진적으로 크기를 늘려가며 응답 시간을 측정하고 패킷 손실 여부를 관찰해야 합니다. 만약 특정 크기 이상에서 전송이 실패한다면, MTU 협상이 제대로 이루어지지 않았거나, 기기 펌웨어 측에서 큰 패킷을 처리하는 로직에 결함이 있을 수 있습니다.

전송 속도가 기대보다 느리다면, Write Without Response 모드를 사용하는지 확인하세요. 일반적인 Write 연산은 기기로 부터 확인 응답 (ACK) 을 받을 때까지 다음 데이터를 보내지 못합니다. 실시간성이 중요한 애플리케이션이라면, 신뢰성은 약간 희생하더라도 속도를 확보하기 위해 Response 가 없는 쓰기 명령을 활용하는 전략을 채택해야 합니다.

또한, 브라우저 탭이 백그라운드로 전환될 때 연결이 유지되는지도 체크해야 합니다. 모바일 환경에서는 화면이 꺼지거나 앱이 최소화되면 OS 가 블루투스 스캔이나 연결 유지 작업을 일시 중단하기도 합니다. 이는 웹 개발자가 제어할 수 있는 영역이 아니지만, 이러한 동작 특성을 이해하고 재연결 로직을 어떻게 구현할 수 있게 할지 고민해야 합니다.

시스템 업데이트 직후라면 블루투스 스택의 버전 변화로 인해 기존에 작동하던 MTU 협상 로직이 달라졌을 수도 있습니다. 이런 경우 하드웨어를 교체하기 전에, 브라우저의 캐시를 삭제하고 블루투스 어댑터를 껐다 켜는 기본적인 초기화 작업을 수행하는 것만으로도 문제가 해결되는 경우가 상당한 수준으로 많습니다.

마치며: 추측을 넘어선 데이터 기반의 접근

블루투스 연결 문제는 종종 "왜 안 되지?"라는 막연한 질문에서 시작해 불필요한 하드웨어 교체로 끝납니다. 하지만 대부분의 장애물은 코드 내의 사소한 필터링 오류, 권한 설정의 누락, 혹은 프로토콜 특성에 대한 오해에서 비롯됩니다.

복잡한 드라이버 설치나 펌웨어 리플래싱을 수행하기 전에, 위에서 언급한 3 단계 진단 프로세스를 체계적으로 적용해 보세요. 웹 환경에서 즉시 실행 가능한 도구를 활용해 객관적인 데이터를 바탕으로 문제를 특정하는 것이 시간을 절약하는 지름길입니다.

기술은 완벽하지 않습니다. 브라우저도, OS 도, 때로는 하드웨어조차 예상치 못한 방식으로 동작합니다. 중요한 것은 그 불확실성 속에서 논리적으로 원인을 추적해 나가는 태도입니다. 다음 번에 브라우저가 침묵할 때, 당황하지 말고 차근차근 단서를 따라가 보세요. 답은 항상 로그와 스펙 사이에 숨어 있습니다.