GodotBluetooth: A Java repository from drentsoft

This module is a native Bluetooth implementation intended to perform fundamental tasks in a communication between bluetooth devices, built for use in Godot Engine, running on the Android platform. It does not support iOS Bluetooth Low-Energy (BLE) at the moment, but it could be added in the future.

The plugin has been tested with:

Godot 3.3 Stable
ESP-32S microcontroller
Multiple android devices

Credits

This fork is based on work done by faverete and DisDoh.

Available Featuress

Native dialog box layout for easy device connection
Easy implementation of custom layouts inside Godot
Communication with microcontrollers with bluetooth
Communication between two mobile devices running android

Known Issues

Crash when trying to call connect_device while there is already an established connection. Temporary fix: just make sure to allow a connection to fail or use close_connection before trying to start a new connection.

Plugin Installation

This module has been updated to be used with Godot's new android .aar based plugin system, and so, it must be used with Godot 3.2.2+

Godot 3.3.1 Plugin Release (GodotBluetooth v1.1)
Godot 3.3 Plugin Release (GodotBluetooth v1.1)

[Note] Newer builds may successfully compile, but not fully be bug tested. They may result in unexpected crashes.

To install this plugin in your Godot, you must create a custom android build for your project. Creating a custom android build in itself requires that you setup your system to export for android.

After completting these steps, the plugin installation is very straight forward. Download the proper release listed above for your version of Godot or you can build the plugin yourself by following the steps in "Building the Plugin" below.

Extract GodotBluetooth.aar and GodotBluetooth.gdap into the android/plugins folder in your project that was created from creating a custom android build.

Make sure that "use custom build" and "Godot Bluetooth" are checked under the runnable android export template in the export dialog.

Make sure that "Bluetooth", "Bluetooth Admin", and "Access Fine Location" permissions are checked in the export dialog.

Deploy your project!

Building the Plugin

TODO: Build instructions

Getting Started with GodotBluetooth

To use the bluetooth plugin you must first get and initialize the JNISingleton object:

var bluetooth_controller:JNISingleton = null

func _ready() -> void:
	if(Globals.has_singleton("GodotBluetooth")):
		bluetooth_controller = Globals.get_singleton("GodotBluetooth")
		bluetooth_controller.init(false, false, 2048)

Devices that are able to be communicated with should be paired before establishing a connection through this plugin. You can pair the devices in the settings of your android device. You can use device discovery to connect to a device that has not been paired in the settings.

To get the list of paired devices:

if (bluetooth_controller):
	var paired_devices:Dictionary = bluetooth_controller.get_paired_devices()

To connect to a device from the list:

bluetooth_controller.connect_device(paired_devices.device_0.device_address)

API Reference

Initialize Bluetooth

func init(discovery_enabled:bool, bluetooth_required:bool, data_buffer_size:int) -> void

Initializes bluetooth functionality.

bluetooth_required is a boolean that tells if the bluetooth is required inside the game/application. If true, the game/application will close when the bluetooth is off and the user refuses to activate on the startup, if false, the game/application will continue in the occurrence of the same situation.

Get Paired Devices

func get_paired_devices() -> Dictionary

Gets the list of paired devices and returns them as a Dictionary containing a set of nested dictionaries.

Dictionary structure:

{
	"device_0":{
		"device_name":device_name,
		"device_address":device_address
	},
	"device_1":{ ... },
	...
}

Connect Device

func connect_device(device_address:String) -> void

Attempts to connect to the given device_address.

device_address is a String containing the bluetooth address of the device you want to connect. You only need to use this function if you're not using native_select_paired_device.

Native Select Paired Device

func native_select_paired_device(override_connection:bool) -> void

Brings up a native dialog to select which paired device to connect. It will fail if a connection is already open unless override_connection is true.

override_connection is a bool determining whether any open connection will be overridden.

Start Server

func start_server(server_name:String) -> void

Starts a server thread on the android device to allow for accepting connections from other android devices. The results and actions of connections are controlled by signals similar to Godot's high-level networking.

server_name is a string contains the server name for use in discovery or pairing.

Close Connection

func close_connection() -> void

Stops all bluetooth related threads and closes any open bluetooth connections.

Start Discovery

func start_discovery() -> void

Starts the discovery process for searching for bluetooth devices. This will be canceled if start_server or connect_device is called. It is an intensive process and requires a lot of bandwidth. It is recommended to use cancel_discovery even if you think discovery is no longer active. Discovered bluetooth devices will be returned with the device_discovered signal. It can only be used if discovery_enabled is set to true on init, otherwise, the function will fail.

Cancel Discovery

func cancel_discovery() -> void

Cancels the discovery process for searching for bluetooth devices. It can only be used if discovery_enabled is set to true on init, otherwise, the function will fail.

Get UUID

func get_uuid() -> String

Returns the bluetooth UUID of the current android device.

Make Discoverable

func make_discoverable(discovery_duration:int) -> void

Starts a discovery activity on your current device so other devices can discover your device by using start_discovery. This is a system process and uses a lot of battery and bandwidth. Continuous broadcasting has been disabled and you must use a duration value greater than 0 seconds.

discovery_duration is an int that determines how long in seconds that your device will broadcast for other devices to discover it.

Get Device Name

func get_device_name() -> String

Returns the bluetooth name of the current android device.

Get Device Address

func get_device_address() -> String

Returns the bluetooth address of the current android device.

Send Data

func send_data(data:String) -> void

Sends a String of data as bytes over the bluetooth socket.

Send Raw Data

func send_raw_data(raw_data:PoolByteArray) -> void

Sends a byte array over the bluetooth socket.

Is Server

func is_server() -> bool

Returns whether or not the current android device is the server.

Is Initialized

func is_initialized() -> bool

Returns whether the bluetooth adapter has been initialized.

Clean Up

func cleanup() -> void

Frees the broadcast receiver and uninitializes the bluetooth adapter. It has to be used when using device discovery to unregister the broadcast receiver or it will stay active in the system process even after the app has been killed. It is not necessary otherwise, but it is still good practice, and it will also allow you to reinitialize the bluetooth adapter with different initialization properties.

Signals

signal status_logged(status_type:int, status:String) # Status update = 0, Error = 1
signal device_discovered(device_name:String, device_address:String)
signal device_connected(device_name:String, device_address:String)
signal device_disconnected(device_name:String, device_address:String)
signal connection_closed()
signal connection_failed(java_connection_error:String)
signal connection_received(device_name:String, device_address:String)
signal data_received(data:String, raw_data:PoolByteArray)

TODO

Finish readme documentation(Building)

drentsoft/GodotBluetooth