Interface functions description - sigfox-tech-radio/sigfox-ep-lib GitHub Wiki

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. For better readability, the compilation flags are written without the SIGFOX_EP prefix.

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. For better readability, the compilation flags are written without the SIGFOX_EP prefix.

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.	`AES_HW`
`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_ep_key()`Returns the Sigfox end-point private key.	Not `AES_HW`
`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_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. For better readability, the compilation flags are written without the SIGFOX_EP prefix.

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.