Configuring ZBOSS traces

The ZBOSS Zigbee stack (ZBOSS stack) comes included in the nRF Connect SDK in a set of precompiled libraries, which can complicate the debugging process. To help with that, the ZBOSS stack can be configured to print trace logs that allow you to trace the stack behavior. This page describes how to enable and configure ZBOSS trace logs.

Trace logs are printed in binary form and require access to stack source files to be decoded into log messages. Enabling trace logs can help with the debugging process even if you cannot decode them (due to lack of access to stack source files). This is because of the information they can provide about the stack behavior whenever an issue is found or reproduced.

If any issues are found with the ZBOSS stack, trace logs can be enabled to collect this information while reproducing the issue. A ticket can then be created in DevZone with the log file attached for assistance with the debugging process, and for decoding trace log files.

Note

ZBOSS trace logs are meant to be used for debugging ZBOSS based applications. These libraries are not certified and should not be used for production firmware or end products.

Requirements

To collect and view the log files, you will need the following:

• A terminal emulator, such as nRF Connect Serial Terminal (from the nRF Connect for Desktop application) or the nRF Terminal (part of the nRF Connect for Visual Studio Code extension).

• Correct COM port.

  • For traces using the UART, the J-Link COM port is used. The development kit is assigned to a COM port (Windows) or a ttyACM device (Linux), which is visible in the system’s Device Manager.

Switch to ZBOSS libraries with compiled-in trace logs

Set the Kconfig option CONFIG_ZIGBEE_ENABLE_TRACES to switch to ZBOSS libraries with compiled-in trace logs.

The ZBOSS stack comes in a precompiled form and trace logs are not compiled-in by default. An additional set of ZBOSS libraries are available in nrfxlib, which does have trace logs compiled-in.

Select which ZBOSS trace logs to print

Complete the following steps:

1. Select from which subsystems you would like to receive logs by configuring the ZBOSS trace mask with the Kconfig option CONFIG_ZBOSS_TRACE_MASK. Trace masks can be created by adding up masks of subsystems to receive the trace logs from. For available subsystems, see nrfxlib/zboss/production/include/zb_trace.h.

2. Select the level of logs you want to receive. Configure ZBOSS trace level by selecting one of the following levels with the corresponding Kconfig option:

   • Error trace logs level - Set CONFIG_ZBOSS_TRACE_LOG_LEVEL_ERR

   • Warning trace logs level - Set CONFIG_ZBOSS_TRACE_LOG_LEVEL_WRN

   • Info trace logs level - Set CONFIG_ZBOSS_TRACE_LOG_LEVEL_INF

   • Debug trace logs level - Set CONFIG_ZBOSS_TRACE_LOG_LEVEL_DBG

If you do not want to receive trace logs, turn them off by setting the Kconfig option CONFIG_ZBOSS_TRACE_LOG_LEVEL_OFF.

Each of the following levels on the list also includes the previous one. See Stack logs to read more about trace logs.

Configure how to print ZBOSS trace logs

The ZBOSS OSIF serial abstract offers a few backends to choose from for printing ZBOSS trace logs. It is recommended to use the Zigbee serial logger, as it is the most efficient. To enable it, set the Kconfig option CONFIG_ZBOSS_TRACE_BINARY_LOGGING.

Optional: Increasing the size of the ring buffer

You can increase size of the ring buffer that temporarily stores the trace logs. To do this, use the CONFIG_ZBOSS_TRACE_LOGGER_BUFFER_SIZE Kconfig option to assign a value for size of the buffer. This can prevent losing some of the logs in demanding scenarios such as high network traffic, multiple devices being configured or joined, and so on. See Zigbee serial logger for more information.

Trace logs using UART (default)

When the CONFIG_ZBOSS_TRACE_BINARY_LOGGING Kconfig option is selected, trace logs are printed using the UART by default. To configure trace logs using the UART, complete the following steps:

1. Set the CONFIG_ZBOSS_TRACE_UART_LOGGING Kconfig option.

2. Provide the ZBOSS tracing serial device in Devicetree like this:

   chosen {
       ncs,zboss-trace-uart = &uart1;
   };
   

3. Configure the UART device that you want to use to be connected to the onboard J-Link instead of UART_0, by extending the DTS overlay file for the selected board with the following:

   &pinctrl {
      uart0_default_alt: uart0_default_alt {
         group1 {
            psels = <NRF_PSEL(UART_TX, 1, 2)>,
                    <NRF_PSEL(UART_RX, 1, 1)>;
         };
      };
   
      uart0_sleep_alt: uart0_sleep_alt {
         group1 {
            psels = <NRF_PSEL(UART_TX, 1, 2)>,
                    <NRF_PSEL(UART_RX, 1, 1)>;
            low-power-enable;
         };
      };
   
      uart1_default_alt: uart1_default_alt {
         group1 {
            psels = <NRF_PSEL(UART_TX, 0, 6)>,
                    <NRF_PSEL(UART_RX, 0, 8)>,
                    <NRF_PSEL(UART_RTS, 0, 5)>,
                    <NRF_PSEL(UART_CTS, 0, 7)>;
         };
      };
   
      uart1_sleep_alt: uart1_sleep_alt {
         group1 {
            psels = <NRF_PSEL(UART_TX, 0, 6)>,
                    <NRF_PSEL(UART_RX, 0, 8)>,
                    <NRF_PSEL(UART_RTS, 0, 5)>,
                    <NRF_PSEL(UART_CTS, 0, 7)>;
            low-power-enable;
         };
      };
   };
   
   &uart1 {
      pinctrl-0 = <&uart1_default_alt>;
      pinctrl-1 = <&uart1_sleep_alt>;
      pinctrl-names = "default", "sleep";
   };
   
   &uart0 {
      pinctrl-0 = <&uart0_default_alt>;
      pinctrl-1 = <&uart0_sleep_alt>;
      pinctrl-names = "default", "sleep";
   };
   

   Note

   By connecting the UART device to the on-board J-Link, trace logs can be read directly from the J-Link COM port. As a consequence, the UART device used by the logger is disconnected and application logs cannot be accessed from the J-Link COM port.

Optional: Increasing the UART throughput

You can also increase the UART throughput by changing the baudrate. Some of the trace logs will be dropped if the throughput is too low. By default, the UART baudrate is set to 115200. To increase the baudrate to 1000000, add the current-speed = <1000000>; property to the uart1 node in the DTS overlay file. This can be done like the following:

&pinctrl {
   uart1_default_alt: uart1_default_alt {
      group1 {
         psels = <NRF_PSEL(UART_TX, 0, 6)>,
                 <NRF_PSEL(UART_RX, 0, 8)>,
                 <NRF_PSEL(UART_RTS, 0, 5)>,
                 <NRF_PSEL(UART_CTS, 0, 7)>;
      };
   };

   uart1_sleep_alt: uart1_sleep_alt {
      group1 {
         psels = <NRF_PSEL(UART_TX, 0, 6)>,
                 <NRF_PSEL(UART_RX, 0, 8)>,
                 <NRF_PSEL(UART_RTS, 0, 5)>,
                 <NRF_PSEL(UART_CTS, 0, 7)>;
         low-power-enable;
      };
   };
};

&uart1 {
   current-speed = <1000000>;
   pinctrl-0 = <&uart1_default_alt>;
   pinctrl-1 = <&uart1_sleep_alt>;
   pinctrl-names = "default", "sleep";
};