HT32SX Generic Push Button
Generic Push Button application for HT32SX
mcu_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 MCU API functions are described below.
35 * The Manufacturer can add more error code taking care of the limits defined.
36 *
37 ********************************************************/
38 
51 #include "sigfox_types.h"
52 #include "sigfox_api.h"
53 
54 /*
55  * ----------------------------------------------------------------
56  * Bytes reserved for MCU API ERROR CODES : From 0x10 to 0x2F
57  * ----------------------------------------------------------------
58  */
59 
60 #define MCU_ERR_API_MALLOC (sfx_u8)(0x11)
61 #define MCU_ERR_API_FREE (sfx_u8)(0x12)
62 #define MCU_ERR_API_VOLT_TEMP (sfx_u8)(0x13)
63 #define MCU_ERR_API_DLY (sfx_u8)(0x14)
64 #define MCU_ERR_API_AES (sfx_u8)(0x15)
65 #define MCU_ERR_API_GETNVMEM (sfx_u8)(0x16)
66 #define MCU_ERR_API_SETNVMEM (sfx_u8)(0x17)
67 #define MCU_ERR_API_TIMER_START (sfx_u8)(0x18)
68 #define MCU_ERR_API_TIMER_START_CS (sfx_u8)(0x19)
69 #define MCU_ERR_API_TIMER_STOP_CS (sfx_u8)(0x1A)
70 #define MCU_ERR_API_TIMER_STOP (sfx_u8)(0x1B)
71 #define MCU_ERR_API_TIMER_END (sfx_u8)(0x1C)
72 #define MCU_ERR_API_TEST_REPORT (sfx_u8)(0x1D)
73 #define MCU_ERR_API_GET_VERSION (sfx_u8)(0x1E)
75 #define MCU_ERR_API_GET_ID_PAYLOAD_ENCR_FLAG (sfx_u8)(0x1F)
76 #define MCU_ERR_API_GET_PAC (sfx_u8)(0x20)
78 /*
79  * ----------------------------------------------------------------
80  * Bytes reserved for RF API ERROR CODES : From 0x30 to 0x3F
81  * ----------------------------------------------------------------
82  */
83 
84 /*
85  * ----------------------------------------------------------------
86  * Bytes reserved for SE API ERROR CODES : From 0x40 to 0x5F
87  * ----------------------------------------------------------------
88  */
89 
90 /*
91  * ----------------------------------------------------------------
92  * Bytes reserved for REPEATER API ERROR CODES : From 0x60 to 0x7F
93  * ----------------------------------------------------------------
94  */
95 
96 /*
97  * ----------------------------------------------------------------
98  * Bytes reserved for MONARCH API ERROR CODES : From 0x80 to 0x8F
99  * ----------------------------------------------------------------
100  */
101 
105 /*!******************************************************************
106  * \fn sfx_u8 MCU_API_malloc(sfx_u16 size, sfx_u8 **returned_pointer)
107  * \brief Allocate memory for library usage (Memory usage = size (Bytes))
108  * This function is only called once at the opening of the Sigfox Library ( SIGF
109  *
110  * IMPORTANT NOTE:
111  * --------------
112  * The address reported need to be aligned with architecture of the microprocessor used.
113  * For a Microprocessor of:
114  * - 8 bits => any address is allowed
115  * - 16 bits => only address multiple of 2 are allowed
116  * - 32 bits => only address multiple of 4 are allowed
117  *
118  * \param[in] sfx_u16 size size of buffer to allocate in bytes
119  * \param[out] sfx_u8 **returned_pointer pointer to buffer (can be static)
120  *
121  * \retval SFX_ERR_NONE: No error
122  * \retval MCU_ERR_API_MALLOC Malloc error
123  *******************************************************************/
124 sfx_u8 MCU_API_malloc(sfx_u16 size, sfx_u8** returned_pointer);
125 
126 /*!******************************************************************
127  * \fn sfx_u8 MCU_API_free(sfx_u8 *ptr)
128  * \brief Free memory allocated to library
129  *
130  * \param[in] sfx_u8 *ptr pointer to buffer
131  * \param[out] none
132  *
133  * \retval SFX_ERR_NONE: No error
134  * \retval MCU_ERR_API_FREE: Free error
135  *******************************************************************/
136 sfx_u8 MCU_API_free(sfx_u8* ptr);
137 
138 /*!******************************************************************
139  * \fn sfx_u8 MCU_API_get_voltage_temperature(sfx_u16 *voltage_idle, sfx_u16 *voltage_tx, sfx_s16 *temperature)
140  * \brief Get voltage and temperature for Out of band frames
141  * Value must respect the units bellow for <B>backend compatibility</B>
142  *
143  * \param[in] none
144  * \param[out] sfx_u16 *voltage_idle Device's voltage in Idle state (mV)
145  * \param[out] sfx_u16 *voltage_tx Device's voltage in Tx state (mV) - for the last transmission
146  * \param[out] sfx_s16 *temperature Device's temperature in 1/10 of degrees celcius
147  *
148  * \retval SFX_ERR_NONE: No error
149  * \retval MCU_ERR_API_VOLT_TEMP: Get voltage/temperature error
150  *******************************************************************/
151 sfx_u8 MCU_API_get_voltage_temperature(sfx_u16* voltage_idle,
152  sfx_u16* voltage_tx,
153  sfx_s16* temperature);
154 
155 /*!******************************************************************
156  * \fn sfx_u8 MCU_API_delay(sfx_delay_t delay_type)
157  * \brief Inter stream delay, called between each RF_API_send
158  * - SFX_DLY_INTER_FRAME_TX : 0 to 2s in Uplink DC
159  * - SFX_DLY_INTER_FRAME_TRX : 500 ms in Uplink/Downlink FH & Downlink DC
160  * - SFX_DLY_OOB_ACK : 1.4s to 4s for Downlink OOB
161  * - SFX_CS_SLEEP : delay between several trials of Carrier Sense (for the first frame only)
162  *
163  * \param[in] sfx_delay_t delay_type Type of delay to call
164  * \param[out] none
165  *
166  * \retval SFX_ERR_NONE: No error
167  * \retval MCU_ERR_API_DLY: Delay error
168  *******************************************************************/
169 sfx_u8 MCU_API_delay(sfx_delay_t delay_type);
170 
171 /*!******************************************************************
172  * \fn sfx_u8 MCU_API_aes_128_cbc_encrypt(sfx_u8 *encrypted_data, sfx_u8 *data_to_encrypt, sfx_u8 aes_block_len, sfx_u8 key[16], sfx_credentials_use_key_t use_key)
173  * \brief Encrypt a complete buffer with Secret or Test key.<BR>
174  * The secret key corresponds to the private key provided from the CRA.
175  * <B>These keys must be stored in a secure place.</B> <BR>
176  * Can be hardcoded or soft coded (iv vector contains '0')
177  *
178  * \param[out] sfx_u8 *encrypted_data Result of AES Encryption
179  * \param[in] sfx_u8 *data_to_encrypt Input data to Encrypt
180  * \param[in] sfx_u8 aes_block_len Input data length (should be a multiple of an AES block size, ie. AES_BLOCK_SIZE bytes)
181  * \param[in] sfx_u8 key[16] Input key
182  * \param[in] sfx_credentials_use_key_t use_key Key to use - private key or input key
183  *
184  * \retval SFX_ERR_NONE: No error
185  * \retval MCU_ERR_API_AES: AES Encryption error
186  *******************************************************************/
187 sfx_u8 MCU_API_aes_128_cbc_encrypt(sfx_u8 *encrypted_data,
188  sfx_u8 *data_to_encrypt,
189  sfx_u8 aes_block_len,
190  sfx_u8 key[16],
191  sfx_credentials_use_key_t use_key);
192 
193 /*!******************************************************************
194  * \fn sfx_u8 MCU_API_get_nv_mem(sfx_u8 read_data[SFX_NVMEM_BLOCK_SIZE])
195  * \brief This function copies the data read from non volatile memory
196  * into the buffer pointed by read_data.<BR>
197  * The size of the data to read is \link SFX_NVMEM_BLOCK_SIZE \endlink
198  * bytes.
199  * CAREFUL : this value can change according to the features included
200  * in the library (covered zones, etc.)
201  *
202  * \param[in] none
203  * \param[out] sfx_u8 read_data[SFX_NVMEM_BLOCK_SIZE] Pointer to the data bloc to write with the data stored in memory
204  *
205  * \retval SFX_ERR_NONE: No error
206  * \retval MCU_ERR_API_GETNVMEM: Read nvmem error
207  *******************************************************************/
208 sfx_u8 MCU_API_get_nv_mem(sfx_u8 read_data[SFX_NVMEM_BLOCK_SIZE]);
209 
210 /*!******************************************************************
211  * \fn sfx_u8 MCU_API_set_nv_mem(sfx_u8 data_to_write[SFX_NVMEM_BLOCK_SIZE])
212  * \brief This function writes data pointed by data_to_write to non
213  * volatile memory.<BR> It is strongly recommanded to use NV memory
214  * like EEPROM since this function is called at each SIGFOX_API_send_xxx.
215  * The size of the data to write is \link SFX_NVMEM_BLOCK_SIZE \endlink
216  * bytes.
217  * CAREFUL : this value can change according to the features included
218  * in the library (covered zones, etc.)
219  *
220  * \param[in] sfx_u8 data_to_write[SFX_NVMEM_BLOCK_SIZE] Pointer to data bloc to be written in memory
221  * \param[out] none
222  *
223  * \retval SFX_ERR_NONE: No error
224  * \retval MCU_ERR_API_SETNVMEM: Write nvmem error
225  *******************************************************************/
226 sfx_u8 MCU_API_set_nv_mem(sfx_u8 data_to_write[SFX_NVMEM_BLOCK_SIZE]);
227 
228 /*!******************************************************************
229  * \fn sfx_u8 MCU_API_timer_start_carrier_sense(sfx_u16 time_duration_in_ms)
230  * \brief Start timer for :
231  * - carrier sense maximum window (used in ARIB standard)
232  *
233  * \param[in] sfx_u16 time_duration_in_ms Timer value in milliseconds
234  * \param[out] none
235  *
236  * \retval SFX_ERR_NONE: No error
237  * \retval MCU_ERR_API_TIMER_START_CS: Start CS timer error
238  *******************************************************************/
239 sfx_u8 MCU_API_timer_start_carrier_sense(sfx_u16 time_duration_in_ms);
240 
241 /*!******************************************************************
242  * \fn sfx_u8 MCU_API_timer_start(sfx_u32 time_duration_in_s)
243  * \brief Start timer for in second duration
244  *
245  * \param[in] sfx_u32 time_duration_in_s Timer value in seconds
246  * \param[out] none
247  *
248  * \retval SFX_ERR_NONE: No error
249  * \retval MCU_ERR_API_TIMER_START: Start timer error
250  *******************************************************************/
251 sfx_u8 MCU_API_timer_start(sfx_u32 time_duration_in_s);
252 
253 /*!******************************************************************
254  * \fn sfx_u8 MCU_API_timer_stop(void)
255  * \brief Stop the timer (started with MCU_API_timer_start)
256  *
257  * \param[in] none
258  * \param[out] none
259  *
260  * \retval SFX_ERR_NONE: No error
261  * \retval MCU_ERR_API_TIMER_STOP: Stop timer error
262  *******************************************************************/
263 sfx_u8 MCU_API_timer_stop(void);
264 
265 /*!******************************************************************
266  * \fn sfx_u8 MCU_API_timer_stop_carrier_sense(void)
267  * \brief Stop the timer (started with MCU_API_timer_start_carrier_sense)
268  *
269  * \param[in] none
270  * \param[out] none
271  *
272  * \retval SFX_ERR_NONE: No error
273  * \retval MCU_ERR_API_TIMER_STOP_CS: Stop timer error
274  *******************************************************************/
275 sfx_u8 MCU_API_timer_stop_carrier_sense(void);
276 
277 /*!******************************************************************
278  * \fn sfx_u8 MCU_API_timer_wait_for_end(void)
279  * \brief Blocking function to wait for interrupt indicating timer
280  * elapsed.<BR> This function is only used for the 20 seconds wait
281  * in downlink.
282  *
283  * \param[in] none
284  * \param[out] none
285  *
286  * \retval SFX_ERR_NONE: No error
287  * \retval MCU_ERR_API_TIMER_END: Wait end of timer error
288  *******************************************************************/
289 sfx_u8 MCU_API_timer_wait_for_end(void);
290 
291 /*!******************************************************************
292  * \fn sfx_u8 MCU_API_report_test_result(sfx_bool status, sfx_s16 rssi)
293  * \brief To report the result of Rx test for each valid message
294  * received/validated by library.<BR> Manufacturer api to show the result
295  * of RX test mode : can be uplink radio frame or uart print or
296  * gpio output.
297  * RSSI parameter is only used to report the rssi of received frames (downlink test)
298  *
299  * \param[in] sfx_bool status Is SFX_TRUE when result ok else SFX_FALSE
300  * See SIGFOX_API_test_mode summary
301  * \param[in] rssi RSSI of the received frame
302  *
303  * \retval SFX_ERR_NONE: No error
304  * \retval MCU_ERR_API_TEST_REPORT: Report test result error
305  *******************************************************************/
306 sfx_u8 MCU_API_report_test_result(sfx_bool status, sfx_s16 rssi);
307 
308 /*!******************************************************************
309  * \fn sfx_u8 MCU_API_get_version(sfx_u8 **version, sfx_u8 *size)
310  * \brief Returns current MCU API version
311  *
312  * \param[out] sfx_u8 **version Pointer to Byte array (ASCII format) containing library version
313  * \param[out] sfx_u8 *size Size of the byte array pointed by *version
314  *
315  * \retval SFX_ERR_NONE: No error
316  * \retval MCU_ERR_API_GET_VERSION: Get Version error
317  *******************************************************************/
318 sfx_u8 MCU_API_get_version(sfx_u8** version, sfx_u8* size);
319 
320 /*!******************************************************************
321  * \fn sfx_u8 MCU_API_get_device_id_and_payload_encryption_flag(sfx_u8 dev_id[ID_LENGTH], sfx_bool *payload_encryption_enabled)
322  * \brief This function copies the device ID in dev_id, and
323  * the payload encryption flag in payload_encryption_enabled.
324  *
325  * \param[in] none
326  * \param[out] sfx_u8 dev_id[ID_LENGTH] Pointer on the device ID
327  * \param[out] sfx_bool *payload_encryption_enabled Payload is encrypted if SFX_TRUE, not encrypted else
328  *
329  * \retval SFX_ERR_NONE: No error
330  * \retval MCU_ERR_API_GET_ID_PAYLOAD_ENCR_FLAG: Error when getting device ID or payload encryption flag
331  *******************************************************************/
332 sfx_u8 MCU_API_get_device_id_and_payload_encryption_flag(sfx_u8 dev_id[ID_LENGTH], sfx_bool *payload_encryption_enabled);
333 
334 /*!******************************************************************
335  * \fn sfx_u8 MCU_API_get_initial_pac(sfx_u8 initial_pac[PAC_LENGTH])
336  * \brief Get the value of the initial PAC stored in the device. This
337  * value is used when the device is registered for the first time on
338  * the backend.
339  *
340  * \param[in] none
341  * \param[out] sfx_u8 *initial_pac Pointer to initial PAC
342  *
343  * \retval SFX_ERR_NONE: No error
344  * \retval MCU_ERR_API_GET_PAC: Error when getting initial PAC
345  *******************************************************************/
346 sfx_u8 MCU_API_get_initial_pac(sfx_u8 initial_pac[PAC_LENGTH]);
MCU_API_delay
sfx_u8 MCU_API_delay(sfx_delay_t delay_type)
Inter stream delay, called between each RF_API_send.
Definition: mcu_api_stm32.c:131
sigfox_api.h
Sigfox user functions.
MCU_API_get_nv_mem
sfx_u8 MCU_API_get_nv_mem(sfx_u8 read_data[SFX_NVMEM_BLOCK_SIZE])
This function copies the data read from non volatile memory into the buffer pointed by read_data....
Definition: mcu_api_stm32.c:74
MCU_API_set_nv_mem
sfx_u8 MCU_API_set_nv_mem(sfx_u8 data_to_write[SFX_NVMEM_BLOCK_SIZE])
This function writes data pointed by data_to_write to non volatile memory. It is strongly recommande...
Definition: mcu_api_stm32.c:85
MCU_API_timer_start
sfx_u8 MCU_API_timer_start(sfx_u32 time_duration_in_s)
Start timer for in second duration.
Definition: tim.c:284
MCU_API_timer_start_carrier_sense
sfx_u8 MCU_API_timer_start_carrier_sense(sfx_u16 time_duration_in_ms)
Start timer for :
Definition: tim.c:228
MCU_API_malloc
sfx_u8 MCU_API_malloc(sfx_u16 size, sfx_u8 **returned_pointer)
Allocate memory for library usage (Memory usage = size (Bytes)) This function is only called once at ...
Definition: mcu_api_stm32.c:53
MCU_API_get_voltage_temperature
sfx_u8 MCU_API_get_voltage_temperature(sfx_u16 *voltage_idle, sfx_u16 *voltage_tx, sfx_s16 *temperature)
Get voltage and temperature for Out of band frames Value must respect the units bellow for backend co...
Definition: mcu_api_stm32.c:104
sfx_credentials_use_key_t
sfx_credentials_use_key_t
Definition: sigfox_api.h:448
MCU_API_aes_128_cbc_encrypt
sfx_u8 MCU_API_aes_128_cbc_encrypt(sfx_u8 *encrypted_data, sfx_u8 *data_to_encrypt, sfx_u8 aes_block_len, sfx_u8 key[16], sfx_credentials_use_key_t use_key)
Encrypt a complete buffer with Secret or Test key. The secret key corresponds to the private key pro...
Definition: mcu_api_stm32.c:155
MCU_API_get_device_id_and_payload_encryption_flag
sfx_u8 MCU_API_get_device_id_and_payload_encryption_flag(sfx_u8 dev_id[ID_LENGTH], sfx_bool *payload_encryption_enabled)
This function copies the device ID in dev_id, and the payload encryption flag in payload_encryption_e...
Definition: mcu_api_stm32.c:36
MCU_API_report_test_result
sfx_u8 MCU_API_report_test_result(sfx_bool status, sfx_s16 rssi)
To report the result of Rx test for each valid message received/validated by library....
Definition: mcu_api_stm32.c:180
sfx_delay_t
sfx_delay_t
Definition: sigfox_api.h:437
MCU_API_get_version
sfx_u8 MCU_API_get_version(sfx_u8 **version, sfx_u8 *size)
Returns current MCU API version.
Definition: mcu_api_stm32.c:172
MCU_API_free
sfx_u8 MCU_API_free(sfx_u8 *ptr)
Free memory allocated to library.
Definition: mcu_api_stm32.c:96
sigfox_types.h
Sigfox types definition.
MCU_API_timer_stop_carrier_sense
sfx_u8 MCU_API_timer_stop_carrier_sense(void)
Stop the timer (started with MCU_API_timer_start_carrier_sense)
Definition: tim.c:345
MCU_API_timer_stop
sfx_u8 MCU_API_timer_stop(void)
Stop the timer (started with MCU_API_timer_start)
Definition: tim.c:333
MCU_API_get_initial_pac
sfx_u8 MCU_API_get_initial_pac(sfx_u8 initial_pac[PAC_LENGTH])
Get the value of the initial PAC stored in the device. This value is used when the device is register...
Definition: mcu_api_stm32.c:45
MCU_API_timer_wait_for_end
sfx_u8 MCU_API_timer_wait_for_end(void)
Blocking function to wait for interrupt indicating timer elapsed. This function is only used for the...
Definition: tim.c:371