esb: Implemented monitor mode with sample

Monitor mode forces radio to stay in RX state,
to avoid sending ACKs for received packets.

Jira: NCSDK-34441
Jira: NCSDK-34442

Signed-off-by: Michał Strządała <[email protected]>

Author: Tryton77

doc/nrf/protocols/esb/index.rst

@@ -40,6 +40,7 @@ Features
  * Individual TX and RX FIFOs for every pipe
  * Backward compatible with legacy nRF24Lxx Enhanced ShockBurst
  * Support for external front-end modules.
+ * Monitor mode for protocol debugging purposes.
 
 .. _esb_config:
 
@@ -129,6 +130,13 @@ When the :c:member:`selective_auto_ack` field in the :c:struct:`esb_config` conf
 When the PRX receives a packet that does not require an ACK, it does not send an ACK packet to the PTX.
 In this case, when :c:member:`esb_payload.noack` = ``true``, packet retransmission does not occur.
 
+.. _esb_monitor_mode:
+
+ESB Monitor mode
+================
+
+ESB Monitor mode feature allows you to capture both packets and ACKs sent by other ESB devices, which can be useful when analyzing or debugging the protocol.
+
 .. _esb_getting_started:
 
 Setting up an ESB application
@@ -171,6 +179,28 @@ Perform the following steps to set up an application to send and receive packets
 	After a queued payload is sent with an acknowledgment, it is assumed that it reaches the other device.
 	Therefore, an :c:macro:`ESB_EVENT_TX_SUCCESS` event is queued.
 
+To set up an application as MONITOR, complete the following steps:
+
+1. Initialize the ESB module using the :c:func:`esb_init` function with default parameters from :c:macro:`ESB_DEFAULT_CONFIG`.
+   Set the :c:member:`esb_config.mode` parameter to :c:macro:`ESB_MODE_MONITOR` value and set :c:member:`esb.config.event_handler` callback.
+
+   You can adjust the following parameters:
+
+      * :c:member:`esb_config.protocol`
+      * :c:member:`esb_config.bitrate`
+      * :c:member:`esb_config.crc`
+      * :c:member:`esb_config.payload_length`
+
+   These parameters as well as addresses and prefixes must be the same as those configured in the PTX and PRX nodes that you want to monitor.
+
+#. Set up the high-frequency clock in the same manner as in the PRX or PTX mode.
+
+#. Start monitoring using the :c:func:`esb_start_rx` function.
+
+#. Handle the :c:macro:`ESB_EVENT_RX_RECEIVED` events using the :c:func:`esb_read_rx_payload` function.
+
+#. Stop monitoring using the :c:func:`esb_stop_rx` function.
+
 To stop the ESB module, call :c:func:`esb_disable`.
 Note, however, that if a transaction is ongoing when you disable the module, it is not completed.
 Therefore, you might want to check if the module is idle before disabling it.
@@ -258,11 +288,18 @@ If an ACK received by a PTX contains a payload, this payload is added to the PTX
 PRX FIFO handling
 *****************
 
-When ESB is enabled in PRX mode, all enabled pipes (addresses) are simultaneously monitored for incoming packets.
+When ESB is enabled in PRX or Monitor mode, all enabled pipes (addresses) are simultaneously monitored for incoming packets.
+
+PRX:
+
+   If a new packet that was not previously added to the PRX's RX FIFO is received, and RX FIFO has available space for it, the packet is added to the RX FIFO and an ACK is sent in return to the PTX.
+   If the TX FIFO contains any packets, the next serviceable packet in the TX FIFO is attached as a payload in the ACK packet.
+   This TX packet must have been uploaded to the TX FIFO before the packet is received.
+
+Monitor:
 
-If a new packet that was not previously added to the PRX's RX FIFO is received, and RX FIFO has available space for the packet, the packet is added to the RX FIFO and an ACK is sent in return to the PTX.
-If the TX FIFO contains any packets, the next serviceable packet in the TX FIFO is attached as a payload in the ACK packet.
-Note that this TX packet must have been uploaded to the TX FIFO before the packet is received.
+   All received packets are added to the RX FIFO if it has available space, without sending ACKs.
+   Packets in the TX FIFO are ignored.
 
 .. _callback_queuing:
 
@@ -301,10 +338,11 @@ If you are sure that you do not require support for revision 2 chips, you may re
 Examples
 ========
 
-The |NCS| provides the following two samples that show how to use the ESB protocol:
+The |NCS| provides the following three samples that show how to use the ESB protocol:
 
 * :ref:`esb_ptx`
 * :ref:`esb_prx`
+* :ref:`esb_monitor`
 
 .. _esb_fast_ramp_up:
 

doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst

@@ -148,7 +148,7 @@ DECT NR+
 Enhanced ShockBurst (ESB)
 -------------------------
 
-|no_changes_yet_note|
+* Added the :ref:`esb_monitor_mode` feature.
 
 Gazell
 ------
@@ -278,7 +278,7 @@ Edge Impulse samples
 Enhanced ShockBurst samples
 ---------------------------
 
-|no_changes_yet_note|
+* Added the :ref:`esb_monitor` sample to demonstrate how to use the :ref:`ug_esb` protocol in Monitor mode.
 
 Gazell samples
 --------------

include/esb.h

@@ -98,8 +98,9 @@ enum esb_protocol {
 
 /** @brief Enhanced ShockBurst modes. */
 enum esb_mode {
-	ESB_MODE_PTX,	/**< Primary transmitter mode. */
-	ESB_MODE_PRX	/**< Primary receiver mode.    */
+	ESB_MODE_PTX,		/**< Primary transmitter mode. */
+	ESB_MODE_PRX,		/**< Primary receiver mode.    */
+	ESB_MODE_MONITOR	/**< Primary monitor mode.     */
 };
 
 /** @brief Enhanced ShockBurst bitrate modes. */

samples/esb/esb_monitor/CMakeLists.txt

@@ -0,0 +1,14 @@
+#
+# Copyright (c) 2025 Nordic Semiconductor
+#
+# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+#
+cmake_minimum_required(VERSION 3.20.0)
+
+find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+project(NONE)
+
+FILE(GLOB app_sources src/*.c)
+# NORDIC SDK APP START
+target_sources(app PRIVATE ${app_sources})
+# NORDIC SDK APP END

samples/esb/esb_monitor/Kconfig

@@ -0,0 +1,21 @@
+#
+# Copyright (c) 2025 Nordic Semiconductor
+#
+# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+#
+
+source "Kconfig.zephyr"
+
+menu "Enhanced ShockBurst: Monitor"
+
+config LED_ENABLE
+	bool "LED changes when receiving packets"
+	default y
+	help
+	  Turns on led updates when receiving packets from PTX sample.
+
+module = ESB_MONITOR_APP
+module-str = "ESB Monitor app"
+source "${ZEPHYR_BASE}/subsys/logging/Kconfig.template.log_config"
+
+endmenu

samples/esb/esb_monitor/Kconfig.sysbuild

@@ -0,0 +1,4 @@
+source "share/sysbuild/Kconfig"
+
+config NRF_DEFAULT_EMPTY
+	default y if SOC_SERIES_NRF53X

samples/esb/esb_monitor/README.rst

@@ -0,0 +1,93 @@
+.. _esb_monitor:
+
+Enhanced ShockBurst: Monitor
+#############################
+
+.. contents::
+   :local:
+   :depth: 2
+
+The Monitor sample shows how to use the :ref:`ug_esb` protocol in Monitor mode.
+It demonstrates how to configure the Enhanced ShockBurst protocol to receive all the traffic generated on the configured channel and pipes.
+
+Requirements
+************
+
+The sample supports the following development kits:
+
+.. table-from-sample-yaml::
+
+Overview
+********
+
+The sample consist of one receiver configured as a monitor that uses the :ref:`esb_README` library.
+After building and programming each sample on a DK, you can monitor the traffic generated by the kits programmed with the :ref:`Transmitter <esb_ptx>` and :ref:`Receiver <esb_prx>` samples, respectively.
+You can see the received traffic in real time using the `Serial Terminal app`_.
+Successful monitoring is also indicated by the LEDs that should be in sync on all kits.
+
+User interface
+***************
+
+All LEDs:
+
+   Indicate that packets are received.
+
+   When used together with the :ref:`Transmitter <esb_ptx>` sample:
+
+       The first four packets turn on the LEDs sequentially.
+
+       The next four packets turn them off again in the same order.
+
+   To disable LEDs, unset the :kconfig:option:`CONFIG_LED_ENABLE` Kconfig option.
+
+Configuration
+*************
+
+|config|
+
+Building and running
+********************
+
+The Monitor sample is located in the :file:`samples/esb/esb_monitor` folder in the |NCS| folder structure.
+
+See :ref:`building` and :ref:`programming` for information on how to build and program the application, respectively.
+
+.. include:: /includes/nRF54H20_erase_UICR.txt
+
+FEM support
+===========
+
+.. include:: /includes/sample_fem_support.txt
+
+Testing
+=======
+
+After programming the DKs with the Monitor, Transmitter, and Receiver samples, you can test their functionality.
+
+Complete the following steps to test the samples:
+
+1. Power on all kits.
+#. Observe that the LEDs change synchronously on all kits.
+#. Connect to the monitor DK with a terminal emulator (for example, the `Serial Terminal app`_).
+   See :ref:`test_and_optimize` for the required settings and steps.
+#. Observe the logged traffic of the DK programmed with the Monitor sample.
+
+Dependencies
+************
+
+This sample uses the following |NCS| library:
+
+* :ref:`esb_readme`
+
+In addition, it uses the following Zephyr libraries:
+
+* :file:`include/zephyr/types.h`
+* :ref:`zephyr:logging_api`
+* :ref:`zephyr:kernel_api`:
+
+  * :file:`include/kernel.h`
+  * :file:`include/irq.h`
+
+* :ref:`zephyr:api_peripherals`:
+
+   * :file:`include/gpio.h`

samples/esb/esb_monitor/boards/nrf54h20dk_nrf54h20_cpurad.overlay

@@ -0,0 +1,77 @@
+/*
+ * Copyright (c) 2025 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+ */
+
+/ {
+	leds {
+		compatible = "gpio-leds";
+
+		led0: led_0 {
+			gpios = < &gpio9 0 GPIO_ACTIVE_HIGH >;
+			label = "Green LED 0";
+		};
+
+		led1: led_1 {
+			gpios = < &gpio9 1 GPIO_ACTIVE_HIGH >;
+			label = "Green LED 1";
+		};
+
+		led2: led_2 {
+			gpios = < &gpio9 2 GPIO_ACTIVE_HIGH >;
+			label = "Green LED 2";
+		};
+
+		led3: led_3 {
+			gpios = < &gpio9 3 GPIO_ACTIVE_HIGH >;
+			label = "Green LED 3";
+		};
+	};
+
+	aliases {
+		led0 = &led0;
+		led1 = &led1;
+		led2 = &led2;
+		led3 = &led3;
+	};
+
+	chosen {
+		zephyr,console = &uart136;
+	};
+
+	cpurad_cpusys_errata216_mboxes: errata216_mboxes {
+		compatible = "zephyr,mbox-ipm";
+		status = "okay";
+		mboxes = < &cpusys_vevif 0x14 >, < &cpusys_vevif 0x15 >;
+		mbox-names = "on_req", "off_req";
+	};
+};
+
+&gpio9 {
+	status = "okay";
+};
+
+&gpio0 {
+	status = "okay";
+};
+
+&gpiote130 {
+	owned-channels = <0 1 2 3 4 5 6 7>;
+	status = "okay";
+};
+
+&uart136 {
+	status = "okay";
+	memory-regions = <&cpurad_dma_region>;
+};
+
+&uart135 {
+	status = "disabled";
+};
+
+&dppic020 {
+	status = "okay";
+	source-channels = < 0 1 2 3 4 5 >;
+	sink-channels = < 6 7 8 9 10 11 >;
+};

samples/esb/esb_monitor/boards/nrf54l15dk_nrf54l05_cpuapp.conf

@@ -0,0 +1,8 @@
+#
+# Copyright (c) 2025 Nordic Semiconductor
+#
+# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+#
+
+# Enable DPPI driver
+CONFIG_NRFX_DPPI10=y

samples/esb/esb_monitor/boards/nrf54l15dk_nrf54l10_cpuapp.conf

@@ -0,0 +1,8 @@
+#
+# Copyright (c) 2025 Nordic Semiconductor
+#
+# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+#
+
+# Enable DPPI driver
+CONFIG_NRFX_DPPI10=y