Flutter中的低功耗蓝牙技术：开发者手册

了解特征属性

每个特征都会通过其properties对象来说明它支持哪些操作，如果尝试执行不支持的操作，就会引发错误。事先检查这些属性，正是让应用程序变得稳定运行的关键所在——这样的程序才能在遇到意外的硬件环境时依然正常运行，而不会崩溃。

void printProperties(BluetoothCharacteristic c) {
  final p = c.properties;
  print('read: ${p.read}`);
  print('write: ${p.write}`);
  print('writeWithoutResponse: ${p.writeWithoutResponse}`);
  print('notify: ${p.notify}`);
  print('indicate: ${p.indicate}`);
  print('broadcast: ${p.broadcast}");
  print('authenticatedSignedWrites: ${p.authenticatedSigned Writes'));
}

这个函数会输出所有特征属性的详细信息。read表示可以按需读取该属性的值；write表示设备会确认接收到的写入操作；而writeWithoutResponse则是一种快速且不会引起设备确认的写入方式。

notify和indicate这两种方法都会让设备主动向应用程序发送更新信息，但不同之处在于：indicate要求中央设备必须对每一条更新信息进行确认，而notify则不需要；因此indicate更为可靠，但处理速度也会更慢。

broadcast表示该属性的值可以被包含在广告数据包中；authenticatedSignedWrites则表示该特征支持需要建立连接关系才能进行的加密写入操作。

在采取任何行动之前先查看这些属性信息，可以帮助你选择正确的方法，并避开设备不支持的那些操作。当你的应用程序需要与来自不同厂商的硬件设备进行交互时，这一点尤为重要——因为这些设备的逻辑功能可能相同，但所支持的属性设置却可能有所不同。

从特征中读取数据

读取数据意味着可以根据需要获取某个特征的当前值。返回的数据总是以字节列表的形式出现，你需要根据该设备的规格说明来解读这些字节。

Future<List<int>>> readCharacteristic(BluetoothCharacteristic c) async {
  if (!c.properties.read) {
    print('这个特征无法被读取');
    return [];
  }

  List<int>> value = await c.read();
  print('原始字节数据: $value');
  return value;
}

该函数首先会通过检查c.properties.read来确认是否可以读取某个特征的数据；如果不允许进行这种操作，就会返回一个空列表。随后它会调用c.read方法，该方法会返回一个List<int>类型的列表，其中每个元素都是0到255之间的字节。

由于BLE在数据传输层并不区分数据类型，因此你收到的是原始字节数据，必须根据设备的技术规格说明书自行对这些数据进行解码。我们将在后面的编码部分详细介绍这一过程。返回原始字节数据的目的，就是让调用者能够自行决定如何解读这些数据。在任何情况下，都务必先确认该特征是否支持被读取——如果尝试读取一个无法被读取的特征，就会引发FlutterBluePlusException错误。

将数据写入特性值

写入操作实际上是向外设发送字节数据，通过这种方式可以发送命令、更改设置或向自定义硬件传输数据。

存在两种写入模式，选择合适的模式对于确保数据的可靠性和传输速度至关重要。

Future writeCharacteristic(
  BluetoothCharacteristic c,
  List data,
) async {
  if (c.properties.write) {
    await c.write(data, withoutResponse: false);
    print('带有响应的写入操作已完成');
  } else if (c.properties.writeWithoutResponse) {
    await c.write(data, withoutResponse: true);
    print('无响应的写入操作已完成');
  } else {
    print('该特性值无法被写入');
  }
}

此函数会检查相关属性来确定具体的写入方式。如果该特性值支持write方法，就会使用带有响应的写入模式，此时需要传入withoutResponse: false参数，这样外设会在接收到数据后给出确认反馈，只有在收到确认信号后，await操作才会完成。这种方式的可靠性较高，但传输速度较慢，因为需要等待往返通信的过程。

如果该特性值支持writeWithoutResponse方法，就会采用直接发送数据而不等待响应的方式，此时传入withoutResponse: true参数。这种方式传输速度较快，非常适合高吞吐量的数据流传输，但无法保证数据一定能被成功送达。

如果这两种属性都不存在，说明该特性值无法被写入，函数也会相应地给出提示。data参数是一个包含字节数据的List对象，因此如果要发送一个由两个字节组成的命令，就可以传入[0x01, 0xFF]这样的数组。

当需要传输的数据量超过了MTU的最大允许长度时，应该将数据分成若干份，每份的大小为协商确定的MTU大小减去一些开销字节，然后依次进行写入操作。

Future writeLongData(
  BluetoothCharacteristic c,
  List data,
  int mtu,
) async {
  final chunkSize = mtu - 3;
  for (var i = 0; i < data.length; i += chunkSize) {
    final end = (i + chunkSize < data.length) ? i + chunkSize : data.length;
    final chunk = data.sublist(i, end);
    await c.write(chunk, withoutResponse: false);
  }
  print('已分${chunkSize}大小的几份数据，共发送了${data.length}字节');
}

此函数会将较大的数据量拆分成MTU大小为单位的若干部分。它首先计算出chunkSize的值，即协商确定的MTU大小减去3字节的ATT开销，然后按照这个大小来分割数据并依次进行写入操作。

在每次写入操作中，都会计算出数据的结束索引，从而确保不会超出数据列表的边界。使用sublist方法提取出相应的数据部分后进行写入。由于这里采用了带有响应的写入模式（withoutResponse: false），因此每个写入操作都会等待外设的确认信号后再开始下一个操作，这样就能有效防止外设缓冲区被溢出。

如果你的外设有自己专门的数据重组协议，那么应该按照该协议来执行写入操作，因为有些设备要求在每份数据中包含长度字段或序列号等信息。

订阅通知与数据更新

正是由于这种通知机制，蓝牙技术才能具备高效性。你无需反复查询某个特性值，只需进行一次订阅，当外围设备的数据发生变化时，它就会自动将新数值推送给你的设备。这样一来，像心率、温度或加速度传感器的数据就能以最低的能耗持续传送到你的设备上。

StreamSubscription>? _valueSubscription;

Future subscribe(BluetoothCharacteristic c) async {
  if (!c.properties.notify && !c.properties.indicate) {
    print('该特性不支持通知功能');
    return;
  }

  _valueSubscription = c.onValueReceived.listen((value) {
    print('收到更新值: $value');
  });

  c.device.cancelWhenDisconnected(_valueSubscription!);

  await c.setNotifyValue(true);
}

Future unsubscribe(BluetoothCharacteristic c) async {
  await c.setNotifyValue(false);
  await _valueSubscription?.cancel();
}

subscribe函数首先会确认该特性是否支持notify或indicate功能，这两种功能都属于服务器主动发起的数据更新机制。随后，它会通过c.onValueReceived监听器来接收外围设备发送的更新数据；同时，使用cancelWhenDisconnected确保在连接断开时能够及时停止数据接收。最后，该函数会调用setNotifyValue(true)，从而让外围设备开始发送数据。需要注意的是，如果某个特性仅支持indicate功能，插件会自动选择使用这种机制。

Future exploreDescriptors(BluetoothCharacteristic c) async {
  for (BluetoothDescriptor d in c.descriptors) {
    print('描述符: ${d.uuid}`);
    List value = await d.read();
    print('  值: $value');
  }
}

Future writeDescriptor(BluetoothDescriptor d, List data) async {
  await d.write(data);
  print('描述符已写入');
}

writeDescriptor函数通过d.write将字节发送到描述符中。大多数应用程序都不会直接操作描述符，因为setNotifyValue会负责管理这些重要的描述符；但如果你使用的硬件使用了自定义的描述符——比如用于存储人类可读标签的“特征用户描述”描述符（0x2901），那么你就需要通过这种方式来访问它。

应将描述符中的数据视为原始字节，并根据相关规范对其进行解码，就像处理其他特征数据一样。

字节数据的编码与解码

BLE协议传输的是不包含类型信息的原始字节，因此编码和解码过程很容易出错。你必须了解每种特征的字节布局，包括每个字段的大小、整数是否带符号以及字节顺序。

在BLE协议中，最常用的字节顺序是小端序，即最低有效位字节会先被发送；但无论如何都应对照设备的文档进行验证。

import 'dart:typed_data';

int readUint8(List bytes, int offset) => bytes[offset];

int readUint16LE(List bytes, int offset) {
  return bytes[offset] | (bytes[offset + 1] << 8);
}

int readUint32LE(List bytes, int offset) {
  return bytesoffset] |
      (bytes[offset + 1] << 8) |
      (bytes[offset + 2] << 16) |
      (bytes[offset + 3] << 24);
}

int readInt16LE(List bytes, int offset) {
  final data = ByteData.sublistView(Uint8List.fromList(bytes));
  return data.getInt16(offset, Endian.little);
}

double readFloat32LE(List bytes, int offset) {
  final data = ByteData.sublistView(Uint8List.fromList(bytes));
  return data.getFloat32offset, Endian.little);
}

这些辅助函数涵盖了你最常遇到的数据类型。readUint8简单地将一个字节作为无符号整数返回；readUint16LE通过将低字节放在前面，并将高字节左移8位，然后使用按位或运算，将两个字节组合成一个16位的无符号数值；readUint32LE则将这个原理扩展到四个字节，分别进行8位、16位和24位的位移操作。

对于带符号的整数和浮点数来说，手动处理字节很容易出错，因此readInt16LE和readFloat32LE会先将字节封装到ByteData对象中，然后使用其getInt16和getFloat32方法，并指定Endian.little参数，这样就能正确处理符号扩展和IEEE 754浮点数的解码工作。对于任何复杂的数据类型来说，使用ByteData都是推荐的做法，因为这种方法既准确又便于理解。

在将数据编码后发送时，需要按照相反的步骤进行操作，而ByteData依然是最合适的工具。

List encodeCommand(int commandId, int value) {
  final data = ByteData(5);
  data.setUint8(0, commandId);
  data.setUint32(1, value, Endian.little);
  return data.buffer.asUint8List();
}

这个函数用于构建一个长度为5字节的命令数据包。它首先分配一个长度为5字节的`ByteData`缓冲区，然后使用`setUint8`方法将命令标识符写入该缓冲区的偏移量为0的位置；接着使用`setUint32`方法以小端序格式将一个32位数值写入偏移量为1的位置。最后，通过`buffer.asUint8List()`方法将该缓冲区转换为`Uint8List`类型的数据结构，而`characteristic.write`方法正是期望接收这种类型的数据的。

使用`ByteData`来构建数据包能够确保偏移量的准确性以及字节序的正确性，从而有效避免那些在手工组装字节列表时容易出现的错误。

int parseHeartRate(List bytes) {
  final flags = bytes[0];
  final is16Bit = (flags & 0x01) != 0;
  if (is16Bit) {
    return readUint16LE(bytes, 1);
  } else {
    return readUint8(bytes, 1);
  }
}

这个函数遵循标准的心率测量数据格式。数据包的第一个字节用于携带标志信息，其中最低位用来指示后续的心率数值是8位还是16位。代码通过与该位进行按位与操作来判断这一信息：如果该位被设置为1，那么心率数值就是从偏移量1开始读取的两个字节组成的小端序整数；否则，心率数值就是一个位于偏移量1处的单个字节。

这种“先标志位再数据 payload”的结构在标准的BLE特性中非常常见，因此识别这种格式能够节省解析时间。这也说明了一个道理：如果没有相关规范，就无法正确解码BLE数据——因为同一特性会根据不同的标志位来改变数据的结构。

配对、绑定与加密

有些BLE特性要求使用加密连接，而访问这些特性时就会触发配对过程。配对是指两台设备互相交换密钥的过程，而绑定则是将这些密钥保存下来，这样以后在连接时就可以自动进行加密，而无需再次进行配对操作。

许多安全设备都是按照这种机制工作的，了解这一流程有助于避免遇到“认证失败”这类令人困惑的错误。

Future readLiveRssi(BluetoothDevice device) async {
  int rssi = await device.readRssi();
  print('当前信号强度：$rssi dBm');
}

Future setHighThroughput(BluetoothDevice device) async {
  if (Platform.isAndroid) {
    await device.requestConnectionPriority(
      connectionPriorityRequest: ConnectionPriority.high,
    );
    print('已请求高优先级连接');
  }
}

int _retryCount = 0;
const int _maxRetries = 5;

void setupAutoReconnect(BluetoothDevice device) {
  device.connectionState.listen((state) async {
    if (state == BluetoothConnectionState.connected) {
      _retryCount = 0;
      await device.discoverServices();
    } else if (state == BluetoothConnectionState.disconnected) {
      print('已断开连接：${devicedisconnectReason?.description}`);
      await _attemptReconnect(device);
    }
  });
}

Future _attemptReconnect(BluetoothDevice device) async {
  while (_retryCount < _maxRetries && !device.isConnected) {
    _retryCount++;
    final backoff = Duration(seconds: 1 << _retryCount);
    print('正在尝试重新连接，当前尝试次数为 $_retryCount，等待时间为 ${backoff.inSeconds} 秒');
    await Future.delayed(backoff);
    try {
      await device.connect(timeout: const Durationseconds: 15));
      print('重新连接成功');
      return;
    } catch (e) {
      print('重新连接失败：$e');
    }
  }
  if (!device.isConnected) {
    print('经过 $_maxRetries 次尝试后，放弃重新连接');
  }
}

enum BleConnectionStatus { disconnected, scanning, connecting, connected }

class BleService {
  BluetoothDevice? _device;
  BluetoothCharacteristic? _dataCharacteristic;

  final _statusController =
      StreamController.broadcast();
  final _dataController = StreamController get status => _statusController.stream;
  Stream> get data => _dataController.stream;

  final Guid serviceUuid = Guid('180D');
  final Guid characteristicUuid = Guid('2A37');

  Future scanAndConnect() async {
    _statusController.add(BleConnectionStatus.scanning);

    await FlutterBluePlus.startScan(
      withServices: [serviceUuid],
      timeout: const Duration(seconds: 15),
    );

    final results = await FlutterBluePlus.onScanResults.first;
    if (results.isEmpty) {
      _statusController.add(BleConnectionStatus.disconnected);
      return;
    }

    await FlutterBluePlus.stopScan();
    await _connect(results.first.device);
  }

  Future _connect(BluetoothDevice device) async {
    _device = device;
    _statusController.add(BleConnectionStatus.connecting);

    device.connectionState.listen((state) {
      if (state == BluetoothConnectionState.connected) {
        _statusController.add(BleConnectionStatusconnected);
      } else if (state == BluetoothConnectionState.disconnected) {
        _statusController.add(BleConnectionStatus.disconnected);
      }
    });

    await device.connect(timeout: const Duration(seconds: 15));
    await _setupCharacteristic();
  }

  Future _setupCharacteristic() async {
    final services = await _device!.discoverServices();
    for (final service in services) {
      if (service.uuid == serviceUuid) {
        for (final c in service.characteristics) {
          if (c.uuid == characteristicUuid) {
            _dataCharacteristic = c;
            c.onValueReceived.listen(_dataController.add);
            await c.setNotifyValue(true);
          }
        }
      }
    }
  }

  Future send(List bytes) async {
    await _dataCharacteristic?.write(bytes);
  }

  Future dispose() async {
    await _device?.disconnect();
    await _statusController.close();
    await _dataController.close();
  }
}

import 'package:flutter/material.dart';

class BleHomePage extends StatefulWidget {
  final BleService service;
  const BleHomePage({super.key, required this.service});

  @override
  State createState() => _BleHomePageState();
}

class _BleHomePageState extends State {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('BLE演示')),
      body: Column(
        children: [
          StreamBuilder( 
            stream: widget.service.status,
            initialData: BleConnectionStatus.disconnected,
            builder: (context, snapshot) {
              return ListTile(
                leading: const IconIcons.bluetooth),
                title: Text('状态：${snapshot.data?.name}'),
              );
            },
          ),
          Expanded(
            child: StreamBuilder>>(
              stream: widget.service.data,
              builder: (context, snapshot) {
                if (!snapshot.hasData) {
                  return const Center(child: Text('尚未获取到数据'));
                }
                final hr = snapshot.data!.length > 1 ? snapshot.data![1] : 0;
                return Center(
                  child: Text('$hr bpm'),
                      style: const TextStyle(fontSize: 48)),
                );
              },
            ),
          ),
        ],
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: widget.service.scanAndConnect,
        child: const IconIcons.search),
      ),
    );
  }
}

import 'packageflutter_test/flutter_test.dart';

void main() {
  test('readUint16LE能正确解析小端字节序', () {
    expect(readUint16LE([0x34, 0x12], 0), equals(0x1234));
  });

  test('parseHeartRate能正确处理8位格式的数据', () {
    expect(parseHeartRate([0x00, 72]), equals(72));
  });

  test('parseHeartRate能正确处理16位格式的数据', () {
    expect.parseHeartRate([0x01, 0x2C, 0x01]), equals(300));
  });
}

FlutterBluePlus.setLogLevel(LogLevelverbose, color: true);