nRF5 SDK v17.1.0
DFU protocol

The DFU process is designed to be transport agnostic, as long as a reliable transport layer is used. The DFU transport module defines a generic interface that must be implemented for each transport layer. Currently, the DFU transport module supports BLE, UART, and USB CDC transport.

To register a transport layer, call the macro DFU_TRANSPORT_REGISTER with a nrf_dfu_transport_t registration structure as parameter. When nrf_dfu_transports_init is called, all registered transport layers are initialized with their respective init functions (as defined in nrf_dfu_transport_t::init_func).

The transport layer implementation is responsible for forwarding DFU requests to the application by calling nrf_dfu_req_handler_on_req. This function takes a request of type nrf_dfu_request_t and returns a response of type nrf_dfu_response_t, along with a response code of type nrf_dfu_result_t.

The following table shows the types of request (see nrf_dfu_request_t::request) and responses (see nrf_dfu_response_t):

Request Opcode Type Parameters Response parameters
Protocol version 0x00 NRF_DFU_OP_PROTOCOL_VERSION None Version
Create 0x01 NRF_DFU_OP_OBJECT_CREATE Object type
Object size
None
Set receipt notification 0x02 NRF_DFU_OP_RECEIPT_NOTIF_SET Target value
None
CRC 0x03 NRF_DFU_OP_CRC_GET None Offset
CRC
Execute 0x04 NRF_DFU_OP_OBJECT_EXECUTE None None
Select 0x06 NRF_DFU_OP_OBJECT_SELECT Object type Offset
CRC
Maximum object size
MTU Get 0x07 NRF_DFU_OP_MTU_GET None Size
Write 0x08 NRF_DFU_OP_OBJECT_WRITE Request payload
The length of the payload must be word-aligned.
None or CRC Response
Ping 0x09 NRF_DFU_OP_PING ID
ID
HW Version Get 0x0A NRF_DFU_OP_HARDWARE_VERSION None Part
Variant nrf_dfu_response_hardware_t::memory "ROM size" nrf_dfu_response_hardware_t::memory "ROM page size" nrf_dfu_response_hardware_t::memory "RAM size"
FW Version Get 0x0B NRF_DFU_OP_FIRMWARE_VERSION Image number Type
Version Start address Size
Abort 0x0C NRF_DFU_OP_ABORT None None

Requests

When calling nrf_dfu_req_handler_on_req to submit a request, a result code of type nrf_dfu_result_t is returned. When the DFU request was handled successfully, the result code is NRF_DFU_RES_CODE_SUCCESS. Possible error codes depend on the kind of request; see the following sections for more information. If several errors occur, only one error code is returned.

Protocol Version

Syntax and ID of this command is permanent. If protocol version changes other opcode may not be valid any more.

Note
This command is optional (NRF_DFU_PROTOCOL_VERSION_MSG).

Create request

The Create request triggers the creation of an object of the specified type. Valid types are a command object (for example, an init packet) or a data object.

A Create request requires the following actions on the DFU target:

If any of these operations fail, one of the following error codes must be returned:

Error condition Response code
The specified object type is not supported. NRF_DFU_RES_CODE_UNSUPPORTED_TYPE
The specified size is zero. NRF_DFU_RES_CODE_INVALID_PARAMETER
The specified size for a data object is not page aligned, and it is not the last object. NRF_DFU_RES_CODE_INVALID_PARAMETER
The DFU target cannot accept an object of the specified size. NRF_DFU_RES_CODE_INSUFFICIENT_RESOURCES
The current state of the transfer does not permit creating an object of the given size and type. NRF_DFU_RES_CODE_OPERATION_NOT_PERMITTED
The progress cannot be reset. NRF_DFU_RES_CODE_OPERATION_FAILED

Set receipt notification

This request configures the frequency of sending CRC responses after Write request commands. If set to 0, then the CRC response is never sent after Write request. Otherwise, it is sent every n'th Write request, where n is nrf_dfu_request_prn_t::target.

CRC request

The CRC request triggers a report of the offset and CRC of the transferred data of the current object. The DFU controller must regularly check these values to ensure that the data is transferred correctly.

If the operation fails, the following error code must be returned:

Error condition Response code
The object type of the currently selected object is invalid. NRF_DFU_RES_CODE_INVALID_OBJECT

Execute request

The Execute request should be submitted after an object has been written completely. The triggered actions depend on the type of the object that was transferred. When all objects of the firmware image have been transferred, postvalidation is called. If postvalidation is successful, it triggers the activation of the received firmware image.

If any of the operations fail, one of the following error codes must be returned:

Error condition Response code
The object type of the currently selected object is invalid. NRF_DFU_RES_CODE_INVALID_OBJECT
The current state of the transfer does not permit executing the current object. NRF_DFU_RES_CODE_OPERATION_NOT_PERMITTED

Select request

The Select request triggers the last transferred object of the specified object type to be selected, thus to be made the currently active object. It also requests information about the object (the maximum size, the current offset, and the current CRC). If there is no valid object of that type, the object type is still selected. In this case, the returned CRC and offset are zero.

MTU Get request

Transport returns the preferred MTU size on this request.

Write request

The Write request triggers storing the received data on the device. How the data is written depends on the type of the currently selected object.

After storing the received data, the DFU target must calculate the new CRC and offset. It may respond with a CRC response (see Set receipt notification).

If any of the operations fail, one of the following error codes must be returned:

Error condition Response code
The object type of the currently selected object is invalid. NRF_DFU_RES_CODE_INVALID_OBJECT
The current state of the transfer does not permit writing to the current object. NRF_DFU_RES_CODE_OPERATION_NOT_PERMITTED
The specified size is zero. NRF_DFU_RES_CODE_INVALID_PARAMETER
The specified size is too large. NRF_DFU_RES_CODE_INVALID_PARAMETER

Ping

The DFU target responds with the same ID value as received in the Ping request.

Hardware version

The DFU target responds with a message containing hardware version details.

Firmware version

The DFU target responds with a message containing type and version of the requested firmware. Firmware is identified by the ID.

Firmware ID
Bootloader 0
SoftDevice 1
Application 2 (1 if SoftDevice not present)

If firmware with the given ID does not exist, the response contains type NRF_DFU_FIRMWARE_TYPE_UNKNOWN.

Note
This command is optional (NRF_DFU_PROTOCOL_FW_VERSION_MSG).

Abort

Aborts the current DFU process. The bootloader resets on that message.

Transport layers

The following transport layers are available:


Documentation feedback | Developer Zone | Subscribe | Updated