btleplug

btleplug 是一个异步 Rust BLE 库，支持 Windows 10、macOS、Linux、iOS 和 Android（包括 Flutter，更多信息见下文）。

btleplug 是从几个早期废弃的针对各种平台的库（如 rumble、blurmac 等）发展而来的，目标是构建一个完全跨平台的库。计划添加对其他平台（如 Android）的支持。

btleplug 仅支持主机/中心模式。如果您对外围 BTLE（即充当蓝牙 LE 设备而不是连接到设备）感兴趣，请查看 bluster。

此库不支持蓝牙 2/CLASSIC。没有计划添加 BT2/Classic 支持。

平台状态

• Linux / Windows / macOS / iOS / Android
  • 设备枚举和特性/服务已实现并工作。
  • 如果您发现任何错误或缺失功能，请提交报告。
• WASM/WebBluetooth
  • WebBluetooth 是可能的，并且已有 PR，但需要审查。
  • 跟踪问题在这里
  • 请等待基本实现落地后再提交更多问题。

平台功能表

• X: 完成并发布
• O: 开发中
• 空白：未开始

库功能

序列化/反序列化

为了在 api 模块中的一些常见类型上实现 serde 的 Serialize 和 Deserialize，请使用 serde 功能。

[dependencies]
btleplug = { version = "0.10", features = ["serde"] }

特定平台构建/安装说明

macOS

要在 macOS Big Sur (11) 或更高版本上使用蓝牙，您需要将您的二进制文件打包成一个包含 NSBluetoothAlwaysUsageDescription 的应用程序包，或者（对于如 btleplug 中的示例这样的命令行应用程序）为您的终端启用蓝牙权限。您可以通过进入 系统偏好设置 → 安全性与隐私 → 隐私 → 蓝牙，点击 '+' 按钮，并选择 '终端'（或 iTerm 或您使用的任何终端应用程序）来执行此操作。

Android

由于需要混合 Rust/Java 构建，btleplug for Android 需要一个相当复杂的设置。

有关执行构建的一些信息可在 btlplug 在 Android 上的原始问题 中找到。

构建过程的简要概述

• 对于 Java，您需要 jni-utils-rs 的 Java 部分，它可以在 Maven 仓库中找到，或者本地（如果本地，则需要检出 btleplug 并更改 gradle 文件）。
• 您可以选择在 src/droidplug/java 目录中构建 btleplug 的 Java 部分，使用包含的 gradle 文件，并将其放入 Maven 仓库，或者让您的 Android 应用程序的 Java 部分指向该本地实现。
• 对于 Rust，构建应按常规进行，但我们建议使用 cargo-ndk 构建。输出 jniLibs 并确保它们出现在您的应用程序的正确位置。

当使用 btleplug 时，Proguard 优化可能会成为一个问题，因为 btleplug 中由 Java 代码生成的 .aar 文件仅由本地代码访问，并且可以作为死代码删除和资源缩减的一部分进行优化。为了解决这个问题，需要修改您的 build.gradle 文件，并定义 Proguard 规则。

对于 build.gradle

    buildTypes {
        release {
            // TODO: Add your own signing config for the release build.
            // Signing with the debug keys for now, so `flutter run --release` works.
            signingConfig signingConfigs.debug

            shrinkResources true
            minifyEnabled true

            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'

        }
    }

proguard-rules.pro

#Flutter Wrapper - Only needed if using flutter
-keep class io.flutter.app.** { *; }
-keep class io.flutter.plugin.**  { *; }
-keep class io.flutter.util.**  { *; }
-keep class io.flutter.view.**  { *; }
-keep class io.flutter.**  { *; }
-keep class io.flutter.plugins.**  { *; }

#btleplug resources
-keep class com.nonpolynomial.** { *; }
-keep class io.github.gedgygedgy.** { *; }

iOS

由于 Corebluetooth 实现在 macOS 和 iOS 之间共享，因此 btleplug 在 iOS 上应该“直接使用”，并且看起来很稳定。构建方式可能因您的应用程序设置和您正在绑定到的语言而异，但示例说明如下（此处摘录）

• 编写一个使用 btleplug 并向 C 暴露 FFI API 的 Rust 库（静态）
• 使用 cbindgen 为该 API 生成 C 头文件
• 使用 cargo-lipo 构建通用的静态库
• 将头文件和库拖入您的 Xcode 项目中
• 将 NSBluetoothAlwaysUsageDescription 添加到您的 Info.plist 文件中

下面列出了 Flutter shim 的一些示例。

Flutter

虽然我们还没有在这个存储库中专门支持 Flutter，但有一个模板存储库可在 https://github.com/trobanga/flutter_btleplug 找到。此模板为 Android 和 iOS 使用 btleplug 提供了构建。

替代库

每个人的蓝牙需求都不同，所以如果 btleplug 不适合您，请尝试这些由 Rust 社区提供的其他库！

• Bluey - 采用不同 API 方法（不太关注 Bluez）的跨平台 BLE 库
• Bluer - Linux 上 Bluez 的官方 Rust 接口，由于它仅支持一个平台，因此具有更多功能（我们内部使用 Bluez-async。）

许可证

BTLEPlug遵循BSD 3-Clause许可证，其中部分内容来自Rumble/Blurmac，分别遵循MIT/Apache双许可和BSD 3-Clause许可证。更多信息及版权信息请参阅LICENSE.md文件。