Basic examples

Except for the ASYNCHRONOUS flag, the following examples are given for the default full-featured compilation flags set (sigfox_ep_flags.h file provided in the repository). But depending on your flags selection, not all fields will be required when filling the structures: for example, if you define the flag TX_POWER_DBM_EIRP with value 14, the dynamic field tx_power_dbm_eirp will not appear anymore in the input structure, the macro value will be sent to the radio driver directly.

All examples are based on the following common definitions:

#include "sigfox_ep_api.h"
#include "sigfox_error.h"
#include "sigfox_rc.h"
#include "sigfox_types.h"

// Applicative error codes.
typedef enum {
    APP_SUCCESS = 0,
    APP_ERROR_EP_LIBRARY,
    APP_ERROR_LAST
} APP_status_t;

// Global variables.
APP_status_t status = APP_SUCCESS;
SIGFOX_EP_API_status_t sigfox_ep_api_status = SIGFOX_EP_API_SUCCESS;

If you want to use the macro SIGFOX_EP_API_check_status() as shown below, you need to define the error label within the function it is called.

Blocking mode

In this section, the ASYNCHRONOUS is disabled, all functions will block until their full completion.

Opening the library

// Local variables.
SIGFOX_EP_API_config_t lib_config;

// Configure library.
lib_config.rc = &SIGFOX_RC1;
lib_config.message_counter_rollover = SIGFOX_MESSAGE_COUNTER_ROLLOVER_4096;

// Open library.
sigfox_ep_api_status = SIGFOX_EP_API_open(&lib_config);
SIGFOX_EP_API_check_status(APP_ERROR_EP_LIBRARY);

Closing the library

sigfox_ep_api_status = SIGFOX_EP_API_close();
SIGFOX_EP_API_check_status(APP_ERROR_EP_LIBRARY);

Sending application messages

// UL payload size macro.
#define APP_UL_PAYLOAD_SIZE    9

// Local variables.
SIGFOX_EP_API_application_message_t application_message;
SIGFOX_EP_API_message_status_t message_status;
sfx_u8 app_ul_payload[APP_UL_PAYLOAD_SIZE] = {0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08};
sfx_u8 app_dl_payload[SIGFOX_DL_PAYLOAD_SIZE_BYTES];
sfx_s16 dl_rssi_dbm = 0;

// Configure message.
application_message.common_parameters.ul_bit_rate = SIGFOX_UL_BIT_RATE_100BPS;
application_message.common_parameters.tx_power_dbm_eirp = 14;
application_message.common_parameters.number_of_frames = 3;
application_message.common_parameters.t_ifu_ms = 500;
application_message.common_parameters.ep_key_type = SIGFOX_EP_KEY_PRIVATE;
application_message.type = SIGFOX_APPLICATION_MESSAGE_TYPE_BYTE_ARRAY;
application_message.ul_payload = (sfx_u8*) app_ul_payload;
application_message.ul_payload_size_bytes = APP_UL_PAYLOAD_SIZE;
application_message.t_conf_ms = 2000;

Uplink only mode

// Reset bidirectional flag.
application_message.bidirectional_flag = SFX_FALSE;

// Send message.
sigfox_ep_api_status = SIGFOX_EP_API_send_application_message(&application_message);
SIGFOX_EP_API_check_status(APP_ERROR_EP_LIBRARY);

Uplink with downlink request

// Set bidirectional flag.
application_message.bidirectional_flag = SFX_TRUE;

// Send message.
sigfox_ep_api_status = SIGFOX_EP_API_send_application_message(&application_message);
SIGFOX_EP_API_check_status(APP_ERROR_EP_LIBRARY);

// Read message status to check if downlink sequence was successful.
message_status = SIGFOX_EP_API_get_message_status();
if (message_status.field.dl_frame != 0) {
    // Read downlink data.
    sigfox_ep_api_status = SIGFOX_EP_API_get_dl_payload(app_dl_payload,
                                                        SIGFOX_DL_PAYLOAD_SIZE_BYTES,
                                                        &dl_rssi_dbm);
    SIGFOX_EP_API_check_status(APP_ERROR_EP_LIBRARY);
}

Sending control keep alive messages

// Local variables.
SIGFOX_EP_API_control_message_t control_message;

// Configure message.
control_message.common_parameters.ul_bit_rate = SIGFOX_UL_BIT_RATE_600BPS;
control_message.common_parameters.tx_power_dbm_eirp = 14;
control_message.common_parameters.number_of_frames = 3;
control_message.common_parameters.t_ifu_ms = 500;
control_message.common_parameters.ep_key_type = SIGFOX_EP_KEY_PRIVATE;
control_message.type = SIGFOX_CONTROL_MESSAGE_TYPE_KEEP_ALIVE;

// Send message.
sigfox_ep_api_status = SIGFOX_EP_API_send_control_message(&control_message);
SIGFOX_EP_API_check_status(APP_ERROR_EP_LIBRARY);

Asynchronous mode

In this section, the ASYNCHRONOUS is enabled. All functions will return directly but you need to define at least the process callback (of type SIGFOX_EP_API_process_cb_t) which will be called by the core library when it has to be processed. Since this function can be called within an interrupt context, the best practice is to set a flag and process the library in the main routine, as shown below.

Tip

If you set the process callback to NULL when opening the library, it will operate in blocking mode.

Optional callbacks for the uplink, downlink and full message sequences completion can be defined to notify the application that the current operation has been completed. You can also poll the message status to read the progress of the current transmission.

// Global variables.
static volatile sfx_bool sigfox_process_flag = SFX_FALSE;
static volatile sfx_bool sigfox_message_completion_flag = SFX_FALSE;

// Process callback.
void SIGFOX_process_callback(void) {
    sigfox_process_flag = SFX_TRUE;
}

// Message completion callback.
void SIGFOX_message_completion_callback(void) {
    sigfox_message_completion_flag = SFX_TRUE;
}

// Main routine.
int main(void) {
    // Local variables.
    SIGFOX_EP_API_message_status_t message_status;
    sfx_u8 app_dl_payload[SIGFOX_DL_PAYLOAD_SIZE_BYTES];
    sfx_s16 dl_rssi_dbm = 0;
    // Main loop.
    while (1) {
        // Check Sigfox process flag.
        if (sigfox_process_flag == SFX_TRUE) {
            // Call process handler.
            sigfox_ep_api_status = SIGFOX_EP_API_process();
            // Clear flag.
	    sigfox_process_flag = SFX_FALSE;
            // Check status.
            SIGFOX_EP_API_check_status(APP_ERROR_EP_LIBRARY);
        }
        // Check message completion.
        if (sigfox_message_completion_flag == SFX_TRUE) {
            // Clear flag.
            sigfox_message_completion_flag = SFX_FALSE;
            // Read message status to check if message sequence was successful.
            message_status = SIGFOX_EP_API_get_message_status();
            if (message_status.field.dl_frame != 0) {
                // Read downlink data.
                sigfox_ep_api_status = SIGFOX_EP_API_get_dl_payload(app_dl_payload,
                                                                    SIGFOX_DL_PAYLOAD_SIZE_BYTES,
                                                                    &dl_rssi_dbm);
                SIGFOX_EP_API_check_status(APP_ERROR_EP_LIBRARY);
            }
            // Process applicative state machine accordingly...
        }
    }
errors:
    return 0;
}

Opening the library

// Local variables.
SIGFOX_EP_API_config_t lib_config;

// Configure library.
lib_config.rc = &SIGFOX_RC1;
lib_config.message_counter_rollover = SIGFOX_MESSAGE_COUNTER_ROLLOVER_4096;
lib_config.process_cb = &SIGFOX_process_callback;

// Open library.
sigfox_ep_api_status = SIGFOX_EP_API_open(&lib_config);
SIGFOX_EP_API_check_status(APP_ERROR_EP_LIBRARY);

Closing the library

sigfox_ep_api_status = SIGFOX_EP_API_close();
SIGFOX_EP_API_check_status(APP_ERROR_EP_LIBRARY);

Sending application messages

// UL payload size macro.
#define APP_UL_PAYLOAD_SIZE    9

// Local variables.
SIGFOX_EP_API_application_message_t application_message;
SIGFOX_EP_API_message_status_t message_status;
sfx_u8 app_ul_payload[APP_UL_PAYLOAD_SIZE] = {0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08};

// Configure message.
application_message.common_parameters.ul_bit_rate = SIGFOX_UL_BIT_RATE_100BPS;
application_message.common_parameters.tx_power_dbm_eirp = 14;
application_message.common_parameters.number_of_frames = 3;
application_message.common_parameters.t_ifu_ms = 500;
application_message.common_parameters.ep_key_type = SIGFOX_EP_KEY_PRIVATE;
application_message.type = SIGFOX_APPLICATION_MESSAGE_TYPE_BYTE_ARRAY;
application_message.ul_payload = (sfx_u8*) app_ul_payload;
application_message.ul_payload_size_bytes = APP_UL_PAYLOAD_SIZE;
application_message.t_conf_ms = 2000;
application_message.uplink_cplt_cb = SFX_NULL;
application_message.downlink_cplt_cb = SFX_NULL;
application_message.message_cplt_cb = &SIGFOX_message_completion_callback;

Uplink only mode

// Reset bidirectional flag.
application_message.bidirectional_flag = SFX_FALSE;

// Send message.
sigfox_ep_api_status = SIGFOX_EP_API_send_application_message(&application_message);
SIGFOX_EP_API_check_status(APP_ERROR_EP_LIBRARY);

Uplink with downlink request

// Set bidirectional flag.
application_message.bidirectional_flag = SFX_TRUE;

// Send message.
sigfox_ep_api_status = SIGFOX_EP_API_send_application_message(&application_message);
SIGFOX_EP_API_check_status(APP_ERROR_EP_LIBRARY);

Sending control keep alive messages

// Local variables.
SIGFOX_EP_API_control_message_t control_message;

// Configure message.
control_message.common_parameters.ul_bit_rate = SIGFOX_UL_BIT_RATE_600BPS;
control_message.common_parameters.tx_power_dbm_eirp = 14;
control_message.common_parameters.number_of_frames = 3;
control_message.common_parameters.t_ifu_ms = 500;
control_message.common_parameters.ep_key_type = SIGFOX_EP_KEY_PRIVATE;
control_message.type = SIGFOX_CONTROL_MESSAGE_TYPE_KEEP_ALIVE;
control_message.uplink_cplt_cb = SFX_NULL;
control_message.message_cplt_cb = &SIGFOX_message_completion_callback;

// Send message.
sigfox_ep_api_status = SIGFOX_EP_API_send_control_message(&control_message);
SIGFOX_EP_API_check_status(APP_ERROR_EP_LIBRARY);

SIGFOX 0G TECHNOLOGY BY UNABIZ
WebSite | YouTube | Linkedin | Build

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Basic examples

Blocking mode

Opening the library

Closing the library

Sending application messages

Sending control keep alive messages

Asynchronous mode

Opening the library

Closing the library

Sending application messages

Sending control keep alive messages

Content

Clone this wiki locally