Interface functions description

User API

The user API is the applicative entry point of the Sigfox End-Point library. It is defined in the sigfox_ep_api.h header file which provide the functions to configure the library and send messages over Sigfox network.

Function & brief description	Required flag(s)	Input state(s)	Output state(s)
SIGFOX_EP_API_open() Open the library in a given radio configuration (RCx), initialize its internal context and open manufacturer drivers.		CLOSED	READY
SIGFOX_EP_API_close() Close the library and manufacturer drivers.		READY	CLOSED
SIGFOX_EP_API_process() In asynchronous mode, this function must be called to process the internal library state machine after a low level event, notified through the process callback (RF and MCU interrupts such as end of timer, end of transmission, etc...).	ASYNCHRONOUS	Any	See state machine
SIGFOX_EP_API_send_application_message() Send an application message over Sigfox network. In blocking mode, this function only returns at the end of the message sending sequence.	APPLICATION_MESSAGES	READY	See state machine
SIGFOX_EP_API_send_control_message() Send a control keep-alive message over Sigfox network. In blocking mode, this function only returns at the end of the message sending sequence.	CONTROL_KEEP_ALIVE_MESSAGE	READY	See state machine
SIGFOX_EP_API_get_dl_payload() Get the downlink payload received after the last successful bidirectional procedure.	APPLICATION_MESSAGES and BIDIRECTIONAL	Any except CLOSED	Unchanged
SIGFOX_EP_API_get_message_status() Get the status of the last message sequence.		Any	Any
SIGFOX_EP_API_get_state() In asynchronous mode, get the current library state.	ASYNCHRONOUS	Any	Any
SIGFOX_EP_API_get_ep_id() Get the Sigfox end-point ID stored by the manufacturer.	VERBOSE	Any except CLOSED	Unchanged
SIGFOX_EP_API_get_initial_pac() Get the Sigfox enf-point initial PAC code stored by the manufacturer.	VERBOSE	Any except CLOSED	Unchanged
SIGFOX_EP_API_get_version() Get version of end-point library components (Core library, MCU driver and RF driver).	VERBOSE	Any except CLOSED	Unchanged
SIGFOX_EP_API_get_flags() Get the compilation flags list used to optimize the code (read as string).	VERBOSE	Any	Unchanged
SIGFOX_EP_API_unstack_error() Unstack the last low level error catched by the library. This function can be called multiple times to unstack all errors, until the source is set to SIGFOX_ERROR_SOURCE_NONE.	ERROR_CODES and ERROR_STACK	Any	Unchanged
SIGFOX_EP_API_stack_error() This macro adds a SIGFOX EP API error in the stack (if enabled).	ERROR_CODES	Any	Unchanged
SIGFOX_EP_API_check_status() This macro checks a SIGFOX EP API status. In case of error, it stores the code in the stack (if enabled) and directly jumps to the error label.	ERROR_CODES	Any	Unchanged

MCU API

This low level API defines the MCU related functions needed by the Sigfox end-point library. Templates are defined in the mcu_api.h header file.

Function & brief description	Required flag(s)
MCU_API_open() Open MCU driver. This function is called when opening the library and can be used to initialize the required peripherals.	ASYNCHRONOUS or LOW_LEVEL_OPEN_CLOSE
MCU_API_close() Close MCU driver. This function is called when closing the library and can be used to release the required peripherals.	LOW_LEVEL_OPEN_CLOSE
MCU_API_process() In asynchronous mode, this optional function can be used to execute some code in the MCU driver when the library is processed.	ASYNCHRONOUS
MCU_API_timer_start() Start a timer.	TIMER_REQUIRED
MCU_API_timer_stop() Stop a timer	TIMER_REQUIRED
MCU_API_timer_status() In blocking mode, get the current status of a timer.	TIMER_REQUIRED and not ASYNCHRONOUS
MCU_API_timer_wait_cplt() In blocking mode, waits for a timer completion.	TIMER_REQUIRED and not ASYNCHRONOUS
MCU_API_aes_128_cbc_encrypt() Perform AES-128 encryption to compute UL_AUTH or DL_AUTH fields.
MCU_API_compute_crc16() If you want to use a custom or hardware CRC, this function will be called to perform a 16-bits CRC operation needed to compute the UL_CRC field.	CRC_HW
MCU_API_compute_crc8() If you want to use a custom or hardware CRC, this function will be called to perform a 8-bits CRC operation needed to compute the DL_CRC field.	CRC_HW and BIDIRECTIONAL
MCU_API_get_ep_id() Returns the Sigfox end-point ID.
MCU_API_get_nvm() Read the library non-volatile data.
MCU_API_set_nvm() Write the library non-volatile data.
MCU_API_get_voltage_temperature() Perform idle voltage, TX voltage and temperature measurements.	CONTROL_KEEP_ALIVE_MESSAGE or BIDIRECTIONAL
MCU_API_print_dl_payload() This function is used during downlink test modes to print a received downlink payload. It is only called by the RF & Protocol addon	CERTIFICATION and BIDIRECTIONAL
MCU_API_get_initial_pac() Returns the Sigfox end-point PAC code.	VERBOSE
MCU_API_get_latency() When latency compensation feature is enabled, this function returns the MCU operations latency.	TIMER_REQUIRED and LATENCY_COMPENSATION and BIDIRECTIONAL
MCU_API_get_version() Returns the MCU driver version.	VERBOSE
MCU_API_error() This function is called by the core library as soon as an error occurs during the processing. It should put all the MCU driver in a sane state, in order to be able to start new operations after the error.	ERROR_CODES
MCU_API_stack_error() This macro stacks an MCU API error in the stack (if enabled).	ERROR_CODES
MCU_API_check_status() This macro checks an MCU API status. In case of error, it stores the code in the stack (if enabled) and directly jumps to the error label.	ERROR_CODES

Note

TIMER_REQUIRED is a secondary flag derived from the compilation flags. It is defined in the sigfox_types.h file.

RF API

This low level API defines the radio related functions needed by the Sigfox end-point library. Templates are defined in the rf_api.h header file.

Function & brief description	Required flag(s)
RF_API_open() Open RF driver. This function is called when opening the library and can be used to initialize the required peripherals.	ASYNCHRONOUS or LOW_LEVEL_OPEN_CLOSE
RF_API_close() Close RF driver. This function is called when closing the library and can be used to release the required peripherals.	LOW_LEVEL_OPEN_CLOSE
RF_API_process() In asynchronous mode, this optional function can be used to execute some code in the RF driver when the library is processed.	ASYNCHRONOUS
RF_API_wake_up() Turn radio on. This function is called once at the beginning of an uplink sequence and once at the beginning of a downlink sequence.
RF_API_sleep() Turn radio off. This function is called once at the end of an uplink sequence and once at the end of a downlink sequence.
RF_API_init() Init the radio. This function is called before each individual uplink frame transmission and before each individual downlink window.
RF_API_de_init() Stop the radio. This function is called after each individual uplink frame transmission and after each individual downlink window.
RF_API_send() Send an uplink frame over the air (using the radio parameters given in the init function). In blocking mode, this function blocks until the full bitstream is sent. In asynchronous mode, this function only starts the modulation.
RF_API_receive() Receive a downlink frame (using the radio parameters given in the init function). In blocking mode, this function blocks until the frame is received or the downlink timeout is reached. In asynchronous mode, this function only starts the reception.	BIDIRECTIONAL
RF_API_get_dl_phy_content_and_rssi() Read the last downlink PHY content and RSSI received by the radio.	BIDIRECTIONAL
RF_API_carrier_sense() Perform a carrier sense operation (LBT).	REGULATORY and SPECTRUM_ACCESS_LBT
RF_API_get_latency() When latency compensation feature is enabled, this function returns the RF operations latency.	TIMER_REQUIRED and LATENCY_COMPENSATION
RF_API_start_continuous_wave() Start continuous wave. This function is only called by the Type Approval addon.	CERTIFICATION
RF_API_get_version() Returns the RF driver version.	VERBOSE
RF_API_error() This function is called by the core library as soon as an error occurs during the processing. It should put all the RF driver in a sane state, in order to be able to start new operations after the error.	VERBOSE
RF_API_stack_error() This macro stacks an RF API error in the stack (if enabled).	ERROR_CODES
RF_API_check_status() This macro checks an RF API status. In case of error, it stores the code in the stack (if enabled) and directly jumps to the error label.	ERROR_CODES

Note

TIMER_REQUIRED and SPECTRUM_ACCESS_LBT are secondary flags derived from the compilation flags. They are defined in the sigfox_types.h file.