ST / X_NUCLEO_IDB0XA1

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

Dependents:   Nucleo_Zumo_BLE_IDB04A1 contest_IOT5 contest_IOT6 contest_IOT_10 ... more

Fork of X_NUCLEO_IDB0XA1 by ST Expansion SW Team

Arduino Connector Compatibility Warning

X-NUCLEO-IDB04A1 and X-NUCLEO-IDB05A1 are Arduino compatible with an exception: instead of using pin D13 for the SPI clock, they use pin D3. The default configuration for this library is having the SPI clock on pin D3.

To be fully Arduino compatible, X-NUCLEO-IDB04A1 and X-NUCLEO-IDB05A1 need a small HW patch.

For X-NUCLEO-IDB04A1 this patch consists in removing zero resistor R10 and instead soldering zero resistor R11. For X-NUCLEO-IDB05A1 this patch consists in removing zero resistor R4 and instead soldering zero resistor R6.

In case you patch your board, then you also have to configure this library to use pin D13 to drive the SPI clock (see macro IDB0XA1_D13_PATCH in file x_nucleo_idb0xa1_targets.h).

If you use pin D13 for the SPI clock, please be aware that on STM32 Nucleo boards you may not drive the LED, otherwise you will get a conflict: the LED on STM32 Nucleo boards is connected to pin D13.

Referring to the current list of tested platforms (see X-NUCLEO-IDB04A1 and X-NUCLEO-IDB05A1 pages), the patch is required by ST-Nucleo-F103RB; ST-Nucleo-F302R8; ST-Nucleo-F411RE; and ST-Nucleo-F446RE.

x-nucleo-idb0xa1/bluenrg-hci/bluenrg_utils.h@307:fa98703ece8e, 2016-09-16 (annotated)

Committer:
Andrea Palmieri
Date:
Fri Sep 16 12:03:25 2016 +0200
Revision:
307:fa98703ece8e
Parent:
294:fd19310b086d 
Sync with 21bfd161ace255bb6214d6b74cae1fd30b3e24c9



2016-09-16 11:53:47+02:00: Andrea Palmieri

Get rid of warnings

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 ------------------------------------------------------------------*/
Vincent Coubard 294:fd19310b086d 30 #include "ble_hal_types.h"
Vincent Coubard 294:fd19310b086d 31 #include "ble_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 /**
Antonio Vilei 245:6830f71c197c 185 * @brief Get BlueNRG HW version in bootloader mode
Antonio Vilei 245:6830f71c197c 186 * @param version This parameter returns the updater HW version.
Antonio Vilei 245:6830f71c197c 187 * @retval Status of the call
Antonio Vilei 245:6830f71c197c 188 */
Antonio Vilei 245:6830f71c197c 189 uint8_t getBlueNRGUpdaterHWVersion(uint8_t *version);
Antonio Vilei 245:6830f71c197c 190
Antonio Vilei 245:6830f71c197c 191 /**
Wolfgang Betz 132:51056160fa4a 192 * @brief Verifies if the bootloader is patched or not. This function shall be used to fix a bug on
Wolfgang Betz 132:51056160fa4a 193 * the HW bootloader related to the 32 MHz external crystal oscillator.
Wolfgang Betz 132:51056160fa4a 194 * @retval TRUE if the HW bootloader is already patched, FALSE otherwise
Wolfgang Betz 132:51056160fa4a 195 */
Wolfgang Betz 132:51056160fa4a 196 uint8_t isHWBootloader_Patched(void);
Wolfgang Betz 132:51056160fa4a 197
Wolfgang Betz 132:51056160fa4a 198 #ifdef __cplusplus
Wolfgang Betz 132:51056160fa4a 199 }
Wolfgang Betz 132:51056160fa4a 200 #endif
Wolfgang Betz 132:51056160fa4a 201
Wolfgang Betz 132:51056160fa4a 202 #endif /*__BLUENRG_UTILS_H */
Wolfgang Betz 132:51056160fa4a 203
Vincent Coubard 294:fd19310b086d 204 /************************ (C) COPYRIGHT STMicroelectronics *****END OF FILE****/