btleplug

btleplug 是一个异步 Rust BLE 库，支持 Windows 10、macOS、Linux、iOS 和 Android（包括 Flutter，下面有更多详情）。

它源自几个早期废弃的针对不同平台的库（rumble、blurmac 等...），旨在构建一个完全跨平台的库。计划添加对其他平台（如 Android）的支持。

btleplug 旨在作为 主机/中心模式。如果您对外围 BTLE（即作为蓝牙 LE 设备运行而不是连接到其中一个）感兴趣，请查看 bluster。

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

平台状态

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

平台功能表

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

库功能

序列化/反序列化

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

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

特定平台的构建/安装说明

macOS

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

Android

btleplug for Android 需要一个相对复杂的设置，因为它需要混合 Rust/Java 构建。

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

构建过程的简要概述

• 对于 Java，您需要在 Maven 仓库或本地（如果本地，则需要检出 btleplug 并更改 gradle 文件）中获取 jni-utils-rs 的 Java 部分。
• 您可以选择在 src/droidplug/java 目录中使用包含的 gradle 文件构建 btleplug 的 Java 部分，并将其放入 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 之间是共享的，因此 iOS 上的 btleplug 应该“正常工作”，并且看起来很稳定。构建方式可能因您的应用程序设置和您所绑定的语言而异，但以下是一些示例指令（此处摘录）

• 编写一个使用 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。