Sigfox MCU functions. More...

#include "main.h"
#include "st_mcu_api.h"
#include "mcu_api.h"
#include "tim.h"
#include "usart.h"
#include "retriever_api.h"

Macros
#define	MCU_ERR_API_AES_GET_CRYPT (sfx_u8)(0x21)

#define	MCU_ERR_API_AES_DECRYPT (sfx_u8)(0x22)

#define	MCU_API_VER "v2.3.5"

Functions
void	ST_MCU_API_SetEncryptionPayload (uint8_t ePayload)
	This function toggles the payload encryption option. More...

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_enabled. More...

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 registered for the first time on the backend. More...

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 the opening of the Sigfox Library ( SIGF. More...

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. The size of the data to read is SFX_NVMEM_BLOCK_SIZE bytes. CAREFUL : this value can change according to the features included in the library (covered zones, etc.) More...

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 recommanded to use NV memory like EEPROM since this function is called at each SIGFOX_API_send_xxx. The size of the data to write is SFX_NVMEM_BLOCK_SIZE bytes. CAREFUL : this value can change according to the features included in the library (covered zones, etc.) More...

sfx_u8	MCU_API_free (sfx_u8 *ptr)
	Free memory allocated to library. More...

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 compatibility More...

sfx_u8	MCU_API_delay (sfx_delay_t delay_type)
	Inter stream delay, called between each RF_API_send. More...

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 provided from the CRA. These keys must be stored in a secure place. Can be hardcoded or soft coded (iv vector contains '0') More...

sfx_u8	MCU_API_get_version (sfx_u8 *version, sfx_u8 size)
	Returns current MCU API version. More...

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. Manufacturer api to show the result of RX test mode : can be uplink radio frame or uart print or gpio output. RSSI parameter is only used to report the rssi of received frames (downlink test) More...

Detailed Description

Sigfox MCU functions.

Author: R&D HT Micron, STMicroelectronics

Version: 1.0

Date: Sept 2, 2019

Author: R&D HT Micron

Version: 1.0

Date: Sept 2, 2019

Author: R&D HT Micron, H�ndrick Bataglin Gon�alves, Vilson Petry, STMicroelectronics

Version: 1.0

Date: Sept 2, 2019

Macro Definition Documentation

◆ MCU_ERR_API_AES_DECRYPT

#define MCU_ERR_API_AES_DECRYPT (sfx_u8)(0x22)

Error on MCU_API_aes_128_cbc_decrypt

◆ MCU_ERR_API_AES_GET_CRYPT

#define MCU_ERR_API_AES_GET_CRYPT (sfx_u8)(0x21)

Error on MCU_API_get_encrypted_info

Function Documentation

◆ 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 provided from the CRA. These keys must be stored in a secure place.
Can be hardcoded or soft coded (iv vector contains '0')

Parameters

[out]	sfx_u8	*encrypted_data Result of AES Encryption
[in]	sfx_u8	*data_to_encrypt Input data to Encrypt
[in]	sfx_u8	aes_block_len Input data length (should be a multiple of an AES block size, ie. AES_BLOCK_SIZE bytes)
[in]	sfx_u8	key[16] Input key
[in]	sfx_credentials_use_key_t	use_key Key to use - private key or input key

Return values

SFX_ERR_NONE	No error
MCU_ERR_API_AES	AES Encryption error

◆ MCU_API_delay()

sfx_u8 MCU_API_delay ( sfx_delay_t delay_type )

Inter stream delay, called between each RF_API_send.

SFX_DLY_INTER_FRAME_TX : 0 to 2s in Uplink DC
SFX_DLY_INTER_FRAME_TRX : 500 ms in Uplink/Downlink FH & Downlink DC
SFX_DLY_OOB_ACK : 1.4s to 4s for Downlink OOB
SFX_CS_SLEEP : delay between several trials of Carrier Sense (for the first frame only)

Parameters

[in]	sfx_delay_t	delay_type Type of delay to call
[out]	none

Return values

SFX_ERR_NONE	No error
MCU_ERR_API_DLY	Delay error

◆ MCU_API_free()

sfx_u8 MCU_API_free ( sfx_u8 * ptr )

Free memory allocated to library.

Parameters

[in]	sfx_u8	*ptr pointer to buffer
[out]	none

Return values

SFX_ERR_NONE	No error
MCU_ERR_API_FREE	Free error

◆ 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_enabled.

Parameters

[in]	none
[out]	sfx_u8	dev_id[ID_LENGTH] Pointer on the device ID
[out]	sfx_bool	*payload_encryption_enabled Payload is encrypted if SFX_TRUE, not encrypted else

Return values

SFX_ERR_NONE	No error
MCU_ERR_API_GET_ID_PAYLOAD_ENCR_FLAG	Error when getting device ID or payload encryption flag

◆ 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 registered for the first time on the backend.

Parameters

[in]	none
[out]	sfx_u8	*initial_pac Pointer to initial PAC

Return values

SFX_ERR_NONE	No error
MCU_ERR_API_GET_PAC	Error when getting initial PAC

◆ 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.
The size of the data to read is SFX_NVMEM_BLOCK_SIZE bytes. CAREFUL : this value can change according to the features included in the library (covered zones, etc.)

Parameters

[in]	none
[out]	sfx_u8	read_data[SFX_NVMEM_BLOCK_SIZE] Pointer to the data bloc to write with the data stored in memory

Return values

SFX_ERR_NONE	No error
MCU_ERR_API_GETNVMEM	Read nvmem error

◆ MCU_API_get_version()

sfx_u8 MCU_API_get_version	(	sfx_u8 **	version,
		sfx_u8 *	size
	)

Returns current MCU API version.

Parameters

[out]	sfx_u8	**version Pointer to Byte array (ASCII format) containing library version
[out]	sfx_u8	size Size of the byte array pointed by version

Return values

SFX_ERR_NONE	No error
MCU_ERR_API_GET_VERSION	Get Version error

◆ 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 compatibility

Parameters

[in]	none
[out]	sfx_u16	*voltage_idle Device's voltage in Idle state (mV)
[out]	sfx_u16	*voltage_tx Device's voltage in Tx state (mV) - for the last transmission
[out]	sfx_s16	*temperature Device's temperature in 1/10 of degrees celcius

Return values

SFX_ERR_NONE	No error
MCU_ERR_API_VOLT_TEMP	Get voltage/temperature error

◆ 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 the opening of the Sigfox Library ( SIGF.

IMPORTANT NOTE:

The address reported need to be aligned with architecture of the microprocessor used. For a Microprocessor of:

8 bits => any address is allowed
16 bits => only address multiple of 2 are allowed
32 bits => only address multiple of 4 are allowed

Parameters

[in]	sfx_u16	size size of buffer to allocate in bytes
[out]	sfx_u8	**returned_pointer pointer to buffer (can be static)

Return values

SFX_ERR_NONE	No error
MCU_ERR_API_MALLOC	Malloc error

◆ 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.
Manufacturer api to show the result of RX test mode : can be uplink radio frame or uart print or gpio output. RSSI parameter is only used to report the rssi of received frames (downlink test)

Parameters

[in]	sfx_bool	status Is SFX_TRUE when result ok else SFX_FALSE See SIGFOX_API_test_mode summary
[in]	rssi	RSSI of the received frame

Return values

SFX_ERR_NONE	No error
MCU_ERR_API_TEST_REPORT	Report test result error

◆ 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 recommanded to use NV memory like EEPROM since this function is called at each SIGFOX_API_send_xxx. The size of the data to write is SFX_NVMEM_BLOCK_SIZE bytes. CAREFUL : this value can change according to the features included in the library (covered zones, etc.)

Parameters

[in]	sfx_u8	data_to_write[SFX_NVMEM_BLOCK_SIZE] Pointer to data bloc to be written in memory
[out]	none

Return values

SFX_ERR_NONE	No error
MCU_ERR_API_SETNVMEM	Write nvmem error

◆ ST_MCU_API_SetEncryptionPayload()

void ST_MCU_API_SetEncryptionPayload ( uint8_t ePayloads )

This function toggles the payload encryption option.

Parameters

[in] sfx_u8 ePayload : set to 1 to enable encryption, 0 to disable.

Return values

None.

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ MCU_ERR_API_AES_DECRYPT

◆ MCU_ERR_API_AES_GET_CRYPT

Function Documentation

◆ MCU_API_aes_128_cbc_encrypt()

◆ MCU_API_delay()

◆ MCU_API_free()

◆ MCU_API_get_device_id_and_payload_encryption_flag()

◆ MCU_API_get_initial_pac()

◆ MCU_API_get_nv_mem()

◆ MCU_API_get_version()

◆ MCU_API_get_voltage_temperature()

◆ MCU_API_malloc()

IMPORTANT NOTE:

◆ MCU_API_report_test_result()

◆ MCU_API_set_nv_mem()

◆ ST_MCU_API_SetEncryptionPayload()