How to use Sigfox library in FH bands - sigfox-tech-radio/sigfox-ep-lib GitHub Wiki

For better readability, the following examples are written in blocking mode with dynamic radio parameters. The code must be adapted to your specific flags selection.

Testing the 54 channels coverage (long message)

The device firmware has to embed the Type Approval addon which features the long message option when using the continuous uplink test mode (CSUL). The certification flag must be enabled to use the addon.

In the sigfox_ep_flags.h file:

#define SIGFOX_EP_CERTIFICATION

In the Sigfox application (example with RC2):

#ifndef SIGFOX_EP_DISABLE_FLAGS_FILE
#include "sigfox_ep_flags.h"
#endif
#include "sigfox_ep_addon_ta_api.h"
#include "sigfox_error.h"
#include "sigfox_rc.h"
#include "sigfox_types.h"

int main(void) {

    // Local variables.
    SIGFOX_EP_ADDON_TA_API_status_t sigfox_ep_addon_ta_status = SIGFOX_EP_ADDON_TA_API_SUCCESS;
    SIGFOX_EP_ADDON_TA_API_config_t addon_config;
    SIGFOX_EP_ADDON_TA_API_csul_test_mode_t csul_test_mode;

    // Addon configuration.
    addon_config.rc = &SIGFOX_RC2;
    // Open type approval addon.
    sigfox_ep_addon_ta_status = SIGFOX_EP_ADDON_TA_API_open(&addon_config);
    if (sigfox_ep_addon_ta_status != SIGFOX_EP_ADDON_TA_API_SUCCESS) {
        // Handle error.
    }

    // Continuous uplink test mode parameters.
    csul_test_mode.number_of_frames = 10000;
    csul_test_mode.tx_frequency_hz = 0;
    csul_test_mode.frequency_hopping_mode = SIGFOX_EP_ADDON_TA_API_FH_MODE_ALL_MACRO_CHANNELS; // <= v2.1
    csul_test_mode.frequency_hopping_mode = SIGFOX_EP_ADDON_TA_API_FH_MODE_LONG_MESSAGE; // >= v3.0
    csul_test_mode.ul_bit_rate = SIGFOX_UL_BIT_RATE_600BPS;
    csul_test_mode.tx_power_dbm_eirp = 22;
    // Execute test in long message mode.
    sigfox_ep_addon_ta_status = SIGFOX_EP_ADDON_TA_API_execute_continuous_sigfox_uplink(&csul_test_mode);
    if (sigfox_ep_addon_ta_status != SIGFOX_EP_ADDON_TA_API_SUCCESS) {
        // Handle error.
    }

    // Close addon.
    sigfox_ep_addon_ta_status = SIGFOX_EP_ADDON_TA_API_close();
    if (sigfox_ep_addon_ta_status != SIGFOX_EP_ADDON_TA_API_SUCCESS) {
        // Handle error.
    }
    
    return 0;
}

Using the device on the field (short message)

As Sigfox maximum uplink payload is limited to 12 bytes, the device firmware does not require any addon and the certification flag can be disabled. Assuming that the regulatory flag is enabled, the Sigfox EP library will implement the short message feature in FH zones.

In the sigfox_ep_flags.h file:

#define SIGFOX_EP_REGULATORY
//#define SIGFOX_EP_CERTIFICATION

In the Sigfox application (example with RC2):

#ifndef SIGFOX_EP_DISABLE_FLAGS_FILE
#include "sigfox_ep_flags.h"
#endif
#include "sigfox_ep_api.h"
#include "sigfox_error.h"
#include "sigfox_rc.h"
#include "sigfox_types.h"

#define APP_UL_PAYLOAD_SIZE     9

int main(void) {

    // Local variables.
    SIGFOX_EP_API_status_t sigfox_ep_api_status = SIGFOX_EP_API_SUCCESS;
    SIGFOX_EP_API_config_t lib_config;
    SIGFOX_EP_API_application_message_t application_message;
    sfx_u8 app_ul_payload[APP_UL_PAYLOAD_SIZE] = {0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08};

    // Open library.
    lib_config.rc = &SIGFOX_RC2;
    lib_config.message_counter_rollover = SIGFOX_MESSAGE_COUNTER_ROLLOVER_4096;
    sigfox_ep_api_status = SIGFOX_EP_API_open(&lib_config);
    if (sigfox_ep_api_status != SIGFOX_EP_API_SUCCESS) {
        // Handle error.
    }

    // Send message in short message mode.
    application_message.common_parameters.ul_bit_rate = SIGFOX_UL_BIT_RATE_600BPS;
    application_message.common_parameters.tx_power_dbm_eirp = 22;
    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.bidirectional_flag = SIGFOX_FALSE;
    application_message.t_conf_ms = 2000;
    sigfox_ep_api_status = SIGFOX_EP_API_send_application_message(&application_message);
    if (sigfox_ep_api_status != SIGFOX_EP_API_SUCCESS) {
        // Handle error.
    }

    // Close library.
    sigfox_ep_api_status = SIGFOX_EP_API_close();
    if (sigfox_ep_api_status != SIGFOX_EP_API_SUCCESS) {
        // Handle error.
    }
    
    return 0;
}