Microbug / nRF51822_FOTA

Patched version of nrf51822 FOTA compatible driver, with GPTIO disabled, as it clashed with the mbed definitions...

Fork of nRF51822 by Nordic Semiconductor

nordic-sdk/components/ble/ble_services/ble_dfu/ble_dfu.h@177:dad139e1e3c4, 2015-05-21 (annotated)

Committer:
finneyj
Date:
Thu May 21 09:35:07 2015 +0000
Revision:
177:dad139e1e3c4
Parent:
103:138bdc859cc9
Child:
112:737b08b3b995
Disabled GPTIOE as it conflicts with mbed definitions.

Who changed what in which revision?

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