Building a Cross-Platform BLE GATT Editor with Python and Dear ImGui: Custom Service/Characteristic Creation and Real-Time Data Logging

Building a Cross-Platform BLE GATT Editor with Python and Dear ImGui: Custom Service/Characteristic Creation and Real-Time Data Logging

Bluetooth Low Energy (BLE) has become a cornerstone of modern wireless communication, powering everything from medical devices to smart home sensors. At the heart of BLE lies the Generic Attribute Profile (GATT), a hierarchical data structure that defines how devices expose services, characteristics, and descriptors. For embedded developers and test engineers, the ability to inspect, create, and log GATT data in real-time is invaluable. This article explores how to build a cross-platform BLE GATT editor using Python and the Dear ImGui library, focusing on custom service/characteristic creation and real-time data logging. By leveraging Python’s bleak library for BLE communication and Dear ImGui for a responsive GUI, we can create a tool that rivals commercial offerings like TI’s BLE-STACK or nRF Connect, but with the flexibility of open-source development.

Understanding GATT Services and Characteristics

Before diving into implementation, it’s essential to understand the GATT hierarchy. A GATT profile consists of services, each containing one or more characteristics. Characteristics are data points that can be read, written, or notified. For example, the Scan Parameters Service (ScPS) defined in the Bluetooth specification (ScPS_SPEC_V10.pdf) allows a GATT client to store LE scan parameters on a server to optimize power consumption and reconnection latency. This service includes characteristics like the Scan Interval Window and Scan Refresh. Similarly, the Multi-Channel Adaptation Protocol (MCAP) from MCAP_SPEC_V10.pdf provides a control channel for managing data channels in medical device applications. Understanding these standards is crucial for building a tool that can handle real-world BLE devices.

Our editor will support two primary modes: Discover Mode, where we connect to a BLE device and browse its existing GATT structure, and Create Mode, where we define custom services and characteristics. The latter is particularly useful for prototyping proprietary BLE profiles or testing GATT client behavior.

Architecture Overview

The tool is built on three layers:

• BLE Communication Layer: Uses the bleak Python library, which provides asynchronous BLE operations (scan, connect, read/write/notify) across Windows, macOS, and Linux.
• GUI Layer: Uses Dear ImGui via the imgui and glfw bindings for a lightweight, cross-platform interface. Dear ImGui is ideal for tools due to its immediate-mode paradigm, which simplifies UI state management.
• Data Logging Layer: Records all GATT transactions (read/write/notify values, timestamps, and service UUIDs) to a CSV or SQLite database for post-analysis.

Implementing Custom Service/Characteristic Creation

Creating custom services and characteristics requires simulating a GATT server. Since most BLE adapters don’t expose a server API through Python directly, we implement a virtual GATT tree that mirrors what a real server would expose. Users can define services by UUID, add characteristics with properties (read, write, notify) and descriptors (e.g., Client Characteristic Configuration Descriptor – CCCD). The tool then connects to a real BLE device and writes these custom definitions to the device’s GATT database if the device supports it (e.g., via a vendor-specific command or OTA update). For devices that don’t allow dynamic GATT changes, the tool can act as a proxy, intercepting and logging traffic.

import asyncio
from bleak import BleakClient, BleakScanner
from imgui_bundle import imgui, immapp, hello_imgui

class GattEditor:
    def __init__(self):
        self.services = {}  # UUID -> Service object
        self.connected_device = None
        self.log_buffer = []

    async def discover_services(self, address):
        async with BleakClient(address) as client:
            self.connected_device = client
            for service in client.services:
                svc_uuid = service.uuid
                self.services[svc_uuid] = {"characteristics": {}}
                for char in service.characteristics:
                    self.services[svc_uuid]["characteristics"][char.uuid] = {
                        "properties": char.properties,
                        "value": None
                    }
                    # Read initial value if readable
                    if "read" in char.properties:
                        val = await client.read_gatt_char(char.uuid)
                        self.services[svc_uuid]["characteristics"][char.uuid]["value"] = val

    def add_custom_service(self, uuid):
        if uuid not in self.services:
            self.services[uuid] = {"characteristics": {}}
            self.log_event(f"Added custom service: {uuid}")

    def add_custom_characteristic(self, svc_uuid, char_uuid, properties=["read", "write"]):
        if svc_uuid in self.services:
            self.services[svc_uuid]["characteristics"][char_uuid] = {
                "properties": properties,
                "value": None
            }
            self.log_event(f"Added characteristic {char_uuid} to service {svc_uuid}")

    def log_event(self, message):
        import datetime
        self.log_buffer.append(f"[{datetime.datetime.now()}] {message}")

Real-Time Data Logging

The logging system captures every GATT operation. For notifications, we register a callback that logs the value and timestamp. The buffer is displayed in a Dear ImGui window and periodically flushed to a file. This is critical for debugging transient issues, such as the Scan Parameters Service where the server might adjust behavior based on scan intervals.

async def notification_handler(sender, data):
    timestamp = datetime.datetime.now().isoformat()
    log_entry = f"Notify from {sender}: {data.hex()} at {timestamp}"
    self.log_buffer.append(log_entry)
    # Optionally write to SQLite
    self.db.execute("INSERT INTO gatt_log (timestamp, uuid, value) VALUES (?, ?, ?)",
                    (timestamp, str(sender), data.hex()))

# During connection
await client.start_notify(char_uuid, notification_handler)

Dear ImGui Integration

Dear ImGui provides a clean interface for displaying the GATT tree. Each service is a collapsible tree node, and characteristics are leaves. Buttons allow adding new services/characteristics, and input fields let users specify UUIDs and values. The real-time log is shown in a separate window with auto-scroll.

def draw_gui(self):
    imgui.begin("BLE GATT Editor")
    if imgui.button("Scan for Devices"):
        # Trigger async scan
        pass
    imgui.separator()
    imgui.text("Services")
    for svc_uuid, svc in self.services.items():
        expanded, _ = imgui.tree_node(svc_uuid)
        if expanded:
            for char_uuid, char in svc["characteristics"].items():
                imgui.text(f"  {char_uuid} [{', '.join(char['properties'])}]")
                if "read" in char["properties"] and imgui.button(f"Read##{char_uuid}"):
                    # Read value
                    pass
            imgui.tree_pop()
    imgui.end()

    imgui.begin("Log")
    for entry in self.log_buffer[-100:]:  # Show last 100 entries
        imgui.text(entry)
    imgui.end()

Performance Considerations

BLE communication is asynchronous, so the GUI must remain responsive. Using asyncio with Dear ImGui requires careful integration. The hello_imgui library (part of imgui_bundle) provides a runner that can integrate an asyncio event loop. For high-throughput logging (e.g., multiple notifications per second), buffering and batch writes to disk are essential. In our tests, a simple CSV logger handled 1000+ entries per second without blocking the UI.

Another challenge is UUID handling. Bluetooth specifications use 16-bit UUIDs (e.g., 0x180D for Heart Rate Service) that are expanded to 128-bit format. Our tool automatically expands short UUIDs to comply with the Bluetooth Core Specification.

Protocol Details: Scan Parameters Service Example

To illustrate real-world use, consider the Scan Parameters Service (ScPS). According to the ScPS_SPEC_V10.pdf, this service has two characteristics: Scan Interval Window (UUID 0x2A4F) and Scan Refresh (UUID 0x2A50). The Scan Interval Window characteristic is writable by a GATT client to store its scan parameters on the server. Our editor can write to this characteristic and observe how the server’s power consumption changes. The log would show:

[2025-03-28 10:15:32] Write to 0x2A4F: 0x1234  ; Scan interval = 0x1234 * 0.625 ms
[2025-03-28 10:15:33] Notify from 0x2A50: 0x01    ; Scan refresh requested

This demonstrates the editor’s value in validating protocol compliance.

Conclusion

Building a cross-platform BLE GATT editor with Python and Dear ImGui is a powerful way to accelerate BLE development and testing. By combining bleak for robust BLE access and Dear ImGui for a responsive UI, we can create a tool that supports custom service/characteristic creation and real-time data logging. The architecture is extensible—adding support for Bluetooth Mesh or LE Audio would follow similar patterns. For embedded developers, this tool bridges the gap between low-level protocol analysis and high-level application debugging, making it a valuable addition to any wireless engineer’s toolkit.

Future enhancements could include GATT database export to JSON, scripting for automated test sequences, and integration with protocol analyzers like Wireshark. The open-source nature of Python and Dear ImGui ensures that the community can adapt the editor to emerging BLE specifications, such as the Multi-Channel Adaptation Protocol for medical devices. Start building your own editor today, and gain deeper insight into the wireless world around you.

💬 欢迎到论坛参与讨论： 点击这里分享您的见解或提问