Serial Modem XDFU library

Note

This library is Experimental.

The Serial Modem XDFU library implements the host side of the AT#XDFU update sequence, so that a host MCU can update the nRF91 Series SiP that runs the Serial Modem application. This library is intended for applications running on an external MCU that use Zephyr’s modem_cellular driver to control the Serial Modem device over UART, for example, the PPP shell sample.

Overview

The Serial Modem XDFU library drives the full DFU exchange described in DFU AT commands on behalf of the application:

  • Sends AT#XDFUINIT, AT#XDFUWRITE, and AT#XDFUAPPLY for one of the following image types: application firmware, delta modem firmware, full modem firmware, or the MCUboot bootloader.

  • Streams the update file from a mounted file system to the Serial Modem device in chunks, using the modem_cellular driver’s UART pipe directly. This means the pipe must not be otherwise in use by the driver’s own chat scripts while the update runs.

  • For full modem firmware updates, decodes the CBOR-encoded update package (as produced for nRF Connect SDK full modem firmware updates) and writes each firmware segment to the address indicated in the package.

  • Resets the Serial Modem device with AT#XRESET after the update (except after a successful full modem firmware update, where the final AT#XDFUAPPLY already reboots the modem into the new firmware) and waits for it to become ready again.

The library exposes a single blocking call, sm_xdfu_run(), that runs the whole sequence for one file and returns only once the update has completed, failed, or timed out.

Configuration

Configure the following Kconfig option to enable the library:

  • CONFIG_SM_XDFU_LIB - Enables the Serial Modem XDFU library.

The library also depends on the following features, which must be enabled by the application:

  • CONFIG_MODEM_CELLULAR - Provides the modem device and UART pipe that the library attaches to.

  • CONFIG_FILE_SYSTEM - Provides access to the update file.

  • CONFIG_ZCBOR - Decodes the CBOR-encoded full modem firmware update package.

  • CONFIG_COMMON_LIBC_MALLOC - Provides dynamic memory for the library’s internal chat instance and CBOR metadata buffer.

Usage

Call sm_xdfu_run() with the modem_cellular-compatible device for the Serial Modem device, the image type to update, and the path to the update file on a mounted file system:

#include <sm_xdfu.h>

const struct device *modem = DEVICE_DT_GET_ONE(nordic_nrf91_sm_v2);

int ret = sm_xdfu_run(modem, SM_XDFU_TYPE_APP, "/lfs1/app_update.bin");

if (ret < 0) {
    /* Handle error, see sm_xdfu_run() return values */
}

Before calling sm_xdfu_run(), ensure that the modem device and its underlying UART are not in use, for example, by suspending networking on the modem_cellular device. The function returns -EBUSY if either is in use.

The PPP shell sample sample wraps this call in an xdfu shell command, see its source for a complete example, including how to report the different error codes in your application.

API documentation

Header file: include/sm_xdfu.h
Source file: lib/sm_xdfu/sm_xdfu.c
group Serial Modem XDFU library

Public APIs for the Serial Modem XDFU library.

Enums

enum sm_xdfu_image_type

Image type accepted by the modem’s AT#XDFU command.

Values:

enumerator SM_XDFU_TYPE_APP
enumerator SM_XDFU_TYPE_DELTA_MFW
enumerator SM_XDFU_TYPE_FULL_MFW
enumerator SM_XDFU_TYPE_MCUBOOT_BL

Functions

int sm_xdfu_run(const struct device *modem, enum sm_xdfu_image_type type, const char *file)

Run an AT#XDFU update on the given cellular modem.

Attach the modem’s UART pipe, transfers file to the modem using AT#XDFU commands, and resets the modem with AT#XRESET afterwards.

Parameters:

  • modem – Cellular modem device (compatible with the Zephyr modem_cellular driver).

  • type – Image type to update.

  • file – Path to the update file (for example, on a mounted filesystem).

Return values:

  • 0 – on success.

  • -EINVAL – Invalid type, or file is missing/empty.

  • -ENODEV – Modem or its UART device is not ready.

  • -EBUSY – Modem or its UART is currently in use.

  • -ETIMEDOUT – Timed out waiting for the modem to respond.

  • -EIO – Transfer or apply failed.