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_hal_aci.h@307:fa98703ece8e, 2016-09-16 (annotated)

Committer:
Andrea Palmieri
Date:
Fri Sep 16 12:03:25 2016 +0200
Revision:
307:fa98703ece8e
Parent:
229:9981f62cdb1a 
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_hal_aci.h
Wolfgang Betz 132:51056160fa4a 3 * Author : AMS - AAS
Wolfgang Betz 132:51056160fa4a 4 * Version : V1.0.0
Wolfgang Betz 132:51056160fa4a 5 * Date : 26-Jun-2014
Wolfgang Betz 132:51056160fa4a 6 * Description : Header file with HCI commands for BlueNRG FW6.3.
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 #ifndef __BLUENRG_HAL_ACI_H__
Wolfgang Betz 132:51056160fa4a 17 #define __BLUENRG_HAL_ACI_H__
Wolfgang Betz 132:51056160fa4a 18
Wolfgang Betz 132:51056160fa4a 19 /**
Wolfgang Betz 132:51056160fa4a 20 *@addtogroup HAL HAL
Wolfgang Betz 132:51056160fa4a 21 *@brief Hardware Abstraction Layer.
Wolfgang Betz 132:51056160fa4a 22 *@{
Wolfgang Betz 132:51056160fa4a 23 */
Wolfgang Betz 132:51056160fa4a 24
Wolfgang Betz 132:51056160fa4a 25 /**
Wolfgang Betz 132:51056160fa4a 26 * @defgroup HAL_Functions HAL functions
Wolfgang Betz 132:51056160fa4a 27 * @brief API for BlueNRG HAL layer.
Wolfgang Betz 132:51056160fa4a 28 * @{
Wolfgang Betz 132:51056160fa4a 29 */
Wolfgang Betz 132:51056160fa4a 30
Wolfgang Betz 132:51056160fa4a 31 /**
Wolfgang Betz 132:51056160fa4a 32 * @brief This command writes a value to a low level configure data structure.
Wolfgang Betz 132:51056160fa4a 33 * @note It is useful to setup directly some low level parameters for the system at runtime.
Wolfgang Betz 132:51056160fa4a 34 * @param offset Offset in the data structure. The starting member in the data structure will have an offset 0.\n
Wolfgang Betz 132:51056160fa4a 35 * See @ref Config_vals.
Wolfgang Betz 132:51056160fa4a 36 *
Wolfgang Betz 132:51056160fa4a 37 * @param len Length of data to be written
Wolfgang Betz 132:51056160fa4a 38 * @param[out] val Data to be written
Wolfgang Betz 132:51056160fa4a 39 * @return Value indicating success or error code.
Wolfgang Betz 132:51056160fa4a 40 */
Wolfgang Betz 132:51056160fa4a 41 tBleStatus aci_hal_write_config_data(uint8_t offset,
Wolfgang Betz 132:51056160fa4a 42 uint8_t len,
Wolfgang Betz 132:51056160fa4a 43 const uint8_t *val);
Wolfgang Betz 132:51056160fa4a 44
Wolfgang Betz 132:51056160fa4a 45 /**
Andrea Palmieri 229:9981f62cdb1a 46 * @brief This command requests the value in the low level configure data structure.
Andrea Palmieri 229:9981f62cdb1a 47 * The number of read bytes changes for different Offset.
Andrea Palmieri 229:9981f62cdb1a 48 * @param offset Offset in the data structure. The starting member in the data structure will have an offset 0.\n
Andrea Palmieri 229:9981f62cdb1a 49 * See @ref Config_vals.
Andrea Palmieri 229:9981f62cdb1a 50 * @param data_len Length of the data buffer
Andrea Palmieri 229:9981f62cdb1a 51 * @param[out] data_len_out_p length of the data returned by the read.
Andrea Palmieri 229:9981f62cdb1a 52 * @param[out] data Read data
Andrea Palmieri 229:9981f62cdb1a 53 * @return Value indicating success or error code.
Andrea Palmieri 229:9981f62cdb1a 54 */
Andrea Palmieri 229:9981f62cdb1a 55 tBleStatus aci_hal_read_config_data(uint8_t offset, uint16_t data_len, uint8_t *data_len_out_p, uint8_t *data);
Andrea Palmieri 229:9981f62cdb1a 56
Andrea Palmieri 229:9981f62cdb1a 57 /**
Wolfgang Betz 132:51056160fa4a 58 * @brief This command sets the TX power level of the BlueNRG.
Wolfgang Betz 132:51056160fa4a 59 * @note By controlling the EN_HIGH_POWER and the PA_LEVEL, the combination of the 2 determines
Wolfgang Betz 132:51056160fa4a 60 * the output power level (dBm).
Wolfgang Betz 132:51056160fa4a 61 * When the system starts up or reboots, the default TX power level will be used, which is
Wolfgang Betz 132:51056160fa4a 62 * the maximum value of 8dBm. Once this command is given, the output power will be changed
Wolfgang Betz 132:51056160fa4a 63 * instantly, regardless if there is Bluetooth communication going on or not. For example,
Wolfgang Betz 132:51056160fa4a 64 * for debugging purpose, the BlueNRG can be set to advertise all the time and use this
Wolfgang Betz 132:51056160fa4a 65 * command to observe the signal strength changing. The system will keep the last received
Wolfgang Betz 132:51056160fa4a 66 * TX power level from the command, i.e. the 2nd command overwrites the previous TX power
Wolfgang Betz 132:51056160fa4a 67 * level. The new TX power level remains until another Set TX Power command, or the system
Wolfgang Betz 132:51056160fa4a 68 * reboots.\n
Wolfgang Betz 132:51056160fa4a 69 * @param en_high_power Can be only 0 or 1. Set high power bit on or off. It is strongly adviced to use the
Wolfgang Betz 132:51056160fa4a 70 * right value, depending on the selected hardware configuration for the RF network:
Wolfgang Betz 132:51056160fa4a 71 * normal mode or high power mode.
Wolfgang Betz 132:51056160fa4a 72 * @param pa_level Can be from 0 to 7. Set the PA level value.
Wolfgang Betz 132:51056160fa4a 73 * @return Value indicating success or error code.
Wolfgang Betz 132:51056160fa4a 74 */
Wolfgang Betz 132:51056160fa4a 75 tBleStatus aci_hal_set_tx_power_level(uint8_t en_high_power, uint8_t pa_level);
Wolfgang Betz 132:51056160fa4a 76
Wolfgang Betz 132:51056160fa4a 77 /**
Andrea Palmieri 229:9981f62cdb1a 78 * @brief This command returns the number of packets sent in Direct Test Mode.
Andrea Palmieri 229:9981f62cdb1a 79 * @note When the Direct TX test is started, a 32-bit counter is used to count how many packets
Andrea Palmieri 229:9981f62cdb1a 80 * have been transmitted. This command can be used to check how many packets have been sent
Andrea Palmieri 229:9981f62cdb1a 81 * during the Direct TX test.\n
Andrea Palmieri 229:9981f62cdb1a 82 * The counter starts from 0 and counts upwards. The counter can wrap and start from 0 again.
Andrea Palmieri 229:9981f62cdb1a 83 * The counter is not cleared until the next Direct TX test starts.
Andrea Palmieri 229:9981f62cdb1a 84 * @param[out] number_of_packets Number of packets sent during the last Direct TX test.
Andrea Palmieri 229:9981f62cdb1a 85 * @return Value indicating success or error code.
Andrea Palmieri 229:9981f62cdb1a 86 */
Andrea Palmieri 229:9981f62cdb1a 87 tBleStatus aci_hal_le_tx_test_packet_number(uint32_t *number_of_packets);
Andrea Palmieri 229:9981f62cdb1a 88
Andrea Palmieri 229:9981f62cdb1a 89 /**
Wolfgang Betz 132:51056160fa4a 90 * @brief Put the device in standby mode.
Wolfgang Betz 132:51056160fa4a 91 * @note Normally the BlueNRG will automatically enter sleep mode to save power. This command puts the
Wolfgang Betz 132:51056160fa4a 92 * device into the Standby mode instead of the sleep mode. The difference is that, in sleep mode,
Wolfgang Betz 132:51056160fa4a 93 * the device can still wake up itself with the internal timer. But in standby mode, this timer is
Wolfgang Betz 132:51056160fa4a 94 * disabled. So the only possibility to wake up the device is by external signals, e.g. a HCI command
Wolfgang Betz 132:51056160fa4a 95 * sent via SPI bus.
Wolfgang Betz 132:51056160fa4a 96 * The command is only accepted when there is no other Bluetooth activity. Otherwise an error code
Wolfgang Betz 132:51056160fa4a 97 * ERR_COMMAND_DISALLOWED will be returned.
Wolfgang Betz 132:51056160fa4a 98 *
Wolfgang Betz 132:51056160fa4a 99 * @return Value indicating success or error code.
Wolfgang Betz 132:51056160fa4a 100 */
Wolfgang Betz 132:51056160fa4a 101 tBleStatus aci_hal_device_standby(void);
Wolfgang Betz 132:51056160fa4a 102
Wolfgang Betz 132:51056160fa4a 103 /**
Wolfgang Betz 132:51056160fa4a 104 * @brief This command starts a carrier frequency, i.e. a tone, on a specific channel.
Wolfgang Betz 132:51056160fa4a 105 * @note The frequency sine wave at the specific channel may be used for test purpose only.
Wolfgang Betz 132:51056160fa4a 106 * The channel ID is a parameter from 0 to 39 for the 40 BLE channels, e.g. 0 for 2.402GHz, 1 for 2.404GHz etc.
Wolfgang Betz 132:51056160fa4a 107 * This command shouldn't be used when normal Bluetooth activities are ongoing.
Wolfgang Betz 132:51056160fa4a 108 * The tone should be stopped by aci_hal_tone_stop() command.
Wolfgang Betz 132:51056160fa4a 109 *
Wolfgang Betz 132:51056160fa4a 110 * @param rf_channel BLE Channel ID, from 0 to 39 meaning (2.402 + 2*N) GHz. Actually the tone will be emitted at the
Wolfgang Betz 132:51056160fa4a 111 * channel central frequency minus 250 kHz.
Wolfgang Betz 132:51056160fa4a 112 * @return Value indicating success or error code.
Wolfgang Betz 132:51056160fa4a 113 */
Wolfgang Betz 132:51056160fa4a 114 tBleStatus aci_hal_tone_start(uint8_t rf_channel);
Wolfgang Betz 132:51056160fa4a 115
Wolfgang Betz 132:51056160fa4a 116 /**
Wolfgang Betz 132:51056160fa4a 117 * This command is used to stop the previously started aci_hal_tone_start() command.
Wolfgang Betz 132:51056160fa4a 118 * @return Value indicating success or error code.
Wolfgang Betz 132:51056160fa4a 119 */
Wolfgang Betz 132:51056160fa4a 120 tBleStatus aci_hal_tone_stop(void);
Wolfgang Betz 132:51056160fa4a 121
Wolfgang Betz 132:51056160fa4a 122 /**
Wolfgang Betz 132:51056160fa4a 123 * @}
Wolfgang Betz 132:51056160fa4a 124 */
Wolfgang Betz 132:51056160fa4a 125
Wolfgang Betz 132:51056160fa4a 126 /**
Wolfgang Betz 132:51056160fa4a 127 * @defgroup Config_vals Offsets and lengths for configuration values.
Wolfgang Betz 132:51056160fa4a 128 * @brief Offsets and lengths for configuration values.
Wolfgang Betz 132:51056160fa4a 129 * See aci_hal_write_config_data().
Wolfgang Betz 132:51056160fa4a 130 * @{
Wolfgang Betz 132:51056160fa4a 131 */
Wolfgang Betz 132:51056160fa4a 132
Wolfgang Betz 132:51056160fa4a 133 /**
Wolfgang Betz 132:51056160fa4a 134 * @name Configuration values.
Wolfgang Betz 132:51056160fa4a 135 * See @ref aci_hal_write_config_data().
Wolfgang Betz 132:51056160fa4a 136 * @{
Wolfgang Betz 132:51056160fa4a 137 */
Wolfgang Betz 132:51056160fa4a 138 #define CONFIG_DATA_PUBADDR_OFFSET (0x00) /**< Bluetooth public address */
Wolfgang Betz 132:51056160fa4a 139 #define CONFIG_DATA_DIV_OFFSET (0x06) /**< DIV used to derive CSRK */
Wolfgang Betz 132:51056160fa4a 140 #define CONFIG_DATA_ER_OFFSET (0x08) /**< Encryption root key used to derive LTK and CSRK */
Wolfgang Betz 132:51056160fa4a 141 #define CONFIG_DATA_IR_OFFSET (0x18) /**< Identity root key used to derive LTK and CSRK */
Wolfgang Betz 132:51056160fa4a 142 #define CONFIG_DATA_LL_WITHOUT_HOST (0x2C) /**< Switch on/off Link Layer only mode. Set to 1 to disable Host.
Wolfgang Betz 132:51056160fa4a 143 It can be written only if aci_hal_write_config_data() is the first command
Wolfgang Betz 132:51056160fa4a 144 after reset. */
Wolfgang Betz 132:51056160fa4a 145
Andrea Palmieri 229:9981f62cdb1a 146 #define CONFIG_DATA_RANDOM_ADDRESS_IDB05A1 (0x80) /**< Stored static random address. Read-only (IDB05A1 only) */
Andrea Palmieri 229:9981f62cdb1a 147
Wolfgang Betz 132:51056160fa4a 148 /**
Wolfgang Betz 132:51056160fa4a 149 * Select the BlueNRG roles and mode configurations.\n
Wolfgang Betz 132:51056160fa4a 150 * @li Mode 1: slave or master, 1 connection, RAM1 only (small GATT DB)
Wolfgang Betz 132:51056160fa4a 151 * @li Mode 2: slave or master, 1 connection, RAM1 and RAM2 (large GATT DB)
Wolfgang Betz 132:51056160fa4a 152 * @li Mode 3: master only, 8 connections, RAM1 and RAM2.
Wolfgang Betz 132:51056160fa4a 153 */
Wolfgang Betz 132:51056160fa4a 154 #define CONFIG_DATA_ROLE (0x2D)
Wolfgang Betz 132:51056160fa4a 155 /**
Wolfgang Betz 132:51056160fa4a 156 * @}
Wolfgang Betz 132:51056160fa4a 157 */
Wolfgang Betz 132:51056160fa4a 158
Wolfgang Betz 132:51056160fa4a 159 /**
Wolfgang Betz 132:51056160fa4a 160 * @name Length for configuration values.
Wolfgang Betz 132:51056160fa4a 161 * See @ref aci_hal_write_config_data().
Wolfgang Betz 132:51056160fa4a 162 * @{
Wolfgang Betz 132:51056160fa4a 163 */
Wolfgang Betz 132:51056160fa4a 164 #define CONFIG_DATA_PUBADDR_LEN (6)
Wolfgang Betz 132:51056160fa4a 165 #define CONFIG_DATA_DIV_LEN (2)
Wolfgang Betz 132:51056160fa4a 166 #define CONFIG_DATA_ER_LEN (16)
Wolfgang Betz 132:51056160fa4a 167 #define CONFIG_DATA_IR_LEN (16)
Wolfgang Betz 132:51056160fa4a 168 #define CONFIG_DATA_LL_WITHOUT_HOST_LEN (1)
Wolfgang Betz 132:51056160fa4a 169 #define CONFIG_DATA_ROLE_LEN (1)
Wolfgang Betz 132:51056160fa4a 170 /**
Wolfgang Betz 132:51056160fa4a 171 * @}
Wolfgang Betz 132:51056160fa4a 172 */
Wolfgang Betz 132:51056160fa4a 173
Wolfgang Betz 132:51056160fa4a 174 /**
Wolfgang Betz 132:51056160fa4a 175 * @}
Wolfgang Betz 132:51056160fa4a 176 */
Wolfgang Betz 132:51056160fa4a 177
Wolfgang Betz 132:51056160fa4a 178 /**
Wolfgang Betz 132:51056160fa4a 179 * @}
Wolfgang Betz 132:51056160fa4a 180 */
Wolfgang Betz 132:51056160fa4a 181
Wolfgang Betz 132:51056160fa4a 182
Wolfgang Betz 132:51056160fa4a 183 #endif /* __BLUENRG_HAL_ACI_H__ */