writeCharacteristic method

  1. @override
Future<void> writeCharacteristic({
  1. required BleCharacteristic characteristic,
  2. required String value,
  3. int? writeType,
})
override

Asynchronously writes data to a specified Bluetooth Low Energy (BLE) characteristic.

BLE Communication Overview

In the BLE protocol, devices communicate by reading and writing to 'characteristics' exposed by each other's services. Characteristics are essentially data variables that a peripheral device exposes to other devices. When writing data to a characteristic, the information is generally treated as a list of hexadecimal numbers, mapping to bytes at a relatively low level in the Bluetooth communication stack.

Encrypted Write Operations

If the target characteristic has encrypted write permissions, the Android operating system should automatically prompt the user to complete a pairing request with the BLE device. Pairing is a prerequisite to encrypted communication and enhances the security of the data exchange.

Parameters

  • characteristic: The BLE characteristic to which the data will be written. This should include both the device address and the UUID of the characteristic.
  • value: The data to be written to the characteristic, generally a string that will be converted into bytes/hexadecimals.
  • writeType: Optional parameter to specify the type of write operation. Defaults to BluetoothGattCharacteristic.WRITE_TYPE_DEFAULT. Different write types have different transmission and confirmation behaviors.

Implementation

@override
Future<void> writeCharacteristic({
  required BleCharacteristic characteristic,
  required String value,
  int? writeType,
}) async {
  try {
    await channel.invokeMethod('writeCharacteristic', {
      'address': characteristic.address,
      'characteristicUuid': characteristic.uuid,
      'value': value,
      if (writeType != null) 'writeType': writeType,
    });
  } on PlatformException catch (e) {
    // Handle different error types accordingly.
    if (e.message?.contains('permissions') ?? false) {
      throw BluetoothPermissionException('Permission error: ${e.message}');
    } else {
      throw BluetoothWriteException(
        'Failed to write BLE characteristic: ${e.message}',
      );
    }
  }
}