bluenrg_utils.h

00001 /******************** (C) COPYRIGHT 2014 STMicroelectronics ********************
00002 * File Name          : bluenrg_utils.h
00003 * Author             : AMS - VMA, RF Application Team
00004 * Version            : V1.0.1
00005 * Date               : 03-October-2014
00006 * Description        : Header file for BlueNRG utility functions 
00007 ********************************************************************************
00008 * THE PRESENT FIRMWARE WHICH IS FOR GUIDANCE ONLY AIMS AT PROVIDING CUSTOMERS
00009 * WITH CODING INFORMATION REGARDING THEIR PRODUCTS IN ORDER FOR THEM TO SAVE TIME.
00010 * AS A RESULT, STMICROELECTRONICS SHALL NOT BE HELD LIABLE FOR ANY DIRECT,
00011 * INDIRECT OR CONSEQUENTIAL DAMAGES WITH RESPECT TO ANY CLAIMS ARISING FROM THE
00012 * CONTENT OF SUCH FIRMWARE AND/OR THE USE MADE BY CUSTOMERS OF THE CODING
00013 * INFORMATION CONTAINED HEREIN IN CONNECTION WITH THEIR PRODUCTS.
00014 *******************************************************************************/
00015 /**
00016  * @file  bluenrg_utils.h
00017  * @brief BlueNRG IFR updater & BlueNRG stack updater utility APIs description
00018  *
00019  * <!-- Copyright 2014 by STMicroelectronics.  All rights reserved.       *80*-->
00020 **/
00021 /* Define to prevent recursive inclusion -------------------------------------*/
00022 #ifndef __BLUENRG_UTILS_H
00023 #define __BLUENRG_UTILS_H
00024 
00025 #ifdef __cplusplus
00026  extern "C" {
00027 #endif
00028 
00029 /* Includes ------------------------------------------------------------------*/
00030 #include "ble_hal_types.h" 
00031 #include "ble_compiler.h"
00032 
00033 /* Exported types ------------------------------------------------------------*/
00034 typedef struct{
00035   uint8_t stack_mode;
00036   uint8_t day;
00037   uint8_t month;
00038   uint8_t year;
00039   uint16_t slave_sca_ppm;
00040   uint8_t master_sca;
00041   uint16_t hs_startup_time; /* In system time units*/
00042 } IFR_config2_TypeDef;
00043 
00044 /**
00045  * Structure inside IFR for configuration options. 
00046  */
00047 typedef __packed struct{
00048   uint8_t cold_ana_act_config_table[64];
00049   uint8_t hot_ana_config_table[64];
00050   uint8_t stack_mode;
00051   uint8_t gpio_config;
00052   uint8_t rsrvd1[2];
00053   uint32_t rsrvd2[3];
00054   uint32_t max_conn_event_time;
00055   uint32_t ls_crystal_period;
00056   uint32_t ls_crystal_freq;
00057   uint16_t slave_sca_ppm;
00058   uint8_t master_sca;
00059   uint8_t rsrvd3;
00060   uint16_t hs_startup_time; /* In system time units*/
00061   uint8_t rsrvd4[2];
00062   uint32_t uid;
00063   uint8_t rsrvd5;
00064   uint8_t year;  
00065   uint8_t month;
00066   uint8_t day;
00067   uint32_t unused[5];
00068 } PACKED IFR_config_TypeDef;
00069 
00070 /* Exported constants --------------------------------------------------------*/
00071 extern const IFR_config_TypeDef IFR_config;
00072 
00073 /* Exported macros -----------------------------------------------------------*/
00074 #define FROM_US_TO_SYS_TIME(us)      ((uint16_t)(us/2.4414))
00075 #define FROM_SYS_TIME_TO_US(sys)     ((uint16_t)(sys*2.4414))
00076 
00077 /* Convert 2 digit BCD number to an integer */
00078 #define BCD_TO_INT(bcd) ((bcd & 0xF) + ((bcd & 0xF0) >> 4)*10)
00079 
00080 /* Convert 2 digit number to a BCD number */
00081 #define INT_TO_BCD(n) ((((uint8_t)n/10)<<4) + (uint8_t)n%10)
00082 
00083 /** 
00084   * Return values 
00085   */ 
00086 #define BLE_UTIL_SUCCESS                 0
00087 #define BLE_UTIL_UNSUPPORTED_VERSION     1
00088 #define BLE_UTIL_WRONG_IMAGE_SIZE        2
00089 #define BLE_UTIL_ACI_ERROR               3
00090 #define BLE_UTIL_CRC_ERROR               4
00091 #define BLE_UTIL_PARSE_ERROR             5
00092 #define BLE_UTIL_WRONG_VERIFY            6
00093 
00094 /* Exported functions ------------------------------------------------------- */ 
00095 /**
00096   * @brief  Flash a new firmware using internal bootloader.
00097   * @param  fw_image     Pointer to the firmware image (raw binary data,
00098   *                      little-endian).
00099   * @param  fw_size      Size of the firmware image. The firmware image size shall
00100   *                      be multiple of 4 bytes.
00101   * @retval int      It returns 0 if successful, or a number not equal to 0 in
00102   *                  case of error (ACI_ERROR, UNSUPPORTED_VERSION,
00103   *                  WRONG_IMAGE_SIZE, CRC_ERROR)
00104   */
00105 int program_device(const uint8_t *fw_image, uint32_t fw_size);
00106 
00107 /**
00108   * @brief  Read raw data from IFR (3 64-bytes blocks).
00109   * @param  data     Pointer to the buffer that will contain the read data.
00110   *                  Its size must be 192 bytes. This data can be parsed by
00111   *                  parse_IFR_data_config().
00112   * @retval int      It returns 0 if successful, or a number not equal to 0 in
00113   *                  case of error (ACI_ERROR, UNSUPPORTED_VERSION)
00114   */
00115 int read_IFR(uint8_t data[192]);
00116 
00117 /**
00118   * @brief  Verify raw data from IFR (3 64-bytes blocks).
00119   * @param  ifr_data Pointer to the buffer that will contain the data to verify.
00120   *                  Its size must be 192 bytes.
00121   * @retval int      It returns 0 if successful, or a number not equal to 0 in
00122                      case of error (ACI_ERROR, BLE_UTIL_WRONG_VERIFY)
00123   */
00124 uint8_t verify_IFR(const IFR_config_TypeDef *ifr_data);
00125 
00126 /**
00127   * @brief  Program raw data to IFR (3 64-bytes blocks).
00128   * @param  ifr_image     Pointer to the buffer that will contain the data to program.
00129   *                  Its size must be 192 bytes.
00130   * @retval int      It returns 0 if successful
00131   */
00132 int program_IFR(const IFR_config_TypeDef *ifr_image);
00133 
00134 /**
00135   * @brief  Parse IFR raw data.
00136   * @param  data     Pointer to the raw data: last 64 bytes read from IFR sector.
00137   * @param  IFR_config     Data structure that will be filled with parsed data.
00138   * @retval None
00139   */
00140 void parse_IFR_data_config(const uint8_t data[64], IFR_config2_TypeDef *IFR_config);
00141 
00142 /**
00143   * @brief  Check for the correctness of parsed data.
00144   * @param  IFR_config     Data structure filled with parsed data.
00145   * @retval int      It returns 0 if successful, or PARSE_ERROR in case data is
00146   *                  not correct.
00147   */
00148 int IFR_validate(IFR_config2_TypeDef *IFR_config);
00149 
00150 /**
00151   * @brief  Modify IFR data. (Last 64-bytes block).
00152   * @param  IFR_config   Structure that contains the new parameters inside the
00153   *                      IFR configuration data.
00154   * @note   It is highly recommended to parse the IFR configuration from
00155   *         a working IFR block (this should be done with parse_IFR_data_config()).
00156   *         Then it is possible to write the new parameters inside the IFR_config
00157   *         structure.
00158   * @param  data     Pointer to the buffer that contains the original data. It
00159   *                  will be modified according to the new data in the IFR_config
00160   *                  structure. Then this data must be written in the last
00161   *                  64-byte block in the IFR.
00162   *                  Its size must be 64 bytes.
00163   * @retval None
00164   */
00165 void change_IFR_data_config(IFR_config2_TypeDef *IFR_config, uint8_t data[64]);
00166 
00167 /**
00168   * @brief  Get BlueNRG hardware and firmware version
00169   * @param  hwVersion This parameter returns the Hardware Version (i.e. CUT 3.0 = 0x30, CUT 3.1 = 0x31).
00170   * @param  fwVersion This parameter returns the Firmware Version in the format 0xJJMN
00171   *                   where JJ = Major Version number, M = Minor Version number and N = Patch Version number.
00172   * @retval Status of the call
00173   */
00174 uint8_t getBlueNRGVersion(uint8_t *hwVersion, uint16_t *fwVersion);
00175 
00176 /**
00177   * @brief  Get BlueNRG updater version
00178   * @param  version This parameter returns the updater version. If the updadter version is 0x03 
00179   *                 the chip has the updater old, needs to update the bootloader.
00180   * @retval Status of the call
00181   */
00182 uint8_t getBlueNRGUpdaterVersion(uint8_t *version);
00183 
00184 /**
00185   * @brief  Get BlueNRG HW version in bootloader mode
00186   * @param  version This parameter returns the updater HW version.
00187   * @retval Status of the call
00188   */
00189 uint8_t getBlueNRGUpdaterHWVersion(uint8_t *version);
00190 
00191 /**
00192   * @brief  Verifies if the bootloader is patched or not. This function shall be used to fix a bug on
00193   *         the HW bootloader related to the 32 MHz external crystal oscillator.
00194   * @retval TRUE if the HW bootloader is already patched, FALSE otherwise
00195   */
00196 uint8_t isHWBootloader_Patched(void);
00197    
00198 #ifdef __cplusplus
00199 }
00200 #endif
00201 
00202 #endif /*__BLUENRG_UTILS_H */
00203 
00204 /************************ (C) COPYRIGHT STMicroelectronics *****END OF FILE****/