Bluetooth: Define connection event prepare callbacks

doc/nrf/protocols/bt/ble/radio_notification_conn_cb.rst

@@ -0,0 +1,39 @@
+.. _ug_radio_notification_conn_cb:
+
+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 :c:member:`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.
+
+.. figure:: images/ConnEvtCb.svg
+   :alt: Radio Notification callback
+
+   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 :ref:`ble_radio_notification_conn_cb` sample demonstrates how you can use this feature to reduce the latency between data sampling and data transmission.
+
+You can use this feature only with the :ref:`SoftDevice Controller <nrfxlib:softdevice_controller>` and only when the Bluetooth controller and application are located on the same core.
+
+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 :c:member:`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.
+
+.. figure:: images/ConnEvtCbPeripheralLatency.svg
+   :alt: Radio Notification callback with peripheral latency
+
+   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 :c:macro:`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.

doc/nrf/protocols/bt/index.rst

@@ -12,5 +12,6 @@ To enable Bluetooth LE in your application, you can use the standard HCI-based a
    :caption: Subpages:
 
    ble/index.rst
+   ble/radio_notification_conn_cb.rst
    bt_mesh/index.rst
    bt_qualification/index.rst

include/bluetooth/radio_notification_cb.h

@@ -0,0 +1,95 @@
+/*
+ * Copyright (c) 2024 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+ */
+
+#ifndef BT_RADIO_NOTIFICATION_CB_H__
+#define BT_RADIO_NOTIFICATION_CB_H__
+
+/**
+ * @file
+ * @defgroup bt_radio_notification_cb Radio Notification callback
+ * @{
+ * @brief 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.
+ */
+
+#include <stdint.h>
+#include <zephyr/bluetooth/conn.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** 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 @ref bt_radio_notification_conn_cb_register for more details about
+ * prepare distance selection and clock drift.
+ */
+#define BT_RADIO_NOTIFICATION_CONN_CB_PREPARE_DISTANCE_US_RECOMMENDED 3000
+
+/** Radio Notification connection callbacks
+ *
+ * The callbacks will be called from the system workqueue.
+ */
+struct bt_radio_notification_conn_cb {
+	/** Radio Notification prepare callback
+	 *
+	 * The prepare callback will be triggered a configurable amount
+	 * of time before the connection event starts.
+	 *
+	 * @param[in] conn The connection context.
+	 */
+	void (*prepare)(struct bt_conn *conn);
+};
+
+/** 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_v5.4, Vol 6, Part 4.2.4 for more details on clock drift.
+ *
+ * @param[in] cb                  The callback structure to be used.
+ *                                The memory pointed to needs to be kept alive by the user.
+ * @param[in] prepare_distance_us The distance in time from the start of the
+ *   prepare callback to the start of the connection event.
+ *   See also @ref BT_RADIO_NOTIFICATION_CONN_CB_PREPARE_DISTANCE_US_RECOMMENDED.
+ *
+ *  @retval 0          The callback structure has been successfully registered.
+ *  @retval -EALREADY  A callback has already been registered.
+ *  @retval -ENOMEM    There are not enough PPI channels available to use this feature.
+ */
+int bt_radio_notification_conn_cb_register(const struct bt_radio_notification_conn_cb *cb,
+					   uint32_t prepare_distance_us);
+
+#ifdef __cplusplus
+}
+#endif
+
+/**
+ * @}
+ */
+
+#endif /* BT_RADIO_NOTIFICATION_CB_H__ */