HT32SX Generic Push Button
Generic Push Button application for HT32SX
rf_api.h
Go to the documentation of this file.
1 
31 /********************************************************
32 * External API dependencies to link with this library.
33 *
34 * Error codes of the RF API functions are described below.
35 * The Manufacturer can add more error code taking care of the limits defined.
36 *
37 ********************************************************/
38 
50 /*
51  * ----------------------------------------------------------------
52  * Bytes reserved for MCU API ERROR CODES : From 0x10 to 0x2F
53  * ----------------------------------------------------------------
54  */
55 
56 /*
57  * ----------------------------------------------------------------
58  * Bytes reserved for RF API ERROR CODES : From 0x30 to 0x3F
59  * ----------------------------------------------------------------
60  */
61 #define RF_ERR_API_INIT (sfx_u8)(0x30)
62 #define RF_ERR_API_SEND (sfx_u8)(0x31)
63 #define RF_ERR_API_CHANGE_FREQ (sfx_u8)(0x32)
64 #define RF_ERR_API_STOP (sfx_u8)(0x33)
65 #define RF_ERR_API_WAIT_FRAME (sfx_u8)(0x34)
66 #define RF_ERR_API_WAIT_CLEAR_CHANNEL (sfx_u8)(0x35)
67 #define RF_ERR_API_START_CONTINUOUS_TRANSMISSION (sfx_u8)(0x36)
68 #define RF_ERR_API_STOP_CONTINUOUS_TRANSMISSION (sfx_u8)(0x37)
69 #define RF_ERR_API_GET_VERSION (sfx_u8)(0x38)
70 /*
71  * ----------------------------------------------------------------
72  * Bytes reserved for SE API ERROR CODES : From 0x40 to 0x5F
73  * ----------------------------------------------------------------
74  */
75 
76 /*
77  * ----------------------------------------------------------------
78  * Bytes reserved for REPEATER API ERROR CODES : From 0x60 to 0x7F
79  * ----------------------------------------------------------------
80  */
81 
82 /*
83  * ----------------------------------------------------------------
84  * Bytes reserved for MONARCH API ERROR CODES : From 0x80 to 0x8F
85  * ----------------------------------------------------------------
86  */
87 
91 /*!******************************************************************
92  * \fn sfx_u8 RF_API_init(sfx_rf_mode_t rf_mode)
93  * \brief Init and configure Radio link in RX/TX
94  *
95  * [RX Configuration]
96  * To receive Sigfox Frame on your device, program the following:
97  * - Preamble : 0xAAAAAAAAA
98  * - Sync Word : 0xB227
99  * - Packet of the Sigfox frame is 15 bytes length.
100  *
101  * \param[in] sfx_rf_mode_t rf_mode Init Radio link in Tx or RX
102  * \param[out] none
103  *
104  * \retval SFX_ERR_NONE: No error
105  * \retval RF_ERR_API_INIT: Init Radio link error
106  *******************************************************************/
107 sfx_u8 RF_API_init(sfx_rf_mode_t rf_mode);
108 
109 /*!******************************************************************
110  * \fn sfx_u8 RF_API_stop(void)
111  * \brief Close Radio link
112  *
113  * \param[in] none
114  * \param[out] none
115  *
116  * \retval SFX_ERR_NONE: No error
117  * \retval RF_ERR_API_STOP: Close Radio link error
118  *******************************************************************/
119 sfx_u8 RF_API_stop(void);
120 
121 /*!******************************************************************
122  * \fn sfx_u8 RF_API_send(sfx_u8 *stream, sfx_modulation_type_t type, sfx_u8 size)
123  * \brief BPSK Modulation of data stream
124  * (from synchro bit field to CRC)
125  *
126  * NOTE : during this function, the voltage_tx needs to be retrieved and stored in
127  * a variable to be returned into the MCU_API_get_voltage_and_temperature or
128  * MCU_API_get_voltage functions.
129  *
130  * \param[in] sfx_u8 *stream Complete stream to modulate
131  * \param[in]sfx_modulation_type_t Type of the modulation ( enum with baudrate and modulation information)
132  * \param[in] sfx_u8 size Length of stream
133  * \param[out] none
134  *
135  * \retval SFX_ERR_NONE: No error
136  * \retval RF_ERR_API_SEND: Send data stream error
137  *******************************************************************/
138 sfx_u8 RF_API_send(sfx_u8* stream, sfx_modulation_type_t type, sfx_u8 size);
139 
140 /*!******************************************************************
141  * \fn sfx_u8 RF_API_start_continuous_transmission (sfx_modulation_type_t type)
142  * \brief Generate a signal with modulation type. All the configuration ( Init of the RF and Frequency have already been executed
143  * when this function is called.
144  *
145  * \param[in] sfx_modulation_type_t Type of the modulation ( enum with baudrate and modulation information is contained in sigfox_api.h)
146  *
147  * \retval SFX_ERR_NONE: No error
148  * \retval RF_ERR_API_START_CONTINUOUS_TRANSMISSION: Continuous Transmission Start error
149  *******************************************************************/
150 sfx_u8 RF_API_start_continuous_transmission(sfx_modulation_type_t type);
151 
152 /*!******************************************************************
153  * \fn sfx_u8 RF_API_stop_continuous_transmission (void)
154  * \brief Stop the current continuous transmisssion
155  *
156  * \retval SFX_ERR_NONE: No error
157  * \retval RF_ERR_API_STOP_CONTINUOUS_TRANSMISSION: Continuous Transmission Stop error
158  *******************************************************************/
159 sfx_u8 RF_API_stop_continuous_transmission(void);
160 
161 /*!******************************************************************
162  * \fn sfx_u8 RF_API_change_frequency(sfx_u32 frequency)
163  * \brief Change synthesizer carrier frequency
164  *
165  * \param[in] sfx_u32 frequency Frequency in Hz to program in the radio chipset
166  * \param[out] none
167  *
168  * \retval SFX_ERR_NONE: No error
169  * \retval RF_ERR_API_CHANGE_FREQ: Change frequency error
170  *******************************************************************/
171 sfx_u8 RF_API_change_frequency(sfx_u32 frequency);
172 
173 /*!******************************************************************
174  * \fn sfx_u8 RF_API_wait_frame(sfx_u8 *frame, sfx_s16 *rssi, sfx_rx_state_enum_t * state)
175  * \brief Get all GFSK frames received in Rx buffer, structure of
176  * frame is : Synchro bit + Synchro frame + 15 Bytes.<BR> This function must
177  * be blocking state since data is received or timer of 25 s has elapsed.
178  *
179  * - If received buffer, function returns SFX_ERR_NONE then the
180  * library will try to decode frame. If the frame is not correct, the
181  * library will recall RF_API_wait_frame.
182  *
183  * - If 25 seconds timer has elapsed, function returns into the state the timeout enum code.
184  * and then library will stop receive frame phase.
185  *
186  * \param[in] none
187  * \param[out] sfx_s8 *frame Receive buffer
188  * \param[out] sfx_s16 *rssi Chipset RSSI
189  * Warning: This is the 'raw' RSSI value. Do not add 100 as made
190  * in Library versions 1.x.x
191  * Resolution: 1 LSB = 1 dBm
192  *
193  * \param[out] sfx_rx_state_enum_t state Indicate the final state of the reception. Value can be DL_TIMEOUT or DL_PASSED
194  * if a frame has been received, as defined in sigfox_api.h file.
195  *
196  * \retval SFX_ERR_NONE: No error
197  *******************************************************************/
198 sfx_u8 RF_API_wait_frame(sfx_u8* frame, sfx_s16* rssi, sfx_rx_state_enum_t* state);
199 
200 /*!******************************************************************
201  * \fn sfx_u8 RF_API_wait_for_clear_channel (sfx_u8 cs_min, sfx_s8 cs_threshold, sfx_rx_state_enum_t * state);
202  * \brief This function is used in ARIB standard for the Listen Before Talk
203  * feature. It listens on a specific frequency band initialized through the RF_API_init(), during a sliding window set
204  * in the MCU_API_timer_start_carrier_sense().
205  * If the channel is clear during the minimum carrier sense
206  * value (cs_min), under the limit of the cs_threshold,
207  * the functions returns with SFX_ERR_NONE (transmission
208  * allowed). Otherwise it continues to listen to the channel till the expiration of the
209  * carrier sense maximum window and then updates the state ( with timeout enum ).
210  *
211  * \param[in] sfx_u8 cs_min Minimum Carrier Sense time in ms.
212  * \param[in] sfx_s8 cs_threshold Power threshold limit to declare the channel clear.
213  * i.e : cs_threshold value -80dBm in Japan / -65dBm in Korea
214  * \param[out] sfx_rx_state_enum_t state Indicate the final state of the carrier sense. Value can be DL_TIMEOUT or PASSED
215  * as per defined in sigfox_api.h file.
216  *
217  * \retval SFX_ERR_NONE: No error
218  *******************************************************************/
219 sfx_u8 RF_API_wait_for_clear_channel(sfx_u8 cs_min, sfx_s8 cs_threshold, sfx_rx_state_enum_t* state);
220 
221 /*!******************************************************************
222  * \fn sfx_u8 RF_API_get_version(sfx_u8 **version, sfx_u8 *size)
223  * \brief Returns current RF API version
224  *
225  * \param[out] sfx_u8 **version Pointer to Byte array (ASCII format) containing library version
226  * \param[out] sfx_u8 *size Size of the byte array pointed by *version
227  *
228  * \retval SFX_ERR_NONE: No error
229  * \retval RF_ERR_API_GET_VERSION: Get Version error
230  *******************************************************************/
231 sfx_u8 RF_API_get_version(sfx_u8** version, sfx_u8* size);
RF_API_stop
sfx_u8 RF_API_stop(void)
Close Radio link.
Definition: rf_api.c:1217
RF_API_change_frequency
sfx_u8 RF_API_change_frequency(sfx_u32 frequency)
Change synthesizer carrier frequency.
Definition: rf_api.c:1399
sfx_modulation_type_t
sfx_modulation_type_t
Definition: sigfox_api.h:399
RF_API_wait_frame
sfx_u8 RF_API_wait_frame(sfx_u8 *frame, sfx_s16 *rssi, sfx_rx_state_enum_t *state)
Get all GFSK frames received in Rx buffer, structure of frame is : Synchro bit + Synchro frame + 15 B...
Definition: rf_api.c:1483
RF_API_send
sfx_u8 RF_API_send(sfx_u8 *stream, sfx_modulation_type_t type, sfx_u8 size)
BPSK Modulation of data stream (from synchro bit field to CRC)
Definition: rf_api.c:1259
RF_API_init
sfx_u8 RF_API_init(sfx_rf_mode_t rf_mode)
Init and configure Radio link in RX/TX.
Definition: rf_api.c:1075
sfx_rf_mode_t
sfx_rf_mode_t
Definition: sigfox_api.h:425
RF_API_start_continuous_transmission
sfx_u8 RF_API_start_continuous_transmission(sfx_modulation_type_t type)
Generate a signal with modulation type. All the configuration ( Init of the RF and Frequency have alr...
Definition: rf_api.c:1302
RF_API_wait_for_clear_channel
sfx_u8 RF_API_wait_for_clear_channel(sfx_u8 cs_min, sfx_s8 cs_threshold, sfx_rx_state_enum_t *state)
This function is used in ARIB standard for the Listen Before Talk feature. It listens on a specific f...
Definition: rf_api.c:1609
RF_API_get_version
sfx_u8 RF_API_get_version(sfx_u8 **version, sfx_u8 *size)
Returns current RF API version.
Definition: rf_api.c:1736
RF_API_stop_continuous_transmission
sfx_u8 RF_API_stop_continuous_transmission(void)
Stop the current continuous transmisssion.
Definition: rf_api.c:1373