test
Fork of nrf51-sdk by
Embed:
(wiki syntax)
Show/hide line numbers
ble_dfu.h
Go to the documentation of this file.
00001 /* 00002 * Copyright (c) Nordic Semiconductor ASA 00003 * All rights reserved. 00004 * 00005 * Redistribution and use in source and binary forms, with or without modification, 00006 * are permitted provided that the following conditions are met: 00007 * 00008 * 1. Redistributions of source code must retain the above copyright notice, this 00009 * list of conditions and the following disclaimer. 00010 * 00011 * 2. Redistributions in binary form must reproduce the above copyright notice, this 00012 * list of conditions and the following disclaimer in the documentation and/or 00013 * other materials provided with the distribution. 00014 * 00015 * 3. Neither the name of Nordic Semiconductor ASA nor the names of other 00016 * contributors to this software may be used to endorse or promote products 00017 * derived from this software without specific prior written permission. 00018 * 00019 * 00020 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 00021 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 00022 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 00023 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR 00024 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 00025 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 00026 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON 00027 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 00028 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 00029 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 00030 * 00031 */ 00032 00033 /**@file 00034 * 00035 * @defgroup ble_sdk_srv_dfu Device Firmware Update Service 00036 * @{ 00037 * @ingroup ble_sdk_srv 00038 * @brief Device Firmware Update Service 00039 * 00040 * @details The Device Firmware Update (DFU) service is a GATT based service that can be used for 00041 * performing firmware updates over BLE. Note that this implementation uses vendor 00042 * specific UUIDs for service and characteristics and is intended to demonstrate the 00043 * firmware updates over BLE. Refer @ref bledfu_transport_bleservice and @ref 00044 * bledfu_transport_bleprofile for more information on the service and profile respectively. 00045 */ 00046 00047 #ifndef BLE_DFU_H__ 00048 #define BLE_DFU_H__ 00049 00050 #include <stdint.h> 00051 #include "ble_gatts.h" 00052 #include "ble_gap.h" 00053 #include "ble.h" 00054 #include "ble_srv_common.h " 00055 00056 #define BLE_DFU_SERVICE_UUID 0x1530 /**< The UUID of the DFU Service. */ 00057 #define BLE_DFU_PKT_CHAR_UUID 0x1532 /**< The UUID of the DFU Packet Characteristic. */ 00058 #define BLE_DFU_CTRL_PT_UUID 0x1531 /**< The UUID of the DFU Control Point. */ 00059 #define BLE_DFU_STATUS_REP_UUID 0x1533 /**< The UUID of the DFU Status Report Characteristic. */ 00060 #define BLE_DFU_REV_CHAR_UUID 0x1534 /**< The UUID of the DFU Revision Characteristic. */ 00061 00062 /**@brief DFU Event type. 00063 * 00064 * @details This enumeration contains the types of events that will be received from the DFU Service. 00065 */ 00066 typedef enum 00067 { 00068 BLE_DFU_START, /**< The event indicating that the peer wants the application to prepare for a new firmware update. */ 00069 BLE_DFU_RECEIVE_INIT_DATA, /**< The event indicating that the peer wants the application to prepare to receive init parameters. */ 00070 BLE_DFU_RECEIVE_APP_DATA, /**< The event indicating that the peer wants the application to prepare to receive the new firmware image. */ 00071 BLE_DFU_VALIDATE, /**< The event indicating that the peer wants the application to validate the newly received firmware image. */ 00072 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 */ 00073 BLE_DFU_SYS_RESET, /**< The event indicating that the peer wants the application to undergo a reset and start the currently valid application image.*/ 00074 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.*/ 00075 BLE_DFU_PKT_RCPT_NOTIF_DISABLED, /**< The event indicating that the peer has disabled the packet receipt notifications.*/ 00076 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.*/ 00077 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. */ 00078 } ble_dfu_evt_type_t; 00079 00080 /**@brief DFU Procedure type. 00081 * 00082 * @details This enumeration contains the types of DFU procedures. 00083 */ 00084 typedef enum 00085 { 00086 BLE_DFU_START_PROCEDURE = 1, /**< DFU Start procedure.*/ 00087 BLE_DFU_INIT_PROCEDURE = 2, /**< DFU Initialization procedure.*/ 00088 BLE_DFU_RECEIVE_APP_PROCEDURE = 3, /**< Firmware receiving procedure.*/ 00089 BLE_DFU_VALIDATE_PROCEDURE = 4, /**< Firmware image validation procedure .*/ 00090 BLE_DFU_PKT_RCPT_REQ_PROCEDURE = 8 /**< Packet receipt notification request procedure. */ 00091 } ble_dfu_procedure_t; 00092 00093 /**@brief DFU Response value type. 00094 */ 00095 typedef enum 00096 { 00097 BLE_DFU_RESP_VAL_SUCCESS = 1, /**< Success.*/ 00098 BLE_DFU_RESP_VAL_INVALID_STATE, /**< Invalid state.*/ 00099 BLE_DFU_RESP_VAL_NOT_SUPPORTED, /**< Operation not supported.*/ 00100 BLE_DFU_RESP_VAL_DATA_SIZE, /**< Data size exceeds limit.*/ 00101 BLE_DFU_RESP_VAL_CRC_ERROR, /**< CRC Error.*/ 00102 BLE_DFU_RESP_VAL_OPER_FAILED /**< Operation failed.*/ 00103 } ble_dfu_resp_val_t; 00104 00105 00106 /**@brief DFU Packet structure. 00107 * 00108 * @details This structure contains the value of the DFU Packet characteristic as written by the 00109 * peer and the length of the value written. It will be filled by the DFU Service when the 00110 * peer writes to the DFU Packet characteristic. 00111 */ 00112 typedef struct 00113 { 00114 uint8_t * p_data; /**< Pointer to the received packet. This will point to a word aligned memory location.*/ 00115 uint8_t len; /**< Length of the packet received. */ 00116 } ble_dfu_pkt_write_t; 00117 00118 /**@brief Packet receipt notification request structure. 00119 * 00120 * @details This structure contains the contents of the packet receipt notification request 00121 * sent by the DFU Controller. 00122 */ 00123 typedef struct 00124 { 00125 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. */ 00126 } ble_pkt_rcpt_notif_req_t; 00127 00128 /**@brief DFU Event structure. 00129 * 00130 * @details This structure contains the event generated by the DFU Service based on the data 00131 * received from the peer. 00132 */ 00133 typedef struct 00134 { 00135 ble_dfu_evt_type_t ble_dfu_evt_type; /**< Type of the event.*/ 00136 union 00137 { 00138 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.*/ 00139 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.*/ 00140 } evt; 00141 } ble_dfu_evt_t; 00142 00143 // Forward declaration of the ble_dfu_t type. 00144 typedef struct ble_dfu_s ble_dfu_t; 00145 00146 /**@brief DFU Service event handler type. */ 00147 typedef void (*ble_dfu_evt_handler_t) (ble_dfu_t * p_dfu, ble_dfu_evt_t * p_evt); 00148 00149 /**@brief DFU service structure. 00150 * 00151 * @details This structure contains status information related to the service. 00152 */ 00153 struct ble_dfu_s 00154 { 00155 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. */ 00156 uint16_t revision; /**< Handle of DFU Service (as provided by the S110 SoftDevice). */ 00157 uint16_t service_handle; /**< Handle of DFU Service (as provided by the S110 SoftDevice). */ 00158 uint8_t uuid_type; /**< UUID type assigned for DFU Service by the S110 SoftDevice. */ 00159 ble_gatts_char_handles_t dfu_pkt_handles; /**< Handles related to the DFU Packet characteristic. */ 00160 ble_gatts_char_handles_t dfu_ctrl_pt_handles; /**< Handles related to the DFU Control Point characteristic. */ 00161 ble_gatts_char_handles_t dfu_status_rep_handles; /**< Handles related to the DFU Status Report characteristic. */ 00162 ble_gatts_char_handles_t dfu_rev_handles; /**< Handles related to the DFU Revision characteristic. */ 00163 ble_dfu_evt_handler_t evt_handler; /**< The event handler to be called when an event is to be sent to the application.*/ 00164 ble_srv_error_handler_t error_handler; /**< Function to be called in case of an error. */ 00165 }; 00166 00167 /**@brief DFU service initialization structure. 00168 * 00169 * @details This structure contains the initialization information for the DFU Service. The 00170 * application needs to fill this structure and pass it to the DFU Service using the 00171 * @ref ble_dfu_init function. 00172 */ 00173 typedef struct 00174 { 00175 uint16_t revision; /**< Revision number to be exposed by the DFU service. */ 00176 ble_dfu_evt_handler_t evt_handler; /**< Event handler to be called for handling events in the Device Firmware Update Service. */ 00177 ble_srv_error_handler_t error_handler; /**< Function to be called in case of an error. */ 00178 } ble_dfu_init_t; 00179 00180 /**@brief Function for handling a BLE event. 00181 * 00182 * @details The DFU service expects the application to call this function each time an event 00183 * is received from the S110 SoftDevice. This function processes the event, if it is 00184 * relevant for the DFU service and calls the DFU event handler of the application if 00185 * necessary. 00186 * 00187 * @param[in] p_dfu Pointer to the DFU service structure. 00188 * @param[in] p_ble_evt Pointer to the event received from S110 SoftDevice. 00189 */ 00190 void ble_dfu_on_ble_evt(ble_dfu_t * p_dfu, ble_evt_t * p_ble_evt); 00191 00192 /**@brief Function for initializing the DFU service. 00193 * 00194 * @param[out] p_dfu Device Firmware Update service structure. This structure will have to be 00195 * supplied by the application. It will be initialized by this function, 00196 * and will later be used to identify the service instance. 00197 * @param[in] p_dfu_init Information needed to initialize the service. 00198 * 00199 * @return NRF_SUCCESS if the DFU service and its characteristics were successfully added to the 00200 * S110 SoftDevice. Otherwise an error code. 00201 * This function returns NRF_ERROR_NULL if the value of evt_handler in p_dfu_init 00202 * structure provided is NULL or if the pointers supplied as input are NULL. 00203 */ 00204 uint32_t ble_dfu_init(ble_dfu_t * p_dfu, ble_dfu_init_t * p_dfu_init); 00205 00206 /**@brief Function for sending response to a control point command. 00207 * 00208 * @details This function will encode a DFU Control Point response using the given input 00209 * parameters and will send a notification of the same to the peer. 00210 * 00211 * @param[in] p_dfu Pointer to the DFU service structure. 00212 * @param[in] dfu_proc Procedure for which this response is to be sent. 00213 * @param[in] resp_val Response value. 00214 * 00215 * @return NRF_SUCCESS if the DFU Service has successfully requested the S110 SoftDevice to 00216 * send the notification. Otherwise an error code. 00217 * This function returns NRF_ERROR_INVALID_STATE if the device is not connected to a 00218 * peer or if the DFU service is not initialized or if the notification of the DFU 00219 * Status Report characteristic was not enabled by the peer. It returns NRF_ERROR_NULL 00220 * if the pointer p_dfu is NULL. 00221 */ 00222 uint32_t ble_dfu_response_send(ble_dfu_t * p_dfu, 00223 ble_dfu_procedure_t dfu_proc, 00224 ble_dfu_resp_val_t resp_val); 00225 00226 /**@brief Function for notifying the peer about the number of bytes of firmware data received. 00227 * 00228 * @param[in] p_dfu Pointer to the DFU service structure. 00229 * @param[in] num_of_firmware_bytes_rcvd Number of bytes. 00230 * 00231 * @return NRF_SUCCESS if the DFU Service has successfully requested the S110 SoftDevice to send 00232 * the notification. Otherwise an error code. 00233 * This function returns NRF_ERROR_INVALID_STATE if the device is not connected to a 00234 * peer or if the DFU service is not initialized or if the notification of the DFU 00235 * Status Report characteristic was not enabled by the peer. It returns NRF_ERROR_NULL 00236 * if the pointer p_dfu is NULL. 00237 */ 00238 uint32_t ble_dfu_bytes_rcvd_report(ble_dfu_t * p_dfu, uint32_t num_of_firmware_bytes_rcvd); 00239 00240 /**@brief Function for sending Packet Receipt Notification to the peer. 00241 * 00242 * This function will encode the number of bytes received as input parameter into a 00243 * notification of the control point characteristic and send it to the peer. 00244 * 00245 * @param[in] p_dfu Pointer to the DFU service structure. 00246 * @param[in] num_of_firmware_bytes_rcvd Number of bytes of firmware image received. 00247 * 00248 * @return NRF_SUCCESS if the DFU Service has successfully requested the S110 SoftDevice to send 00249 * the notification. Otherwise an error code. 00250 * This function returns NRF_ERROR_INVALID_STATE if the device is not connected to a 00251 * peer or if the DFU service is not initialized or if the notification of the DFU 00252 * Status Report characteristic was not enabled by the peer. It returns NRF_ERROR_NULL 00253 * if the pointer p_dfu is NULL. 00254 */ 00255 uint32_t ble_dfu_pkts_rcpt_notify(ble_dfu_t * p_dfu, uint32_t num_of_firmware_bytes_rcvd); 00256 00257 #endif // BLE_DFU_H__ 00258 00259 /** @} */
Generated on Tue Jul 12 2022 15:51:26 by 1.7.2