Cefn Hoile / nRF51822

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.

Dependencies:   nrf51-sdk

Dependents:   microbit-dal

Fork of nRF51822 by Lancaster University

nordic-sdk/components/libraries/bootloader_dfu/dfu.h@362:6fa0d4d555f6, 2015-07-02 (annotated)

Committer:
rgrover1
Date:
Thu Jul 02 09:08:44 2015 +0100
Revision:
362:6fa0d4d555f6
Parent:
361:d2405f5a4853
Child:
370:295f76db798e
Synchronized with git rev 2716309c

Author: Rohit Grover

Release 0.4.0

=============



This is a major release which introduces the GATT Client functionality. It

aligns with release 0.4.0 of BLE_API.



Enhancements

~~~~~~~~~~~~



* Introduce GattClient. This includes functionality for service-discovery,

  connections, and attribute-reads and writes. You'll find a demo program for

  LEDBlinker on the mbed.org Bluetooth team page to use the new APIs. Some of

  the GATT client functionality hasn't been implemented yet, but the APIs have

  been added.



* We've added an implementation for the abstract base class for

  SecurityManager. All security related APIs have been moved into that.



* There has been a major cleanup of APIs under BLE. APIs have now been

  categorized as belonging to Gap, GattServer, GattClient, or SecurityManager.

  There are accessors to get references for Gap, GattServer, GattClient, and

  SecurityManager. A former call to ble.setAddress(...) is now expected to be

  achieved with ble.gap().setAddress(...).



* We've cleaned up our APIs, and this has resulted in dropping some APIs like

  BLE::reset().



* We've also dropped GattServer::initializeGattDatabase(). THis was added at

  some point to support controllers where a commit point was needed to

  indicate when the application had finished constructing the GATT database.

  This API would get called internally before Gap::startAdvertising(). We now

  expect the underlying port to do the equivalent of initializeGattDatabase()

  implicitly upon Gap::startAdvertising().



* We've added a version of Gap::disconnect() which takes a connection handle.

  The previous API (which did not take a connection handle) has been

  deprecated; it will still work for situations where there's only a single

  active connection. We hold on to that API to allow existing code to migrate

  to the new API.



Bugfixes

~~~~~~~~



* None.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
rgrover1 362:6fa0d4d555f6 1 /*
rgrover1 362:6fa0d4d555f6 2 * Copyright (c) Nordic Semiconductor ASA
rgrover1 362:6fa0d4d555f6 3 * All rights reserved.
rgrover1 362:6fa0d4d555f6 4 *
rgrover1 362:6fa0d4d555f6 5 * Redistribution and use in source and binary forms, with or without modification,
rgrover1 362:6fa0d4d555f6 6 * are permitted provided that the following conditions are met:
rgrover1 362:6fa0d4d555f6 7 *
rgrover1 362:6fa0d4d555f6 8 * 1. Redistributions of source code must retain the above copyright notice, this
rgrover1 362:6fa0d4d555f6 9 * list of conditions and the following disclaimer.
rgrover1 362:6fa0d4d555f6 10 *
rgrover1 362:6fa0d4d555f6 11 * 2. Redistributions in binary form must reproduce the above copyright notice, this
rgrover1 362:6fa0d4d555f6 12 * list of conditions and the following disclaimer in the documentation and/or
rgrover1 362:6fa0d4d555f6 13 * other materials provided with the distribution.
rgrover1 362:6fa0d4d555f6 14 *
rgrover1 362:6fa0d4d555f6 15 * 3. Neither the name of Nordic Semiconductor ASA nor the names of other
rgrover1 362:6fa0d4d555f6 16 * contributors to this software may be used to endorse or promote products
rgrover1 362:6fa0d4d555f6 17 * derived from this software without specific prior written permission.
rgrover1 362:6fa0d4d555f6 18 *
rgrover1 362:6fa0d4d555f6 19 *
rgrover1 362:6fa0d4d555f6 20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
rgrover1 362:6fa0d4d555f6 21 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
rgrover1 362:6fa0d4d555f6 22 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
rgrover1 362:6fa0d4d555f6 23 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
rgrover1 362:6fa0d4d555f6 24 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
rgrover1 362:6fa0d4d555f6 25 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
rgrover1 362:6fa0d4d555f6 26 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
rgrover1 362:6fa0d4d555f6 27 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
rgrover1 362:6fa0d4d555f6 28 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
rgrover1 362:6fa0d4d555f6 29 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
rgrover1 362:6fa0d4d555f6 30 *
rgrover1 362:6fa0d4d555f6 31 */
rgrover1 362:6fa0d4d555f6 32
rgrover1 362:6fa0d4d555f6 33 /**@file
rgrover1 362:6fa0d4d555f6 34 *
rgrover1 362:6fa0d4d555f6 35 * @defgroup nrf_dfu Device Firmware Update API.
rgrover1 362:6fa0d4d555f6 36 * @{
rgrover1 362:6fa0d4d555f6 37 *
rgrover1 362:6fa0d4d555f6 38 * @brief Device Firmware Update module interface.
rgrover1 362:6fa0d4d555f6 39 */
rgrover1 362:6fa0d4d555f6 40
rgrover1 362:6fa0d4d555f6 41 #ifndef DFU_H__
rgrover1 362:6fa0d4d555f6 42 #define DFU_H__
rgrover1 362:6fa0d4d555f6 43
rgrover1 362:6fa0d4d555f6 44 #include "dfu_types.h"
rgrover1 362:6fa0d4d555f6 45 #include <stdbool.h>
rgrover1 362:6fa0d4d555f6 46 #include <stdint.h>
rgrover1 362:6fa0d4d555f6 47
rgrover1 362:6fa0d4d555f6 48
rgrover1 362:6fa0d4d555f6 49 /**@brief DFU event callback for asynchronous calls.
rgrover1 362:6fa0d4d555f6 50 *
rgrover1 362:6fa0d4d555f6 51 * @param[in] packet Packet type for which this callback is related. START_PACKET, DATA_PACKET.
rgrover1 362:6fa0d4d555f6 52 * @param[in] result Operation result code. NRF_SUCCESS when a queued operation was successful.
rgrover1 362:6fa0d4d555f6 53 * @param[in] p_data Pointer to the data to which the operation is related.
rgrover1 362:6fa0d4d555f6 54 */
rgrover1 362:6fa0d4d555f6 55 typedef void (*dfu_callback_t)(uint32_t packet, uint32_t result, uint8_t * p_data);
rgrover1 362:6fa0d4d555f6 56
rgrover1 362:6fa0d4d555f6 57 /**@brief Function for initializing the Device Firmware Update module.
rgrover1 362:6fa0d4d555f6 58 *
rgrover1 362:6fa0d4d555f6 59 * @return NRF_SUCCESS on success, an error_code otherwise.
rgrover1 362:6fa0d4d555f6 60 */
rgrover1 362:6fa0d4d555f6 61 uint32_t dfu_init(void);
rgrover1 362:6fa0d4d555f6 62
rgrover1 362:6fa0d4d555f6 63 /**@brief Function for registering a callback listener for \ref dfu_data_pkt_handle callbacks.
rgrover1 362:6fa0d4d555f6 64 *
rgrover1 362:6fa0d4d555f6 65 * @param[in] callback_handler Callback handler for receiving DFU events on completed operations
rgrover1 362:6fa0d4d555f6 66 * of DFU packets.
rgrover1 362:6fa0d4d555f6 67 */
rgrover1 362:6fa0d4d555f6 68 void dfu_register_callback(dfu_callback_t callback_handler);
rgrover1 362:6fa0d4d555f6 69
rgrover1 362:6fa0d4d555f6 70 /**@brief Function for setting the DFU image size.
rgrover1 362:6fa0d4d555f6 71 *
rgrover1 362:6fa0d4d555f6 72 * @details Function sets the DFU image size. This function must be called when an update is started
rgrover1 362:6fa0d4d555f6 73 * in order to notify the DFU of the new image size. If multiple images are to be
rgrover1 362:6fa0d4d555f6 74 * transferred within the same update context then this function must be called with size
rgrover1 362:6fa0d4d555f6 75 * information for each image being transfered.
rgrover1 362:6fa0d4d555f6 76 * If an image type is not being transfered, e.g. SoftDevice but no Application , then the
rgrover1 362:6fa0d4d555f6 77 * image size for application must be zero.
rgrover1 362:6fa0d4d555f6 78 *
rgrover1 362:6fa0d4d555f6 79 * @param[in] p_packet Pointer to the DFU packet containing information on DFU update process to
rgrover1 362:6fa0d4d555f6 80 * be started.
rgrover1 362:6fa0d4d555f6 81 *
rgrover1 362:6fa0d4d555f6 82 * @return NRF_SUCCESS on success, an error_code otherwise.
rgrover1 362:6fa0d4d555f6 83 */
rgrover1 362:6fa0d4d555f6 84 uint32_t dfu_start_pkt_handle(dfu_update_packet_t * p_packet);
rgrover1 362:6fa0d4d555f6 85
rgrover1 362:6fa0d4d555f6 86 /**@brief Function for handling DFU data packets.
rgrover1 362:6fa0d4d555f6 87 *
rgrover1 362:6fa0d4d555f6 88 * @param[in] p_packet Pointer to the DFU packet.
rgrover1 362:6fa0d4d555f6 89 *
rgrover1 362:6fa0d4d555f6 90 * @return NRF_SUCCESS on success, an error_code otherwise.
rgrover1 362:6fa0d4d555f6 91 */
rgrover1 362:6fa0d4d555f6 92 uint32_t dfu_data_pkt_handle(dfu_update_packet_t * p_packet);
rgrover1 362:6fa0d4d555f6 93
rgrover1 362:6fa0d4d555f6 94 /**@brief Function for handling DFU init packets.
rgrover1 362:6fa0d4d555f6 95 *
rgrover1 362:6fa0d4d555f6 96 * @return NRF_SUCCESS on success, an error_code otherwise.
rgrover1 362:6fa0d4d555f6 97 */
rgrover1 362:6fa0d4d555f6 98 uint32_t dfu_init_pkt_handle(dfu_update_packet_t * p_packet);
rgrover1 362:6fa0d4d555f6 99
rgrover1 362:6fa0d4d555f6 100 /**@brief Function for validating a transferred image after the transfer has completed.
rgrover1 362:6fa0d4d555f6 101 *
rgrover1 362:6fa0d4d555f6 102 * @return NRF_SUCCESS on success, an error_code otherwise.
rgrover1 362:6fa0d4d555f6 103 */
rgrover1 362:6fa0d4d555f6 104 uint32_t dfu_image_validate(void);
rgrover1 362:6fa0d4d555f6 105
rgrover1 362:6fa0d4d555f6 106 /**@brief Function for activating the transfered image after validation has successfully completed.
rgrover1 362:6fa0d4d555f6 107 *
rgrover1 362:6fa0d4d555f6 108 * @return NRF_SUCCESS on success, an error_code otherwise.
rgrover1 362:6fa0d4d555f6 109 */
rgrover1 362:6fa0d4d555f6 110 uint32_t dfu_image_activate(void);
rgrover1 362:6fa0d4d555f6 111
rgrover1 362:6fa0d4d555f6 112 /**@brief Function for reseting the current update procedure and return to initial state.
rgrover1 362:6fa0d4d555f6 113 *
rgrover1 362:6fa0d4d555f6 114 * @details This function call will result in a system reset to ensure correct system behavior.
rgrover1 362:6fa0d4d555f6 115 * The reset will might be scheduled to execute at a later point in time to ensure pending
rgrover1 362:6fa0d4d555f6 116 * flash operations has completed.
rgrover1 362:6fa0d4d555f6 117 */
rgrover1 362:6fa0d4d555f6 118 void dfu_reset(void);
rgrover1 362:6fa0d4d555f6 119
rgrover1 362:6fa0d4d555f6 120 /**@brief Function for validating that new bootloader has been correctly installed.
rgrover1 362:6fa0d4d555f6 121 *
rgrover1 362:6fa0d4d555f6 122 * @return NRF_SUCCESS if install was successful. NRF_ERROR_NULL if the images differs.
rgrover1 362:6fa0d4d555f6 123 */
rgrover1 362:6fa0d4d555f6 124 uint32_t dfu_bl_image_validate(void);
rgrover1 362:6fa0d4d555f6 125
rgrover1 362:6fa0d4d555f6 126 /**@brief Function for validating that new SoftDevicehas been correctly installed.
rgrover1 362:6fa0d4d555f6 127 *
rgrover1 362:6fa0d4d555f6 128 * @return NRF_SUCCESS if install was successful. NRF_ERROR_NULL if the images differs.
rgrover1 362:6fa0d4d555f6 129 */
rgrover1 362:6fa0d4d555f6 130 uint32_t dfu_sd_image_validate(void);
rgrover1 362:6fa0d4d555f6 131
rgrover1 362:6fa0d4d555f6 132 /**@brief Function for swapping existing bootloader with newly received.
rgrover1 362:6fa0d4d555f6 133 *
rgrover1 362:6fa0d4d555f6 134 * @return NRF_SUCCESS on succesfull swapping. For error code please refer to
rgrover1 362:6fa0d4d555f6 135 * \ref sd_mbr_command_copy_bl_t.
rgrover1 362:6fa0d4d555f6 136 */
rgrover1 362:6fa0d4d555f6 137 uint32_t dfu_bl_image_swap(void);
rgrover1 362:6fa0d4d555f6 138
rgrover1 362:6fa0d4d555f6 139 /**@brief Function for swapping existing SoftDevice with newly received.
rgrover1 362:6fa0d4d555f6 140 *
rgrover1 362:6fa0d4d555f6 141 * @return NRF_SUCCESS on succesfull swapping. For error code please refer to
rgrover1 362:6fa0d4d555f6 142 * \ref sd_mbr_command_copy_sd_t.
rgrover1 362:6fa0d4d555f6 143 */
rgrover1 362:6fa0d4d555f6 144 uint32_t dfu_sd_image_swap(void);
rgrover1 362:6fa0d4d555f6 145
rgrover1 362:6fa0d4d555f6 146 /**@brief Function for handling DFU init packet complete.
rgrover1 362:6fa0d4d555f6 147 *
rgrover1 362:6fa0d4d555f6 148 * @return NRF_SUCCESS on success, an error_code otherwise.
rgrover1 362:6fa0d4d555f6 149 */
rgrover1 362:6fa0d4d555f6 150 uint32_t dfu_init_pkt_complete(void);
rgrover1 362:6fa0d4d555f6 151
rgrover1 362:6fa0d4d555f6 152 #endif // DFU_H__
rgrover1 362:6fa0d4d555f6 153
rgrover1 362:6fa0d4d555f6 154 /** @} */