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.
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.
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 |
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 |
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:
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 |
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 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.
The following transport layer is available: