-
- 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()); }); });
Android Configuration
The permissions
android.permission.BLUETOOTH
andandroid.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>NSLocationAlwaysUsageDescription</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-overviewExample
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()); });
Android Configuration
The same permissions
Note: these modifications are handled automatically by Client plugin if it is used.android.permission.BLUETOOTH
,android.permission.BLUETOOTH_ADMIN
andandroid.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>
-
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Modifier and Type Method Description void
connect(BleDevice device)
Connects to a given BLE devicestatic java.util.Optional<BleService>
create()
Returns an instance ofBleService
.void
disconnect(BleDevice device)
Disconnects from a given BLE devicevoid
readCharacteristic(BleDevice device, java.util.UUID uuidProfile, java.util.UUID uuidCharacteristic)
Given a BleDevice, with a given BleProfile and a given BleCharacteristic, reads its valuevoid
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 UUIDvoid
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 beaconvoid
stopScanning()
Stops the last called startScanning operation.void
stopScanningDevices()
Stops scanning for BLE devicesvoid
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 valuevoid
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 valuevoid
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 ofBleService
.- 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 scannedcallback
- 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 advertisedmajor
- the most significant valueminor
- the least significant valueidentifier
- 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 BleDeviceuuidProfile
- The UUID that identifies the BLE ProfileuuidCharacteristic
- 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 BleDeviceuuidProfile
- The UUID that identifies the BLE ProfileuuidCharacteristic
- The UUID that identifies the BLE Characteristicvalue
- 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 BleDeviceuuidProfile
- The UUID that identifies the BLE ProfileuuidCharacteristic
- 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 BleDeviceuuidProfile
- The UUID that identifies the BLE ProfileuuidCharacteristic
- The UUID that identifies the BLE Characteristic- Since:
- 4.0.6
-
-