Cellular: Modem trace external flash backend

This sample demonstrates how to add a modem trace backend that stores the trace data to external flash.

Requirements

The sample supports the following development kits:

Hardware platforms

PCA

Board name

Build target

nRF9161 DK

PCA10153

nrf9161dk_nrf9161

nrf9161dk_nrf9161_ns

nRF9160 DK

PCA10090

nrf9160dk_nrf9160

nrf9160dk_nrf9160_ns

nRF9151 DK

nrf9151dk_nrf9151

nrf9151dk_nrf9151_ns

For the nRF9160 DK, version 0.14.0 or higher is supported by the sample.

When built for an _ns build target, the sample is configured to compile and run as a non-secure application with Cortex-M Security Extensions enabled. Therefore, it automatically includes Trusted Firmware-M that prepares the required peripherals and secure services to be available for the application.

External flash

To use the external flash memory on the nRF9160 DK v0.14.0 or later versions, the board controller firmware must be of version v2.0.1. This is the factory firmware version. If you need to program the board controller firmware again, complete the following steps:

  1. Download the nRF9160 DK board controller firmware from the nRF9160 DK downloads page.

  2. Make sure the PROG/DEBUG SW10 switch on the nRF9160 DK is set to nRF52.

  3. Program the board controller firmware (nrf9160_dk_board_controller_fw_2.0.1.hex) using the Programmer app in nRF Connect for Desktop.

Note

The board controller firmware version must be v2.0.1 or higher, which enables the pin routing to external flash.

See Board controller for more details.

Overview

You can use this sample to implement storing and reading of modem traces on an external flash device. The sample contains an implementation of a custom trace backend that writes modem traces on the external flash chip of the nRF91 Series DK. In addition, it reads out the traces from the external flash and writes them out to UART1 on a button press.

You can use the sample for creating a trace backend for your own flash device. You can store a reduced set of modem traces using the CONFIG_NRF_MODEM_LIB_TRACE_LEVEL_CHOICE option. The sample starts storing modem traces when the backend is initialized by the Modem library integration layer library. However, you can also start storing the modem traces during runtime. Use the nrf_modem_lib_trace_level_set() function for enabling or disabling modem traces at runtime.

Write performance

A modem trace backend must be able to handle the trace data as fast as they are produced to avoid dropping traces. It is recommended to handle the trace data at approximately 1 Mbps.

The Macronix MX25R6435 Ultra Low Power Flash on the nRF9160 DK is optimized for low power consumption rather than write speed, but it features a high performance mode. The high-performance mode consumes more power but is able to erase and write at roughly double the speed. Use the device tree property mxicy,mx25r-power-mode to configure MX25R6435 in either high-performance or low-power mode. In this sample, the MX25R6435 is configured in high-performance mode.

The use of CONFIG_SPI_NOR_IDLE_IN_DPD option to enable deep-power-down mode significantly reduces the stand-by power consumption. However, it adds overhead for each SPI instruction, which causes an approximately 20% reduction in write performance.

The sample uses the Modem library to turn on and off the modem traces and also enable and disable the modem. In addition, it uses the Universal Asynchronous Receiver-Transmitter (UART) to send modem traces over UART1.

Flash space

The sample uses 1 MB (out of 8 MB) of the external flash. This is sufficient for the modem traces that are handled by this sample. Since the external flash area is erased during startup, the size of the flash used affects the startup time. Erasing 1 MB takes approximately 8 seconds in high performance mode. Erasing the whole flash (8 MB) takes approximately 1 minute in high performance mode.

User interface

Button 1:

Reads out the modem traces from external flash and sends it on UART 1.

Building and running

This sample can be found under samples/cellular/modem_trace_flash in the nRF Connect SDK folder structure.

When built as firmware image for the _ns build target, the sample has Cortex-M Security Extensions (CMSE) enabled and separates the firmware between Non-Secure Processing Environment (NSPE) and Secure Processing Environment (SPE). Because of this, it automatically includes the Trusted Firmware-M (TF-M). To read more about CMSE, see Processing environments.

To build the sample with Visual Studio Code, follow the steps listed on the How to build an application page in the nRF Connect for VS Code extension documentation. See Configuring and building an application for other building scenarios, Programming an application for programming steps, and Testing for general information about testing and debugging in the nRF Connect SDK.

Testing

After programming the sample to your development kit, complete the following steps to test it:

After programming the sample and board controller firmware (as mentioned in Requirements section) to your development kit, test it by performing the following steps:

  1. Connect the kit to the computer using a USB cable. The kit is assigned a COM port (Windows) or ttyACM device (Linux), which is visible in the Device Manager.

  2. Open the Cellular Monitor desktop application and connect the DK.

  3. Select Autoselect from the Modem trace database drop-down menu, or a modem firmware version that is programmed on the DK.

  4. Select Reset device on start.

  5. Make sure that either Open in Wireshark or Save trace file to disk is selected.

  6. Click Open Serial Terminal and keep the terminal window open (optional).

  7. Click Start to begin the modem trace. The button changes to Stop and is greyed out.

  8. When the console output Flushed modem traces to flash is received in Serial Terminal, press Button 1 on the development kit. If you are not using a serial terminal, you can approximately wait for one minute after clicking the Start button, and then press Button 1.

  9. Observe modem traces received on the Cellular Monitor desktop application.

Note

Since the external flash is erased at startup, there will be a few seconds of delay before the first console output is received from the sample.

Dependencies

It uses the following sdk-nrfxlib libraries:

It uses the following Zephyr libraries:

In addition, it uses the following secure firmware components: