ver:init
x-nucleo-idb0xa1/bluenrg-hci/bluenrg_utils.h@0:4946262d6030, 2017-06-18 (annotated)
- Committer:
- iv123
- Date:
- Sun Jun 18 16:11:03 2017 +0000
- Revision:
- 0:4946262d6030
Initial commit
Who changed what in which revision?
User | Revision | Line number | New contents of line |
---|---|---|---|
iv123 | 0:4946262d6030 | 1 | /******************** (C) COPYRIGHT 2014 STMicroelectronics ******************** |
iv123 | 0:4946262d6030 | 2 | * File Name : bluenrg_utils.h |
iv123 | 0:4946262d6030 | 3 | * Author : AMS - VMA, RF Application Team |
iv123 | 0:4946262d6030 | 4 | * Version : V1.0.1 |
iv123 | 0:4946262d6030 | 5 | * Date : 03-October-2014 |
iv123 | 0:4946262d6030 | 6 | * Description : Header file for BlueNRG utility functions |
iv123 | 0:4946262d6030 | 7 | ******************************************************************************** |
iv123 | 0:4946262d6030 | 8 | * THE PRESENT FIRMWARE WHICH IS FOR GUIDANCE ONLY AIMS AT PROVIDING CUSTOMERS |
iv123 | 0:4946262d6030 | 9 | * WITH CODING INFORMATION REGARDING THEIR PRODUCTS IN ORDER FOR THEM TO SAVE TIME. |
iv123 | 0:4946262d6030 | 10 | * AS A RESULT, STMICROELECTRONICS SHALL NOT BE HELD LIABLE FOR ANY DIRECT, |
iv123 | 0:4946262d6030 | 11 | * INDIRECT OR CONSEQUENTIAL DAMAGES WITH RESPECT TO ANY CLAIMS ARISING FROM THE |
iv123 | 0:4946262d6030 | 12 | * CONTENT OF SUCH FIRMWARE AND/OR THE USE MADE BY CUSTOMERS OF THE CODING |
iv123 | 0:4946262d6030 | 13 | * INFORMATION CONTAINED HEREIN IN CONNECTION WITH THEIR PRODUCTS. |
iv123 | 0:4946262d6030 | 14 | *******************************************************************************/ |
iv123 | 0:4946262d6030 | 15 | /** |
iv123 | 0:4946262d6030 | 16 | * @file bluenrg_utils.h |
iv123 | 0:4946262d6030 | 17 | * @brief BlueNRG IFR updater & BlueNRG stack updater utility APIs description |
iv123 | 0:4946262d6030 | 18 | * |
iv123 | 0:4946262d6030 | 19 | * <!-- Copyright 2014 by STMicroelectronics. All rights reserved. *80*--> |
iv123 | 0:4946262d6030 | 20 | **/ |
iv123 | 0:4946262d6030 | 21 | /* Define to prevent recursive inclusion -------------------------------------*/ |
iv123 | 0:4946262d6030 | 22 | #ifndef __BLUENRG_UTILS_H |
iv123 | 0:4946262d6030 | 23 | #define __BLUENRG_UTILS_H |
iv123 | 0:4946262d6030 | 24 | |
iv123 | 0:4946262d6030 | 25 | #ifdef __cplusplus |
iv123 | 0:4946262d6030 | 26 | extern "C" { |
iv123 | 0:4946262d6030 | 27 | #endif |
iv123 | 0:4946262d6030 | 28 | |
iv123 | 0:4946262d6030 | 29 | /* Includes ------------------------------------------------------------------*/ |
iv123 | 0:4946262d6030 | 30 | #include "ble_hal_types.h" |
iv123 | 0:4946262d6030 | 31 | #include "ble_compiler.h" |
iv123 | 0:4946262d6030 | 32 | |
iv123 | 0:4946262d6030 | 33 | /* Exported types ------------------------------------------------------------*/ |
iv123 | 0:4946262d6030 | 34 | typedef struct{ |
iv123 | 0:4946262d6030 | 35 | uint8_t stack_mode; |
iv123 | 0:4946262d6030 | 36 | uint8_t day; |
iv123 | 0:4946262d6030 | 37 | uint8_t month; |
iv123 | 0:4946262d6030 | 38 | uint8_t year; |
iv123 | 0:4946262d6030 | 39 | uint16_t slave_sca_ppm; |
iv123 | 0:4946262d6030 | 40 | uint8_t master_sca; |
iv123 | 0:4946262d6030 | 41 | uint16_t hs_startup_time; /* In system time units*/ |
iv123 | 0:4946262d6030 | 42 | } IFR_config2_TypeDef; |
iv123 | 0:4946262d6030 | 43 | |
iv123 | 0:4946262d6030 | 44 | /** |
iv123 | 0:4946262d6030 | 45 | * Structure inside IFR for configuration options. |
iv123 | 0:4946262d6030 | 46 | */ |
iv123 | 0:4946262d6030 | 47 | typedef __packed struct{ |
iv123 | 0:4946262d6030 | 48 | uint8_t cold_ana_act_config_table[64]; |
iv123 | 0:4946262d6030 | 49 | uint8_t hot_ana_config_table[64]; |
iv123 | 0:4946262d6030 | 50 | uint8_t stack_mode; |
iv123 | 0:4946262d6030 | 51 | uint8_t gpio_config; |
iv123 | 0:4946262d6030 | 52 | uint8_t rsrvd1[2]; |
iv123 | 0:4946262d6030 | 53 | uint32_t rsrvd2[3]; |
iv123 | 0:4946262d6030 | 54 | uint32_t max_conn_event_time; |
iv123 | 0:4946262d6030 | 55 | uint32_t ls_crystal_period; |
iv123 | 0:4946262d6030 | 56 | uint32_t ls_crystal_freq; |
iv123 | 0:4946262d6030 | 57 | uint16_t slave_sca_ppm; |
iv123 | 0:4946262d6030 | 58 | uint8_t master_sca; |
iv123 | 0:4946262d6030 | 59 | uint8_t rsrvd3; |
iv123 | 0:4946262d6030 | 60 | uint16_t hs_startup_time; /* In system time units*/ |
iv123 | 0:4946262d6030 | 61 | uint8_t rsrvd4[2]; |
iv123 | 0:4946262d6030 | 62 | uint32_t uid; |
iv123 | 0:4946262d6030 | 63 | uint8_t rsrvd5; |
iv123 | 0:4946262d6030 | 64 | uint8_t year; |
iv123 | 0:4946262d6030 | 65 | uint8_t month; |
iv123 | 0:4946262d6030 | 66 | uint8_t day; |
iv123 | 0:4946262d6030 | 67 | uint32_t unused[5]; |
iv123 | 0:4946262d6030 | 68 | } PACKED IFR_config_TypeDef; |
iv123 | 0:4946262d6030 | 69 | |
iv123 | 0:4946262d6030 | 70 | /* Exported constants --------------------------------------------------------*/ |
iv123 | 0:4946262d6030 | 71 | extern const IFR_config_TypeDef IFR_config; |
iv123 | 0:4946262d6030 | 72 | |
iv123 | 0:4946262d6030 | 73 | /* Exported macros -----------------------------------------------------------*/ |
iv123 | 0:4946262d6030 | 74 | #define FROM_US_TO_SYS_TIME(us) ((uint16_t)(us/2.4414)) |
iv123 | 0:4946262d6030 | 75 | #define FROM_SYS_TIME_TO_US(sys) ((uint16_t)(sys*2.4414)) |
iv123 | 0:4946262d6030 | 76 | |
iv123 | 0:4946262d6030 | 77 | /* Convert 2 digit BCD number to an integer */ |
iv123 | 0:4946262d6030 | 78 | #define BCD_TO_INT(bcd) ((bcd & 0xF) + ((bcd & 0xF0) >> 4)*10) |
iv123 | 0:4946262d6030 | 79 | |
iv123 | 0:4946262d6030 | 80 | /* Convert 2 digit number to a BCD number */ |
iv123 | 0:4946262d6030 | 81 | #define INT_TO_BCD(n) ((((uint8_t)n/10)<<4) + (uint8_t)n%10) |
iv123 | 0:4946262d6030 | 82 | |
iv123 | 0:4946262d6030 | 83 | /** |
iv123 | 0:4946262d6030 | 84 | * Return values |
iv123 | 0:4946262d6030 | 85 | */ |
iv123 | 0:4946262d6030 | 86 | #define BLE_UTIL_SUCCESS 0 |
iv123 | 0:4946262d6030 | 87 | #define BLE_UTIL_UNSUPPORTED_VERSION 1 |
iv123 | 0:4946262d6030 | 88 | #define BLE_UTIL_WRONG_IMAGE_SIZE 2 |
iv123 | 0:4946262d6030 | 89 | #define BLE_UTIL_ACI_ERROR 3 |
iv123 | 0:4946262d6030 | 90 | #define BLE_UTIL_CRC_ERROR 4 |
iv123 | 0:4946262d6030 | 91 | #define BLE_UTIL_PARSE_ERROR 5 |
iv123 | 0:4946262d6030 | 92 | #define BLE_UTIL_WRONG_VERIFY 6 |
iv123 | 0:4946262d6030 | 93 | |
iv123 | 0:4946262d6030 | 94 | /* Exported functions ------------------------------------------------------- */ |
iv123 | 0:4946262d6030 | 95 | /** |
iv123 | 0:4946262d6030 | 96 | * @brief Flash a new firmware using internal bootloader. |
iv123 | 0:4946262d6030 | 97 | * @param fw_image Pointer to the firmware image (raw binary data, |
iv123 | 0:4946262d6030 | 98 | * little-endian). |
iv123 | 0:4946262d6030 | 99 | * @param fw_size Size of the firmware image. The firmware image size shall |
iv123 | 0:4946262d6030 | 100 | * be multiple of 4 bytes. |
iv123 | 0:4946262d6030 | 101 | * @retval int It returns 0 if successful, or a number not equal to 0 in |
iv123 | 0:4946262d6030 | 102 | * case of error (ACI_ERROR, UNSUPPORTED_VERSION, |
iv123 | 0:4946262d6030 | 103 | * WRONG_IMAGE_SIZE, CRC_ERROR) |
iv123 | 0:4946262d6030 | 104 | */ |
iv123 | 0:4946262d6030 | 105 | int program_device(const uint8_t *fw_image, uint32_t fw_size); |
iv123 | 0:4946262d6030 | 106 | |
iv123 | 0:4946262d6030 | 107 | /** |
iv123 | 0:4946262d6030 | 108 | * @brief Read raw data from IFR (3 64-bytes blocks). |
iv123 | 0:4946262d6030 | 109 | * @param data Pointer to the buffer that will contain the read data. |
iv123 | 0:4946262d6030 | 110 | * Its size must be 192 bytes. This data can be parsed by |
iv123 | 0:4946262d6030 | 111 | * parse_IFR_data_config(). |
iv123 | 0:4946262d6030 | 112 | * @retval int It returns 0 if successful, or a number not equal to 0 in |
iv123 | 0:4946262d6030 | 113 | * case of error (ACI_ERROR, UNSUPPORTED_VERSION) |
iv123 | 0:4946262d6030 | 114 | */ |
iv123 | 0:4946262d6030 | 115 | int read_IFR(uint8_t data[192]); |
iv123 | 0:4946262d6030 | 116 | |
iv123 | 0:4946262d6030 | 117 | /** |
iv123 | 0:4946262d6030 | 118 | * @brief Verify raw data from IFR (3 64-bytes blocks). |
iv123 | 0:4946262d6030 | 119 | * @param ifr_data Pointer to the buffer that will contain the data to verify. |
iv123 | 0:4946262d6030 | 120 | * Its size must be 192 bytes. |
iv123 | 0:4946262d6030 | 121 | * @retval int It returns 0 if successful, or a number not equal to 0 in |
iv123 | 0:4946262d6030 | 122 | case of error (ACI_ERROR, BLE_UTIL_WRONG_VERIFY) |
iv123 | 0:4946262d6030 | 123 | */ |
iv123 | 0:4946262d6030 | 124 | uint8_t verify_IFR(const IFR_config_TypeDef *ifr_data); |
iv123 | 0:4946262d6030 | 125 | |
iv123 | 0:4946262d6030 | 126 | /** |
iv123 | 0:4946262d6030 | 127 | * @brief Program raw data to IFR (3 64-bytes blocks). |
iv123 | 0:4946262d6030 | 128 | * @param ifr_image Pointer to the buffer that will contain the data to program. |
iv123 | 0:4946262d6030 | 129 | * Its size must be 192 bytes. |
iv123 | 0:4946262d6030 | 130 | * @retval int It returns 0 if successful |
iv123 | 0:4946262d6030 | 131 | */ |
iv123 | 0:4946262d6030 | 132 | int program_IFR(const IFR_config_TypeDef *ifr_image); |
iv123 | 0:4946262d6030 | 133 | |
iv123 | 0:4946262d6030 | 134 | /** |
iv123 | 0:4946262d6030 | 135 | * @brief Parse IFR raw data. |
iv123 | 0:4946262d6030 | 136 | * @param data Pointer to the raw data: last 64 bytes read from IFR sector. |
iv123 | 0:4946262d6030 | 137 | * @param IFR_config Data structure that will be filled with parsed data. |
iv123 | 0:4946262d6030 | 138 | * @retval None |
iv123 | 0:4946262d6030 | 139 | */ |
iv123 | 0:4946262d6030 | 140 | void parse_IFR_data_config(const uint8_t data[64], IFR_config2_TypeDef *IFR_config); |
iv123 | 0:4946262d6030 | 141 | |
iv123 | 0:4946262d6030 | 142 | /** |
iv123 | 0:4946262d6030 | 143 | * @brief Check for the correctness of parsed data. |
iv123 | 0:4946262d6030 | 144 | * @param IFR_config Data structure filled with parsed data. |
iv123 | 0:4946262d6030 | 145 | * @retval int It returns 0 if successful, or PARSE_ERROR in case data is |
iv123 | 0:4946262d6030 | 146 | * not correct. |
iv123 | 0:4946262d6030 | 147 | */ |
iv123 | 0:4946262d6030 | 148 | int IFR_validate(IFR_config2_TypeDef *IFR_config); |
iv123 | 0:4946262d6030 | 149 | |
iv123 | 0:4946262d6030 | 150 | /** |
iv123 | 0:4946262d6030 | 151 | * @brief Modify IFR data. (Last 64-bytes block). |
iv123 | 0:4946262d6030 | 152 | * @param IFR_config Structure that contains the new parameters inside the |
iv123 | 0:4946262d6030 | 153 | * IFR configuration data. |
iv123 | 0:4946262d6030 | 154 | * @note It is highly recommended to parse the IFR configuration from |
iv123 | 0:4946262d6030 | 155 | * a working IFR block (this should be done with parse_IFR_data_config()). |
iv123 | 0:4946262d6030 | 156 | * Then it is possible to write the new parameters inside the IFR_config |
iv123 | 0:4946262d6030 | 157 | * structure. |
iv123 | 0:4946262d6030 | 158 | * @param data Pointer to the buffer that contains the original data. It |
iv123 | 0:4946262d6030 | 159 | * will be modified according to the new data in the IFR_config |
iv123 | 0:4946262d6030 | 160 | * structure. Then this data must be written in the last |
iv123 | 0:4946262d6030 | 161 | * 64-byte block in the IFR. |
iv123 | 0:4946262d6030 | 162 | * Its size must be 64 bytes. |
iv123 | 0:4946262d6030 | 163 | * @retval None |
iv123 | 0:4946262d6030 | 164 | */ |
iv123 | 0:4946262d6030 | 165 | void change_IFR_data_config(IFR_config2_TypeDef *IFR_config, uint8_t data[64]); |
iv123 | 0:4946262d6030 | 166 | |
iv123 | 0:4946262d6030 | 167 | /** |
iv123 | 0:4946262d6030 | 168 | * @brief Get BlueNRG hardware and firmware version |
iv123 | 0:4946262d6030 | 169 | * @param hwVersion This parameter returns the Hardware Version (i.e. CUT 3.0 = 0x30, CUT 3.1 = 0x31). |
iv123 | 0:4946262d6030 | 170 | * @param fwVersion This parameter returns the Firmware Version in the format 0xJJMN |
iv123 | 0:4946262d6030 | 171 | * where JJ = Major Version number, M = Minor Version number and N = Patch Version number. |
iv123 | 0:4946262d6030 | 172 | * @retval Status of the call |
iv123 | 0:4946262d6030 | 173 | */ |
iv123 | 0:4946262d6030 | 174 | uint8_t getBlueNRGVersion(uint8_t *hwVersion, uint16_t *fwVersion); |
iv123 | 0:4946262d6030 | 175 | |
iv123 | 0:4946262d6030 | 176 | /** |
iv123 | 0:4946262d6030 | 177 | * @brief Get BlueNRG updater version |
iv123 | 0:4946262d6030 | 178 | * @param version This parameter returns the updater version. If the updadter version is 0x03 |
iv123 | 0:4946262d6030 | 179 | * the chip has the updater old, needs to update the bootloader. |
iv123 | 0:4946262d6030 | 180 | * @retval Status of the call |
iv123 | 0:4946262d6030 | 181 | */ |
iv123 | 0:4946262d6030 | 182 | uint8_t getBlueNRGUpdaterVersion(uint8_t *version); |
iv123 | 0:4946262d6030 | 183 | |
iv123 | 0:4946262d6030 | 184 | /** |
iv123 | 0:4946262d6030 | 185 | * @brief Get BlueNRG HW version in bootloader mode |
iv123 | 0:4946262d6030 | 186 | * @param version This parameter returns the updater HW version. |
iv123 | 0:4946262d6030 | 187 | * @retval Status of the call |
iv123 | 0:4946262d6030 | 188 | */ |
iv123 | 0:4946262d6030 | 189 | uint8_t getBlueNRGUpdaterHWVersion(uint8_t *version); |
iv123 | 0:4946262d6030 | 190 | |
iv123 | 0:4946262d6030 | 191 | /** |
iv123 | 0:4946262d6030 | 192 | * @brief Verifies if the bootloader is patched or not. This function shall be used to fix a bug on |
iv123 | 0:4946262d6030 | 193 | * the HW bootloader related to the 32 MHz external crystal oscillator. |
iv123 | 0:4946262d6030 | 194 | * @retval TRUE if the HW bootloader is already patched, FALSE otherwise |
iv123 | 0:4946262d6030 | 195 | */ |
iv123 | 0:4946262d6030 | 196 | uint8_t isHWBootloader_Patched(void); |
iv123 | 0:4946262d6030 | 197 | |
iv123 | 0:4946262d6030 | 198 | #ifdef __cplusplus |
iv123 | 0:4946262d6030 | 199 | } |
iv123 | 0:4946262d6030 | 200 | #endif |
iv123 | 0:4946262d6030 | 201 | |
iv123 | 0:4946262d6030 | 202 | #endif /*__BLUENRG_UTILS_H */ |
iv123 | 0:4946262d6030 | 203 | |
iv123 | 0:4946262d6030 | 204 | /************************ (C) COPYRIGHT STMicroelectronics *****END OF FILE****/ |