1 /* USER CODE BEGIN Header */
2 /**
3   ******************************************************************************
4   * @file    RADIO_utils.h
5   * @author  GPM WBL Application Team
6   * @brief   Header file for HW miscellaneous utilities.
7   ******************************************************************************
8   * @attention
9   *
10   * Copyright (c) 2024 STMicroelectronics.
11   * All rights reserved.
12   *
13   * This software is licensed under terms that can be found in the LICENSE file
14   * in the root directory of this software component.
15   * If no LICENSE file comes with this software, it is provided AS-IS.
16   *
17   ******************************************************************************
18   */
19 /* USER CODE END Header */
20 
21 /* Define to prevent recursive inclusion -------------------------------------*/
22 
23 #ifndef __RADIO_UTILS_H__
24 #define __RADIO_UTILS_H__
25 
26 #include "stm32wb0x.h"
27 #include "ble_status.h"
28 
29 #define RSSI_INVALID          127
30 #define DEFAULT_TX_PA_LEVEL    31
31 
32 #ifndef ANTENNA_ID_BIT_SHIFT
33 #define ANTENNA_ID_BIT_SHIFT (0)
34 #endif
35 
36 /**
37   * @brief  Convert power level expressed in dBm into driver
38   *           coded PALevel
39   * @param  TX_dBm value of Tx power in dBm unit
40   * @retval PA Level table index
41   */
42 uint8_t RADIO_DBmToPALevel(int8_t TX_dBm);
43 
44 /**
45   * @brief  Convert power level expressed in dBm into driver
46   *           coded PALevel
47   * @param  TX_dBm value of Tx power in dBm unit
48   * @retval PA Level table index
49   */
50 uint8_t RADIO_DBmToPALevelGe(int8_t TX_dBm);
51 
52 /**
53   * @brief  Convert power level index into dBm unit tx power
54   * @param  PA Level table index (0 to 31)
55   * @retval power in dBm unit
56   */
57 int8_t RADIO_PALevelToDBm(uint8_t PA_Level);
58 
59 /**
60   * @brief  Get Max PA Level index
61   * @param  None
62   * @retval power level index
63   */
64 uint8_t RADIO_GetMaxPALevel(void);
65 
66 /**
67   * @brief  Get default PA Level set into the driver
68   * @param  None
69   * @retval power level index
70   */
71 uint8_t RADIO_GetDefaultPALevel(void);
72 
73 /**
74   * @brief  Get minimum and maximum transmission power in dBm
75   * @param  [out] Min_Tx_Power minimum transmission power in dBm
76   * @param  [out] Max_Tx_Power maximum transmission power in dBm
77   * @retval None
78   */
79 void RADIO_ReadTransmitPower(int8_t *Min_Tx_Power, int8_t *Max_Tx_Power);
80 
81 int8_t RADIO_UpdateAvgRSSI(int8_t avg_rssi, int8_t rssi, uint8_t rssi_filter_coeff);
82 
83 /**
84   * @brief  Configure the radio to be able to reach 8dbm output power
85   * @note   This function should not be called by the the application if the
86   *         BLE stack is used. Instead, user must call
87   *         aci_hal_set_tx_power_level() to change output power mode.
88   *         This function enables RADIO_TXRX_SEQ_IRQn interrupt: HAL_RADIO_TXRX_SEQ_IRQHandler()
89   *         must be called by RADIO_TXRX_SEQ_IRQHandler().
90   * @param  state Enable or disable the ability to reach 8 dBm. This parameter
91   *               can be set either to ENABLE or DISABLE.
92   * @retval None
93   */
94 void RADIO_SetHighPower(FunctionalState state);
95 
96 /**
97   * @brief  Executes antenna id pattern remap
98   * @param  AntPattLen Antenna ID pattern length
99   * @param  pAntRamTable Antenna ID Ram table reference
100   * @param  pAntPatt Antenna ID pattern
101   * @retval None
102   */
103 void RADIO_AntIdxRemap(uint8_t AntPattLen, uint8_t *pAntRamTable, const uint8_t* pAntPatt);
104 
105 void RADIO_ToneStart(uint8_t RF_Channel, uint8_t Offset, uint8_t PA_Level);
106 void RADIO_ToneStop(void);
107 tBleStatus aci_hal_set_tx_power_level_preprocess(uint8_t En_High_Power, uint8_t PA_Level);
108 
109 /**
110  * @brief This command is used to enable ANTENNA_ID signal by enabling the
111  *        Alternate Function on the corresponding pins. Some IOs may not be
112  *        enabled, depending on resources availability (e.g. IOs used for
113  *        communication).
114  * @param Antenna_IDs ANTENNA_ID pins to be enabled. Each bit in the mask
115  *        enables the corresponding bit of the ANTENNA_ID signal, which is
116  *        output on PB[0:7].
117  *        Flags:
118  *        - 0x01: ANTENNA_ID_0
119  *        - 0x02: ANTENNA_ID_1
120  *        - 0x04: ANTENNA_ID_2
121  *        - 0x08: ANTENNA_ID_3
122  *        - 0x10: ANTENNA_ID_4
123  *        - 0x20: ANTENNA_ID_5
124  *        - 0x40: ANTENNA_ID_6
125  * @param Antenna_ID_Shift This parameter can be set to a value different from
126  *        zero to shift the ANTENNA_ID signal by the given number of bits. This
127  *        number does not affect the pin selected by Antenna_IDs parameter. E.g.
128  *        to have the ANTENNA_ID signal output on PB[2:4], set Antenna_IDs to
129  *        enable ANTENNA_ID[2:4] (Antenna_IDs = 0x1C) and Antenna_ID_Shift to 2.
130  *        Values:
131  *        - 0 ... 6
132  * @param Default_Antenna_ID The ID of antenna that the controller will select
133  *        for regular communication. The antenna to be used when sending or
134  *        receiving the CTE field needs to be specified through the Antenna_IDs
135  *        parameter of the dedicated HCI commands (i.e.
136  *        hci_le_set_connectionless_cte_transmit_parameters,
137  *        hci_le_set_connectionless_iq_sampling_enable,
138  *        hci_le_set_connection_cte_receive_parameters and
139  *        hci_le_set_connection_cte_transmit_parameters).
140  *        Values:
141  *        - 0x00 ... 0x7F
142  * @param RF_Activity_Enable Enable or disable the RF Activity signal, if
143  *        supported by the device. This signal can be used to enable the antenna
144  *        switch only when necessary.
145  *        Values:
146  *        - 0x00: DISABLED
147  *        - 0x01: ENABLED
148  * @retval Value indicating success or error code.
149  */
150 tBleStatus aci_hal_set_antenna_switch_parameters(uint8_t Antenna_IDs,
151                                                  uint8_t Antenna_ID_Shift,
152                                                  uint8_t Default_Antenna_ID,
153                                                  uint8_t RF_Activity_Enable);
154 
155 /**
156  * @brief This command starts a carrier frequency, i.e. a tone, on a specific
157  *        channel. The frequency sine wave at the specific channel may be used
158  *        for debugging purpose only. The channel ID is a parameter from 0x00 to
159  *        0x27 for the 40 BLE channels, e.g. 0x00 for 2.402 GHz, 0x01 for 2.404
160  *        GHz etc. This command should not be used when normal Bluetooth
161  *        activities are ongoing. The tone should be stopped by @ref
162  *        aci_hal_tone_stop command.
163  * @param RF_Channel BLE Channel ID, from 0x00 to 0x27 meaning (2.402 + 2*0xXX)
164  *        GHz.
165  *        Values:
166  *        - 0x00 ... 0x27
167  * @param Offset Specify if the tone must be emitted with an offset from the
168  *        channel center frequency.  If 0, the tone is emitted at the channel
169  *        center frequency. If 1 or 2, the device will continuously emit the
170  *        tone at the center frequency plus or minus 250 kHz respectively.
171  *        Values:
172  *        - 0x00: 0 kHz offset
173  *        - 0x01: +250 kHz offset
174  *        - 0x02: -250 kHz offset
175  * @retval Value indicating success or error code.
176  */
177 tBleStatus aci_hal_tone_start(uint8_t RF_Channel,
178                               uint8_t Offset);
179 /**
180  * @brief This command is used to stop the previously started @ref
181  *        aci_hal_tone_start command.
182  * @retval Value indicating success or error code.
183  */
184 tBleStatus aci_hal_tone_stop(void);
185 
186 #endif /* __RADIO_UTILS_H__ */
187