Antonio Vilei / X_NUCLEO_IDB0XA1

BLE_API wrapper library for STMicroelectronics' BlueNRG Bluetooth Low Energy expansion board shield

Fork of X_NUCLEO_IDB0XA1 by ST Expansion SW Team

x-nucleo-idb0xa1/bluenrg-hci/bluenrg_utils.h@132:51056160fa4a, 2015-10-07 (annotated)

Committer:
Wolfgang Betz
Date:
Wed Oct 07 08:39:04 2015 +0200
Revision:
132:51056160fa4a
Child:
232:f2a7da5d24e1
Andrea's version as of mail from 10/06/2015 05:56 PM



From: Andrea PALMIERI <andrea.palmieri@st.com>

To: Wolfgang BETZ <wolfgang.betz@st.com>, Rohit Grover <rohit.grover@arm.com>,

	Antonio VILEI <antonio.vilei@st.com>, Mihail Stoyanov

	<Mihail.Stoyanov@arm.com>

CC: Nicola CAPOVILLA <nicola.capovilla@st.com>, Silvio Lucio OLIVA

	<silvio.oliva@st.com>, "jonathan.austin@arm.com" <jonathan.austin@arm.com>

Content-Class: urn:content-classes:message

Date: Tue, 6 Oct 2015 17:56:34 +0200

Subject: RE: Arduino Compatibility of X-NUCLEO-IDB04A1

Who changed what in which revision?

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