Sigfox manufacturer functions. More...

#include "sigfox_types.h"
#include "sigfox_api.h"

Include dependency graph for mcu_api.h:

This graph shows which files directly or indirectly include this file:

Macros
#define	MCU_ERR_API_MALLOC (sfx_u8)(0x11)

#define	MCU_ERR_API_FREE (sfx_u8)(0x12)

#define	MCU_ERR_API_VOLT_TEMP (sfx_u8)(0x13)

#define	MCU_ERR_API_DLY (sfx_u8)(0x14)

#define	MCU_ERR_API_AES (sfx_u8)(0x15)

#define	MCU_ERR_API_GETNVMEM (sfx_u8)(0x16)

#define	MCU_ERR_API_SETNVMEM (sfx_u8)(0x17)

#define	MCU_ERR_API_TIMER_START (sfx_u8)(0x18)

#define	MCU_ERR_API_TIMER_START_CS (sfx_u8)(0x19)

#define	MCU_ERR_API_TIMER_STOP_CS (sfx_u8)(0x1A)

#define	MCU_ERR_API_TIMER_STOP (sfx_u8)(0x1B)

#define	MCU_ERR_API_TIMER_END (sfx_u8)(0x1C)

#define	MCU_ERR_API_TEST_REPORT (sfx_u8)(0x1D)

#define	MCU_ERR_API_GET_VERSION (sfx_u8)(0x1E)

#define	MCU_ERR_API_GET_ID_PAYLOAD_ENCR_FLAG (sfx_u8)(0x1F)

#define	MCU_ERR_API_GET_PAC (sfx_u8)(0x20)

Functions
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_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_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_timer_start_carrier_sense (sfx_u16 time_duration_in_ms)
	Start timer for : More...

sfx_u8	MCU_API_timer_start (sfx_u32 time_duration_in_s)
	Start timer for in second duration. More...

sfx_u8	MCU_API_timer_stop (void)
	Stop the timer (started with MCU_API_timer_start) More...

sfx_u8	MCU_API_timer_stop_carrier_sense (void)
	Stop the timer (started with MCU_API_timer_start_carrier_sense) More...

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 20 seconds wait in downlink. 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...

sfx_u8	MCU_API_get_version (sfx_u8 *version, sfx_u8 size)
	Returns current MCU API version. 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...

Detailed Description

Sigfox manufacturer functions.

\if SIGFOX PATTERN

/ ___/ | | / ___| | ___| / _ \ \ \ / /
| |___ | | | | | |__ | | | | \ \/ /
___ \ | | | | _ | __| | | | | } {
___| | | | | |_| | | | | |_| | / /\ \ /_____/ |_| _____/ |_| _____/ /_/ _\

!!!! DO NOT MODIFY THIS FILE !!!!

\endif

Author

Version

Date

Copyright: Copyright (c) 2011-2015 SIGFOX, All Rights Reserved. This is unpublished proprietary source code of SIGFOX.

This file defines the manufacturer's MCU functions to be implemented for library usage.

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

◆ MCU_API_timer_start()

sfx_u8 MCU_API_timer_start ( sfx_u32 time_duration_in_s )

Start timer for in second duration.

Parameters

[in]	sfx_u32	time_duration_in_s Timer value in seconds
[out]	none

Return values

SFX_ERR_NONE	No error
MCU_ERR_API_TIMER_START	Start timer error

◆ MCU_API_timer_start_carrier_sense()

sfx_u8 MCU_API_timer_start_carrier_sense ( sfx_u16 time_duration_in_ms )

Start timer for :

carrier sense maximum window (used in ARIB standard)

Parameters

[in]	sfx_u16	time_duration_in_ms Timer value in milliseconds
[out]	none

Return values

SFX_ERR_NONE	No error
MCU_ERR_API_TIMER_START_CS	Start CS timer error

◆ MCU_API_timer_stop()

sfx_u8 MCU_API_timer_stop ( void )

Stop the timer (started with MCU_API_timer_start)

Parameters

[in]	none
[out]	none

Return values

SFX_ERR_NONE	No error
MCU_ERR_API_TIMER_STOP	Stop timer error

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

Parameters

[in]	none
[out]	none

Return values

SFX_ERR_NONE	No error
MCU_ERR_API_TIMER_STOP_CS	Stop timer error

◆ 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 20 seconds wait in downlink.

Parameters

[in]	none
[out]	none

Return values

SFX_ERR_NONE	No error
MCU_ERR_API_TIMER_END	Wait end of timer error

Macros

Functions

Detailed Description

\if SIGFOX PATTERN

\endif

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()

◆ MCU_API_timer_start()

◆ MCU_API_timer_start_carrier_sense()

◆ MCU_API_timer_stop()

◆ MCU_API_timer_stop_carrier_sense()

◆ MCU_API_timer_wait_for_end()