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

The Secure Device Firmware Update (DFU) Service exposes necessary information to perform Device Firmware Updates on the device. This service is a proprietary service defined by Nordic Semiconductor to demonstrate a typical Device Firmware Update on an nRF5 device.

The UUID for the Secure DFU Service is 0xFE59. The service must be instantiated as a primary service.

The DFU Service does not depend on any other services. Support for the following GATT sub-procedures is mandatory for this service:

- Write Characteristic Value
- Write Characteristic Descriptor
- Read Characteristic Descriptor
- Notification

The DFU Service does not define any new error codes for the Attribute Protocol. Data exchange is in little endian (LSB first) order.

See DFU BLE Service for the API documentation.

# Service characteristics

The following characteristics are mandatory:

Characteristic name | Required properties | Optional properties | UUID
--- | --- | --- | ---
DFU Control Point | Write, Notify |  | 0x8EC90001-F315-4F60-9FB8-838830DAEA50
DFU Packet | WriteWithoutResponse, Notify |  | 0x8EC90002-F315-4F60-9FB8-838830DAEA50

The service does not impose any security requirements, which mean that encryption is not mandatory for any characteristics of the service. However, encryption should be used if available.

# DFU Control Point

The UUID of the DFU Control Point characteristic is 0x0001.

The DFU Control Point characteristic is used to control the state of the DFU process. All DFU procedures are requested by writing to this characteristic. A response that marks the end of the procedure is received as a notification.

The following table shows control point procedure operation codes and the respective parameters and response values:

Opcode | Procedure | Description | Parameters | Response value
--- | --- | --- | --- | ---
0x01 | Create | Creates an object with the given type and selects it. Removes an old object of the same type (if such an object exists). | Type (uint8_t), Size (uint32) Types: 0x01 - Command object 0x02 - Data object (firmware) Size: Object size in little endian |
0x02 | Set Packet Receipt Notification (PRN) value | Sets the number of packets to be sent before receiving a Packet Receipt Notification. The default is 0. | Value (uint16, little endian) |
0x03 | Calculate checksum | Requests the checksum of the object that was sent (applicable only for data objects). The checksum is reset after sending an Execute command. | None | Offset (uint32), CRC32 (uint32)
0x04 | Execute | Executes the last object that was sent. | None |
0x06 | Select | Selects the last object with the given type that was sent. | Type (uint8_t) Types: 0x01 - Command object 0x02 - Data object (firmware) | Maximum size (uint32), offset (uint32), CRC32 (uint32)
0x60 | Response Code |  | Request opcode, result code |

The following table lists the result codes that are sent as part of the response:

Result code | Definition | Description
--- | --- | ---
0x00 | Invalid code | The provided opcode was missing or malformed.
0x01 | Success | The operation completed successfully.
0x02 | Opcode not supported | The provided opcode was invalid.
0x03 | Invalid parameter | A parameter for the opcode was missing.
0x04 | Insufficient resources | There was not enough memory for the data object.
0x05 | Invalid object | The data object did not match the firmware and hardware requirements, the signature was missing, or parsing the command failed.
0x07 | Unsupported type | The provided object type was not valid for a Create or Read operation.
0x08 | Operation not permitted | The state of the DFU process did not allow this operation.
0x0A | Operation failed | The operation failed.

# DFU Packet

The UUID of the DFU Packet characteristic is 0x0002. This characteristic receives data for Device Firmware Updates as DFU packets.

The maximum size of each packet is 20 bytes. Packets must be in little endian (LSB first) order.

# Message sequence charts

The following message sequence charts show the transfer of an init packet and a firmware image, respectively.

## Transfer of an init packet

The DFU controller first checks if the init packet has already been transferred successfully. If not, the DFU controller checks if it has been transferred partially. If some data has been transferred already, the transfer is continued. Otherwise, the DFU controller sends a Create command to create a new data object and then transfers the init packet. When the init packet is available, the DFU controller issues an Execute command to initiate the validation of the init packet.

## Transfer of a firmware image

A firmware image is split up into several data objects that are transferred consecutively. If the transfer of a data object fails (for example, because of a power loss), the transfer can be continued instead of restarted. Therefore, the DFU controller starts by selecting the last data object that was sent and checks if it is complete and valid. If it is, the controller issues an Execute command and then continues the transfer with the next data object. Otherwise, the DFU controller sends a Create command to create a new data object if required (thus if the transfer for this data object has not started yet or the received data is corrupted) and then transfers the next data object.

When all packets are transferred, the DFU controller issues an Execute command to trigger the actual firmware update.

The DFU controller is responsible for keeping track of the progress. The response to each Select command contains information about the maximum object size, the current offset, and the CRC. For example, if the image size is 10 kB and the maximum object size is 4 kB, 3 data objects must be transferred. If the returned offset is 6 kB, the DFU controller knows that the current object is the second object to transfer and that is has not been transferred completely.

# Data reliability

The BLE DFU Service is designed to handle serialized objects. However, transmitting and verifying serialized data is abstracted and not visible outside of the BLE transport layer.

To ensure that all data packets are received even though they are transmitted using WriteWithoutResponse, the DFU controller must perform a cyclic redundancy check (CRC) to validate the object before issuing an Execute command.