1 /****************************************************************************** 2 * @file ble_hal_aci.h 3 * @author MCD Application Team 4 * @date 23 May 2019 5 * @brief Header file for STM32WB (hal_aci) 6 * Auto-generated file: do not edit! 7 ****************************************************************************** 8 * @attention 9 * 10 * <h2><center>© Copyright (c) 2019 STMicroelectronics. 11 * All rights reserved.</center></h2> 12 * 13 * This software component is licensed by ST under Ultimate Liberty license 14 * SLA0044, the "License"; You may not use this file except in compliance with 15 * the License. You may obtain a copy of the License at: 16 * www.st.com/SLA0044 17 * 18 ****************************************************************************** 19 */ 20 21 #ifndef BLE_HAL_ACI_H__ 22 #define BLE_HAL_ACI_H__ 23 24 25 #include "ble_types.h" 26 27 /** 28 * @brief This command returns the build number associated with the firmware version currently running 29 * @param[out] Build_Number Build number of the firmware. 30 * @retval Value indicating success or error code. 31 */ 32 tBleStatus aci_hal_get_fw_build_number(uint16_t *Build_Number); 33 34 /** 35 * @brief This command writes a value to a low level configure data structure. It is useful to setup 36 directly some low level parameters for the system in the runtime. 37 * @param Offset Offset of the element in the configuration data structure 38 which has to be written. The valid offsets are: 39 40 - 0x00: Bluetooth public address, Value length to be written: 6 bytes 41 - 0x06: DIV used to derive CSRK, Value length to be written: 2 bytes 42 - 0x08: Encryption root key used to derive LTK and CSRK, Value length to be written: 16 bytes 43 - 0x18: Identity root key used to derive LTK and CSRK, Value length to be written: 16 bytes 44 - 0x2C: Link layer without host (for certification purposes), Value length to be written: 1 byte 45 - 0x2E: Static Random Address: 6 bytes 46 - 0x2F: Disable watchdog (1=disable, 0=enable). Value length to be written: 1 byte 47 * Values: 48 - 0x00: CONFIG_DATA_PUBADDR_OFFSET 49 - 0x06: CONFIG_DATA_DIV_OFFSET 50 - 0x08: CONFIG_DATA_ER_OFFSET 51 - 0x18: CONFIG_DATA_IR_OFFSET 52 - 0x2C: LL_WITHOUT_HOST 53 - 0x2E: CONFIG_DATA_RANDOM_ADDRESS_WR 54 - 0x2F: CONFIG_DATA_WATCHDOG_DISABLE 55 * @param Length Length of data to be written 56 * @param Value Data to be written 57 * @retval Value indicating success or error code. 58 */ 59 tBleStatus aci_hal_write_config_data(uint8_t Offset, 60 uint8_t Length, 61 uint8_t Value[]); 62 63 /** 64 * @brief This command requests the value in the low level configure data structure. 65 The number of read bytes changes for different Offset. 66 * @param Offset Offset of the element in the configuration data structure 67 which has to be read. The valid offsets are: 68 69 * 0x00: Bluetooth public address, Value length returned: 6 bytes 70 * 0x06: DIV used to derive CSRK, Value length returned: 2 bytes 71 * 0x08: Encryption root key used to derive LTK and CSRK, Value length returned: 16 bytes 72 * 0x18: Identity root key used to derive LTK and CSRK, Value length returned: 16 bytes 73 * 0x2C: Link layer without host (for certification purposes), Value length returned: 1 byte 74 * 0x2F: Disable watchdog (1=disabled, 0=enable). Value length returned: 1 byte 75 * 0x80: Static random address. Value length returned: 6 bytes (read-only) 76 * Values: 77 - 0x00: CONFIG_DATA_PUBADDR_OFFSET 78 - 0x06: CONFIG_DATA_DIV_OFFSET 79 - 0x08: CONFIG_DATA_ER_OFFSET 80 - 0x18: CONFIG_DATA_IR_OFFSET 81 - 0x2C: LL_WITHOUT_HOST 82 - 0x2F: CONFIG_DATA_WATCHDOG_DISABLE 83 - 0x80: CONFIG_DATA_RANDOM_ADDRESS 84 * @param[out] Data_Length Length of Data in octets 85 * @param[out] Data Data field associated with Offset parameter 86 * @retval Value indicating success or error code. 87 */ 88 tBleStatus aci_hal_read_config_data(uint8_t Offset, 89 uint8_t *Data_Length, 90 uint8_t Data[]); 91 92 /** 93 * @brief This command sets the TX power level of the device. By controlling the 94 PA_LEVEL, that determines the output power level (dBm) at the IC pin. 95 When the system starts up or reboots, the default TX power level will be used, which is the 96 maximum value of 6 dBm. Once this command is given, the output power will be changed 97 instantly, regardless if there is Bluetooth communication going on or not. For example, for 98 debugging purpose, the device can be set to advertise all the time. And use this 99 command to observe the signal strength changing. 100 The system will keep the last received TX power level from the command, i.e. the 2nd 101 command overwrites the previous TX power level. The new TX power level remains until 102 another Set TX Power command, or the system reboots. 103 * @param En_High_Power Enable High Power mode - Deprecated and ignored on STM32WB 104 * Values: 105 - 0x00: Standard Power 106 - 0x01: High Power 107 * @param PA_Level Power amplifier output level. Output power is indicative and it depends on the PCB layout and associated 108 components.Here the values are given at the IC pin 109 * Values: 110 - 0x00: -40 dBm 111 - 0x01: -20.85 dBm 112 - 0x02: -19.75 dBm 113 - 0x03: -18.85 dBm 114 - 0x04: -17.6 dBm 115 - 0x05: -16.5 dBm 116 - 0x06: -15.25 dBm 117 - 0x07: -14.1 dBm 118 - 0x08: -13.15 dBm 119 - 0x09: -12.05 dBm 120 - 0x0A: -10.9 dBm 121 - 0x0B: -9.9 dBm 122 - 0x0C: -8.85 dBm 123 - 0x0D: -7.8 dBm 124 - 0x0E: -6.9 dBm 125 - 0x0F: -5.9 dBm 126 - 0x10: -4.95 dBm 127 - 0x11: -4 dBm 128 - 0x12: -3.15 dBm 129 - 0x13: -2.45 dBm 130 - 0x14: -1.8 dBm 131 - 0x15: -1.3 dBm 132 - 0x16: -0.85 dBm 133 - 0x17: -0.5 dBm 134 - 0x18: -0.15 dBm 135 - 0x19: 0 dBm 136 - 0x1A: +1 dBm 137 - 0x1B: +2 dBm 138 - 0x1C: +3 dBm 139 - 0x1D: +4 dBm 140 - 0x1E: +5 dBm 141 - 0x1F: +6 dBm 142 * @retval Value indicating success or error code. 143 */ 144 tBleStatus aci_hal_set_tx_power_level(uint8_t En_High_Power, 145 uint8_t PA_Level); 146 147 /** 148 * @brief This command returns the number of packets sent in Direct Test Mode. 149 When the Direct TX test is started, a 32-bit counter is used to count how many packets have been transmitted. 150 This command can be used to check how many packets have been sent during the Direct TX test. 151 The counter starts from 0 and counts upwards. The counter can wrap and start from 0 again. 152 The counter is not cleared until the next Direct TX test starts. 153 * @param[out] Number_Of_Packets Number of packets sent during the last Direct TX test. 154 * @retval Value indicating success or error code. 155 */ 156 tBleStatus aci_hal_le_tx_test_packet_number(uint32_t *Number_Of_Packets); 157 158 /** 159 * @brief This command starts a carrier frequency, i.e. a tone, on a specific channel. The frequency 160 sine wave at the specific channel may be used for debugging purpose only. The channel ID 161 is a parameter from 0x00 to 0x27 for the 40 BLE channels, e.g. 0x00 for 2.402 GHz, 0x01 162 for 2.404 GHz etc. 163 This command should not be used when normal Bluetooth activities are ongoing. 164 The tone should be stopped by @ref aci_hal_tone_stop command. 165 * @param RF_Channel BLE Channel ID, from 0x00 to 0x27 meaning (2.402 + 2*0xXX) GHz 166 Device will continuously emit 0s, that means that the tone 167 will be at the channel center frequency less the maximum 168 frequency deviation (250kHz). 169 * Values: 170 - 0x00 ... 0x27 171 * @param Freq_offset Frequency Offset for tone channel 172 * Values: 173 - 0x00 ... 0xFF 174 * @retval Value indicating success or error code. 175 */ 176 tBleStatus aci_hal_tone_start(uint8_t RF_Channel, 177 uint8_t Freq_offset); 178 179 /** 180 * @brief This command is used to stop the previously started @ref aci_hal_tone_start command. 181 * @retval Value indicating success or error code. 182 */ 183 tBleStatus aci_hal_tone_stop(void); 184 185 /** 186 * @brief This command returns the status of the 8 Bluetooth low energy links managed by the device 187 * @param[out] Link_Status Array of link status (8 links). Each link status is 1 byte. 188 * @param[out] Link_Connection_Handle Array of connection handles (2 bytes) for 8 links. 189 * @retval Value indicating success or error code. 190 */ 191 tBleStatus aci_hal_get_link_status(uint8_t Link_Status[8], 192 uint16_t Link_Connection_Handle[16 / 2]); 193 194 /** 195 * @brief This command set the bitmask associated to @ref aci_hal_end_of_radio_activity_event. 196 Only the radio activities enabled in the mask will be reported to application by @ref aci_hal_end_of_radio_activity_event 197 * @param Radio_Activity_Mask Bitmask of radio events 198 * Flags: 199 - 0x0001: Idle 200 - 0x0002: Advertising 201 - 0x0004: Connection event slave 202 - 0x0008: Scanning 203 - 0x0010: Connection request 204 - 0x0020: Connection event master 205 - 0x0040: TX test mode 206 - 0x0080: RX test mode 207 * @retval Value indicating success or error code. 208 */ 209 tBleStatus aci_hal_set_radio_activity_mask(uint16_t Radio_Activity_Mask); 210 211 /** 212 * @brief This command returns information about the Anchor Period to help application in selecting 213 slot timings when operating in multi-link scenarios. 214 * @param[out] Anchor_Period Current anchor period. 215 T = N * 0.625 ms. 216 * @param[out] Max_Free_Slot Maximum available time that can be allocated for a new slot. 217 T = N * 0.625 ms. 218 * @retval Value indicating success or error code. 219 */ 220 tBleStatus aci_hal_get_anchor_period(uint32_t *Anchor_Period, 221 uint32_t *Max_Free_Slot); 222 223 /** 224 * @brief This command is used to enable/disable the generation of HAL events 225 * @param Event_Mask Mask to enable/disable generation of HAL events 226 * Flags: 227 - 0x00000000: No events specified (Default) 228 - 0x00000001: ACI_HAL_SCAN_REQ_REPORT_EVENT 229 * @retval Value indicating success or error code. 230 */ 231 tBleStatus aci_hal_set_event_mask(uint32_t Event_Mask); 232 233 /** 234 * @brief This command is used to provide a specific engineering setup to the Security Manager Protocol Layer. It may be used during development/debug only! 235 * @param SMP_Config Mask to configure SMP engineering knobs 236 * Flags: 237 - 0x00000000: Default config (all reset) 238 - 0x00000001: Cheat Level 1 ON 239 - 0x00000002: RFU 240 - 0x00000003: Cheat Level 3 ON 241 - 0x00000004: RFU 242 - 0x00000005: Cheat Level 5 ON 243 - 0x00000006: Cheat Level 6 ON 244 - 0x00000007: Cheat Level 7 ON 245 - 0x00000010: DBG messages ON 246 - 0x00000100: Debug Public Key ON 247 - 0x00000107: Debug KEY On + DBG msg Off + CL=7 248 - 0x00000117: Debug KEY On + DBG msg On + CL=7 249 * @retval Value indicating success or error code. 250 */ 251 tBleStatus aci_hal_set_smp_eng_config(uint32_t SMP_Config); 252 253 /** 254 * @brief This command is used to retrieve TX, RX and total buffer count allocated for ACL packets. 255 * @param[out] Allocated_For_TX MBlocks allocated for TXing 256 * @param[out] Allocated_For_RX MBlocks allocated for RXing 257 * @param[out] Allocated_MBlocks Overall allocated MBlocks 258 * @retval Value indicating success or error code. 259 */ 260 tBleStatus aci_hal_get_pm_debug_info(uint8_t *Allocated_For_TX, 261 uint8_t *Allocated_For_RX, 262 uint8_t *Allocated_MBlocks); 263 264 /** 265 * @brief This command Reads Register value from the RF module 266 * @param Register_Address Address of the register to be read 267 * @param[out] reg_val Register value 268 * @retval Value indicating success or error code. 269 */ 270 tBleStatus aci_hal_read_radio_reg(uint8_t Register_Address, 271 uint8_t *reg_val); 272 273 /** 274 * @brief This command writes Register value to the RF module 275 * @param Register_Address Address of the register to be written 276 * @param Register_Value Value to be written 277 * @retval Value indicating success or error code. 278 */ 279 tBleStatus aci_hal_write_radio_reg(uint8_t Register_Address, 280 uint8_t Register_Value); 281 282 /** 283 * @brief This command returns the raw value of the RSSI 284 * @param[out] Value RAW RSSI value 285 * @retval Value indicating success or error code. 286 */ 287 tBleStatus aci_hal_read_raw_rssi(uint8_t Value[3]); 288 289 /** 290 * @brief This command does set up the RF to listen to a specific RF channel 291 * @param RF_Channel BLE Channel ID, from 0x00 to 0x27 meaning (2.402 + 2*0xXX) GHz 292 Device will continuously emit 0s, that means that the tone 293 will be at the channel center frequency less the maximum 294 frequency deviation (250kHz). 295 * Values: 296 - 0x00 ... 0x27 297 * @retval Value indicating success or error code. 298 */ 299 tBleStatus aci_hal_rx_start(uint8_t RF_Channel); 300 301 /** 302 * @brief This command stop a previous ACI_HAL_RX_START command 303 * @retval Value indicating success or error code. 304 */ 305 tBleStatus aci_hal_rx_stop(void); 306 307 /** 308 * @brief This command is equivalent to HCI_RESET but ensures the sleep mode is entered' immediately after its completion 309 * @retval Value indicating success or error code. 310 */ 311 tBleStatus aci_hal_stack_reset(void); 312 313 /** 314 * @} 315 */ 316 317 #endif /* ! BLE_HAL_ACI_H__ */ 318