BLEZ - Asynchronous Bluetooth Low Energy on Linux for Rust

Related tags

bluetooth-low-energy
Overview

BLEZ - Asynchronous Bluetooth Low Energy on Linux for Rust

This library provides an asynchronous, fully featured interface to the Bluetooth Low Energy (BLE) APIs of the official Linux Bluetooth protocol stack (BlueZ) for Rust. Both publishing local and consuming remote GATT services using idiomatic Rust code is supported. Asynchronous support is dependent by Tokio.

This project started as a fork of blurz but has since then become a full rewrite. Documentation has been mostly copied from the BlueZ API specification, but also adapted where it makes sense.

The following features are provided:

  • Bluetooth adapters
    • enumeration
    • configuration of power, discoverability, name, etc.
    • hot-plug support through change events stream
  • Bluetooth devices
    • discovery
    • querying of address, name, class, signal strength (RSSI), etc.
    • Bluetooth Low Energy advertisements
    • change events stream
    • connecting and pairing
  • consumption of remote GATT services
    • GATT service discovery
    • read, write and notify operations on characteristics
    • read and write operations on characteristic descriptors
    • optional use of low-overhead AsyncRead and AsyncWrite streams for notify and write operations
  • publishing local GATT services
    • read, write and notify operations on characteristics
    • read and write operations on characteristic descriptors
    • two programming models supported
      • callback-based interface
      • low-overhead AsyncRead and AsyncWrite streams
  • sending Bluetooth Low Energy advertisements

Classic Bluetooth is unsupported except for device discovery.

Requirements

This library has been tested with BlueZ version 5.56. Older versions might work, but be aware that many bugs related to GATT handling exist. Refer to the official changelog for details.

bluetoothd must be running and configured for access over D-Bus. On most distributions this should work out of the box.

For building, D-Bus library headers must be installed. On Debian-based distributions install the package libdbus-1-dev.

Troubleshooting

The library returns detailed errors received from BlueZ.

Set the Rust log level to trace to see all D-Bus communications with BlueZ.

In some cases checking the Bluetooth system log might provide further insights. On Debian-based systems it can be displayed by executing journalctl -u bluetooth. Check the bluetoothd man page for increasing the log level.

Examples

Refer to the API documentation and examples folder for examples.

The following example applications are provided.

  • device_monitor: Scans for and monitors Bluetooth devices similar to top.

  • discover_devices: Discover Bluetooth devices and print their properties.

  • gatt_client: Simple GATT client that calls read, write and notify on a characteristic.

  • gatt_server_cb: Corresponding GATT server implemented using callback programming model.

  • gatt_server_io: Corresponding GATT server implemented using IO programming model.

  • le_advertise: Register Bluetooth LE advertisement.

  • list_adapters: List installed Bluetooth adapters and their properties.

Use cargo run --example to run a particular example application.

Issues
  • Build of BLEZ fails due to

    Build of BLEZ fails due to "No such file or directory"

    On my machine the build of current blez master branch 0.9.4 fails. I'm using latest rust stable (1.52.1).

    It gives me the following error message:

    error: failed to run custom build command for `blez v0.9.4 (/home/sojus/src/meshnet/examples/blez/blez)`
    
    Caused by:
      process didn't exit successfully: `/home/sojus/src/meshnet/examples/blez/target/debug/build/blez-32ba4e3e0de9fdbb/build-script-build` (exit code: 101)
      --- stdout
      cargo:rerun-if-changed=bluetooth-numbers-database/v1/service_uuids.json
    
      --- stderr
      thread 'main' panicked at 'services: Os { code: 2, kind: NotFound, message: "No such file or directory" }', blez/build.rs:213:6
      stack backtrace:
         0: rust_begin_unwind
                   at /rustc/9bc8c42bb2f19e745a63f3445f1ac248fb015e53/library/std/src/panicking.rs:493:5
         1: core::panicking::panic_fmt
                   at /rustc/9bc8c42bb2f19e745a63f3445f1ac248fb015e53/library/core/src/panicking.rs:92:14
         2: core::option::expect_none_failed
                   at /rustc/9bc8c42bb2f19e745a63f3445f1ac248fb015e53/library/core/src/option.rs:1329:5
         3: core::result::Result<T,E>::expect
                   at /home/sojus/.rustup/toolchains/stable-x86_64-unknown-linux-gnu/lib/rustlib/src/rust/library/core/src/result.rs:997:23
         4: build_script_build::main
                   at ./build.rs:206:5
         5: core::ops::function::FnOnce::call_once
                   at /home/sojus/.rustup/toolchains/stable-x86_64-unknown-linux-gnu/lib/rustlib/src/rust/library/core/src/ops/function.rs:227:5
      note: Some details are omitted, run with `RUST_BACKTRACE=full` for a verbose backtrace.
    warning: build failed, waiting for other jobs to finish...
    error: build failed
    
    opened by MathJud 2
A runtime for writing reliable asynchronous applications with Rust. Provides I/O, networking, scheduling, timers, ...

Tokio A runtime for writing reliable, asynchronous, and slim applications with the Rust programming language. It is: Fast: Tokio's zero-cost abstracti

Tokio 12.3k Jun 14, 2021
Docker daemon API in Rust

Bollard: an asynchronous rust client library for the docker API Bollard leverages the latest Hyper and Tokio improvements for an asynchronous API cont

Niel Drummond 204 May 20, 2021
Cross-platform, low level networking using the Rust programming language.

libpnet Linux ∪ OS X Build Status: Windows Build Status: Discussion and support: #libpnet on freenode / #rust-networking on irc.mozilla.org / #rust on

null 1.4k Jun 11, 2021
An asynchronous Prometheus exporter for iptables

iptables_exporter An asynchronous Prometheus exporter for iptables iptables_exporter runs iptables-save --counter and scrapes the output to build Prom

Kevin K. 4 May 14, 2021
NNTP client for Rust

rust-nntp NNTP Client for Rust Usage extern crate nntp; use nntp::{Article, NNTPStream}; fn main() { let mut nntp_stream = match NNTPStream::connec

Matt McCoy 12 Aug 6, 2019
🥧 Savoury implementation of the QUIC transport protocol and HTTP/3

quiche is an implementation of the QUIC transport protocol and HTTP/3 as specified by the IETF. It provides a low level API for processing QUIC packet

Cloudflare 4.8k Jun 13, 2021
The gRPC library for Rust built on C Core library and futures

gRPC-rs gRPC-rs is a Rust wrapper of gRPC Core. gRPC is a high performance, open source universal RPC framework that puts mobile and HTTP/2 first. Sta

TiKV Project 1.4k Jun 12, 2021
Network simulation in Rust

netsim - A Rust library for network simulation and testing (currently linux-only). netsim is a crate for simulating networks for the sake of testing n

Andrew Cann 83 Jun 3, 2021
A simple message based networking library for the bevy framework

Spicy Networking for Bevy bevy_spicy_networking is a solution to the "How do I connect multiple clients to a single server" problem in your bevy games

Cabbit Studios 21 May 6, 2021
Actor framework for Rust.

Actix Actor framework for Rust Documentation User Guide API Documentation API Documentation (master branch) Features Async and sync actors Actor commu

Actix 6.4k Jun 11, 2021
rpcx microservice framework in Rust

rpcx-rs Rust library for rpcx rpc/microservice framework. Use the simplest style to explore Rust function as cross-platform rpc services. If you can w

smallnest 60 May 15, 2021
Crusty - polite && scalable broad web crawler

Broad web crawling is an activity of going through practically boundless web by starting from a set of locations(urls) and following outgoing links. Usually it doesn't matter where you start from as long as it has outgoing links to external domains.

Sergey F. 42 Jun 16, 2021
Simple VPN implemented using rust

fubuki Simple VPN implemented using rust fubuki是类似与tincVPN的简单组网工具 不支持对等NAT 支持的平台: Windows Linux 工作机制 它由一台拥有公网IP的服务器来维持各个内网客户端的实际地址映射,在客户端和客户端之间实现P2P通信

XTY 37 May 14, 2021