Key Takeaway

In BLE, a Peripheral advertises and a Central scans and connects. The rules for finding and connecting are GAP; the rules for exchanging data once connected are GATT, whose data is organized as a service → characteristic → descriptor tree identified by UUIDs. On Linux, BlueZ bluetoothctl reads a value with connect → menu gatt → select-attribute → read. When you automate the test, don’t treat ServicesResolved: yes as a PASS; only pass when a value appears on the line after Attempting to read ….

When you test a BLE device or integrate one with an app, you often hit “it connected, but I can’t read the value.” This post covers the basic structure of GATT, hands-on reading with Linux BlueZ bluetoothctl, and PASS criteria for automated connection tests, all in one place.

What do the Central and the Peripheral each do?

One-line answer: the Peripheral advertises “I’m here,” and the Central scans for that advertisement and connects.

  1. GAP (Generic Access Profile, Bluetooth Core Specification Vol 3 Part C) defines the LE connection roles Central and Peripheral. A phone or Linux PC is usually the Central; a battery-powered sensor, wearable or appliance module is usually the Peripheral.
  2. Advertising happens before any connection. The Peripheral periodically sends short packets on the advertising channels, which can carry the device name or the UUIDs of the services it offers. The Central picks them up by scanning and learns which devices are nearby.
  3. A connection starts when the Central sends a connection request in response to a particular advertisement. After that, the two devices exchange data at agreed intervals, and GATT runs on top. In short: advertising is one-to-many broadcast, a connection is a one-to-one conversation.

How are GAP and GATT different?

One-line answer: GAP decides how devices find and connect to each other; GATT decides what data is read or written after the connection, and how.

BLE flow: advertising, connection, service discovery, read/notify

  1. GAP covers roles (Central/Peripheral), advertising and scanning, and connection setup. If a device won’t connect, the problem is usually at the GAP stage: no advertising, not showing up in the scan, or the connection request timing out.
  2. GATT (Generic Attribute Profile, Core Spec Vol 3 Part G) runs on top of ATT (Attribute Protocol, Vol 3 Part F). The side that holds the data is the GATT server and the side that asks for it is the GATT client. The Peripheral is often the server and the Central the client, but GAP roles and GATT roles are separate ideas. That’s why “connected” (GAP) and “value read” (GATT) are different success criteria, which comes back in the PASS verdict section below.

How do services, characteristics and UUIDs fit together?

One-line answer: a service groups a feature, a characteristic holds one actual value, and a UUID is the label that names each of them.

  1. A service groups related data. For example, the Bluetooth SIG-defined Battery Service (UUID 0x180F) holds battery-related values.
  2. A characteristic is one actual value inside a service, plus its properties (read, write, notify and so on). Battery Level (UUID 0x2A19) inside the Battery Service is the classic example; its value is the remaining battery charge in percent. A characteristic can have descriptors; the most common is the CCCD (Client Characteristic Configuration, UUID 0x2902), which turns notifications on and off.
  3. UUIDs come in two kinds: 16-bit values assigned by the SIG (listed in the Bluetooth Assigned Numbers document), and 128-bit values vendors create for their own services. Per the Core Spec (Vol 3 Part B, Bluetooth Base UUID), a 16-bit UUID expands to the 128-bit form 0000xxxx-0000-1000-8000-00805F9B34FB. A custom service uses a 128-bit value such as 12345678-1234-5678-1234-56789abcdef0 (an example UUID for illustration only).

When do you use read, and when notify?

One-line answer: use read to ask once when you need the value; use notify to get it every time it changes.

GATT tree: service, characteristic, descriptor

  1. read: the client asks and the server replies with the current value. It’s also the simplest way for a test to check that GATT communication actually works.
  2. notify: once the client writes the enable value to the CCCD, the server pushes the value whenever it changes. The acknowledged variant is called indicate. Compared with polling (repeated reads), it saves power and radio airtime.

What do UUID expansion and value decoding look like in code?

One-line answer: drop a 16-bit SIG UUID into the Base UUID to get the 128-bit form, and read Battery Level’s single byte directly as a percentage.

  1. Here’s a small Python example that shows the GATT tree and UUID expansion without any real BLE hardware. The value 0x55 is an example value for illustration.
# 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], "%")

Actual output from running it on 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 %

What do you need, and how do you check bluetoothd?

One-line answer: a Linux PC with a BLE adapter, a phone that advertises with an app like nRF Connect, and a running bluetoothd.

  1. Central: a Linux PC with a built-in or USB Bluetooth adapter. BlueZ’s bluetoothd manages the adapter and exposes it over D-Bus; bluetoothctl is an interactive client for that D-Bus API. On systemd distributions, systemctl status bluetooth shows whether the daemon is running.
  2. Peripheral: install Nordic’s nRF Connect app on a phone and expose a service such as the Battery Service (0x180F) via its advertiser or GATT server settings. A real dev board works too if you have one.

In what order do the commands go, from scan to GATT read?

One-line answer: find and connect in the main menu, then enter menu gatt, select the characteristic and read it.

  1. Here is the whole flow. This session is an example (the machine used to write this post has no BLE adapter, so there’s no real device output); the command names were checked against BlueZ 5.82 bluetoothctl. The address AA:BB:CC:DD:EE:FF is an example.
# Example session (AA:BB:CC:DD:EE:FF is an example address)
$ systemctl status bluetooth        # is bluetoothd running?
$ 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     # check 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

Steps from connecting to a GATT read with bluetoothctl

  1. Use scan on to watch nearby advertisements, find the target address, then stop with scan off. If you see Connection successful after connect, the GAP connection is up.
  2. Inside menu gatt, list-attributes lists service and characteristic paths with their UUIDs. select-attribute takes a D-Bus path or a UUID; attribute-info shows the selected item’s UUID and properties (Flags); then read prints Attempting to read … followed by the value. When you’re done, back to main and disconnect.

What do Connected and ServicesResolved mean?

One-line answer: Connected means the link is up; ServicesResolved means discovery of the remote GATT services has finished.

  1. In the BlueZ docs (org.bluez.Device D-Bus API), Connected and ServicesResolved on the org.bluez.Device1 interface are boolean properties for “is the device connected” and “has service discovery finished.” You can see them with info <address> in bluetoothctl, or query D-Bus directly:
# Example: query a Device1 property over D-Bus (hci0 and the address are examples)
$ busctl get-property org.bluez /org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF \
    org.bluez.Device1 ServicesResolved
  1. GATT commands only make sense after service discovery, so it’s safest to wait for ServicesResolved: yes before moving to menu gatt. Still, that only means “discovery finished,” not “a value was read.” The test-verdict problems this gap causes are covered below.

Why do you get Invalid command in menu main: read?

One-line answer: read is a gatt-menu command, and you typed it in the main menu.

  1. bluetoothctl splits its commands into menus such as main and gatt; a command that isn’t in the current menu prints Invalid command in menu <menu>: <command>. Below is a real run on the machine used for this post (BlueZ 5.82) checking the message strings inside the binary:
$ 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 and gatt menus and why read fails

  1. Two cases are common: forgetting menu gatt, or piping commands from a script where a stray back or a fresh session drops you back to main. Check which menu the prompt is in first, and re-enter menu gatt if needed.

Why isn’t ServicesResolved alone enough for a PASS?

One-line answer: ServicesResolved is a midpoint meaning “service discovery finished,” not evidence that a value was actually read.

  1. In the BlueZ docs, ServicesResolved is the property that says whether service discovery has finished. The link can still drop right after discovery, and then the GATT commands that follow never run.
  2. So split the verdict in two. The connection verdict is Connection successful plus ServicesResolved: yes; the read verdict is a value printed on the line right after Attempting to read <path>. Base the final PASS on the read verdict alone, and record connected-only cycles separately as “connect OK, read FAIL” for root-cause analysis.

What do the common failure patterns look like?

One-line answer: the typical ones are a timeout at the connect step, and the link dropping right after Resolved so that read lands in the main menu.

Splitting the connection verdict from the GATT read verdict

  1. Failure A (connect step): connect fails with an error such as br-connection-page-timeout. You can see this when the other side stopped advertising or is out of range.
  2. Failure B (right after Resolved): after ServicesResolved: yes, a br-connection-profile-unavailable error and Connected: no follow, and the read the script pipes in runs in the main menu, giving Invalid command in menu main: read. Judged by connection alone, this cycle looks like a PASS.

Failure points and responses in one test cycle

  1. Both error names are real strings inside BlueZ 5.82 bluetoothd on the machine used for this post:
$ strings /usr/libexec/bluetooth/bluetoothd | grep -E '^br-connection-(page-timeout|profile-unavailable)'
br-connection-page-timeout
br-connection-profile-unavailable
  1. One more lesson: if another BLE feature on the device under test shares the same HCI (Bluetooth controller), pause it before the test so the two don’t interfere with the connection.

How should you retry on failure, and what should you read?

One-line answer: reconnect only once within the same cycle, and read the one characteristic you need by UUID instead of walking the whole tree.

  1. One reconnect: on a drop, reconnect once within the same cycle; if that fails too, record FAIL and move to the next cycle. Unlimited retries hide real defects and make test time unpredictable.
  2. Read by UUID: walking the full tree with list-attributes every time takes longer and gives the link more chances to drop. Pass the UUID of the characteristic you want (for example Battery Level, 00002a19-0000-1000-8000-00805f9b34fb) straight to select-attribute and read.

How do you pin the verdict logic with unit tests?

One-line answer: save the log strings you’ve actually seen as test inputs, and check every time that the verdict function reaches the same conclusion for each pattern.

  1. Here’s an example verdict function that judges one cycle from log text. It runs without hardware and returns connection and read results separately.
"""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. The test inputs are example logs modelled on the failure patterns above (the address and path are examples).
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)

Actual output from running it on 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. The key one is test_resolved_is_not_pass. Once the rule “no value means FAIL, even with ServicesResolved” is pinned in a test, anyone who later loosens the verdict to “connected means PASS” gets caught right away.

References: Bluetooth Core Specification (Vol 3 Part B Base UUID, Part C GAP, Part F ATT, Part G GATT), Bluetooth SIG Assigned Numbers, Battery Service specification, BlueZ documentation (org.bluez.Device and org.bluez.GattCharacteristic D-Bus APIs, bluetoothctl), Nordic nRF Connect app documentation, Python unittest documentation.