iv123 lin / TARGET_ST_BLE

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?

UserRevisionLine numberNew 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****/