Skip to content

Commit ab5aa2c

Browse files
Tryton77rlubos
Tryton77
authored and
rlubos
committed
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]>
1 parent c4bd457 commit ab5aa2c

File tree

16 files changed

+639
-22
lines changed

16 files changed

+639
-22
lines changed

‎doc/nrf/protocols/esb/index.rst‎

Lines changed: 43 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@ Features
4040
* Individual TX and RX FIFOs for every pipe
4141
* Backward compatible with legacy nRF24Lxx Enhanced ShockBurst
4242
* Support for external front-end modules.
43+
* Monitor mode for protocol debugging purposes.
4344

4445
.. _esb_config:
4546

@@ -129,6 +130,13 @@ When the :c:member:`selective_auto_ack` field in the :c:struct:`esb_config` conf
129130
When the PRX receives a packet that does not require an ACK, it does not send an ACK packet to the PTX.
130131
In this case, when :c:member:`esb_payload.noack` = ``true``, packet retransmission does not occur.
131132

133+
.. _esb_monitor_mode:
134+
135+
ESB Monitor mode
136+
================
137+
138+
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.
139+
132140
.. _esb_getting_started:
133141

134142
Setting up an ESB application
@@ -171,6 +179,28 @@ Perform the following steps to set up an application to send and receive packets
171179
After a queued payload is sent with an acknowledgment, it is assumed that it reaches the other device.
172180
Therefore, an :c:macro:`ESB_EVENT_TX_SUCCESS` event is queued.
173181

182+
To set up an application as MONITOR, complete the following steps:
183+
184+
1. Initialize the ESB module using the :c:func:`esb_init` function with default parameters from :c:macro:`ESB_DEFAULT_CONFIG`.
185+
Set the :c:member:`esb_config.mode` parameter to :c:macro:`ESB_MODE_MONITOR` value and set :c:member:`esb.config.event_handler` callback.
186+
187+
You can adjust the following parameters:
188+
189+
* :c:member:`esb_config.protocol`
190+
* :c:member:`esb_config.bitrate`
191+
* :c:member:`esb_config.crc`
192+
* :c:member:`esb_config.payload_length`
193+
194+
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.
195+
196+
#. Set up the high-frequency clock in the same manner as in the PRX or PTX mode.
197+
198+
#. Start monitoring using the :c:func:`esb_start_rx` function.
199+
200+
#. Handle the :c:macro:`ESB_EVENT_RX_RECEIVED` events using the :c:func:`esb_read_rx_payload` function.
201+
202+
#. Stop monitoring using the :c:func:`esb_stop_rx` function.
203+
174204
To stop the ESB module, call :c:func:`esb_disable`.
175205
Note, however, that if a transaction is ongoing when you disable the module, it is not completed.
176206
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
258288
PRX FIFO handling
259289
*****************
260290

261-
When ESB is enabled in PRX mode, all enabled pipes (addresses) are simultaneously monitored for incoming packets.
291+
When ESB is enabled in PRX or Monitor mode, all enabled pipes (addresses) are simultaneously monitored for incoming packets.
292+
293+
PRX:
294+
295+
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.
296+
If the TX FIFO contains any packets, the next serviceable packet in the TX FIFO is attached as a payload in the ACK packet.
297+
This TX packet must have been uploaded to the TX FIFO before the packet is received.
298+
299+
Monitor:
262300

263-
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.
264-
If the TX FIFO contains any packets, the next serviceable packet in the TX FIFO is attached as a payload in the ACK packet.
265-
Note that this TX packet must have been uploaded to the TX FIFO before the packet is received.
301+
All received packets are added to the RX FIFO if it has available space, without sending ACKs.
302+
Packets in the TX FIFO are ignored.
266303

267304
.. _callback_queuing:
268305

@@ -301,10 +338,11 @@ If you are sure that you do not require support for revision 2 chips, you may re
301338
Examples
302339
========
303340

304-
The |NCS| provides the following two samples that show how to use the ESB protocol:
341+
The |NCS| provides the following three samples that show how to use the ESB protocol:
305342

306343
* :ref:`esb_ptx`
307344
* :ref:`esb_prx`
345+
* :ref:`esb_monitor`
308346

309347
.. _esb_fast_ramp_up:
310348

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -148,7 +148,7 @@ DECT NR+
148148
Enhanced ShockBurst (ESB)
149149
-------------------------
150150

151-
|no_changes_yet_note|
151+
* Added the :ref:`esb_monitor_mode` feature.
152152

153153
Gazell
154154
------
@@ -278,7 +278,7 @@ Edge Impulse samples
278278
Enhanced ShockBurst samples
279279
---------------------------
280280

281-
|no_changes_yet_note|
281+
* Added the :ref:`esb_monitor` sample to demonstrate how to use the :ref:`ug_esb` protocol in Monitor mode.
282282

283283
Gazell samples
284284
--------------

‎include/esb.h‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -98,8 +98,9 @@ enum esb_protocol {
9898

9999
/** @brief Enhanced ShockBurst modes. */
100100
enum esb_mode {
101-
ESB_MODE_PTX, /**< Primary transmitter mode. */
102-
ESB_MODE_PRX /**< Primary receiver mode. */
101+
ESB_MODE_PTX, /**< Primary transmitter mode. */
102+
ESB_MODE_PRX, /**< Primary receiver mode. */
103+
ESB_MODE_MONITOR /**< Primary monitor mode. */
103104
};
104105

105106
/** @brief Enhanced ShockBurst bitrate modes. */

‎samples/esb/esb_monitor/CMakeLists.txt‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
#
2+
# Copyright (c) 2025 Nordic Semiconductor
3+
#
4+
# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
5+
#
6+
cmake_minimum_required(VERSION 3.20.0)
7+
8+
find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
9+
project(NONE)
10+
11+
FILE(GLOB app_sources src/*.c)
12+
# NORDIC SDK APP START
13+
target_sources(app PRIVATE ${app_sources})
14+
# NORDIC SDK APP END

‎samples/esb/esb_monitor/Kconfig‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
#
2+
# Copyright (c) 2025 Nordic Semiconductor
3+
#
4+
# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
5+
#
6+
7+
source "Kconfig.zephyr"
8+
9+
menu "Enhanced ShockBurst: Monitor"
10+
11+
config LED_ENABLE
12+
bool "LED changes when receiving packets"
13+
default y
14+
help
15+
Turns on led updates when receiving packets from PTX sample.
16+
17+
module = ESB_MONITOR_APP
18+
module-str = "ESB Monitor app"
19+
source "${ZEPHYR_BASE}/subsys/logging/Kconfig.template.log_config"
20+
21+
endmenu

‎samples/esb/esb_monitor/Kconfig.sysbuild‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
source "share/sysbuild/Kconfig"
2+
3+
config NRF_DEFAULT_EMPTY
4+
default y if SOC_SERIES_NRF53X

‎samples/esb/esb_monitor/README.rst‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
.. _esb_monitor:
2+
3+
Enhanced ShockBurst: Monitor
4+
#############################
5+
6+
.. contents::
7+
:local:
8+
:depth: 2
9+
10+
The Monitor sample shows how to use the :ref:`ug_esb` protocol in Monitor mode.
11+
It demonstrates how to configure the Enhanced ShockBurst protocol to receive all the traffic generated on the configured channel and pipes.
12+
13+
Requirements
14+
************
15+
16+
The sample supports the following development kits:
17+
18+
.. table-from-sample-yaml::
19+
20+
Overview
21+
********
22+
23+
The sample consist of one receiver configured as a monitor that uses the :ref:`esb_README` library.
24+
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.
25+
You can see the received traffic in real time using the `Serial Terminal app`_.
26+
Successful monitoring is also indicated by the LEDs that should be in sync on all kits.
27+
28+
User interface
29+
***************
30+
31+
All LEDs:
32+
33+
Indicate that packets are received.
34+
35+
When used together with the :ref:`Transmitter <esb_ptx>` sample:
36+
37+
The first four packets turn on the LEDs sequentially.
38+
39+
The next four packets turn them off again in the same order.
40+
41+
To disable LEDs, unset the :kconfig:option:`CONFIG_LED_ENABLE` Kconfig option.
42+
43+
Configuration
44+
*************
45+
46+
|config|
47+
48+
Building and running
49+
********************
50+
51+
The Monitor sample is located in the :file:`samples/esb/esb_monitor` folder in the |NCS| folder structure.
52+
53+
See :ref:`building` and :ref:`programming` for information on how to build and program the application, respectively.
54+
55+
.. include:: /includes/nRF54H20_erase_UICR.txt
56+
57+
FEM support
58+
===========
59+
60+
.. include:: /includes/sample_fem_support.txt
61+
62+
Testing
63+
=======
64+
65+
After programming the DKs with the Monitor, Transmitter, and Receiver samples, you can test their functionality.
66+
67+
Complete the following steps to test the samples:
68+
69+
1. Power on all kits.
70+
#. Observe that the LEDs change synchronously on all kits.
71+
#. Connect to the monitor DK with a terminal emulator (for example, the `Serial Terminal app`_).
72+
See :ref:`test_and_optimize` for the required settings and steps.
73+
#. Observe the logged traffic of the DK programmed with the Monitor sample.
74+
75+
Dependencies
76+
************
77+
78+
This sample uses the following |NCS| library:
79+
80+
* :ref:`esb_readme`
81+
82+
In addition, it uses the following Zephyr libraries:
83+
84+
* :file:`include/zephyr/types.h`
85+
* :ref:`zephyr:logging_api`
86+
* :ref:`zephyr:kernel_api`:
87+
88+
* :file:`include/kernel.h`
89+
* :file:`include/irq.h`
90+
91+
* :ref:`zephyr:api_peripherals`:
92+
93+
* :file:`include/gpio.h`

‎samples/esb/esb_monitor/boards/nrf54h20dk_nrf54h20_cpurad.overlay‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
/*
2+
* Copyright (c) 2025 Nordic Semiconductor ASA
3+
*
4+
* SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
5+
*/
6+
7+
/ {
8+
leds {
9+
compatible = "gpio-leds";
10+
11+
led0: led_0 {
12+
gpios = < &gpio9 0 GPIO_ACTIVE_HIGH >;
13+
label = "Green LED 0";
14+
};
15+
16+
led1: led_1 {
17+
gpios = < &gpio9 1 GPIO_ACTIVE_HIGH >;
18+
label = "Green LED 1";
19+
};
20+
21+
led2: led_2 {
22+
gpios = < &gpio9 2 GPIO_ACTIVE_HIGH >;
23+
label = "Green LED 2";
24+
};
25+
26+
led3: led_3 {
27+
gpios = < &gpio9 3 GPIO_ACTIVE_HIGH >;
28+
label = "Green LED 3";
29+
};
30+
};
31+
32+
aliases {
33+
led0 = &led0;
34+
led1 = &led1;
35+
led2 = &led2;
36+
led3 = &led3;
37+
};
38+
39+
chosen {
40+
zephyr,console = &uart136;
41+
};
42+
43+
cpurad_cpusys_errata216_mboxes: errata216_mboxes {
44+
compatible = "zephyr,mbox-ipm";
45+
status = "okay";
46+
mboxes = < &cpusys_vevif 0x14 >, < &cpusys_vevif 0x15 >;
47+
mbox-names = "on_req", "off_req";
48+
};
49+
};
50+
51+
&gpio9 {
52+
status = "okay";
53+
};
54+
55+
&gpio0 {
56+
status = "okay";
57+
};
58+
59+
&gpiote130 {
60+
owned-channels = <0 1 2 3 4 5 6 7>;
61+
status = "okay";
62+
};
63+
64+
&uart136 {
65+
status = "okay";
66+
memory-regions = <&cpurad_dma_region>;
67+
};
68+
69+
&uart135 {
70+
status = "disabled";
71+
};
72+
73+
&dppic020 {
74+
status = "okay";
75+
source-channels = < 0 1 2 3 4 5 >;
76+
sink-channels = < 6 7 8 9 10 11 >;
77+
};

‎samples/esb/esb_monitor/boards/nrf54l15dk_nrf54l05_cpuapp.conf‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
#
2+
# Copyright (c) 2025 Nordic Semiconductor
3+
#
4+
# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
5+
#
6+
7+
# Enable DPPI driver
8+
CONFIG_NRFX_DPPI10=y

‎samples/esb/esb_monitor/boards/nrf54l15dk_nrf54l10_cpuapp.conf‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
#
2+
# Copyright (c) 2025 Nordic Semiconductor
3+
#
4+
# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
5+
#
6+
7+
# Enable DPPI driver
8+
CONFIG_NRFX_DPPI10=y

0 commit comments

Comments
 (0)