Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Fork of nRF51822 by
ble_dfu.h
00001 /* Copyright (c) 2013 Nordic Semiconductor. All Rights Reserved. 00002 * 00003 * The information contained herein is property of Nordic Semiconductor ASA. 00004 * Terms and conditions of usage are described in detail in NORDIC 00005 * SEMICONDUCTOR STANDARD SOFTWARE LICENSE AGREEMENT. 00006 * 00007 * Licensees are granted free, non-transferable use of the information. NO 00008 * WARRANTY of ANY KIND is provided. This heading must NOT be removed from 00009 * the file. 00010 * 00011 */ 00012 00013 /**@file 00014 * 00015 * @defgroup ble_sdk_srv_dfu Device Firmware Update Service 00016 * @{ 00017 * @ingroup ble_sdk_srv 00018 * @brief Device Firmware Update Service 00019 * 00020 * @details The Device Firmware Update (DFU) service is a GATT based service that can be used for 00021 * performing firmware updates over BLE. Note that this implementation uses vendor 00022 * specific UUIDs for service and characteristics and is intended to demonstrate the 00023 * firmware updates over BLE. Refer @ref dfu_ble_service_spec and @ref 00024 * dfu_ble_profile_spec for more information on the service and profile respectively. 00025 */ 00026 00027 #ifndef BLE_DFU_H__ 00028 #define BLE_DFU_H__ 00029 00030 #include <stdint.h> 00031 #include "ble_gatts.h" 00032 #include "ble.h" 00033 #include "ble_srv_common.h " 00034 00035 #define BLE_DFU_SERVICE_UUID 0x1530 /**< The UUID of the DFU Service. */ 00036 #define BLE_DFU_PKT_CHAR_UUID 0x1532 /**< The UUID of the DFU Packet Characteristic. */ 00037 #define BLE_DFU_CTRL_PT_UUID 0x1531 /**< The UUID of the DFU Control Point. */ 00038 #define BLE_DFU_STATUS_REP_UUID 0x1533 /**< The UUID of the DFU Status Report Characteristic. */ 00039 00040 00041 /**@brief DFU Event type. 00042 * 00043 * @details This enumeration contains the types of events that will be received from the DFU Service. 00044 */ 00045 typedef enum 00046 { 00047 BLE_DFU_START, /**< The event indicating that the peer wants the application to prepare for a new firmware update. */ 00048 BLE_DFU_RECEIVE_INIT_DATA, /**< The event indicating that the peer wants the application to prepare to receive init parameters. */ 00049 BLE_DFU_RECEIVE_APP_DATA, /**< The event indicating that the peer wants the application to prepare to receive the new firmware image. */ 00050 BLE_DFU_VALIDATE, /**< The event indicating that the peer wants the application to validate the newly received firmware image. */ 00051 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 */ 00052 BLE_DFU_SYS_RESET, /**< The event indicating that the peer wants the application to undergo a reset and start the currently valid application image.*/ 00053 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.*/ 00054 BLE_DFU_PKT_RCPT_NOTIF_DISABLED, /**< The event indicating that the peer has disabled the packet receipt notifications.*/ 00055 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_pkt_write element contained within @ref ble_dfu_evt_t.*/ 00056 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. */ 00057 } ble_dfu_evt_type_t; 00058 00059 /**@brief DFU Procedure type. 00060 * 00061 * @details This enumeration contains the types of DFU procedures. 00062 */ 00063 typedef enum 00064 { 00065 BLE_DFU_START_PROCEDURE = 1, /**< DFU Start procedure.*/ 00066 BLE_DFU_INIT_PROCEDURE = 2, /**< DFU Initialization procedure.*/ 00067 BLE_DFU_RECEIVE_APP_PROCEDURE = 3, /**< Firmware receiving procedure.*/ 00068 BLE_DFU_VALIDATE_PROCEDURE = 4, /**< Firmware image validation procedure .*/ 00069 BLE_DFU_PKT_RCPT_REQ_PROCEDURE = 8 /**< Packet receipt notification request procedure. */ 00070 } ble_dfu_procedure_t; 00071 00072 /**@brief DFU Response value type. 00073 */ 00074 typedef enum 00075 { 00076 BLE_DFU_RESP_VAL_SUCCESS = 1, /**< Success.*/ 00077 BLE_DFU_RESP_VAL_INVALID_STATE, /**< Invalid state.*/ 00078 BLE_DFU_RESP_VAL_NOT_SUPPORTED, /**< Operation not supported.*/ 00079 BLE_DFU_RESP_VAL_DATA_SIZE, /**< Data size exceeds limit.*/ 00080 BLE_DFU_RESP_VAL_CRC_ERROR, /**< CRC Error.*/ 00081 BLE_DFU_RESP_VAL_OPER_FAILED /**< Operation failed.*/ 00082 } ble_dfu_resp_val_t; 00083 00084 /**@brief DFU Packet structure. 00085 * 00086 * @details This structure contains the value of the DFU Packet characteristic as written by the 00087 * peer and the length of the value written. It will be filled by the DFU Service when the 00088 * peer writes to the DFU Packet characteristic. 00089 */ 00090 typedef struct 00091 { 00092 uint8_t len; /**< Length of the packet received. */ 00093 uint8_t * p_data; /**< Pointer to the received packet. This will point to a word aligned memory location.*/ 00094 } ble_dfu_pkt_write_t; 00095 00096 /**@brief Packet receipt notification request structure. 00097 * 00098 * @details This structure contains the contents of the packet receipt notification request 00099 * sent by the DFU Controller. 00100 */ 00101 typedef struct 00102 { 00103 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. */ 00104 } ble_pkt_rcpt_notif_req_t; 00105 00106 /**@brief DFU Event structure. 00107 * 00108 * @details This structure contains the event generated by the DFU Service based on the data 00109 * received from the peer. 00110 */ 00111 typedef struct 00112 { 00113 ble_dfu_evt_type_t ble_dfu_evt_type; /**< Type of the event.*/ 00114 union 00115 { 00116 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.*/ 00117 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.*/ 00118 } evt; 00119 } ble_dfu_evt_t; 00120 00121 // Forward declaration of the ble_dfu_t type. 00122 typedef struct ble_dfu_s ble_dfu_t; 00123 00124 /**@brief DFU Service event handler type. */ 00125 typedef void (*ble_dfu_evt_handler_t) (ble_dfu_t * p_dfu, ble_dfu_evt_t * p_evt); 00126 00127 /**@brief DFU service structure. 00128 * 00129 * @details This structure contains status information related to the service. 00130 */ 00131 typedef struct ble_dfu_s 00132 { 00133 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. */ 00134 uint16_t service_handle; /**< Handle of DFU Service (as provided by the S110 SoftDevice). */ 00135 uint8_t uuid_type; /**< UUID type assigned for DFU Service by the S110 SoftDevice. */ 00136 ble_gatts_char_handles_t dfu_pkt_handles; /**< Handles related to the DFU Packet characteristic. */ 00137 ble_gatts_char_handles_t dfu_ctrl_pt_handles; /**< Handles related to the DFU Control Point characteristic. */ 00138 ble_gatts_char_handles_t dfu_status_rep_handles; /**< Handles related to the DFU Status Report characteristic. */ 00139 ble_dfu_evt_handler_t evt_handler; /**< The event handler to be called when an event is to be sent to the application.*/ 00140 ble_srv_error_handler_t error_handler; /**< Function to be called in case of an error. */ 00141 } ble_dfu_t; 00142 00143 /**@brief DFU service initialization structure. 00144 * 00145 * @details This structure contains the initialization information for the DFU Service. The 00146 * application needs to fill this structure and pass it to the DFU Service using the 00147 * @ref ble_dfu_init function. 00148 */ 00149 typedef struct 00150 { 00151 ble_dfu_evt_handler_t evt_handler; /**< Event handler to be called for handling events in the Device Firmware Update Service. */ 00152 ble_srv_error_handler_t error_handler; /**< Function to be called in case of an error. */ 00153 } ble_dfu_init_t; 00154 00155 /**@brief Function for handling a BLE event. 00156 * 00157 * @details The DFU service expects the application to call this function each time an event 00158 * is received from the S110 SoftDevice. This function processes the event, if it is 00159 * relevant for the DFU service and calls the DFU event handler of the application if 00160 * necessary. 00161 * 00162 * @param[in] p_dfu Pointer to the DFU service structure. 00163 * @param[in] p_ble_evt Pointer to the event received from S110 SoftDevice. 00164 */ 00165 void ble_dfu_on_ble_evt(ble_dfu_t * p_dfu, ble_evt_t * p_ble_evt); 00166 00167 /**@brief Function for initializing the DFU service. 00168 * 00169 * @param[out] p_dfu Device Firmware Update service structure. This structure will have to be 00170 * supplied by the application. It will be initialized by this function, 00171 * and will later be used to identify the service instance. 00172 * @param[in] p_dfu_init Information needed to initialize the service. 00173 * 00174 * @return NRF_SUCCESS if the DFU service and its characteristics were successfully added to the 00175 * S110 SoftDevice. Otherwise an error code. 00176 * This function returns NRF_ERROR_NULL if the value of evt_handler in p_dfu_init 00177 * structure provided is NULL or if the pointers supplied as input are NULL. 00178 */ 00179 uint32_t ble_dfu_init(ble_dfu_t * p_dfu, ble_dfu_init_t * p_dfu_init); 00180 00181 /**@brief Function for sending response to a control point command. 00182 * 00183 * @details This function will encode a DFU Control Point response using the given input 00184 * parameters and will send a notification of the same to the peer. 00185 * 00186 * @param[in] p_dfu Pointer to the DFU service structure. 00187 * @param[in] dfu_proc Procedure for which this response is to be sent. 00188 * @param[in] resp_val Response value. 00189 * 00190 * @return NRF_SUCCESS if the DFU Service has successfully requested the S110 SoftDevice to 00191 * send the notification. Otherwise an error code. 00192 * This function returns NRF_ERROR_INVALID_STATE if the device is not connected to a 00193 * peer or if the DFU service is not initialized or if the notification of the DFU 00194 * Status Report characteristic was not enabled by the peer. It returns NRF_ERROR_NULL 00195 * if the pointer p_dfu is NULL. 00196 */ 00197 uint32_t ble_dfu_response_send(ble_dfu_t * p_dfu, 00198 ble_dfu_procedure_t dfu_proc, 00199 ble_dfu_resp_val_t resp_val); 00200 00201 /**@brief Function for notifying the peer about the number of bytes of firmware data received. 00202 * 00203 * @param[in] p_dfu Pointer to the DFU service structure. 00204 * @param[in] num_of_firmware_bytes_rcvd Number of bytes. 00205 * 00206 * @return NRF_SUCCESS if the DFU Service has successfully requested the S110 SoftDevice to send 00207 * the notification. Otherwise an error code. 00208 * This function returns NRF_ERROR_INVALID_STATE if the device is not connected to a 00209 * peer or if the DFU service is not initialized or if the notification of the DFU 00210 * Status Report characteristic was not enabled by the peer. It returns NRF_ERROR_NULL 00211 * if the pointer p_dfu is NULL. 00212 */ 00213 uint32_t ble_dfu_bytes_rcvd_report(ble_dfu_t * p_dfu, uint32_t num_of_firmware_bytes_rcvd); 00214 00215 /**@brief Function for sending Packet Receipt Notification to the peer. 00216 * 00217 * This function will encode the number of bytes received as input parameter into a 00218 * notification of the control point characteristic and send it to the peer. 00219 * 00220 * @param[in] p_dfu Pointer to the DFU service structure. 00221 * @param[in] num_of_firmware_bytes_rcvd Number of bytes of firmware image received. 00222 * 00223 * @return NRF_SUCCESS if the DFU Service has successfully requested the S110 SoftDevice to send 00224 * the notification. Otherwise an error code. 00225 * This function returns NRF_ERROR_INVALID_STATE if the device is not connected to a 00226 * peer or if the DFU service is not initialized or if the notification of the DFU 00227 * Status Report characteristic was not enabled by the peer. It returns NRF_ERROR_NULL 00228 * if the pointer p_dfu is NULL. 00229 */ 00230 uint32_t ble_dfu_pkts_rcpt_notify(ble_dfu_t * p_dfu, uint32_t num_of_firmware_bytes_rcvd); 00231 00232 #endif // BLE_DFU_H__ 00233 00234 /** @} */
Generated on Tue Jul 12 2022 18:47:31 by
