| nRF5 SDK v12.0.0 |

Choose documentation: | nRF5 SDK | S130 SoftDevice API | S132 SoftDevice API | S212 SoftDevice API | S332 SoftDevice API

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
DFU transport

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 only available transport layer is BLE.

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_req_op_t and returns a response of type nrf_dfu_res_t, along with a response code of type nrf_dfu_res_code_t.

The following table shows the types of request (see nrf_dfu_req_t::req_type) and responses (see nrf_dfu_res_t):

Request | Opcode | Type | Parameters | Response parameters
--- | --- | --- | --- | ---
Create | 0x01 | NRF_DFU_OBJECT_OP_CREATE | Object type Object size | None
Write | 0x02 | NRF_DFU_OBJECT_OP_WRITE | Request Request length | Offset CRC
Execute | 0x03 | NRF_DFU_OBJECT_OP_EXECUTE | None | None
CRC | 0x04 | NRF_DFU_OBJECT_OP_CRC | None | Offset CRC
Select | 0x06 | NRF_DFU_OBJECT_OP_SELECT | Object type | Offset CRC Maximum object size

The data transfer is handled differently for each transport. Some transports require the data to be split into smaller packets. Some require a termination signal to indicate that the transfer is finished. Because of these differences, the DFU controller must keep track of the amount of data that has been transferred. Based on the returned offset and CRC it can determine whether the data has been transferred completely and when it can send the Execute request.

# Requests

When calling nrf_dfu_req_handler_on_req to submit a request, a result code of type nrf_dfu_res_code_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.

## 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:

- Reserve space for an object
- Reset the progress since the last Execute command
- Select the new object

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

## 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 and return it.

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

## 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.
- Command objects are treated differently by each transport. Therefore, actions and return codes for executing command objects are defined by the implementation.

If any of the operations fail, either an implementation-specific error code or 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

## 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

## 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.

# Transport layers

The following transport layer is available:

- BLE