apache-nimble-sys

Rust bindings for the Apache NimBLE project

Pre-requisites

Ensure you have the proper compiler for the platform you're targeting. For example, if you are using an nRF chip, this means you will need arm-none-eabi-gcc/arm-none-eabi-cc, provided by the Arm GNU Toolchain.

This will allow cc to compile NimBLE's code (more info below).

About

This repository provides the port layer implementations and high level bindings that allow you to use the NimBLE stack in a Rust embedded project.

The apache-nimble-sys crate

This crate provides the raw bindings generated by bindgen from NimBLE's header files. Additionally, it contains implementations for NimBLE's port layer types and functions, and support for different radio drivers through their respective Peripheral Access Crate.

Note that you need to change the BINDGEN_EXTRA_CLANG_ARGS environment variable to contain an argument that points to the correct sysroot for your platform:

# .cargo/config.toml

[env]
BINDGEN_EXTRA_CLANG_ARGS = "--sysroot=/usr/arm-none-eabi"

The apache-nimble crate

This crate provides the high-level bindings intended for your use. Only controller bindings are available, for now.

At build time, cbindgen is used to generate the C types for the port layer implemented in apache-nimble-sys. Then, cc is used to compile the NimBLE code itself, which gets linked into your final binary. Depending on the feature flags you choose, certain parts of NimBLE's code will be compiled. You can enable/disable the following feature flags:

• controller
  • High-level bindings for NimBLE's controller (mynewt-nimble/nimble/controller)
  • Provides bt-hci implementations, enabling usage with other BLE hosts (such as trouble)
• (TODO) host
  • High-level bindings for NimBLE's host subsystem (mynewt-nimble/nimble/host)

Critical Sections

Internally, NimBLE code will use a critical section implementation that disables all interrupts (implemented as part of the port layer).

Code that uses the critical-section crate will use a separate implementation that disables all interrupts, except those that are needed by the NimBLE controller (typically RADIO, RNG, and RTC0). Make sure to enable the critical-section flag on the apache-nimble crate, and remember not to disable NimBLE interrupts in application code, as it may interfere with NimBLE's processing.

Port layers

NimBLE provides a porting layer that allows developers to provide support for different operating systems. This repository contains port layer implementations intended to be used with common Rust embedded environments.

To select a specific port layer, enable one of the following feature flags on the apache-nimble crate:

• port-layer-embassy
  • Implemented with embassy-time-driver, and embassy-sync primitives. Intended to be used with the embassy-executor.

Drivers

The apache-nimble-sys crate provides support for a radio driver by implementing port layer functions that set up their respective interrupt handlers. The apache-nimble crate provides support by compiling the necessary C driver code (mynewt-nimble/nimble/drivers) at build time, based on the chosen chip below.

To select a radio driver to use, enable one of the following feature flags on the apache-nimble crate:

• nrf52840

License

This repository contains code for nrfx, and CMSIS_5, which are available under their own respective licenses.

The apache-nimble and apache-nimble-sys crates are available under the Apache 2.0 license.