nRF51 SDK: Device Firmware Update Service

| nRF51 SDK

- Home
- Related Pages
- API Reference
- Data Structures

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Data Structures | Macros | Typedefs | Enumerations | Functions
Device Firmware Update Service
BLE Services

Device Firmware Update Service. More...

## Data Structures

struct | ble_dfu_pkt_write_t
| DFU Packet structure. More...
struct | ble_pkt_rcpt_notif_req_t
| Packet receipt notification request structure. More...
struct | ble_dfu_evt_t
| DFU Event structure. More...
struct | ble_dfu_s
| DFU service structure. More...
struct | ble_dfu_init_t
| DFU service initialization structure. More...

## Macros

#define | BLE_DFU_SERVICE_UUID 0x1530
#define | BLE_DFU_PKT_CHAR_UUID 0x1532
#define | BLE_DFU_CTRL_PT_UUID 0x1531
#define | BLE_DFU_STATUS_REP_UUID 0x1533

## Typedefs

typedef struct ble_dfu_s | ble_dfu_t
| DFU service structure. More...
typedef void(* | ble_dfu_evt_handler_t )(ble_dfu_t *p_dfu, ble_dfu_evt_t *p_evt)
| DFU Service event handler type.

## Enumerations

enum

ble_dfu_evt_type_t {
BLE_DFU_START, BLE_DFU_RECEIVE_INIT_DATA, BLE_DFU_RECEIVE_APP_DATA, BLE_DFU_VALIDATE,
BLE_DFU_ACTIVATE_N_RESET, BLE_DFU_SYS_RESET, BLE_DFU_PKT_RCPT_NOTIF_ENABLED, BLE_DFU_PKT_RCPT_NOTIF_DISABLED,
BLE_DFU_PACKET_WRITE, BLE_DFU_BYTES_RECEIVED_SEND
}

| DFU Event type. More...
enum | ble_dfu_procedure_t { BLE_DFU_START_PROCEDURE = 1, BLE_DFU_INIT_PROCEDURE = 2, BLE_DFU_RECEIVE_APP_PROCEDURE = 3, BLE_DFU_VALIDATE_PROCEDURE = 4, BLE_DFU_PKT_RCPT_REQ_PROCEDURE = 8 }
| DFU Procedure type. More...
enum | ble_dfu_resp_val_t { BLE_DFU_RESP_VAL_SUCCESS = 1, BLE_DFU_RESP_VAL_INVALID_STATE, BLE_DFU_RESP_VAL_NOT_SUPPORTED, BLE_DFU_RESP_VAL_DATA_SIZE, BLE_DFU_RESP_VAL_CRC_ERROR, BLE_DFU_RESP_VAL_OPER_FAILED }
| DFU Response value type. More...

## Functions

void | ble_dfu_on_ble_evt (ble_dfu_t *p_dfu, ble_evt_t *p_ble_evt)
| Function for handling a BLE event. More...
uint32_t | ble_dfu_init (ble_dfu_t *p_dfu, ble_dfu_init_t *p_dfu_init)
| Function for initializing the DFU service. More...
uint32_t | ble_dfu_response_send (ble_dfu_t *p_dfu, ble_dfu_procedure_t dfu_proc, ble_dfu_resp_val_t resp_val)
| Function for sending response to a control point command. More...
uint32_t | ble_dfu_bytes_rcvd_report (ble_dfu_t *p_dfu, uint32_t num_of_firmware_bytes_rcvd)
| Function for notifying the peer about the number of bytes of firmware data received. More...
uint32_t | ble_dfu_pkts_rcpt_notify (ble_dfu_t *p_dfu, uint32_t num_of_firmware_bytes_rcvd)
| Function for sending Packet Receipt Notification to the peer. More...

## Detailed Description

Device Firmware Update Service.

The Device Firmware Update (DFU) service is a GATT based service that can be used for performing firmware updates over BLE. Note that this implementation uses vendor specific UUIDs for service and characteristics and is intended to demonstrate the firmware updates over BLE. Refer dfu_ble_service_spec and dfu_ble_profile_spec for more information on the service and profile respectively.

## Macro Definition Documentation

#define BLE_DFU_CTRL_PT_UUID 0x1531

The UUID of the DFU Control Point.

#define BLE_DFU_PKT_CHAR_UUID 0x1532

The UUID of the DFU Packet Characteristic.

#define BLE_DFU_SERVICE_UUID 0x1530

The UUID of the DFU Service.

#define BLE_DFU_STATUS_REP_UUID 0x1533

The UUID of the DFU Status Report Characteristic.

## Typedef Documentation

typedef struct ble_dfu_s ble_dfu_t

DFU service structure.

This structure contains status information related to the service.

## Enumeration Type Documentation

enum ble_dfu_evt_type_t

DFU Event type.

This enumeration contains the types of events that will be received from the DFU Service.

Enumerator
BLE_DFU_START | The event indicating that the peer wants the application to prepare for a new firmware update.
BLE_DFU_RECEIVE_INIT_DATA | The event indicating that the peer wants the application to prepare to receive init parameters.
BLE_DFU_RECEIVE_APP_DATA | The event indicating that the peer wants the application to prepare to receive the new firmware image.
BLE_DFU_VALIDATE | The event indicating that the peer wants the application to validate the newly received firmware image.
BLE_DFU_ACTIVATE_N_RESET | The event indicating that the peer wants the application to undergo activate new firmware and restart with new valid application
BLE_DFU_SYS_RESET | The event indicating that the peer wants the application to undergo a reset and start the currently valid application image.
BLE_DFU_PKT_RCPT_NOTIF_ENABLED | The event indicating that the peer has enabled packet receipt notifications. It is the responsibility of the application to call ble_dfu_pkts_rcpt_notify each time the number of packets indicated by num_of_pkts field in ble_dfu_evt_t is received.
BLE_DFU_PKT_RCPT_NOTIF_DISABLED | The event indicating that the peer has disabled the packet receipt notifications.
BLE_DFU_PACKET_WRITE | The event indicating that the peer has written a value to the 'DFU Packet' characteristic. The data received from the peer will be present in the ble_dfu_pkt_write element contained within ble_dfu_evt_t.
BLE_DFU_BYTES_RECEIVED_SEND | The event indicating that the peer is requesting for the number of bytes of firmware data last received by the application. It is the responsibility of the application to call ble_dfu_pkts_rcpt_notify in response to this event.

enum ble_dfu_procedure_t

DFU Procedure type.

This enumeration contains the types of DFU procedures.

Enumerator
BLE_DFU_START_PROCEDURE | DFU Start procedure.
BLE_DFU_INIT_PROCEDURE | DFU Initialization procedure.
BLE_DFU_RECEIVE_APP_PROCEDURE | Firmware receiving procedure.
BLE_DFU_VALIDATE_PROCEDURE | Firmware image validation procedure .
BLE_DFU_PKT_RCPT_REQ_PROCEDURE | Packet receipt notification request procedure.

enum ble_dfu_resp_val_t

DFU Response value type.

Enumerator
BLE_DFU_RESP_VAL_SUCCESS | Success.
BLE_DFU_RESP_VAL_INVALID_STATE | Invalid state.
BLE_DFU_RESP_VAL_NOT_SUPPORTED | Operation not supported.
BLE_DFU_RESP_VAL_DATA_SIZE | Data size exceeds limit.
BLE_DFU_RESP_VAL_CRC_ERROR | CRC Error.
BLE_DFU_RESP_VAL_OPER_FAILED | Operation failed.

## Function Documentation

uint32_t ble_dfu_bytes_rcvd_report | ( | ble_dfu_t * | p_dfu,
|  | uint32_t | num_of_firmware_bytes_rcvd
| ) |  |

Function for notifying the peer about the number of bytes of firmware data received.

Parameters

  [in] | p_dfu | Pointer to the DFU service structure.
  [in] | num_of_firmware_bytes_rcvd | Number of bytes.

Returns
  NRF_SUCCESS if the DFU Service has successfully requested the S110 SoftDevice to send the notification. Otherwise an error code. This function returns NRF_ERROR_INVALID_STATE if the device is not connected to a peer or if the DFU service is not initialized or if the notification of the DFU Status Report characteristic was not enabled by the peer. It returns NRF_ERROR_NULL if the pointer p_dfu is NULL.

uint32_t ble_dfu_init | ( | ble_dfu_t * | p_dfu,
|  | ble_dfu_init_t * | p_dfu_init
| ) |  |

Function for initializing the DFU service.

Parameters

  [out] | p_dfu | Device Firmware Update service structure. This structure will have to be supplied by the application. It will be initialized by this function, and will later be used to identify the service instance.
  [in] | p_dfu_init | Information needed to initialize the service.

Returns
  NRF_SUCCESS if the DFU service and its characteristics were successfully added to the S110 SoftDevice. Otherwise an error code. This function returns NRF_ERROR_NULL if the value of evt_handler in p_dfu_init structure provided is NULL or if the pointers supplied as input are NULL.

void ble_dfu_on_ble_evt | ( | ble_dfu_t * | p_dfu,
|  | ble_evt_t * | p_ble_evt
| ) |  |

Function for handling a BLE event.

The DFU service expects the application to call this function each time an event is received from the S110 SoftDevice. This function processes the event, if it is relevant for the DFU service and calls the DFU event handler of the application if necessary.

Parameters

  [in] | p_dfu | Pointer to the DFU service structure.
  [in] | p_ble_evt | Pointer to the event received from S110 SoftDevice.

uint32_t ble_dfu_pkts_rcpt_notify | ( | ble_dfu_t * | p_dfu,
|  | uint32_t | num_of_firmware_bytes_rcvd
| ) |  |

Function for sending Packet Receipt Notification to the peer.

            This function will encode the number of bytes received as input parameter into a
            notification of the control point characteristic and send it to the peer.

Parameters

  [in] | p_dfu | Pointer to the DFU service structure.
  [in] | num_of_firmware_bytes_rcvd | Number of bytes of firmware image received.

Returns
  NRF_SUCCESS if the DFU Service has successfully requested the S110 SoftDevice to send the notification. Otherwise an error code. This function returns NRF_ERROR_INVALID_STATE if the device is not connected to a peer or if the DFU service is not initialized or if the notification of the DFU Status Report characteristic was not enabled by the peer. It returns NRF_ERROR_NULL if the pointer p_dfu is NULL.

uint32_t ble_dfu_response_send | ( | ble_dfu_t * | p_dfu,
|  | ble_dfu_procedure_t | dfu_proc,
|  | ble_dfu_resp_val_t | resp_val
| ) |  |

Function for sending response to a control point command.

This function will encode a DFU Control Point response using the given input parameters and will send a notification of the same to the peer.

Parameters

  [in] | p_dfu | Pointer to the DFU service structure.
  [in] | dfu_proc | Procedure for which this response is to be sent.
  [in] | resp_val | Response value.

Returns
  NRF_SUCCESS if the DFU Service has successfully requested the S110 SoftDevice to send the notification. Otherwise an error code. This function returns NRF_ERROR_INVALID_STATE if the device is not connected to a peer or if the DFU service is not initialized or if the notification of the DFU Status Report characteristic was not enabled by the peer. It returns NRF_ERROR_NULL if the pointer p_dfu is NULL.