핵심 요약

BLE에서 Peripheral은 광고하고 Central은 스캔해 연결합니다. 찾고 연결하는 규칙이 GAP, 연결 후 데이터를 주고받는 규칙이 GATT이며, GATT 데이터는 서비스 → 캐릭터리스틱 → 디스크립터 트리와 UUID로 구분됩니다. 리눅스에서는 BlueZ bluetoothctl로 connect → menu gatt → select-attribute → read 순서로 값을 읽습니다. 테스트를 자동화할 때는 ServicesResolved: yes를 PASS로 보지 말고, Attempting to read … 다음 줄에 값이 찍혔을 때만 PASS로 판정합니다.

BLE 기기를 테스트하거나 앱과 연동하다 보면 “연결은 됐는데 값이 안 읽힌다” 같은 상황을 자주 만납니다. 이 글은 GATT의 기본 구조, 리눅스 BlueZ bluetoothctl로 직접 읽어 보는 실습, 연결 테스트 자동화의 PASS 판정 기준을 한 번에 정리합니다.

Central과 Peripheral은 누가 무엇을 하나?

한 줄 답: Peripheral은 “나 여기 있어요”라고 광고하고, Central은 광고를 스캔한 뒤 연결을 겁니다.

  1. Bluetooth Core Specification의 GAP(Generic Access Profile, Vol 3 Part C)는 LE 연결에서 역할을 Central과 Peripheral로 정의합니다. 스마트폰이나 리눅스 PC가 보통 Central, 배터리로 동작하는 센서·웨어러블·가전 모듈이 보통 Peripheral입니다.
  2. **Advertising(광고)**은 연결 전 단계입니다. Peripheral은 광고 채널로 짧은 패킷을 주기적으로 내보내고, 여기에 기기 이름이나 제공하는 서비스 UUID 같은 정보를 담을 수 있습니다. Central은 스캔으로 이 패킷을 수신해 어떤 기기가 주변에 있는지 압니다.
  3. **Connection(연결)**은 Central이 특정 광고에 연결 요청을 보내면서 시작됩니다. 연결 후에는 두 기기가 정해진 간격으로 데이터를 주고받고, 이 위에서 GATT 통신이 이뤄집니다. 정리하면 “광고 = 1:다 방송”, “연결 = 1:1 대화”입니다.

GAP와 GATT는 어떻게 다른가?

한 줄 답: GAP는 “어떻게 찾고 연결하나”, GATT는 “연결 후 어떤 데이터를 어떻게 읽고 쓰나”를 정합니다.

BLE 연결 흐름: 광고, 연결, 서비스 탐색, read/notify

  1. GAP는 역할(Central/Peripheral), 광고·스캔, 연결 수립 절차를 다룹니다. 연결이 안 된다면 대부분 GAP 단계 문제입니다(광고가 안 나감, 스캔에 안 잡힘, 연결 요청 시간 초과 등).
  2. GATT(Generic Attribute Profile, Core Spec Vol 3 Part G)는 ATT(Attribute Protocol, Vol 3 Part F) 위에서 동작하며, 데이터를 가진 쪽을 GATT 서버, 요청하는 쪽을 GATT 클라이언트라고 부릅니다. 흔히 Peripheral이 서버, Central이 클라이언트이지만 GAP 역할과 GATT 역할은 별개 개념입니다. 그래서 “연결됨(GAP)“과 “값을 읽음(GATT)“은 서로 다른 성공 기준이고, 이 차이는 아래 PASS 판정에서 다시 다룹니다.

서비스·캐릭터리스틱·UUID는 어떤 구조로 묶이나?

한 줄 답: 서비스는 기능 묶음, 캐릭터리스틱은 실제 값 하나, UUID는 그 둘을 가리키는 이름표입니다.

  1. **서비스(Service)**는 관련 데이터의 묶음입니다. 예를 들어 Bluetooth SIG가 정의한 Battery Service(UUID 0x180F)는 배터리 관련 값을 모아 둡니다.
  2. **캐릭터리스틱(Characteristic)**은 서비스 안의 실제 값 하나와 그 속성(properties: read, write, notify 등)입니다. Battery Service 안의 Battery Level(UUID 0x2A19)이 대표적이며, 값은 배터리 잔량을 퍼센트로 나타냅니다. 캐릭터리스틱 아래에는 **디스크립터(Descriptor)**가 붙을 수 있는데, notify를 켜고 끄는 CCCD(Client Characteristic Configuration, UUID 0x2902)가 가장 자주 쓰입니다.
  3. UUID는 SIG가 표준으로 할당한 16비트 값(Bluetooth Assigned Numbers 문서)과, 제조사가 자체 서비스용으로 만드는 128비트 값으로 나뉩니다. 16비트 UUID는 Core Spec(Vol 3 Part B, Bluetooth Base UUID)에 따라 0000xxxx-0000-1000-8000-00805F9B34FB 형태의 128비트로 확장됩니다. 커스텀 서비스는 예를 들어 12345678-1234-5678-1234-56789abcdef0(설명용 예시 UUID) 같은 128비트 값을 씁니다.

read와 notify는 언제 각각 쓰나?

한 줄 답: 필요할 때 한 번 물어보면 read, 값이 바뀔 때마다 받고 싶으면 notify입니다.

GATT 트리: 서비스, 캐릭터리스틱, 디스크립터

  1. read: 클라이언트가 요청하고 서버가 현재 값을 응답합니다. 테스트에서 “GATT 통신이 실제로 되는가”를 확인하는 가장 단순한 방법이기도 합니다.
  2. notify: 클라이언트가 CCCD에 notify 활성화 값을 써 두면, 서버가 값이 바뀔 때마다 먼저 보내 줍니다. 응답 확인이 필요한 방식은 indicate라고 부릅니다. 계속 폴링(read 반복)하는 것보다 전력과 무선 대역을 아낄 수 있습니다.

UUID 확장과 값 해석을 코드로 확인하면?

한 줄 답: 16비트 SIG UUID를 Base UUID에 끼우면 128비트가 되고, Battery Level은 1바이트 값을 그대로 퍼센트로 읽습니다.

  1. 아래는 실제 BLE 장치 없이 GATT 트리 구조와 UUID 확장을 보여 주는 작은 Python 예제입니다. 읽은 값 0x55는 설명용 예시 값입니다.
# Example: 16-bit SIG UUID -> 128-bit (Bluetooth Base UUID) and Battery Level decoding
BASE = "0000{:04x}-0000-1000-8000-00805f9b34fb"
def full_uuid(short): return BASE.format(short)
tree = {0x180F: ("Battery Service", {0x2A19: ("Battery Level", ["read", "notify"])})}
for s, (sname, chars) in tree.items():
    print(f"Service {sname}: {full_uuid(s)}")
    for c, (cname, props) in chars.items():
        print(f"  Characteristic {cname}: {full_uuid(c)} props={props}")
raw = bytes([0x55])  # example value read from 0x2A19 (uint8, percent)
print("Battery Level =", raw[0], "%")

Python 3.13.5에서 실제로 실행한 출력입니다.

Service Battery Service: 0000180f-0000-1000-8000-00805f9b34fb
  Characteristic Battery Level: 00002a19-0000-1000-8000-00805f9b34fb props=['read', 'notify']
Battery Level = 85 %

실습 준비물은 무엇이고 bluetoothd는 어떻게 확인하나?

한 줄 답: BLE 어댑터가 있는 리눅스 PC, nRF Connect 같은 앱으로 광고를 내보낼 폰, 그리고 실행 중인 bluetoothd만 있으면 됩니다.

  1. Central: 내장 또는 USB 블루투스 어댑터가 있는 리눅스 PC. BlueZ의 bluetoothd가 어댑터를 관리하고 기능을 D-Bus로 노출하며, bluetoothctl은 그 D-Bus API를 쓰는 대화형 클라이언트입니다. systemd 배포판에서는 systemctl status bluetooth로 데몬이 떠 있는지 봅니다.
  2. Peripheral: 스마트폰에 Nordic의 nRF Connect 앱을 설치하고, 앱의 광고(Advertiser) 기능이나 GATT 서버 설정으로 Battery Service(0x180F) 같은 서비스를 노출하면 실습용 Peripheral이 됩니다. 실제 개발 보드가 있다면 그것을 써도 됩니다.

스캔부터 연결, GATT read까지 명령은 어떤 순서인가?

한 줄 답: main 메뉴에서 찾고 연결한 다음, menu gatt로 들어가서 캐릭터리스틱을 고르고 읽습니다.

  1. 전체 흐름은 아래와 같습니다. 이 글의 세션은 예시이며(이 글을 쓴 환경에는 BLE 어댑터가 없어 실기 출력은 싣지 않았습니다), 명령 이름은 BlueZ 5.82 bluetoothctl에서 확인했습니다. 주소 AA:BB:CC:DD:EE:FF는 예시입니다.
# 예시 세션 (주소 AA:BB:CC:DD:EE:FF 는 예시)
$ systemctl status bluetooth        # bluetoothd 실행 여부
$ bluetoothctl
[bluetoothctl]> power on
[bluetoothctl]> scan on
[bluetoothctl]> scan off
[bluetoothctl]> connect AA:BB:CC:DD:EE:FF
[bluetoothctl]> info AA:BB:CC:DD:EE:FF     # Connected / ServicesResolved 확인
[bluetoothctl]> menu gatt
[bluetoothctl]> list-attributes
[bluetoothctl]> select-attribute 00002a19-0000-1000-8000-00805f9b34fb
[bluetoothctl]> attribute-info
[bluetoothctl]> read
[bluetoothctl]> back
[bluetoothctl]> disconnect AA:BB:CC:DD:EE:FF

bluetoothctl로 연결부터 GATT read까지의 순서

  1. scan on으로 주변 광고를 보고 대상 주소를 찾은 뒤 scan off로 멈춥니다. connect 후 Connection successful이 보이면 GAP 연결이 된 것입니다.
  2. menu gatt로 들어가면 list-attributes로 서비스·캐릭터리스틱 경로와 UUID 목록을 볼 수 있습니다. select-attribute에는 D-Bus 경로나 UUID를 줄 수 있고, attribute-info로 선택한 항목의 UUID와 속성(Flags)을 확인한 뒤 read하면 Attempting to read … 다음에 값이 출력됩니다. 끝나면 back으로 main에 돌아와 disconnect합니다.

Connected와 ServicesResolved는 무엇을 뜻하나?

한 줄 답: Connected는 링크가 붙었다는 뜻, ServicesResolved는 원격 GATT 서비스 탐색이 끝났다는 뜻입니다.

  1. BlueZ 문서(org.bluez.Device D-Bus API)에서 org.bluez.Device1 인터페이스의 Connected는 장치 연결 여부, ServicesResolved는 서비스 탐색 완료 여부를 나타내는 boolean 속성입니다. bluetoothctl의 info <주소>로 보거나, D-Bus로 직접 조회할 수 있습니다.
# 예시: D-Bus로 Device1 속성 직접 조회 (경로의 hci0, 주소는 예시)
$ busctl get-property org.bluez /org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF \
    org.bluez.Device1 ServicesResolved
  1. GATT 명령은 서비스 탐색이 끝난 뒤에야 의미가 있으므로, ServicesResolved: yes를 기다린 다음 menu gatt로 넘어가는 것이 안전합니다. 다만 이것도 “탐색이 끝났다”일 뿐 “값을 읽었다”는 아닙니다. 이 차이로 생기는 테스트 판정 문제는 아래에서 다룹니다.

왜 Invalid command in menu main: read가 나오나?

한 줄 답: read는 gatt 메뉴의 명령인데 main 메뉴에서 입력했기 때문입니다.

  1. bluetoothctl은 main, gatt 같은 메뉴로 명령이 나뉘어 있고, 현재 메뉴에 없는 명령을 입력하면 Invalid command in menu <메뉴>: <명령>을 출력합니다. 아래는 이 글 작성 환경(BlueZ 5.82)에서 실제로 실행해 바이너리 안의 메시지 문자열을 확인한 결과입니다.
$ bluetoothctl --version
bluetoothctl: 5.82
$ strings /usr/bin/bluetoothctl | grep -iE 'invalid command in menu|Attempting to read'
Attempting to read %s
Invalid command in menu %s: %s

bluetoothctl main 메뉴와 gatt 메뉴, read 실패 원인

  1. 자주 겪는 경우는 두 가지입니다. 하나는 menu gatt를 빼먹은 경우, 다른 하나는 스크립트로 명령을 흘려 넣다가 중간에 back이 섞이거나 세션이 새로 시작되어 main으로 돌아간 경우입니다. 프롬프트가 어느 메뉴인지 먼저 확인하고, 필요하면 다시 menu gatt로 들어갑니다.

왜 ServicesResolved만으로 PASS 처리하면 안 될까?

한 줄 답: ServicesResolved는 “서비스 탐색이 끝났다”는 중간 지점일 뿐, 값을 실제로 읽었다는 증거가 아니기 때문입니다.

  1. BlueZ 문서에서 ServicesResolved는 서비스 탐색 완료 여부를 나타내는 속성입니다. 탐색이 끝난 직후에도 링크는 끊길 수 있고, 그러면 그 뒤의 GATT 명령은 실행되지 못합니다.
  2. 그래서 판정을 두 단계로 나눕니다. 연결 판정은 Connection successful과 ServicesResolved: yes, read 판정은 Attempting to read <경로> 바로 다음 줄에 값이 찍힌 것입니다. 최종 PASS는 read 판정만 기준으로 하고, 연결만 된 사이클은 “연결 OK, read FAIL”로 따로 기록해 원인 분석에 씁니다.

자주 보이는 실패 패턴은 어떤 모양인가?

한 줄 답: 연결 단계의 시간 초과와, Resolved 직후 링크가 끊기면서 read가 main 메뉴로 떨어지는 경우가 대표적입니다.

연결 판정과 GATT read 판정 분리

  1. 실패 A (연결 단계): connect가 br-connection-page-timeout 같은 오류로 실패합니다. 상대가 광고를 멈췄거나 범위를 벗어났을 때 볼 수 있습니다.
  2. 실패 B (Resolved 직후): ServicesResolved: yes가 찍힌 뒤 br-connection-profile-unavailable 오류와 Connected: no가 이어지고, 스크립트가 흘려 넣은 read가 main 메뉴에서 실행되어 Invalid command in menu main: read가 나옵니다. 연결 판정만 보면 이 사이클은 PASS처럼 보입니다.

테스트 한 사이클의 실패 지점과 대응

  1. 두 오류 이름은 이 글을 쓴 환경의 BlueZ 5.82 bluetoothd에 실제로 들어 있는 문자열입니다.
$ strings /usr/libexec/bluetooth/bluetoothd | grep -E '^br-connection-(page-timeout|profile-unavailable)'
br-connection-page-timeout
br-connection-profile-unavailable
  1. 또 하나의 교훈: 테스트 대상 기기에 있는 다른 BLE 기능이 같은 HCI(블루투스 컨트롤러)를 함께 쓴다면, 테스트 전에 그 기능을 잠시 멈춰야 연결이 서로 방해받지 않습니다.

실패하면 어떻게 재시도하고 무엇을 read해야 할까?

한 줄 답: 같은 사이클 안에서 재연결은 1회만 하고, 전체 탐색 대신 UUID를 지정해 필요한 캐릭터리스틱 하나를 읽습니다.

  1. 재연결 1회: 끊김을 만나면 같은 사이클 안에서 한 번만 재연결하고, 그래도 실패하면 FAIL로 기록하고 다음 사이클로 넘어갑니다. 무한 재시도는 진짜 결함을 가리고 테스트 시간도 예측할 수 없게 만듭니다.
  2. UUID 지정 read: 매번 list-attributes로 전체 트리를 훑으면 시간이 길어지고 그 사이 끊길 기회도 늘어납니다. select-attribute에 확인하려는 캐릭터리스틱의 UUID(예: Battery Level 00002a19-0000-1000-8000-00805f9b34fb)를 바로 주고 read합니다.

판정 로직은 어떻게 단위 테스트로 고정할까?

한 줄 답: 실제로 본 로그 문자열을 테스트 입력으로 저장해 두고, 판정 함수가 각 패턴에 같은 결론을 내는지 매번 확인합니다.

  1. 아래는 로그 텍스트로 한 사이클을 판정하는 예시 판정 함수입니다. 실기 없이도 돌아가며, 연결 여부와 read 여부를 따로 돌려줍니다.
"""Example: judge one BLE test cycle from bluetoothctl log text.
Connection success and GATT read success are judged separately."""
import re

HEX_LINE = re.compile(r"^\s*([0-9a-f]{2}\s)+", re.I)

def judge(log: str) -> dict:
    lines = log.splitlines()
    connected = any("Connection successful" in l for l in lines)
    resolved = any("ServicesResolved: yes" in l for l in lines)
    read_ok, reason = False, "no read attempted"
    for i, l in enumerate(lines):
        if "Invalid command in menu main: read" in l:
            reason = "read ran in main menu (gatt context lost)"
        if "Connected: no" in l and not read_ok:
            reason = "link dropped before read"
        if "Attempting to read" in l:
            nxt = lines[i + 1] if i + 1 < len(lines) else ""
            if HEX_LINE.match(nxt):
                read_ok, reason = True, "value read"
                break
            reason = "read attempted, no value"
        m = re.search(r"Failed to connect: \S+ (\S+)", l)
        if m:
            reason = m.group(1)
    return {"connected": connected, "resolved": resolved,
            "read_ok": read_ok, "verdict": "PASS" if read_ok else "FAIL",
            "reason": reason}
  1. 테스트 입력은 위 실패 패턴을 본뜬 예시 로그입니다(주소·경로는 예시).
import unittest
from verdict import judge

DEV = "AA:BB:CC:DD:EE:FF"  # example address
PATH = "/org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF/service000a/char000b"  # example path

OK = f"""Attempting to connect to {DEV}
Connection successful
[CHG] Device {DEV} ServicesResolved: yes
Attempting to read {PATH}
  55                                               U"""

DROPPED = f"""Attempting to connect to {DEV}
Connection successful
[CHG] Device {DEV} ServicesResolved: yes
Failed to connect: org.bluez.Error.Failed br-connection-profile-unavailable
[CHG] Device {DEV} Connected: no
Invalid command in menu main: read"""

TIMEOUT = f"""Attempting to connect to {DEV}
Failed to connect: org.bluez.Error.Failed br-connection-page-timeout"""

class T(unittest.TestCase):
    def test_pass_needs_value(self):
        r = judge(OK); self.assertEqual(r["verdict"], "PASS")
    def test_resolved_is_not_pass(self):
        r = judge(DROPPED)
        self.assertTrue(r["resolved"]); self.assertEqual(r["verdict"], "FAIL")
        self.assertIn("main menu", r["reason"])
    def test_page_timeout(self):
        r = judge(TIMEOUT)
        self.assertFalse(r["connected"]); self.assertEqual(r["reason"], "br-connection-page-timeout")

if __name__ == "__main__":
    unittest.main(verbosity=2)

Python 3.13.5에서 실제로 실행한 결과입니다.

$ python3 test_verdict.py
test_page_timeout (__main__.T.test_page_timeout) ... ok
test_pass_needs_value (__main__.T.test_pass_needs_value) ... ok
test_resolved_is_not_pass (__main__.T.test_resolved_is_not_pass) ... ok

----------------------------------------------------------------------
Ran 3 tests in 0.000s

OK
  1. 핵심은 test_resolved_is_not_pass입니다. ServicesResolved가 찍혔어도 값이 없으면 FAIL이어야 한다는 규칙을 테스트로 박아 두면, 나중에 누가 판정을 “연결만 되면 PASS”로 느슨하게 바꿔도 바로 드러납니다.

참고: Bluetooth Core Specification (Vol 3 Part B Base UUID, Part C GAP, Part F ATT, Part G GATT), Bluetooth SIG Assigned Numbers, Battery Service 사양, BlueZ 문서(org.bluez.Device·org.bluez.GattCharacteristic D-Bus API, bluetoothctl), Nordic nRF Connect 앱 문서, Python unittest 문서.