Qt Bluetooth

블루투스 API는 블루투스 지원 기기 간의 연결을 제공합니다.

현재 이 API는 다음 플랫폼에서 지원됩니다:

개요

블루투스는 단거리(100미터 미만) 무선 기술입니다. 데이터 전송 속도는 2.1 Mbps로, 기기 간 데이터 전송에 이상적입니다. 블루투스 연결은 기기 검색, 기기 정보 수집, 기기 간 데이터 교환과 같은 기본적인 기기 관리 기능을 기반으로 합니다.

Qt Bluetooth 클라이언트/중앙 역할 사용 사례를 위한 블루투스 저에너지(Bluetooth Low Energy ) 개발을 지원합니다. 자세한 내용은 ‘블루투스 저에너지 개요’ 섹션에서 확인할 수 있습니다.

모듈 사용

Qt 모듈의 C++ API를 사용하려면 모듈 라이브러리를 직접 또는 다른 종속성을 통해 링크해야 합니다. CMake 및 qmake를 비롯한 여러 빌드 도구가 이를专门으로 지원합니다.

CMake를 사용한 빌드

find_package() 명령을 사용하여 Qt6 패키지 내에서 필요한 모듈 구성 요소를 찾으십시오:

find_package(Qt6 REQUIRED COMPONENTS Bluetooth)
target_link_libraries(mytarget PRIVATE Qt6::Bluetooth)

자세한 내용은 ‘CMake를 사용한 빌드’ 개요를 참조하십시오.

qmake를 사용한 빌드

qmake를 사용하여 모듈을 빌드하도록 구성하려면, 프로젝트의 .pro 파일에서 QT 변수의 값으로 모듈을 추가하십시오:

QT += bluetooth

권한

Qt 6.6부터 Qt Bluetooth 모듈은 Bluetooth 권한을 처리하기 위해 새로운 QPermission API를 사용합니다. 즉, Qt 자체에서는 더 이상 이러한 권한을 조회하지 않으므로, 클라이언트 애플리케이션에서 직접 처리해야 합니다.

새로운 QPermission API를 애플리케이션에 통합하는 방법에 대한 예제는 ‘애플리케이션 권한 (Application Permissions )’ 페이지를 참조하십시오.

관련 정보

빌드 Qt Bluetooth

이 모듈은 모든 Qt 플랫폼에서 빌드할 수 있지만, 모든 플랫폼으로 포팅되지는 않았습니다. 지원되지 않는 플랫폼의 경우, 해당 플랫폼이 지원되지 않을 때 자동으로 선택되는 더미 백엔드가 사용됩니다. 더미 백엔드는 적절한 오류 메시지와 값을 반환하므로, 런타임 시 현재 플랫폼이 지원되지 않음을 감지할 수 있습니다. 또한 빌드 시 BlueZ 개발 헤더를 찾을 수 없거나 Qt가 Qt D-Bus 지원 없이 빌드된 경우, Linux에서도 더미 백엔드가 선택됩니다.

더미 백엔드의 사용 여부는 빌드 및 실행 중에 적절한 경고 메시지를 통해 표시됩니다.

Linux 관련

Qt 6.5부터 Linux 주변기기 지원에는 BlueZ DBus와 Bluetooth 커널 API라는 두 가지 백엔드 대안이 있습니다. DBus 백엔드는 Qt 6.7부터 기본 백엔드로 사용됩니다.

BlueZ DBus는 최신 BlueZ 스택이며, 기존 커널 API의 최종 후속 버전이 될 가능성이 높습니다. 기능 면에서는 다소 제한적이지만, 일반적인 사용 환경에서는 큰 문제가 되지 않습니다. DBus 백엔드를 사용할 때 주목할 만한 이점 중 하나는 사용자 프로세스가 더 이상 CAP_NET_ADMIN 권한을 가질 필요가 없다는 점입니다(예: root 사용자로 실행하는 경우).

DBus 백엔드를 사용하려면 BlueZ 버전 5.56 이상이 필요하며, 필요한 DBus API를 제공해야 합니다. 이러한 요구 사항이 충족되지 않으면 Qt는 자동으로 Bluetooth 커널 API 백엔드로 전환됩니다.

QT_BLUETOOTH_USE_KERNEL_PERIPHERAL 환경 변수를 설정하여 구형 커널 백엔드를 수동으로 선택할 수도 있습니다.

macOS 관련

macOS의 블루투스 API는 특정 유형의 이벤트 디스패처를 필요로 하며, 이로 인해 Qt에서는 QGuiApplication 에 대한 의존성이 발생합니다. 그러나 QT_EVENT_DISPATCHER_CORE_FOUNDATION=1 환경 변수를 설정하여 이 문제를 우회할 수 있습니다.

클래식 블루투스를 사용하지 않는 애플리케이션의 경우, CoreBluetooth(블루투스 LE)는 QApplication 나 QGuiApplication 를 필요로 하지 않으므로, QtBluetooth 의 일부 기능만 사용할 수 있습니다.

문서 및 가이드

• 클래식 블루투스 개요
• 블루투스 저에너지(Bluetooth Low Energy) 개요

참조

• C++ Classes

로깅 범주

QtBluetooth 모듈은 다음과 같은 로깅 카테고리( logging categories)를 출력합니다:

로깅 범주를 사용하면 QtBluetooth 에 대한 추가 경고 및 디버그 출력을 활성화할 수 있습니다. 로깅에 대한 자세한 내용은 QLoggingCategory 에서 확인할 수 있습니다. QtBluetooth 의 모든 로깅을 활성화하는 빠른 방법은 main() 함수에 다음 줄을 추가하는 것입니다:

QLoggingCategory::setFilterRules(QStringLiteral("qt.bluetooth* = true"));

예제

• QML
  • 블루투스 저에너지 심박수 게임
  • 블루투스 저에너지 심박수 서버
  • 블루투스 저에너지 스캐너
• C++
  • 블루투스 채팅

모듈 발전

Qt Bluetooth 에는 Qt 6 시리즈를 위해 적용된 모듈 API 및 기능의 주요변경 사항이 나열되어 있습니다.

라이선스 및 출처 표기

Qt Bluetooth 는 The Qt Company의 상용 라이선스 하에 제공됩니다. 또한, GNU Lesser General Public License 버전 3 또는 GNU General Public License 버전 2 하에서도 사용할 수 있습니다. 자세한 내용은 Qt 라이선싱을 참조하십시오.

Linux에서 Qt Bluetooth 는 별도의 실행 파일인 sdpscanner 를 사용하여 공식 Linux 블루투스 프로토콜 스택인 BlueZ와 통합됩니다. BlueZ는 GNU 일반 공중 사용 허가서(GNU General Public License) 버전 2에 따라 제공됩니다.