HT32SX Monarch Scan
Monarch Scan application for HT32SX
st_rf_api.h
Go to the documentation of this file.
1 
14 #include "sigfox_types.h"
15 
16 #define ST_RF_ERR_API_ERROR (sfx_u8)(0x01)
18 #define TIMER_START 0
19 #define TIMER_STOP 1
20 
21 /*!******************************************************************
22  * \fn sfx_u8 ST_RF_API_set_xtal_freq(sfx_u32 xtal)
23  * \brief Sets the XTAL frequency of the S2-LP in Hertz (default is 50MHz).
24  * \param[in] sfx_u32 xtal: the xtal frequency of the S2-LP in Hz as an integer.
25  * \note If this function is not called, the default xtal frequency is 50MHz.
26  * \retval 0 if no error, 1 otherwise.
27  *******************************************************************/
28 sfx_u8 ST_RF_API_set_xtal_freq(sfx_u32 xtal);
29 
30 /*!******************************************************************
31  * \fn sfx_u32 ST_RF_API_get_xtal_freq(sfx_u32 *xtal)
32  * \brief Gets the RF frequency offset of the S2-LP XTAL in Hertz.
33  * \param[in] sfx_s32* xtal: a pointer to the integer representing the S2-LP XTAL frequency in Hertz.
34  * \retval 0 if no error, 1 otherwise.
35  *******************************************************************/
36 sfx_u8 ST_RF_API_get_xtal_freq(sfx_u32 *xtal);
37 
38 /*!******************************************************************
39  * \fn sfx_u8 ST_RF_API_set_freq_offset(sfx_s32 offset)
40  * \brief Sets the RF frequency offset in Hertz (default is 0 Hz).
41  * \param[in] sfx_s32 offset: frequency offset in Hz as an integer.
42  * \note If this function is not called, the default frequency offset is 0 Hz.
43  * \retval 0 if no error, 1 otherwise.
44  *******************************************************************/
45 sfx_u8 ST_RF_API_set_freq_offset(sfx_s32 offset);
46 
47 /*!******************************************************************
48  * \fn sfx_s32 ST_RF_API_get_freq_offset
49  * \brief Gets the RF frequency offset in Hertz (default is 0 Hz).
50  * \param[in] sfx_s32* offset: a pointer to the integer representing the frequency offset in Hz.
51  * \retval 0 if no error, 1 otherwise.
52  *******************************************************************/
53 sfx_u8 ST_RF_API_get_freq_offset(sfx_s32 *offset);
54 
55 /*!******************************************************************
56  * \fn sfx_u8 ST_RF_API_set_rssi_offset(sfx_s8 rssi_off)
57  * \brief Set an RSSI offset for the RSSI.
58  * \param[in] sfx_s8 rssi_off: an integer representing the offset in dB.
59  * Default value is 0.
60  * \retval 0 if no error, 1 otherwise.
61  *******************************************************************/
62 sfx_u8 ST_RF_API_set_rssi_offset(sfx_s8 rssi_off);
63 
64 /*!******************************************************************
65  * \fn sfx_u8 ST_RF_API_get_rssi_offset(sfx_s8 *rssi_off)
66  * \brief Get the RSSI offset for the RSSI.
67  * \param[in] sfx_s8* rssi_off: a pointer to the integer representing the offset in dB.
68  * Default value is 0.
69  * \retval 0 if no error, 1 otherwise.
70  *******************************************************************/
71 sfx_u8 ST_RF_API_get_rssi_offset(sfx_s8 *rssi_off);
72 
73 /*!******************************************************************
74  * \fn sfx_u8 ST_RF_API_set_lbt_thr_offset(sfx_s8 lbt_thr_off)
75  * \brief Set an offset (dB) for tuning the LBT mechanism.
76  * \param[in] sfx_s8 lbt_thr_off: an integer representing the offset in dB.
77  * Default value is 0.
78  * \retval 0 if no error, 1 otherwise.
79  *******************************************************************/
80 sfx_u8 ST_RF_API_set_lbt_thr_offset(sfx_s8 lbt_thr_off);
81 
82 /*!******************************************************************
83  * \fn sfx_u8 ST_RF_API_get_lbt_thr_offset(sfx_s8 *lbt_thr_off)
84  * \brief Get the LBT offset (dB) for the LBT mechanism.
85  * \param[in] sfx_s8 *lbt_thr_off: a pointer to the integer representing the offset in dB.
86  * Default value is 0.
87  * \retval 0 if no error, 1 otherwise.
88  *******************************************************************/
89 sfx_u8 ST_RF_API_get_lbt_thr_offset(sfx_s8 *lbt_thr_off);
90 
91 /*!******************************************************************
92  * \fn sfx_u8 ST_RF_API_gpio_irq_pin(sfx_u8 gpio_pin)
93  * \brief Configures one of the S2-LP pin to be an IRQ pin.
94  * \param[in] sfx_u8 gpio_pin: an integer in the range [0,3] representing the GPIO to be used as IRQ.
95  * Default value is 3.
96  * \retval 0 if no error, 1 otherwise.
97  *******************************************************************/
98 sfx_u8 ST_RF_API_gpio_irq_pin(sfx_u8 gpio_pin);
99 
100 /*!******************************************************************
101  * \fn sfx_u8 ST_RF_API_gpio_tx_rx_pin(sfx_u8 gpio_pin)
102  * \brief Configures one of the S2-LP pin to be to be configured as (RX or TX) signal.
103  * \param[in] sfx_u8 gpio_pin: an integer in the range [0,3] representing the GPIO to be configured as (RX or TX) signal.
104  * Pass the value 0xFF if the GPIO should not be configured.
105  * \retval 0 if no error, 1 otherwise.
106  *******************************************************************/
107 sfx_u8 ST_RF_API_gpio_tx_rx_pin(sfx_u8 gpio_pin);
108 
109 /*!******************************************************************
110  * \fn sfx_u8 ST_RF_API_gpio_rx_pin(sfx_u8 gpio_pin)
111  * \brief Configures one of the S2-LP pin to be configured as RX signal.
112  * \param[in] sfx_u8 gpio_pin: an integer in the range [0,3] representing the GPIO to be configured as RX signal.
113  * Pass the value 0xFF if the GPIO should not be configured.
114  * \note Only for RCZ2/4. Uneffective for RCZ1. This function must be called before \ref ST_SIGFOX_API_open .
115  * \retval 0 if no error, 1 otherwise.
116  *******************************************************************/
117 sfx_u8 ST_RF_API_gpio_rx_pin(sfx_u8 gpio_pin);
118 
119 /*!******************************************************************
120  * \fn sfx_u8 ST_RF_API_gpio_tx_pin(sfx_u8 gpio_pin)
121  * \brief Configures one of the S2-LP pin to be configured as TX signal.
122  * \param[in] sfx_u8 gpio_pin: an integer in the range [0,3] representing the GPIO to be configured as TX signal.
123  * Pass the value 0xFF if the GPIO should not be configured.
124  * \note Only for RCZ2/4. Uneffective for RCZ1. This function must be called before \ref ST_SIGFOX_API_open .
125  * \retval 0 if no error, 1 otherwise.
126  *******************************************************************/
127 sfx_u8 ST_RF_API_gpio_tx_pin(sfx_u8 gpio_pin);
128 
129 /*!******************************************************************
130  * \fn sfx_u8 ST_RF_API_reduce_output_power(sfx_s16 reduction)
131  * \brief Reduces the output power of the transmitted signal by a facor (reduction*0.5dB against the actual value).
132  * \details Each positive step of 1 reduces the power at S2-LP level of about 0.5dB. A negative value increase the power level of the same quantity.
133  * <br>The function returns an error if the output power is bigger than the one used dutring cerification.
134  * \param[in] sfx_s16 reduction: the reduction factor.
135  * \retval 0 if no error, 1 otherwise.
136  *******************************************************************/
137 sfx_u8 ST_RF_API_reduce_output_power(sfx_s16 reduction);
138 
139 /*!******************************************************************
140  * \fn sfx_u8 ST_RF_API_set_tcxo(sfx_u8 tcxo)
141  * \brief Instructs the library to configure the S2-LP for a TCXO or for a XTAL.
142  * \param[in] sfx_u8 tcxo: 1 if a TCXO, 0 if XTAL.
143  * \note If this function is not called, the default is to use the S2-LP in XTAL mode.
144  * \retval 0 if no error, 1 otherwise.
145  *******************************************************************/
146 sfx_u8 ST_RF_API_set_tcxo(sfx_u8 tcxo);
147 
148 /*!******************************************************************
149  * \fn sfx_u8 ST_RF_API_smps(sfx_u8 mode)
150  * \brief Instructs the library to configure the S2-LP with a user defined smps frequency.
151  * \param[in] sfx_u8 mode: from 1 (1.2V) to 7 (1.8V).
152  * \note If this function is not called, the default is to use the S2-LP at 1.5V.
153  * \retval 0 if no error, 1 otherwise.
154  *******************************************************************/
155 sfx_u8 ST_RF_API_smps(sfx_u8 mode);
156 
157 /*!******************************************************************
158  * \fn sfx_u8 ST_RF_API_set_pa(sfx_u8 pa)
159  * \brief Instructs the library to configure the S2-LP for a external PA (Power Amplifier).
160  * \param[in] sfx_u8 pa: 1 if a PA, 0 if not.
161  * \note If this function is not called, the default is not configure an external PA.
162  * \retval 0 if no error, 1 otherwise.
163  *******************************************************************/
164 sfx_u8 ST_RF_API_set_pa(sfx_u8 pa);
165 
166 /*!******************************************************************
167  * \fn sfx_u8 ST_RF_API_get_ramp_duration(void)
168  * \brief Returns the duration of the initial (or final) ramp in ms.
169  * \param[in] None.
170  * \retval Ramp duration in ms.
171  *******************************************************************/
172 sfx_u8 ST_RF_API_get_ramp_duration(void);
173 
174 /*!******************************************************************
175  * \fn void ST_RF_API_S2LP_IRQ_CB(void)
176  * \brief This is a <b>callback</b> exported by the RF_API library.
177  * The RF_API module configures the S2-LP to raise interrupts and to notify them
178  * on a GPIO. When the interrupt of that GPIO is raised, this function must be called.
179  * It must be called when the S2-LP raises the IRQ via GPIO.
180  * \param[in] None.
181  * \retval None.
182  *******************************************************************/
183 void ST_RF_API_S2LP_IRQ_CB(void);
184 
185 /*!******************************************************************
186  * \fn void ST_RF_API_Timer_CB(void)
187  * \brief This is a <b>callback</b> exported by the RF_API library.
188  * It must be called when the timer started by \ref MCU_API_timer_start expires.
189  * \param[in] sfx_u8 state: 0 for timer start, 1 for timer stop
190  * \retval None.
191  *******************************************************************/
192 //void ST_RF_API_Timer_CB(void);
193 void ST_RF_API_Timer_CB(sfx_u8 state);
194 
195 /*!******************************************************************
196  * \fn void ST_RF_API_Timer_Channel_Clear_CB(void)
197  * \brief This is a <b>callback</b> exported by the RF_API library.
198  * It must be called when the timer started by \ref MCU_API_timer_start_carrier_sense expires.
199  * \param[in] None.
200  * \retval None.
201  *******************************************************************/
202 void ST_RF_API_Timer_Channel_Clear_CB(void);
203 
204 /*!******************************************************************
205  * \fn sfx_u8 ST_RF_API_Get_Continuous_TX_Flag(void);
206  * \brief This is a function that give informations abou the tx state MCU API.
207  * Used for the implementation for continuos BPSK modulation.
208  * \param[in] None.
209  * \retval 0 IDLE state or TX send frame, 1 Continuos BPSK mode.
210  *******************************************************************/
211 sfx_u8 ST_RF_API_Get_Continuous_TX_or_MONARCH_Scan_Flag(void);
212 
213 /*!******************************************************************
214  * \fn void ST_RF_API_StartTx(void)
215  * \brief This is a function to force S2LP to switch in TX mode.
216  * It is called from Monarch detection algorithm.
217  * \param[in] None.
218  * \retval None.
219  *******************************************************************/
220 sfx_u8 ST_RF_API_StartTx(void);
221 
222 /*!******************************************************************
223  * \fn void ST_RF_API_StartRx(void)
224  * \brief This is a function to force S2LP to switch in RX mode.
225  * It is called from Monarch detection algorithm.
226  * \param[in] None.
227  * \retval None.
228  *******************************************************************/
229 sfx_u8 ST_RF_API_StartRx(void);
230 
231 /*!******************************************************************
232  * \fn void ST_RF_API_StopRxTx(void)
233  * \brief This is a function to force S2LP to switch in Ready mode.
234  * It is called from Monarch detection algorithm.
235  * \param[in] None.
236  * \retval None.
237  *******************************************************************/
238 sfx_u8 ST_RF_API_StopRxTx(void);
239 
240 /*!******************************************************************
241  * \fn void ST_RF_API_GetRSSI(void)
242  * \brief This is a function to Get the latest detected RSSI
243  * It is called from Monarch detection algorithm.
244  * \param[in] None.
245  * \retval RSSI level.
246  *******************************************************************/
247 sfx_s16 ST_RF_API_GetRSSI(void);
248 
249 /*!******************************************************************
250  * \fn void ST_RF_API_ReadFifos(uint8_t address, uint8_t n_bytes, uint8_t* buffer)
251  * \brief This is a function to Get the info containe into S2LP rx fifo
252  * \param[in] None.
253  * \retval RSSI level.
254  *******************************************************************/
255 void ST_RF_API_ReadFifo(sfx_u8 n_bytes, sfx_u8* buffer, sfx_u8 flush);
256 sfx_u8 ST_RF_API_ReadFifoStatus(void);
257 void ST_RF_API_SetFifoLength(sfx_u8 n_bytes);
ST_RF_API_get_ramp_duration
sfx_u8 ST_RF_API_get_ramp_duration(void)
Returns the duration of the initial (or final) ramp in ms.
Definition: rf_api.c:1914
ST_RF_API_gpio_tx_rx_pin
sfx_u8 ST_RF_API_gpio_tx_rx_pin(sfx_u8 gpio_pin)
Configures one of the S2-LP pin to be to be configured as (RX or TX) signal.
ST_RF_API_gpio_rx_pin
sfx_u8 ST_RF_API_gpio_rx_pin(sfx_u8 gpio_pin)
Configures one of the S2-LP pin to be configured as RX signal.
ST_RF_API_S2LP_IRQ_CB
void ST_RF_API_S2LP_IRQ_CB(void)
This is a callback exported by the RF_API library. The RF_API module configures the S2-LP to raise in...
Definition: rf_api.c:1762
ST_RF_API_set_pa
sfx_u8 ST_RF_API_set_pa(sfx_u8 pa)
Instructs the library to configure the S2-LP for a external PA (Power Amplifier).
ST_RF_API_GetRSSI
sfx_s16 ST_RF_API_GetRSSI(void)
This is a function to Get the latest detected RSSI It is called from Monarch detection algorithm.
Definition: rf_api.c:1964
ST_RF_API_StartRx
sfx_u8 ST_RF_API_StartRx(void)
This is a function to force S2LP to switch in RX mode. It is called from Monarch detection algorith...
Definition: rf_api.c:1944
ST_RF_API_StartTx
sfx_u8 ST_RF_API_StartTx(void)
This is a function to force S2LP to switch in TX mode. It is called from Monarch detection algorith...
Definition: rf_api.c:1931
ST_RF_API_set_tcxo
sfx_u8 ST_RF_API_set_tcxo(sfx_u8 tcxo)
Instructs the library to configure the S2-LP for a TCXO or for a XTAL.
Definition: rf_api.c:1900
ST_RF_API_smps
sfx_u8 ST_RF_API_smps(sfx_u8 mode)
Instructs the library to configure the S2-LP with a user defined smps frequency.
ST_RF_API_set_rssi_offset
sfx_u8 ST_RF_API_set_rssi_offset(sfx_s8 rssi_off)
Set an RSSI offset for the RSSI.
ST_RF_API_set_xtal_freq
sfx_u8 ST_RF_API_set_xtal_freq(sfx_u32 xtal)
Sets the XTAL frequency of the S2-LP in Hertz (default is 50MHz).
Definition: rf_api.c:1806
ST_RF_API_get_rssi_offset
sfx_u8 ST_RF_API_get_rssi_offset(sfx_s8 *rssi_off)
Get the RSSI offset for the RSSI.
ST_RF_API_reduce_output_power
sfx_u8 ST_RF_API_reduce_output_power(sfx_s16 reduction)
Reduces the output power of the transmitted signal by a facor (reduction*0.5dB against the actual val...
ST_RF_API_Timer_Channel_Clear_CB
void ST_RF_API_Timer_Channel_Clear_CB(void)
This is a callback exported by the RF_API library. It must be called when the timer started by MCU_AP...
Definition: rf_api.c:1756
ST_RF_API_set_freq_offset
sfx_u8 ST_RF_API_set_freq_offset(sfx_s32 offset)
Sets the RF frequency offset in Hertz (default is 0 Hz).
Definition: rf_api.c:1821
sigfox_types.h
Sigfox types definition.
ST_RF_API_set_lbt_thr_offset
sfx_u8 ST_RF_API_set_lbt_thr_offset(sfx_s8 lbt_thr_off)
Set an offset (dB) for tuning the LBT mechanism.
Definition: rf_api.c:1836
ST_RF_API_get_xtal_freq
sfx_u8 ST_RF_API_get_xtal_freq(sfx_u32 *xtal)
Gets the RF frequency offset of the S2-LP XTAL in Hertz.
Definition: rf_api.c:1813
ST_RF_API_get_lbt_thr_offset
sfx_u8 ST_RF_API_get_lbt_thr_offset(sfx_s8 *lbt_thr_off)
Get the LBT offset (dB) for the LBT mechanism.
Definition: rf_api.c:1843
ST_RF_API_gpio_irq_pin
sfx_u8 ST_RF_API_gpio_irq_pin(sfx_u8 gpio_pin)
Configures one of the S2-LP pin to be an IRQ pin.
ST_RF_API_StopRxTx
sfx_u8 ST_RF_API_StopRxTx(void)
This is a function to force S2LP to switch in Ready mode. It is called from Monarch detection algor...
Definition: rf_api.c:1953
ST_RF_API_gpio_tx_pin
sfx_u8 ST_RF_API_gpio_tx_pin(sfx_u8 gpio_pin)
Configures one of the S2-LP pin to be configured as TX signal.