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