Installation and Setup

Getting started with btleplug involves adding the crate to your project and performing some platform-specific configuration to ensure Bluetooth permissions and dependencies are correctly handled.

Adding btleplug to Your Project

Add btleplug as a dependency in your Cargo.toml file. The simplest way is to use cargo add:

cargo add btleplug

Alternatively, you can manually add it to your Cargo.toml:

[dependencies]
btleplug = "0.11"

Enabling Serde Support

If you need to serialize or deserialize btleplug's data structures, you can enable the serde feature:

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

This will derive serde::Serialize and serde::Deserialize for common types like PeripheralProperties, ScanFilter, and BDAddr.

Platform-Specific Setup

Due to operating system security and packaging requirements, you may need to perform additional steps to get btleplug working.

macOS

On macOS Big Sur (11.0) and later, applications must have the appropriate permissions to access Bluetooth hardware.

For a standard command-line application (like the examples in this documentation), the easiest way to grant permission is to add your terminal application to the Bluetooth privacy settings:

  1. Go to System Preferences → Security & Privacy → Privacy tab.
  2. Select Bluetooth from the list.
  3. Click the + button.
  4. Add your terminal application (e.g., Terminal, iTerm2).

For GUI applications packaged in an application bundle, you must include the NSBluetoothAlwaysUsageDescription key in your Info.plist file with a string explaining why your application needs Bluetooth access.

Android

Setting up btleplug for Android is more complex as it requires a hybrid Rust/Java build.

  1. Java Dependencies: Your project needs to include the Java portion of btleplug (located in src/droidplug/java) and its dependency, jni-utils-rs. These can be included as a local module or from a Maven repository.

  2. Rust Build: Use cargo-ndk to build the Rust code as a JNI library. Ensure the output .so files are correctly placed in your Android app's jniLibs directory.

  3. Permissions: Your AndroidManifest.xml must include the necessary Bluetooth permissions:

    <uses-permission android:name="android.permission.BLUETOOTH"/>
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>
<uses-permission android:name="android.permission.BLUETOOTH_SCAN"/>
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT"/>

  4. Proguard: If you use Proguard for code shrinking and optimization, you must add rules to prevent it from removing the btleplug Java code, which is only accessed via JNI.

    In your proguard-rules.pro:

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

iOS

The Core Bluetooth implementation is shared between macOS and iOS. To build for iOS, you generally follow these steps:

  1. Create a Rust Static Library: Write a Rust library crate that uses btleplug and exposes a C-compatible FFI API.
  2. Generate C Headers: Use a tool like cbindgen to create a C header file from your FFI.
  3. Build a Universal Library: Use cargo-lipo to create a universal static library (.a file) that works on both simulators and physical devices.
  4. Xcode Integration: Drag the header file and the universal library into your Xcode project.
  5. Permissions: Add the NSBluetoothAlwaysUsageDescription key to your Info.plist file with an explanation for why Bluetooth access is needed.