Bluetooth Low Energy Remote Procedure Call

The Bluetooth® Low Energy Remote Procedure Call (RPC) solution is a set of libraries that allows using the Bluetooth Low Energy stack running entirely on a separate device or CPU.

Overview

The solution allows calling the Bluetooth Low Energy API on a different CPU or device. This is accomplished by running a full Bluetooth Low Energy stack on one device and serializing the API from another device. Use this solution when you do not want your firmware to include the Bluetooth stack, for example to offload the application CPU, save memory, or to be able to build your application in a different environment.

Implementation

The Bluetooth Low Energy RPC is a solution that consists of the following components:

• Bluetooth RPC Client and common software libraries that serialize the Bluetooth Host API and enable RPC communication. These libraries need to be part of the user application.

• Bluetooth: Host for nRF RPC Bluetooth Low Energy sample that includes the full configured Bluetooth Low Energy stack, Bluetooth RPC Host, and common libraries that enable communication with the Bluetooth RPC Client. This software includes the Bluetooth LE Controller and needs to run on a device or CPU that has the radio hardware peripheral, for example nRF5340 network core.

• Build system files that automate building a Bluetooth LE application in the RPC variant with the additional image containing the Bluetooth LE stack.

You can add support for serializing Bluetooth-related custom APIs by implementing your own client and host procedures. You can use the following files as examples:

• subsys/bluetooth/rpc/client/bt_rpc_conn_client.c

• subsys/bluetooth/rpc/host/bt_rpc_conn_host.c

Supported backends

The library supports the following two Bluetooth Low Energy controllers:

• Bluetooth Low Energy Controller

• SoftDevice Controller

Requirements

Some configuration options related to Bluetooth Low Energy must be the same on the host and client. Set the following options in the same way for the Bluetooth: Host for nRF RPC Bluetooth Low Energy and application core:

• CONFIG_BT_CENTRAL

• CONFIG_BT_PERIPHERAL

• CONFIG_BT_FILTER_ACCEPT_LIST

• CONFIG_BT_USER_PHY_UPDATE

• CONFIG_BT_USER_DATA_LEN_UPDATE

• CONFIG_BT_PRIVACY

• CONFIG_BT_SCAN_WITH_IDENTITY

• CONFIG_BT_REMOTE_VERSION

• CONFIG_BT_SMP

• CONFIG_BT_CONN - hidden option that depends on CONFIG_BT_CENTRAL or CONFIG_BT_PERIPHERAL.

• CONFIG_BT_REMOTE_INFO

• CONFIG_BT_FIXED_PASSKEY

• CONFIG_BT_SMP_APP_PAIRING_ACCEPT

• CONFIG_BT_EXT_ADV

• CONFIG_BT_OBSERVER

• CONFIG_BT_ECC

• CONFIG_BT_DEVICE_NAME_DYNAMIC

• CONFIG_BT_SMP_SC_PAIR_ONLY

• CONFIG_BT_PER_ADV

• CONFIG_BT_PER_ADV_SYNC

• CONFIG_BT_MAX_PAIRED

• CONFIG_BT_SETTINGS_CCC_LAZY_LOADING

• CONFIG_BT_BROADCASTER

• CONFIG_BT_SETTINGS

• CONFIG_BT_GATT_CLIENT

• CONFIG_BT_RPC_INTERNAL_FUNCTIONS

• CONFIG_BT_DEVICE_APPEARANCE_DYNAMIC

• CONFIG_BT_MAX_CONN

• CONFIG_BT_ID_MAX

• CONFIG_BT_EXT_ADV_MAX_ADV_SET

• CONFIG_BT_DEVICE_NAME_MAX

• CONFIG_BT_PER_ADV_SYNC_MAX

• CONFIG_BT_DEVICE_APPEARANCE

• CONFIG_BT_DEVICE_NAME

• CONFIG_CBKPROXY_OUT_SLOTS on one core must be equal to CONFIG_CBKPROXY_IN_SLOTS on the other.

To keep all the above configuration options in sync, create an overlay file that is shared between the application and network core. Then, you can invoke build command like this:

west build -b board -- -DEXTRA_CONF_FILE=my_overlay_file.conf

Configuration

Set the CONFIG_BT_RPC_STACK Kconfig option to enable the Bluetooth Low Energy RPC library. Build the application using the following command:

west build -b nrf5340dk_nrf5340_cpuapp -- -DCONFIG_BT_RPC_STACK=y

Additionally, you can use the following options:

• CONFIG_BT_RPC

• CONFIG_BT_RPC_CLIENT

• CONFIG_BT_RPC_HOST

• CONFIG_BT_RPC_STACK

• CONFIG_BT_RPC_INITIALIZE_NRF_RPC

• CONFIG_BT_RPC_GATT_SRV_MAX

• CONFIG_BT_RPC_GATT_BUFFER_SIZE

• CONFIG_BT_RPC_INTERNAL_FUNCTIONS

• CONFIG_CBKPROXY_OUT_SLOTS

• CONFIG_CBKPROXY_IN_SLOTS

For more details, see the Kconfig option description.

Samples using the library

The following nRF Connect SDK sample and application use this library:

• Bluetooth: Host for nRF RPC Bluetooth Low Energy

• IPC radio firmware

The Bluetooth: Host for nRF RPC Bluetooth Low Energy sample exposes the Bluetooth LE stack functionality that runs on an MCU with radio (for example, the nRF5340 network core) to another CPU using the Remote procedure call library (nRF RPC). When building samples for the application core, enable the CONFIG_BT_RPC_STACK Kconfig option to run the Bluetooth LE stack on the network core. This option builds Bluetooth: Host for nRF RPC Bluetooth Low Energy automatically as a child image. For more details, see Building and programming a sample.

The IPC radio firmware application is an alternative to the Bluetooth: Host for nRF RPC Bluetooth Low Energy sample.

Limitations

The library currently supports serialization of the following:

• Generic Access Profile (GAP)

• Connection Management

• Generic Attribute Profile (GATT)

• Bluetooth Cryptography

The behavior of the Bluetooth implementation is almost the same as Zephyr’s with the following exceptions:

• The latency is longer because of the overhead for exchanging messages between cores. The Bluetooth LE API is not strictly real-time by design, so the additional latency introduced by the IPC communication should be acceptable in most applications. To reduce the latency, consider using a different transport backend for nRF RPC. See Architecture for details.

• Using advanced Bluetooth LE configurations, such as multiple simultaneous connections or advanced security features can be a limitation, because the child image (Bluetooth: Host for nRF RPC Bluetooth Low Energy or IPC radio firmware) might require significantly more memory than the MCU it runs on has available. Typically, network or radio cores are more memory-constrained than the application MCU.

• The bt_gatt_cancel() function is not implemented.

• The flags field of the bt_gatt_subscribe_params structure is atomic, so it cannot be correctly handled by the nRF RPC. The library implements the following workaround for it:

  • All flags are sent to the network core when either the bt_gatt_subscribe() or bt_gatt_resubscribe() function is called. This covers most of the cases, because the flags are normally set once before those functions calls.

  • If you want to read or write the flags after the subscription, you have to call bt_rpc_gatt_subscribe_flag_set(), bt_rpc_gatt_subscribe_flag_clear(), or bt_rpc_gatt_subscribe_flag_get().

Dependencies

The library has the following dependencies:

• Remote procedure call library (nRF RPC)

• Bluetooth

API documentation

This library does not define a new Bluetooth API except for flags modification. Instead, it uses Zephyr’s Bluetooth APIs.

Header file: include/bluetooth/bt_rpc.h

Source files: subsys/bluetooth/rpc/

group bt_rpc

API additions for the bluetooth over RPC.

Functions

int bt_rpc_gatt_subscribe_flag_set(struct bt_gatt_subscribe_params *params, uint32_t flags_bit)

Set flag in the flags field of the bt_gatt_subscribe_params structure.

This function must be used instead of atomic_set_bit() if you are using BLE API over RPC.

Parameters:

• params – Subscribe parameters.

• flags_bit – Index of bit to set.

Returns:

Previos flag value (retrived non-atomically) in case of success or negative value in case of error.

int bt_rpc_gatt_subscribe_flag_clear(struct bt_gatt_subscribe_params *params, uint32_t flags_bit)

Clear flag in the flags field of the bt_gatt_subscribe_params structure.

This function must be used instead of atomic_clear_bit() if you are using BLE API over RPC.

Parameters:

• params – Subscribe parameters.

• flags_bit – Index of bit to clear.

Returns:

Previos flag value (retrived non-atomically) in case of success or negative value in case of error.

int bt_rpc_gatt_subscribe_flag_get(struct bt_gatt_subscribe_params *params, uint32_t flags_bit)

Get flag value from the flags field of the bt_gatt_subscribe_params structure.

This function must be used instead of atomic_test_bit() if you are using BLE API over RPC.

Parameters:

• params – Subscribe parameters.

• flags_bit – Index of bit to test.

Returns:

Flag value in case of success or negative value in case of error.