Radio Notification callback

The Bluetooth Radio Notification connection callback feature is used to inform the application about upcoming radio activity for a Bluetooth connection. The bt_radio_notification_conn_cb.prepare callback is triggered right before a Bluetooth connection event. This allows the application to trigger sensor data collection for transmission during the upcoming connection event.

The prepare callback is called before a connection event

The timing of the prepare callback is configured with the parameter prepare_time_us. You must set the parameter value large enough to allow the Bluetooth stack to enqueue a data packet for the upcoming connection event.

The Bluetooth: Radio Notification callback sample demonstrates how you can use this feature to reduce the latency between data sampling and data transmission.

Radio Notification connection callback with peripheral latency

When a connection is configured with peripheral latency, the peripheral device may sleep for peripheral_latency consecutive connection events to save power. The device may wake up more often if, for example, it has data to send. The central device assumes that the peripheral will wake up at every connection event.

The ble_radio_notification_conn_cb.prepare callback will be called before every connection event for both the peripheral and central device. If the peripheral application provides data to be sent in this callback, the peripheral device will wake up for that given connection event.

The peripheral wakes up if data is provided in a prepare callback

For this configuration, the application must configure the prepare callback to trigger at least BT_RADIO_NOTIFICATION_CONN_CB_PREPARE_DISTANCE_US_RECOMMENDED before the connection event starts. This allows the Bluetooth stack to start the high frequency clock and radio peripheral if they are not already running. If the data is provided too close to the start of the connection event, the data will be sent in upcoming events.

Limitations

You can use this feature only with the SoftDevice Controller and only when the Bluetooth controller and application are located on the same core.

API documentation

Header file: include/bluetooth/radio_notification_cb.h

Source file: subsys/bluetooth/host_extensions/radio_notification_conn_cb.c

group bt_radio_notification_cb

APIs to set up radio notification callbacks.

The radio notification callbacks are triggered relative to the start of a Link Layer event.

This information can be used to reduce the time from data sampling until data is sent on air.

Defines

BT_RADIO_NOTIFICATION_CONN_CB_PREPARE_DISTANCE_US_RECOMMENDED

Recommended prepare distance for the connection event callback.

The selected distance assumes a maximum processing delay and a maximum of 2 seconds between packets from devices with worst case clock accuracy.

When shorter connection intervals are used or when it known that the local clock accuracy is better a shorter prepare distance can be used.

See bt_radio_notification_conn_cb_register for more details about prepare distance selection and clock drift.

Functions

int bt_radio_notification_conn_cb_register(const struct bt_radio_notification_conn_cb *cb, uint32_t prepare_distance_us)

Register a radio notification callback struct for connections.

When the prepare callback is used to provide data to the Bluetooth stack, the application needs to reserve enough time to allow the data to be forwarded to the link layer.

When used with a peripheral connection, the prepare distance also needs to take clock drift into account to avoid that the callback triggers too late. The clock drift is determined by the distance between packets and the clock accuracy of both the central and the peripheral. The Bluetooth specification allows a worst case clock accurary of 500 ppm. That gives a worst case combined clock accurary of 1000 ppm. This results in 1 ms drift per second.

See Bluetooth Core Specification, Vol 6, Part B, Section 4.2.4 for more details on clock drift.

Parameters:

• cb – [in] The callback structure to be used. The memory pointed to needs to be kept alive by the user.

• prepare_distance_us – [in] The distance in time from the start of the prepare callback to the start of the connection event. See also BT_RADIO_NOTIFICATION_CONN_CB_PREPARE_DISTANCE_US_RECOMMENDED.

Return values:

• 0 – The callback structure has been successfully registered.

• -EALREADY – A callback has already been registered.

• -ENOMEM – There are not enough PPI channels available to use this feature.

struct bt_radio_notification_conn_cb

#include <radio_notification_cb.h>

Radio Notification connection callbacks

The callbacks will be called from the system workqueue.

Public Members

void (*prepare)(struct bt_conn *conn)

Radio Notification prepare callback

The prepare callback will be triggered a configurable amount of time before the connection event starts.

Param conn:

[in] The connection context.