GDBLE - Godot Bluetooth Low Energy Plugin

<img alt="GitHub Actions Workflow Status" src="https://img.shields.io/github/actions/workflow/status/Fantety/GDBLE/release.yml">
<img alt="GitHub code size in bytes" src="https://img.shields.io/github/languages/code-size/Fantety/GDBLE">
<img alt="GitHub language count" src="https://img.shields.io/github/languages/count/Fantety/GDBLE">
<img alt="GitHub License" src="https://img.shields.io/github/license/Fantety/GDBLE">

A modern Bluetooth Low Energy (BLE) plugin for Godot 4

<a href="https://github.com/Fantety/GDBLE/raw/v0.5.5/README.md">🇨🇳 中文</a> | 
<a href="https://github.com/Fantety/GDBLE/raw/v0.5.5/README_EN.md">🇺🇸 English</a>

---

📖 Table of Contents

• 📖 Table of Contents
• Overview
• Why Choose GDBLE?
• Features
• Core Functionality
• Technical Features
• Platform Support
• Installation
• Method 1: Install from Asset Library (Recommended)
• Method 2: Manual Installation
• Quick Start
• Basic Usage
• Connect and Read/Write Data
• API Reference
• BluetoothManager
  • Methods
  • Signals
• BleDevice
  • Methods
  • Signals
• Complete Examples
• Example 1: Scan and Connect to Device
• Example 2: Read Sensor Data
• Example 3: Control Smart Light Bulb
• Debug Mode
• Enable Debug Mode
• Debug Output Example
• Disable Debug Mode
• Conditional Debugging
• FAQ
• Q: Why can't I find any devices?
• Q: What if device connection fails?
• Q: How to handle device disconnection?
• Q: Write operation has no response?
• Q: How to find correct service and characteristic UUIDs?
• Q: Does it support connecting to multiple devices simultaneously?
• Q: How's the performance? Will it affect game frame rate?
• Data Format Description
• DeviceInfo Dictionary
• Service Dictionary
• Characteristic Dictionary
• Best Practices
• 1. Error Handling
• 2. Resource Cleanup
• 3. Timeout Handling
• 4. State Management
• 5. Data Validation
• Performance Optimization Tips
• 1. Scan Optimization
• 2. Write Optimization
• 3. Notification Optimization
• Troubleshooting
• Enable Detailed Logging
• Check Adapter Status
• Verify Device Connection
• View Discovered Services
• Contributing
• License
• Acknowledgments
• Contact

---

Overview

GDBLE is a Bluetooth Low Energy (BLE) plugin designed for Godot 4, built with Rust and GDExtension. Based on the btleplug library, it provides complete BLE functionality including device scanning, connection, service discovery, characteristic read/write, and notification subscription.

Plugin Page: GDBLE - Godot Asset Library

Why Choose GDBLE?

• ✅ Modern Architecture: Built with Rust and async runtime for excellent performance
• ✅ Real-time Response: Non-blocking operations that don't affect game frame rate
• ✅ Complete Features: Supports all BLE operations including scan, connect, read, write, and notify
• ✅ Easy to Use: Clean GDScript API with signal-driven event system
• ✅ Debuggable: Built-in debug mode for development and troubleshooting

---

Features

Core Functionality

• 🔍 Device Scanning: Scan nearby BLE devices, get device name, address, and signal strength
• 🔗 Device Connection: Connect to specified BLE devices
• 🔎 Service Discovery: Automatically discover all GATT services and characteristics
• 📖 Characteristic Reading: Read characteristic values
• ✍️ Characteristic Writing: Write data to characteristics (with/without response)
• 🔔 Notification Subscription: Subscribe to characteristic notifications for real-time data
• 🎯 Multi-device Management: Manage multiple BLE device connections simultaneously

Technical Features

• ⚡ Async Non-blocking: All operations execute asynchronously without blocking main thread
• 🔒 Thread Safe: Uses Tokio runtime to ensure thread safety
• 📊 Signal Driven: Event notification through Godot signal system
• 🐛 Debuggable: Optional debug mode with detailed logging
• 🎮 Game Friendly: Optimized for game development, no frame rate impact

---

Platform Support

Platform	Architecture	Status	Version Required
Windows	x86_64	✅ Tested	Windows 10+
macOS	x86_64	✅ Supported	macOS 10.15+
macOS	ARM64 (M1/M2)	✅ Supported	macOS 11+
Linux	x86_64	✅ Supported	Ubuntu 20.04+
Android	ARM64	⚠️ Not tested	Android 5.0+ (API 21+)
Android	x86_64	⚠️ Not tested	Android 5.0+ (API 21+)

⚠️ Note: Android ARMv7 (32-bit) architecture is not supported. Please use ARM64 or x86_64 architectures.

⚠️ Important: Android builds compile successfully but have not been tested on actual devices. Please test thoroughly before production use.

Thread Safety

Starting from v0.5.3, GDBLE uses a channel-based event system to ensure thread safety:

• All async operations send events through mpsc::UnboundedSender from background threads
• BluetoothManager processes events on the main thread via process() callback
• All Godot API calls (signal emissions, etc.) are executed on the main thread only

This resolves the panic/hang issues caused by calling Godot API from background threads in previous versions (Issue #11, #14).

---

Installation

Method 1: Install from Asset Library (Recommended)

1. Open AssetLib in Godot Editor
2. Search for "GDBLE" or "Bluetooth"
3. Click download and install

Method 2: Manual Installation

1. Download the latest version from Releases
2. Extract to your Godot project's addons folder
3. Ensure the file structure is as follows:

your_project/
├── addons/
│   └── gdble/
│       ├── gdble.gdextension
│       └── gdble.dll (Windows) or libgdble.dylib (macOS)

1. Restart Godot Editor

---

Quick Start

Basic Usage

extends Node

var bluetooth_manager: BluetoothManager

func _ready():
    # 1. Create BluetoothManager instance
    bluetooth_manager = BluetoothManager.new()
    add_child(bluetooth_manager)

    # 2. Connect signals
    bluetooth_manager.adapter_initialized.connect(_on_adapter_initialized)
    bluetooth_manager.device_discovered.connect(_on_device_discovered)
    bluetooth_manager.scan_stopped.connect(_on_scan_stopped)

    # 3. Initialize Bluetooth adapter
    bluetooth_manager.initialize()

func _on_adapter_initialized(success: bool, error: String):
    if success:
        print("Bluetooth initialized successfully")
        # Start scanning for 10 seconds
        bluetooth_manager.start_scan(10.0)
    else:
        print("Bluetooth initialization failed: ", error)

func _on_device_discovered(device_info: Dictionary):
    print("Device found: ", device_info.get("name", "Unknown"))
    print("  Address: ", device_info.get("address"))
    print("  Signal strength: ", device_info.get("rssi"), " dBm")

func _on_scan_stopped():
    print("Scan complete")
    var devices = bluetooth_manager.get_discovered_devices()
    print("Total devices found: ", devices.size())

Connect and Read/Write Data

var connected_device: BleDevice = null

func connect_to_device(address: String):
    # Connect to device
    connected_device = bluetooth_manager.connect_device(address)
    if connected_device:
        # Connect device signals
        connected_device.connected.connect(_on_device_connected)
        connected_device.services_discovered.connect(_on_services_discovered)
        connected_device.characteristic_written.connect(_on_characteristic_written)

        # Start connection
        connected_device.connect_async()


func _on_device_connected():
    print("Device connected")
    # Discover services
    connected_device.discover_services()

func _on_services_discovered(services: Array):
    print("Discovered ", services.size(), " services")

    # Iterate through services and characteristics
    for service in services:
        var service_uuid = service.get("uuid")
        var characteristics = service.get("characteristics", [])

        for characteristic in characteristics:
            var char_uuid = characteristic.get("uuid")
            var properties = characteristic.get("properties", {})

            # If characteristic supports write, write data
            if properties.get("write", false):
                var data = "Hello BLE".to_utf8_buffer()
                connected_device.write_characteristic(service_uuid, char_uuid, data, false)

func _on_characteristic_written(char_uuid: String):
    print("Data written successfully: ", char_uuid)

---

API Reference

BluetoothManager

Bluetooth manager responsible for adapter initialization, device scanning, and connection management.

Methods

Method	Parameters	Return	Description
initialize()	None	void	Initialize Bluetooth adapter
is_initialized()	None	bool	Check if adapter is initialized
start_scan(timeout_seconds)	float	void	Start scanning for devices
stop_scan()	None	void	Stop scanning
get_discovered_devices()	None	Array[Dictionary]	Get list of discovered devices
connect_device(address)	String	BleDevice	Connect to specified device
disconnect_device(address)	String	void	Disconnect specified device
get_device(address)	String	BleDevice	Get connected device instance
get_connected_devices()	None	Array[BleDevice]	Get all connected devices
set_debug_mode(enabled)	bool	void	Enable/disable debug mode
is_debug_mode()	None	bool	Check debug mode status

Signals

Signal	Parameters	Description
adapter_initialized	success: bool, error: String	Adapter initialization complete
device_discovered	device_info: Dictionary	New device discovered
device_updated	device_info: Dictionary	Device information updated
scan_started	None	Scan started
scan_stopped	None	Scan stopped
device_connecting	address: String	Device connection initiated
device_connected	address: String	Device connected successfully
device_disconnected	address: String	Device disconnected
error_occurred	error_message: String	Error occurred

BleDevice

Represents a single BLE device, provides connection, service discovery, and data read/write functionality.

Methods

Method	Parameters	Return	Description
connect_async()	None	void	Asynchronously connect to device
disconnect()	None	void	Disconnect from device
is_connected()	None	bool	Check if connected
get_address()	None	String	Get device address
get_name()	None	String	Get device name
discover_services()	None	void	Discover device services
get_services()	None	Array[Dictionary]	Get discovered services list
read_characteristic(service_uuid, char_uuid)	String, String	void	Read characteristic value
write_characteristic(service_uuid, char_uuid, data, with_response)	String, String, PackedByteArray, bool	void	Write characteristic value
subscribe_characteristic(service_uuid, char_uuid)	String, String	void	Subscribe to characteristic notifications
unsubscribe_characteristic(service_uuid, char_uuid)	String, String	void	Unsubscribe from notifications

Signals

Signal	Parameters	Description
connected	None	Device connected successfully
disconnected	None	Device disconnected
connection_failed	error: String	Connection failed
services_discovered	services: Array	Service discovery complete
characteristic_read	char_uuid: String, data: PackedByteArray	Characteristic read complete
characteristic_written	char_uuid: String	Characteristic write complete
characteristic_notified	char_uuid: String, data: PackedByteArray	Characteristic notification received
operation_failed	operation: String, error: String	Operation fail