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 |
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.
Syntax and ID of this command is permanent. If protocol version changes other opcode may not be valid any more.
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 |
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.
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 |
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 |
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 returns the preferred MTU size on this 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 |
The DFU target responds with the same ID value as received in the Ping request.
The DFU target responds with a message containing hardware version details.
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
.
Aborts the current DFU process. The bootloader resets on that message.
The following transport layers are available: