bluenrg_hal_aci.h

00001 /******************** (C) COPYRIGHT 2014 STMicroelectronics ********************
00002 * File Name          : bluenrg_hal_aci.h
00003 * Author             : AMS - AAS
00004 * Version            : V1.0.0
00005 * Date               : 26-Jun-2014
00006 * Description        : Header file with HCI commands for BlueNRG FW6.3.
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 #ifndef __BLUENRG_HAL_ACI_H__
00017 #define __BLUENRG_HAL_ACI_H__
00018 
00019 /**
00020  *@addtogroup HAL HAL
00021  *@brief Hardware Abstraction Layer.
00022  *@{
00023  */
00024 
00025 /**
00026  * @defgroup HAL_Functions HAL functions
00027  * @brief API for BlueNRG HAL layer.
00028  * @{
00029  */
00030 
00031 /**
00032  * @brief This command writes a value to a low level configure data structure.
00033  * @note  It is useful to setup directly some low level parameters for the system at runtime.
00034  * @param offset Offset in the data structure. The starting member in the data structure will have an offset 0.\n
00035  *               See @ref Config_vals.
00036  *
00037  * @param len Length of data to be written
00038  * @param[out] val Data to be written
00039  * @return Value indicating success or error code.
00040  */
00041 tBleStatus aci_hal_write_config_data(uint8_t offset, 
00042                                     uint8_t len,
00043                                     const uint8_t *val);
00044 
00045 /**
00046  * @brief This command sets the TX power level of the BlueNRG.
00047  * @note  By controlling the EN_HIGH_POWER and the PA_LEVEL, the combination of the 2 determines
00048  *        the output power level (dBm).
00049  *        When the system starts up or reboots, the default TX power level will be used, which is
00050  *        the maximum value of 8dBm. Once this command is given, the output power will be changed
00051  *        instantly, regardless if there is Bluetooth communication going on or not. For example,
00052  *        for debugging purpose, the BlueNRG can be set to advertise all the time and use this
00053  *        command to observe the signal strength changing. The system will keep the last received
00054  *        TX power level from the command, i.e. the 2nd command overwrites the previous TX power
00055  *        level. The new TX power level remains until another Set TX Power command, or the system
00056  *        reboots.\n
00057  * @param en_high_power Can be only 0 or 1. Set high power bit on or off. It is strongly adviced to use the
00058  *                      right value, depending on the selected hardware configuration for the RF network:
00059  *                      normal mode or high power mode.
00060  * @param pa_level Can be from 0 to 7. Set the PA level value.
00061  * @return Value indicating success or error code.
00062  */
00063 tBleStatus aci_hal_set_tx_power_level(uint8_t en_high_power, uint8_t pa_level);
00064 
00065 /**
00066  * @brief Put the device in standby mode.
00067  * @note Normally the BlueNRG will automatically enter sleep mode to save power. This command puts the
00068  *       device into the Standby mode instead of the sleep mode. The difference is that, in sleep mode,
00069  *       the device can still wake up itself with the internal timer. But in standby mode, this timer is
00070  *       disabled. So the only possibility to wake up the device is by external signals, e.g. a HCI command
00071  *       sent via SPI bus.
00072  *       The command is only accepted when there is no other Bluetooth activity. Otherwise an error code
00073  *       ERR_COMMAND_DISALLOWED will be returned.
00074  *
00075  * @return Value indicating success or error code.
00076  */
00077 tBleStatus aci_hal_device_standby(void);
00078 
00079 /**
00080  * @brief This command starts a carrier frequency, i.e. a tone, on a specific channel.
00081  * @note  The frequency sine wave at the specific channel may be used for test purpose only.
00082  *        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.
00083  *        This command shouldn't be used when normal Bluetooth activities are ongoing.
00084  *        The tone should be stopped by aci_hal_tone_stop() command.
00085  *
00086  * @param rf_channel BLE Channel ID, from 0 to 39 meaning (2.402 + 2*N) GHz. Actually the tone will be emitted at the
00087  *                   channel central frequency minus 250 kHz.
00088  * @return Value indicating success or error code.
00089  */
00090 tBleStatus aci_hal_tone_start(uint8_t rf_channel);
00091 
00092 /**
00093  * This command is used to stop the previously started aci_hal_tone_start() command.
00094  * @return Value indicating success or error code.
00095  */
00096 tBleStatus aci_hal_tone_stop(void);
00097 
00098 /**
00099  * @}
00100  */
00101 
00102 /**
00103  * @defgroup Config_vals Offsets and lengths for configuration values.
00104  * @brief Offsets and lengths for configuration values.
00105  *        See aci_hal_write_config_data().
00106  * @{
00107  */
00108 
00109 /**
00110  * @name Configuration values.
00111  * See @ref aci_hal_write_config_data().
00112  * @{
00113  */
00114 #define CONFIG_DATA_PUBADDR_OFFSET          (0x00) /**< Bluetooth public address */
00115 #define CONFIG_DATA_DIV_OFFSET              (0x06) /**< DIV used to derive CSRK */
00116 #define CONFIG_DATA_ER_OFFSET               (0x08) /**< Encryption root key used to derive LTK and CSRK */
00117 #define CONFIG_DATA_IR_OFFSET               (0x18) /**< Identity root key used to derive LTK and CSRK */
00118 #define CONFIG_DATA_LL_WITHOUT_HOST         (0x2C) /**< Switch on/off Link Layer only mode. Set to 1 to disable Host.
00119                                                      It can be written only if aci_hal_write_config_data() is the first command
00120                                                      after reset. */
00121 
00122 /**
00123  * Select the BlueNRG roles and mode configurations.\n
00124  * @li Mode 1: slave or master, 1 connection, RAM1 only (small GATT DB)
00125  * @li Mode 2: slave or master, 1 connection, RAM1 and RAM2 (large GATT DB)
00126  * @li Mode 3: master only, 8 connections, RAM1 and RAM2.
00127  */
00128 #define CONFIG_DATA_ROLE                    (0x2D)
00129 /**
00130  * @}
00131  */
00132 
00133 /**
00134  * @name Length for configuration values.
00135  * See @ref aci_hal_write_config_data().
00136  * @{
00137  */
00138 #define CONFIG_DATA_PUBADDR_LEN             (6)
00139 #define CONFIG_DATA_DIV_LEN                 (2)
00140 #define CONFIG_DATA_ER_LEN                  (16)
00141 #define CONFIG_DATA_IR_LEN                  (16)
00142 #define CONFIG_DATA_LL_WITHOUT_HOST_LEN     (1)
00143 #define CONFIG_DATA_ROLE_LEN                (1)
00144 /**
00145  * @}
00146  */
00147 
00148 /**
00149  * @}
00150  */
00151 
00152 /**
00153  * @}
00154  */
00155 
00156 
00157 #endif /* __BLUENRG_HAL_ACI_H__ */