Devchannel Team / X_NUCLEO_IDB0XA1

HW layer for the Nucleo board, it only work with old BLE_API

Dependents:   Hello_BLE F446RE-BLE

Fork of X_NUCLEO_IDB0XA1 by ST

BlueNRG_HCI/includes/bluenrg_utils.h@70:d20d30f59b1c, 2015-06-08 (annotated)

Committer:
Silvio Lucio Oliva
Date:
Mon Jun 08 17:08:01 2015 +0200
Revision:
70:d20d30f59b1c
Initial commit for mbed support



Signed-off-by: Silvio Lucio Oliva <silvio.oliva@st.com>

Who changed what in which revision?

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