Nordic Semiconductor / nrf51-sdk

Nordic nrf51 sdk sources. Mirrored from https://github.com/ARMmbed/nrf51-sdk.

Dependents:   nRF51822 nRF51822

source/nordic_sdk/components/ble/ble_services/ble_dfu/ble_dfu.h@28:041dac1366b2, 2016-04-07 (annotated)

Committer:
vcoubard
Date:
Thu Apr 07 17:37:56 2016 +0100
Revision:
28:041dac1366b2
Parent:
27:0fe148f1bca3
Child:
29:286940b7ee5a
Synchronized with git rev 012b8118

Author: Liyou Zhou

Pull in files from sdk 10.0

Who changed what in which revision?

UserRevisionLine numberNew contents of line
vcoubard 28:041dac1366b2 1 /* Copyright (c) 2013 Nordic Semiconductor. All Rights Reserved.
vcoubard 28:041dac1366b2 2 *
vcoubard 28:041dac1366b2 3 * The information contained herein is property of Nordic Semiconductor ASA.
vcoubard 28:041dac1366b2 4 * Terms and conditions of usage are described in detail in NORDIC
vcoubard 28:041dac1366b2 5 * SEMICONDUCTOR STANDARD SOFTWARE LICENSE AGREEMENT.
vcoubard 28:041dac1366b2 6 *
vcoubard 28:041dac1366b2 7 * Licensees are granted free, non-transferable use of the information. NO
vcoubard 28:041dac1366b2 8 * WARRANTY of ANY KIND is provided. This heading must NOT be removed from
vcoubard 28:041dac1366b2 9 * the file.
vcoubard 28:041dac1366b2 10 *
Vincent Coubard 0:f2542974c862 11 */
Vincent Coubard 0:f2542974c862 12
Vincent Coubard 0:f2542974c862 13 /**@file
Vincent Coubard 0:f2542974c862 14 *
Vincent Coubard 0:f2542974c862 15 * @defgroup ble_sdk_srv_dfu Device Firmware Update Service
Vincent Coubard 0:f2542974c862 16 * @{
Vincent Coubard 0:f2542974c862 17 * @ingroup ble_sdk_srv
Vincent Coubard 0:f2542974c862 18 * @brief Device Firmware Update Service
Vincent Coubard 0:f2542974c862 19 *
Vincent Coubard 0:f2542974c862 20 * @details The Device Firmware Update (DFU) service is a GATT based service that can be used for
Vincent Coubard 0:f2542974c862 21 * performing firmware updates over BLE. Note that this implementation uses vendor
Vincent Coubard 0:f2542974c862 22 * specific UUIDs for service and characteristics and is intended to demonstrate the
vcoubard 1:ebc0e0ef0a11 23 * firmware updates over BLE. Refer @ref bledfu_transport_bleservice and @ref
vcoubard 1:ebc0e0ef0a11 24 * bledfu_transport_bleprofile for more information on the service and profile respectively.
Vincent Coubard 0:f2542974c862 25 */
Vincent Coubard 0:f2542974c862 26
Vincent Coubard 0:f2542974c862 27 #ifndef BLE_DFU_H__
Vincent Coubard 0:f2542974c862 28 #define BLE_DFU_H__
Vincent Coubard 0:f2542974c862 29
Vincent Coubard 0:f2542974c862 30 #include <stdint.h>
Vincent Coubard 0:f2542974c862 31 #include "ble_gatts.h"
Vincent Coubard 0:f2542974c862 32 #include "ble_gap.h"
Vincent Coubard 0:f2542974c862 33 #include "ble.h"
Vincent Coubard 0:f2542974c862 34 #include "ble_srv_common.h"
Vincent Coubard 0:f2542974c862 35
Vincent Coubard 0:f2542974c862 36 #define BLE_DFU_SERVICE_UUID 0x1530 /**< The UUID of the DFU Service. */
Vincent Coubard 0:f2542974c862 37 #define BLE_DFU_PKT_CHAR_UUID 0x1532 /**< The UUID of the DFU Packet Characteristic. */
Vincent Coubard 0:f2542974c862 38 #define BLE_DFU_CTRL_PT_UUID 0x1531 /**< The UUID of the DFU Control Point. */
Vincent Coubard 0:f2542974c862 39 #define BLE_DFU_STATUS_REP_UUID 0x1533 /**< The UUID of the DFU Status Report Characteristic. */
Vincent Coubard 0:f2542974c862 40 #define BLE_DFU_REV_CHAR_UUID 0x1534 /**< The UUID of the DFU Revision Characteristic. */
Vincent Coubard 0:f2542974c862 41
Vincent Coubard 0:f2542974c862 42 /**@brief DFU Event type.
Vincent Coubard 0:f2542974c862 43 *
Vincent Coubard 0:f2542974c862 44 * @details This enumeration contains the types of events that will be received from the DFU Service.
Vincent Coubard 0:f2542974c862 45 */
Vincent Coubard 0:f2542974c862 46 typedef enum
Vincent Coubard 0:f2542974c862 47 {
Vincent Coubard 0:f2542974c862 48 BLE_DFU_START, /**< The event indicating that the peer wants the application to prepare for a new firmware update. */
Vincent Coubard 0:f2542974c862 49 BLE_DFU_RECEIVE_INIT_DATA, /**< The event indicating that the peer wants the application to prepare to receive init parameters. */
Vincent Coubard 0:f2542974c862 50 BLE_DFU_RECEIVE_APP_DATA, /**< The event indicating that the peer wants the application to prepare to receive the new firmware image. */
Vincent Coubard 0:f2542974c862 51 BLE_DFU_VALIDATE, /**< The event indicating that the peer wants the application to validate the newly received firmware image. */
Vincent Coubard 0:f2542974c862 52 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 */
Vincent Coubard 0:f2542974c862 53 BLE_DFU_SYS_RESET, /**< The event indicating that the peer wants the application to undergo a reset and start the currently valid application image.*/
Vincent Coubard 0:f2542974c862 54 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 @ref ble_dfu_pkts_rcpt_notify each time the number of packets indicated by num_of_pkts field in @ref ble_dfu_evt_t is received.*/
Vincent Coubard 0:f2542974c862 55 BLE_DFU_PKT_RCPT_NOTIF_DISABLED, /**< The event indicating that the peer has disabled the packet receipt notifications.*/
Vincent Coubard 0:f2542974c862 56 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 @ref BLE_DFU_PACKET_WRITE element contained within @ref ble_dfu_evt_t.*/
Vincent Coubard 0:f2542974c862 57 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 @ref ble_dfu_pkts_rcpt_notify in response to this event. */
Vincent Coubard 0:f2542974c862 58 } ble_dfu_evt_type_t;
Vincent Coubard 0:f2542974c862 59
Vincent Coubard 0:f2542974c862 60 /**@brief DFU Procedure type.
Vincent Coubard 0:f2542974c862 61 *
Vincent Coubard 0:f2542974c862 62 * @details This enumeration contains the types of DFU procedures.
Vincent Coubard 0:f2542974c862 63 */
Vincent Coubard 0:f2542974c862 64 typedef enum
Vincent Coubard 0:f2542974c862 65 {
Vincent Coubard 0:f2542974c862 66 BLE_DFU_START_PROCEDURE = 1, /**< DFU Start procedure.*/
Vincent Coubard 0:f2542974c862 67 BLE_DFU_INIT_PROCEDURE = 2, /**< DFU Initialization procedure.*/
Vincent Coubard 0:f2542974c862 68 BLE_DFU_RECEIVE_APP_PROCEDURE = 3, /**< Firmware receiving procedure.*/
Vincent Coubard 0:f2542974c862 69 BLE_DFU_VALIDATE_PROCEDURE = 4, /**< Firmware image validation procedure .*/
Vincent Coubard 0:f2542974c862 70 BLE_DFU_PKT_RCPT_REQ_PROCEDURE = 8 /**< Packet receipt notification request procedure. */
Vincent Coubard 0:f2542974c862 71 } ble_dfu_procedure_t;
Vincent Coubard 0:f2542974c862 72
Vincent Coubard 0:f2542974c862 73 /**@brief DFU Response value type.
Vincent Coubard 0:f2542974c862 74 */
Vincent Coubard 0:f2542974c862 75 typedef enum
Vincent Coubard 0:f2542974c862 76 {
Vincent Coubard 0:f2542974c862 77 BLE_DFU_RESP_VAL_SUCCESS = 1, /**< Success.*/
Vincent Coubard 0:f2542974c862 78 BLE_DFU_RESP_VAL_INVALID_STATE, /**< Invalid state.*/
Vincent Coubard 0:f2542974c862 79 BLE_DFU_RESP_VAL_NOT_SUPPORTED, /**< Operation not supported.*/
Vincent Coubard 0:f2542974c862 80 BLE_DFU_RESP_VAL_DATA_SIZE, /**< Data size exceeds limit.*/
Vincent Coubard 0:f2542974c862 81 BLE_DFU_RESP_VAL_CRC_ERROR, /**< CRC Error.*/
Vincent Coubard 0:f2542974c862 82 BLE_DFU_RESP_VAL_OPER_FAILED /**< Operation failed.*/
Vincent Coubard 0:f2542974c862 83 } ble_dfu_resp_val_t;
Vincent Coubard 0:f2542974c862 84
Vincent Coubard 0:f2542974c862 85
Vincent Coubard 0:f2542974c862 86 /**@brief DFU Packet structure.
Vincent Coubard 0:f2542974c862 87 *
Vincent Coubard 0:f2542974c862 88 * @details This structure contains the value of the DFU Packet characteristic as written by the
Vincent Coubard 0:f2542974c862 89 * peer and the length of the value written. It will be filled by the DFU Service when the
Vincent Coubard 0:f2542974c862 90 * peer writes to the DFU Packet characteristic.
Vincent Coubard 0:f2542974c862 91 */
Vincent Coubard 0:f2542974c862 92 typedef struct
Vincent Coubard 0:f2542974c862 93 {
vcoubard 28:041dac1366b2 94 uint8_t * p_data; /**< Pointer to the received packet. This will point to a word aligned memory location.*/
vcoubard 27:0fe148f1bca3 95 uint8_t len; /**< Length of the packet received. */
Vincent Coubard 0:f2542974c862 96 } ble_dfu_pkt_write_t;
Vincent Coubard 0:f2542974c862 97
Vincent Coubard 0:f2542974c862 98 /**@brief Packet receipt notification request structure.
Vincent Coubard 0:f2542974c862 99 *
Vincent Coubard 0:f2542974c862 100 * @details This structure contains the contents of the packet receipt notification request
Vincent Coubard 0:f2542974c862 101 * sent by the DFU Controller.
Vincent Coubard 0:f2542974c862 102 */
Vincent Coubard 0:f2542974c862 103 typedef struct
Vincent Coubard 0:f2542974c862 104 {
Vincent Coubard 0:f2542974c862 105 uint16_t num_of_pkts; /**< The number of packets of firmware data to be received by application before sending the next Packet Receipt Notification to the peer. */
Vincent Coubard 0:f2542974c862 106 } ble_pkt_rcpt_notif_req_t;
Vincent Coubard 0:f2542974c862 107
Vincent Coubard 0:f2542974c862 108 /**@brief DFU Event structure.
Vincent Coubard 0:f2542974c862 109 *
Vincent Coubard 0:f2542974c862 110 * @details This structure contains the event generated by the DFU Service based on the data
Vincent Coubard 0:f2542974c862 111 * received from the peer.
Vincent Coubard 0:f2542974c862 112 */
Vincent Coubard 0:f2542974c862 113 typedef struct
Vincent Coubard 0:f2542974c862 114 {
Vincent Coubard 0:f2542974c862 115 ble_dfu_evt_type_t ble_dfu_evt_type; /**< Type of the event.*/
Vincent Coubard 0:f2542974c862 116 union
Vincent Coubard 0:f2542974c862 117 {
Vincent Coubard 0:f2542974c862 118 ble_dfu_pkt_write_t ble_dfu_pkt_write; /**< The DFU packet received. This field is when the @ref ble_dfu_evt_type field is set to @ref BLE_DFU_PACKET_WRITE.*/
Vincent Coubard 0:f2542974c862 119 ble_pkt_rcpt_notif_req_t pkt_rcpt_notif_req; /**< Packet receipt notification request. This field is when the @ref ble_dfu_evt_type field is set to @ref BLE_DFU_PKT_RCPT_NOTIF_ENABLED.*/
Vincent Coubard 0:f2542974c862 120 } evt;
Vincent Coubard 0:f2542974c862 121 } ble_dfu_evt_t;
Vincent Coubard 0:f2542974c862 122
Vincent Coubard 0:f2542974c862 123 // Forward declaration of the ble_dfu_t type.
Vincent Coubard 0:f2542974c862 124 typedef struct ble_dfu_s ble_dfu_t;
Vincent Coubard 0:f2542974c862 125
Vincent Coubard 0:f2542974c862 126 /**@brief DFU Service event handler type. */
Vincent Coubard 0:f2542974c862 127 typedef void (*ble_dfu_evt_handler_t) (ble_dfu_t * p_dfu, ble_dfu_evt_t * p_evt);
Vincent Coubard 0:f2542974c862 128
Vincent Coubard 0:f2542974c862 129 /**@brief DFU service structure.
Vincent Coubard 0:f2542974c862 130 *
Vincent Coubard 0:f2542974c862 131 * @details This structure contains status information related to the service.
Vincent Coubard 0:f2542974c862 132 */
Vincent Coubard 0:f2542974c862 133 struct ble_dfu_s
Vincent Coubard 0:f2542974c862 134 {
Vincent Coubard 0:f2542974c862 135 uint16_t conn_handle; /**< Handle of the current connection (as provided by the S110 SoftDevice). This will be BLE_CONN_HANDLE_INVALID when not in a connection. */
Vincent Coubard 0:f2542974c862 136 uint16_t revision; /**< Handle of DFU Service (as provided by the S110 SoftDevice). */
Vincent Coubard 0:f2542974c862 137 uint16_t service_handle; /**< Handle of DFU Service (as provided by the S110 SoftDevice). */
Vincent Coubard 0:f2542974c862 138 uint8_t uuid_type; /**< UUID type assigned for DFU Service by the S110 SoftDevice. */
Vincent Coubard 0:f2542974c862 139 ble_gatts_char_handles_t dfu_pkt_handles; /**< Handles related to the DFU Packet characteristic. */
Vincent Coubard 0:f2542974c862 140 ble_gatts_char_handles_t dfu_ctrl_pt_handles; /**< Handles related to the DFU Control Point characteristic. */
Vincent Coubard 0:f2542974c862 141 ble_gatts_char_handles_t dfu_status_rep_handles; /**< Handles related to the DFU Status Report characteristic. */
Vincent Coubard 0:f2542974c862 142 ble_gatts_char_handles_t dfu_rev_handles; /**< Handles related to the DFU Revision characteristic. */
Vincent Coubard 0:f2542974c862 143 ble_dfu_evt_handler_t evt_handler; /**< The event handler to be called when an event is to be sent to the application.*/
Vincent Coubard 0:f2542974c862 144 ble_srv_error_handler_t error_handler; /**< Function to be called in case of an error. */
Vincent Coubard 0:f2542974c862 145 };
Vincent Coubard 0:f2542974c862 146
Vincent Coubard 0:f2542974c862 147 /**@brief DFU service initialization structure.
Vincent Coubard 0:f2542974c862 148 *
Vincent Coubard 0:f2542974c862 149 * @details This structure contains the initialization information for the DFU Service. The
Vincent Coubard 0:f2542974c862 150 * application needs to fill this structure and pass it to the DFU Service using the
Vincent Coubard 0:f2542974c862 151 * @ref ble_dfu_init function.
Vincent Coubard 0:f2542974c862 152 */
Vincent Coubard 0:f2542974c862 153 typedef struct
Vincent Coubard 0:f2542974c862 154 {
Vincent Coubard 0:f2542974c862 155 uint16_t revision; /**< Revision number to be exposed by the DFU service. */
Vincent Coubard 0:f2542974c862 156 ble_dfu_evt_handler_t evt_handler; /**< Event handler to be called for handling events in the Device Firmware Update Service. */
Vincent Coubard 0:f2542974c862 157 ble_srv_error_handler_t error_handler; /**< Function to be called in case of an error. */
Vincent Coubard 0:f2542974c862 158 } ble_dfu_init_t;
Vincent Coubard 0:f2542974c862 159
Vincent Coubard 0:f2542974c862 160 /**@brief Function for handling a BLE event.
Vincent Coubard 0:f2542974c862 161 *
Vincent Coubard 0:f2542974c862 162 * @details The DFU service expects the application to call this function each time an event
Vincent Coubard 0:f2542974c862 163 * is received from the S110 SoftDevice. This function processes the event, if it is
Vincent Coubard 0:f2542974c862 164 * relevant for the DFU service and calls the DFU event handler of the application if
Vincent Coubard 0:f2542974c862 165 * necessary.
Vincent Coubard 0:f2542974c862 166 *
Vincent Coubard 0:f2542974c862 167 * @param[in] p_dfu Pointer to the DFU service structure.
Vincent Coubard 0:f2542974c862 168 * @param[in] p_ble_evt Pointer to the event received from S110 SoftDevice.
Vincent Coubard 0:f2542974c862 169 */
Vincent Coubard 0:f2542974c862 170 void ble_dfu_on_ble_evt(ble_dfu_t * p_dfu, ble_evt_t * p_ble_evt);
Vincent Coubard 0:f2542974c862 171
Vincent Coubard 0:f2542974c862 172 /**@brief Function for initializing the DFU service.
Vincent Coubard 0:f2542974c862 173 *
Vincent Coubard 0:f2542974c862 174 * @param[out] p_dfu Device Firmware Update service structure. This structure will have to be
Vincent Coubard 0:f2542974c862 175 * supplied by the application. It will be initialized by this function,
Vincent Coubard 0:f2542974c862 176 * and will later be used to identify the service instance.
Vincent Coubard 0:f2542974c862 177 * @param[in] p_dfu_init Information needed to initialize the service.
Vincent Coubard 0:f2542974c862 178 *
Vincent Coubard 0:f2542974c862 179 * @return NRF_SUCCESS if the DFU service and its characteristics were successfully added to the
Vincent Coubard 0:f2542974c862 180 * S110 SoftDevice. Otherwise an error code.
Vincent Coubard 0:f2542974c862 181 * This function returns NRF_ERROR_NULL if the value of evt_handler in p_dfu_init
Vincent Coubard 0:f2542974c862 182 * structure provided is NULL or if the pointers supplied as input are NULL.
Vincent Coubard 0:f2542974c862 183 */
Vincent Coubard 0:f2542974c862 184 uint32_t ble_dfu_init(ble_dfu_t * p_dfu, ble_dfu_init_t * p_dfu_init);
Vincent Coubard 0:f2542974c862 185
Vincent Coubard 0:f2542974c862 186 /**@brief Function for sending response to a control point command.
Vincent Coubard 0:f2542974c862 187 *
Vincent Coubard 0:f2542974c862 188 * @details This function will encode a DFU Control Point response using the given input
Vincent Coubard 0:f2542974c862 189 * parameters and will send a notification of the same to the peer.
Vincent Coubard 0:f2542974c862 190 *
Vincent Coubard 0:f2542974c862 191 * @param[in] p_dfu Pointer to the DFU service structure.
Vincent Coubard 0:f2542974c862 192 * @param[in] dfu_proc Procedure for which this response is to be sent.
Vincent Coubard 0:f2542974c862 193 * @param[in] resp_val Response value.
Vincent Coubard 0:f2542974c862 194 *
Vincent Coubard 0:f2542974c862 195 * @return NRF_SUCCESS if the DFU Service has successfully requested the S110 SoftDevice to
Vincent Coubard 0:f2542974c862 196 * send the notification. Otherwise an error code.
Vincent Coubard 0:f2542974c862 197 * This function returns NRF_ERROR_INVALID_STATE if the device is not connected to a
Vincent Coubard 0:f2542974c862 198 * peer or if the DFU service is not initialized or if the notification of the DFU
Vincent Coubard 0:f2542974c862 199 * Status Report characteristic was not enabled by the peer. It returns NRF_ERROR_NULL
Vincent Coubard 0:f2542974c862 200 * if the pointer p_dfu is NULL.
Vincent Coubard 0:f2542974c862 201 */
Vincent Coubard 0:f2542974c862 202 uint32_t ble_dfu_response_send(ble_dfu_t * p_dfu,
Vincent Coubard 0:f2542974c862 203 ble_dfu_procedure_t dfu_proc,
Vincent Coubard 0:f2542974c862 204 ble_dfu_resp_val_t resp_val);
Vincent Coubard 0:f2542974c862 205
Vincent Coubard 0:f2542974c862 206 /**@brief Function for notifying the peer about the number of bytes of firmware data received.
Vincent Coubard 0:f2542974c862 207 *
Vincent Coubard 0:f2542974c862 208 * @param[in] p_dfu Pointer to the DFU service structure.
Vincent Coubard 0:f2542974c862 209 * @param[in] num_of_firmware_bytes_rcvd Number of bytes.
Vincent Coubard 0:f2542974c862 210 *
Vincent Coubard 0:f2542974c862 211 * @return NRF_SUCCESS if the DFU Service has successfully requested the S110 SoftDevice to send
Vincent Coubard 0:f2542974c862 212 * the notification. Otherwise an error code.
Vincent Coubard 0:f2542974c862 213 * This function returns NRF_ERROR_INVALID_STATE if the device is not connected to a
Vincent Coubard 0:f2542974c862 214 * peer or if the DFU service is not initialized or if the notification of the DFU
Vincent Coubard 0:f2542974c862 215 * Status Report characteristic was not enabled by the peer. It returns NRF_ERROR_NULL
Vincent Coubard 0:f2542974c862 216 * if the pointer p_dfu is NULL.
Vincent Coubard 0:f2542974c862 217 */
Vincent Coubard 0:f2542974c862 218 uint32_t ble_dfu_bytes_rcvd_report(ble_dfu_t * p_dfu, uint32_t num_of_firmware_bytes_rcvd);
Vincent Coubard 0:f2542974c862 219
Vincent Coubard 0:f2542974c862 220 /**@brief Function for sending Packet Receipt Notification to the peer.
Vincent Coubard 0:f2542974c862 221 *
Vincent Coubard 0:f2542974c862 222 * This function will encode the number of bytes received as input parameter into a
Vincent Coubard 0:f2542974c862 223 * notification of the control point characteristic and send it to the peer.
Vincent Coubard 0:f2542974c862 224 *
Vincent Coubard 0:f2542974c862 225 * @param[in] p_dfu Pointer to the DFU service structure.
Vincent Coubard 0:f2542974c862 226 * @param[in] num_of_firmware_bytes_rcvd Number of bytes of firmware image received.
Vincent Coubard 0:f2542974c862 227 *
Vincent Coubard 0:f2542974c862 228 * @return NRF_SUCCESS if the DFU Service has successfully requested the S110 SoftDevice to send
Vincent Coubard 0:f2542974c862 229 * the notification. Otherwise an error code.
Vincent Coubard 0:f2542974c862 230 * This function returns NRF_ERROR_INVALID_STATE if the device is not connected to a
Vincent Coubard 0:f2542974c862 231 * peer or if the DFU service is not initialized or if the notification of the DFU
Vincent Coubard 0:f2542974c862 232 * Status Report characteristic was not enabled by the peer. It returns NRF_ERROR_NULL
Vincent Coubard 0:f2542974c862 233 * if the pointer p_dfu is NULL.
Vincent Coubard 0:f2542974c862 234 */
Vincent Coubard 0:f2542974c862 235 uint32_t ble_dfu_pkts_rcpt_notify(ble_dfu_t * p_dfu, uint32_t num_of_firmware_bytes_rcvd);
Vincent Coubard 0:f2542974c862 236
Vincent Coubard 0:f2542974c862 237 #endif // BLE_DFU_H__
Vincent Coubard 0:f2542974c862 238
vcoubard 1:ebc0e0ef0a11 239 /** @} */