Module com.gluonhq.attach.ble

Package com.gluonhq.attach.ble

Interface BleService

All Known Implementing Classes:

AndroidBleService, DummyBleService, IOSBleService

public interface BleService

Beacons

The BLE scanner, which is short for Bluetooth Low Energy, can be used to communicate with devices that are equipped with Bluetooth low energy wireless technology. After scanning has started, a callback function will be called with a scanned result from a detected nearby BLE enabled device. The scan result will contain the major and minor values of the detected device, as well as its signal strength (rssi) and an approximation of the proximity to the scanning device.

Example

 String uuid = UUID.randomUUID().toString(); // for example a known UUID of a beacon
  BleService.create().ifPresent(service -> {
      service.startScanning(new Configuration(uuid), scanResult -> {
          System.out.printf("major: %d, minor: %d, proximity: %s",
                  scanResult.getMajor(), scanResult.getMinor(),
                  scanResult.getProximity().name());
      });
  });

Requirements

The service requires the following changes on Android and iOS.

However, these are handled automatically by the GluonFX plugin, when used.

Android Configuration

The permissions android.permission.BLUETOOTH and android.permission.BLUETOOTH_ADMIN need to be added.

 <manifest ...>
    <uses-permission android:name="android.permission.BLUETOOTH"/>
    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>
    ...
  </manifest>

iOS Configuration

The following keys are required for Beacons:

 <key>NSLocationUsageDescription</key>
  <string>Reason to use Location Service (iOS 6+)</string>
  <key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
  <string>Reason to use Location Service (iOS 8+)</string>
  <key>NSBluetoothAlwaysUsageDescription</key>
  <string>Reason to use Bluetooth interface (iOS 13+)</string>

Since:

3.9.0

Devices

BLE devices are equipped with Bluetooth low energy wireless technology, such as heart rate monitors and digital thermostats. This BleService can be added to central devices (i.e. mobile device with Bluetooth enabled), to discover other peripheral BLE devices. The central can request to connect to the peripheral so it can explore and interact with its data. The peripheral is responsible for responding to the central in appropriate ways. For more info about BLE see: https://www.bluetooth.com/specifications/generic-attributes-overview

Example

This code snippet shows how to discover devices:

 
 BleService.create().ifPresent(ble -> {
        ble.startScanningDevices().addListener((ListChangeListener.Change<? extends BleDevice> c) -> {
            while (c.next()) {
                if (c.wasAdded()) {
                    for (BleDevice device : c.getAddedSubList()) {
                        System.out.println("Device found: " + device.getName());
                        device.stateProperty().addListener((obs, ov, nv) -> {
                            if (State.STATE_CONNECTED == nv) {
                                System.out.println("Device connected: " + device.getName());
                            }
                        });
                        ble.connect(device);
                    }
                }
            }
        });
    });
 

This code snippet shows how to discover the services for a given device:

 
 BleService.create().ifPresent(ble -> {
        ...
        bleDevice.getProfiles().addListener((ListChangeListener.Change<? extends BleProfile> c) -> {
            while (c.next()) {
                if (c.wasAdded()) {
                    for (BleProfile profile : c.getAddedSubList()) {
                        int assignedNumber = BleSpecs.getAssignedNumber(profile.getUuid());
                        String specificationName = BleSpecs.GattServices.ofAssignedNumber(assignedNumber).getSpecificationName();
                        System.out.println("Profile: " + specificationName + ", " + String.format("UUID: 0x%04x", assignedNumber));
                    }
                }
            }
        });
    });
 

This code snippet shows how to discover the characteristics for a given service:

 
 BleService.create().ifPresent(ble -> {
        ...
        bleProfile.getCharacteristics().addListener((ListChangeListener.Change<? extends BleCharacteristic> c) -> {
            while (c.next()) {
                if (c.wasAdded()) {
                    for (BleCharacteristic characteristic : c.getAddedSubList()) {
                        int assignedNumber = BleSpecs.getAssignedNumber(characteristic.getUuid());
                        String specificationName = BleSpecs.GattServices.ofAssignedNumber(assignedNumber).getSpecificationName();
                        System.out.println("Characteristic: " + specificationName + ", " + String.format("UUID: 0x%04x", assignedNumber));
                    }
                }
            }
        });
    });
 

And finally, this code snippet shows how to subscribe to a characteristic of a given device and service to listen to its values:

 
 BleService.create().ifPresent(ble -> {
        ...
        bleCharacteristic.valueProperty().addListener((obs, ov, nv) ->
              System.out.println("Value: " + Arrays.toString(nv)));
        ble.subscribeCharacteristic(bleDevice, bleProfile.getUuid(), bleCharacteristic.getUuid());
    });
 

Requirements

The service requires the following changes on Android and iOS.

However, these are handled automatically by the GluonFX plugin, when used.

Android Configuration

The same permissions android.permission.BLUETOOTH, android.permission.BLUETOOTH_ADMIN and android.permission.ACCESS_FINE_LOCATION need to be added to the Android manifest.

 <manifest ...>
    <uses-permission android:name="android.permission.BLUETOOTH"/>
    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
    ...
    <activity android:name="com.gluonhq.helloandroid.PermissionRequestActivity" />
  </manifest>

iOS Configuration

The following keys are required for Devices:

 <key>NSBluetoothAlwaysUsageDescription</key>
  <string>Reason to use Bluetooth interface (iOS 13+)</string>

, 4.0.6

Method Summary

Modifier and Type	Method	Description
void	connect(BleDevice device)	Connects to a given BLE device
static java.util.Optional<BleService>	create()	Returns an instance of BleService.
void	disconnect(BleDevice device)	Disconnects from a given BLE device
void	readCharacteristic(BleDevice device, java.util.UUID uuidProfile, java.util.UUID uuidCharacteristic)	Given a BleDevice, with a given BleProfile and a given BleCharacteristic, reads its value
void	startBroadcasting(java.util.UUID beaconUUID, int major, int minor, java.lang.String identifier)	Configure the current device as a Bluetooth beacon, and start advertising with a given UUID
void	startScanning(Configuration configuration, java.util.function.Consumer<ScanDetection> callback)	Start scanning for BLE beacons.
javafx.collections.ObservableList<BleDevice>	startScanningDevices()	Start scanning for BLE Devices.
void	stopBroadcasting()	Stop advertising the current iOS device as a Bluetooth beacon
void	stopScanning()	Stops the last called startScanning operation.
void	stopScanningDevices()	Stops scanning for BLE devices
void	subscribeCharacteristic(BleDevice device, java.util.UUID uuidProfile, java.util.UUID uuidCharacteristic)	Given a BleDevice, with a given BleProfile and a given BleCharacteristic, subscribes to listen to changes in its value
void	unsubscribeCharacteristic(BleDevice device, java.util.UUID uuidProfile, java.util.UUID uuidCharacteristic)	Given a BleDevice, with a given BleProfile and a given BleCharacteristic, unsubscribes and stop listening to changes in its value
void	writeCharacteristic(BleDevice device, java.util.UUID uuidProfile, java.util.UUID uuidCharacteristic, byte[] value)	Given a BleDevice, with a given BleProfile and a given BleCharacteristic, writes its value

Method Detail

create

static java.util.Optional<BleService> create()

Returns an instance of BleService.

Returns:

An instance of BleService.

startScanning

void startScanning(Configuration configuration,
                   java.util.function.Consumer<ScanDetection> callback)

Start scanning for BLE beacons. When such a device is discovered, the callback will be called with the detailed information on the detected beacon. Note that this method can be called multiple times. In order to stop receiving notifications, the stopScanning method should be used.

Parameters:

configuration - provide setting options to filter the beacons to be scanned

callback - provided function that will be called once a beacon is detected

stopScanning

void stopScanning()

Stops the last called startScanning operation.

startBroadcasting

void startBroadcasting(java.util.UUID beaconUUID,
                       int major,
                       int minor,
                       java.lang.String identifier)

Configure the current device as a Bluetooth beacon, and start advertising with a given UUID

Parameters:

beaconUUID - the UUID of the beacon that will be advertised

major - the most significant value

minor - the least significant value

identifier - a string to identify the beacon

Since:

4.0.7

stopBroadcasting

void stopBroadcasting()

Stop advertising the current iOS device as a Bluetooth beacon

Since:

4.0.7

startScanningDevices

javafx.collections.ObservableList<BleDevice> startScanningDevices()

Start scanning for BLE Devices.

Returns:

an observable list of BleDevice found

Since:

4.0.6

stopScanningDevices

void stopScanningDevices()

Stops scanning for BLE devices

connect

void connect(BleDevice device)

Connects to a given BLE device

Parameters:

device - The BleDevice to connect to

Since:

4.0.6

disconnect

void disconnect(BleDevice device)

Disconnects from a given BLE device

Parameters:

device - The BleDevice to disconnect from

Since:

4.0.6

readCharacteristic

void readCharacteristic(BleDevice device,
                        java.util.UUID uuidProfile,
                        java.util.UUID uuidCharacteristic)

Given a BleDevice, with a given BleProfile and a given BleCharacteristic, reads its value

Parameters:

device - The connected BleDevice

uuidProfile - The UUID that identifies the BLE Profile

uuidCharacteristic - The UUID that identifies the BLE Characteristic

Since:

4.0.6

writeCharacteristic

void writeCharacteristic(BleDevice device,
                         java.util.UUID uuidProfile,
                         java.util.UUID uuidCharacteristic,
                         byte[] value)

Given a BleDevice, with a given BleProfile and a given BleCharacteristic, writes its value

Parameters:

device - The connected BleDevice

uuidProfile - The UUID that identifies the BLE Profile

uuidCharacteristic - The UUID that identifies the BLE Characteristic

value - a new value for the Ble Characteristic

Since:

4.0.6

subscribeCharacteristic

void subscribeCharacteristic(BleDevice device,
                             java.util.UUID uuidProfile,
                             java.util.UUID uuidCharacteristic)

Given a BleDevice, with a given BleProfile and a given BleCharacteristic, subscribes to listen to changes in its value

Parameters:

device - The connected BleDevice

uuidProfile - The UUID that identifies the BLE Profile

uuidCharacteristic - The UUID that identifies the BLE Characteristic

Since:

4.0.6

unsubscribeCharacteristic

void unsubscribeCharacteristic(BleDevice device,
                               java.util.UUID uuidProfile,
                               java.util.UUID uuidCharacteristic)

Given a BleDevice, with a given BleProfile and a given BleCharacteristic, unsubscribes and stop listening to changes in its value

Parameters:

device - The connected BleDevice

uuidProfile - The UUID that identifies the BLE Profile

uuidCharacteristic - The UUID that identifies the BLE Characteristic

Since:

4.0.6