Linux.Bluetooth 5.66.0

.NET 的 Linux Bluetooth 库

公告

Plugin.BlueZ 库的下一代！

.NET 的 Linux.Bluetooth 库让开发者能够以极低的代价快速搭建并与 Linux 的 BLE 无线电接口。无需记住繁琐的 D-Bus API 调用，我们将处理这些调用。

此库使用 Tmds.DBus 访问 Linux 的 D-Bus，这是用户空间中 Bluetooth 的首选接口。

查看 SuessLabs 关于使用 Plugin.BlueZ 的文章

要求

• Linux
• .NET 6, 7 或 8

抱歉，不支持的较旧版本 Mono (.NET Framework)。

此项目已针对 BlueZ v5.50 以及更高版本进行验证。您可以使用 bluetoothd -v 检查您正在使用的版本。

支持的发行版

Linux.Bluetooth 致力于支持同时支持 .NET 和 BlueZ 的 Linux 发行版。官方上，此 NuGet 包已针对 Ubuntu 20.04 LTS 进行了测试。

BlueZ 支持的发行版列表

• Ubuntu Linux
• Raspbian (树莓派)
• Debian GNU/Linux
• Fedora Core / Red Hat Linux
• OpenSuSE / SuSE Linux
• Mandrake Linux
• Gentoo Linux
• Chrome OS

安装

dotnet add package Linux.Bluetooth

使用方法

C#事件可用于多个属性。事件对于正确处理断开和重连非常有用。

获取一个蓝牙适配器

using Linux.Bluetooth;
...
IAdapter1 adapter = (await BlueZManager.GetAdaptersAsync()).FirstOrDefault();

或获取特定的适配器

IAdapter1 adapter = await BlueZManager.GetAdapterAsync(adapterName: "hci0");

扫描蓝牙设备

adapter.DeviceFound += adapter_DeviceFoundAsync;

await adapter.StartDiscoveryAsync();
...
await adapter.StopDiscoveryAsync();

获取设备

adapter.DeviceFound（如上所示）将会立即为现有设备调用，当扫描过程中出现新设备时同样会调用；可以使用eventArgs.IsStateChange来区分现有设备和新设备。或者，您可以使用GetDevicesAsync

IReadOnlyList<Device> devices = await adapter.GetDevicesAsync();

连接到设备

device.Connected += device_ConnectedAsync;
device.Disconnected += device_DisconnectedAsync;
device.ServicesResolved += device_ServicesResolvedAsync;

await device.ConnectAsync();

或者，您可以等待“已连接”和“服务解决”变为真值

TimeSpan timeout = TimeSpan.FromSeconds(15);

await device.ConnectAsync();
await device.WaitForPropertyValueAsync("Connected", value: true, timeout);
await device.WaitForPropertyValueAsync("ServicesResolved", value: true, timeout);

检索 GATT 服务和属性

先决条件：您必须连接到设备，并且必须解决服务。您可能需要与设备配对才能使用某些服务。

使用 GATT 设备信息服务 UUID 的示例。

string serviceUUID = "0000180a-0000-1000-8000-00805f9b34fb";
string characteristicUUID = "00002a24-0000-1000-8000-00805f9b34fb";

IGattService1 service = await device.GetServiceAsync(serviceUUID);
IGattCharacteristic1 characteristic = await service.GetCharacteristicAsync(characteristicUUID);

读取 GATT 属性值

byte[] value = await characteristic.ReadValueAsync(timeout);

string modelName = Encoding.UTF8.GetString(value);

订阅 GATT 属性通知

characteristic.Value += characteristic_Value;
...

private static async Task characteristic_Value(GattCharacteristic characteristic, GattCharacteristicValueEventArgs e)
{
  try
  {
    Console.WriteLine($"Characteristic value (hex): {BitConverter.ToString(e.Value)}");

    Console.WriteLine($"Characteristic value (UTF-8): \"{Encoding.UTF8.GetString(e.Value)}\"");
  }
  catch (Exception ex)
  {
    Console.Error.WriteLine(ex);
  }
}

提示

可能需要与设备配对才能使 GATT 服务可见或读取 GATT 属性生效。配对的选项之一是运行bluetoothctl（或sudo bluetoothctl），然后在bluetoothctl中运行default agent和agent on。在bluetoothctl中监视配对请求。

见Ubuntu 配对介绍。

BluetoothCtl 辅助工具

从命令行使用bluetoothctl或蓝牙管理器扫描和检索设备 UUID 和服务，以协助调试。

$ bluetoothctl

; Scan for devices
scan on

; Stop Scanning
scan off

; List known devices
devices

贡献

见贡献。

即将推出

• 弃用Linux.Bluetooth.Extensions。现在它将只是Linux.Bluetooth命名空间。

参考

• 在 Linux 上进行蓝牙低功耗操作
• BlueZ API:
  • HEAD
  • v5.53 —— 即Ubuntu v20.04 LTS
• BlueZ 官方网站
• 在 Raspberry PI 上安装 BlueZ

赞助商：Suess Labs，系Xeno Innovations, Inc的子公司。