LoRa Basics™ Modem User Manual v1.0 documentation

LoRa Basics™ Modem API

LoRa Basics™ Modem provides a set of functions that implement the low-level LoRaWAN® network communications. This allows developers to work at a high level, using an API composed of single-command functions that perform all of the interactions with the LoRaWAN network. This chapter details the functions that make up the LoRa Basics Modem API.

smtc_modem_adr_get_profile()

smtc_modem_return_code_t smtc_modem_adr_get_profile (
                                     uint8_t stack_id,
                                     smtc_modem_adr_profile_t* adr_profile
                                     );
Brief

Get the current adaptive data rate (ADR) profile.

Parameters

[in]

stack_id

Stack identifier

[out]

adr_profile

Current ADR profile

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

Parameter adr_profile is NULL

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

SMTC_MODEM_RC_INVALID_STACK_ID

Invalid stack_id

smtc_modem_adr_set_profile()

smtc_modem_return_code_t smtc_modem_adr_set_profile (
                                    uint8_t stack_id,
                                    smtc_modem_adr_profile_t* adr_profile
                                    const uint8_t  adr_custom_data[SMTC_MODEM_CUSTOM_ADR_DATA_LENGTH]
                                    );
Brief

Set the ADR profile.

Remarks

If SMTC_MODEM_ADR_PROFILE_CUSTOM is selected, custom data are taken into account.

Parameters

[in]

stack_id

Stack identifier

[in]

adr_profile

ADR profile to be configured

[in]

adr_custom_data

Definition of the custom ADR profile

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

One or more invalid parameters

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

SMTC_MODEM_RC_INVALID_STACK_ID

Invalid stack_id

smtc_modem_alarm_clear_timer()

smtc_modem_return_code_t smtc_modem_alarm_clear_timer (void);
Brief

Stop and clear alarm timer.

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_NOT_INIT

No alarm timer currently running

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

smtc_modem_alarm_get_remaining_time()

smtc_modem_return_code_t smtc_modem_alarm_get_remaining_time  (
                                    uint32_t*  remaining_time_in_s
                                    );
Brief

Get the number of seconds remaining before the alarm triggers an event.

Parameters

[out]

remaining_time_in_s

The number of seconds remaining before the alarm triggers an event

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_NOT_INIT

No alarm timer currently running

SMTC_MODEM_RC_INVALID

Parameter remaining_time_in_s is NULL

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

smtc_modem_alarm_start_timer()

smtc_modem_return_code_t smtc_modem_alarm_start_timer  (
                                    uint32_t alarm_timer_in_s
                                    );
Brief

Set and start the alarm timer.

Remarks

When the timer expires, an alarm event is generated.

Parameters

[in]

alarm_timer_in_s

The alarm timer in seconds

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

smtc_modem_connection_timeout_get_current_values()

smtc_modem_return_code_t smtc_modem_connection_timeout_get_current_values (
                                    uint8_t     stack_id,
                                    uint16_t*   nb_of_uplinks_before_network_controlled,
                                    uint16_t*   nb_of_uplinks_before_reset
                                     );
Brief

Get the current status of the connection timeouts.

Parameters

[in]

stack_id

Stack identifier

[out]

nb_of_uplinks_before_network_controlled

Number of remaining uplinks without downlink before ADR profile switches to network-controlled

[out]

nb_of_uplinks_before_reset

Number of remaining uplinks without downlink before reset

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

Parameters nb_of_uplinks_before_network_controlled and/or nb_of_uplinks_before_reset are NULL

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

SMTC_MODEM_RC_INVALID_STACK_ID

Invalid stack_id

smtc_modem_connection_timeout_get_thresholds()

smtc_modem_return_code_t smtc_modem_connection_timeout_get_thresholds  (
                                    uint8_t stack_id,
                                    uint16_t*   nb_of_uplinks_before_network_controlled,
                                    uint16_t*   nb_of_uplinks_before_reset
                                     );
Brief

Get the configured connection timeout thresholds.

Parameters

[in]

stack_id

Stack identifier

[out]

nb_of_uplinks_before_network_controlled

Nnumber of uplinks without downlinks before ADR profile switches to network-controlled

[out]

nb_of_uplinks_before_reset

Number of uplinks without downlinks before reset

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

Parameters nb_of_uplinks_before_network _controlled and/or nb_of_uplinks_before_reset are NULL

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

SMTC_MODEM_RC_INVALID_STACK_ID

Invalid stack_id

smtc_modem_connection_timeout_set_thresholds()

smtc_modem_return_code_t smtc_modem_connection_timeout_set_thresholds  (
                                    uint8_t stack_id,
                                    uint16_t  nb_of_uplinks_before_network_controlled,
                                    uint16_t  nb_of_uplinks_before_reset
                                     );
Brief

Set the connection timeout thresholds.

Remarks

The value 0 deactivates the command. It is recommended to have nb_of_uplinks_before_network_controlled smaller than nb_of_uplink_before_reset.

Parameters

[in]

stack_id

Stack identifier

[out]

nb_of_uplinks_before_network_controlled

The number of uplinks without downlinks before the ADR profile switches to network-controlled

[out]

nb_of_uplinks_before_reset

The number of uplinks without downlinks before reset

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

SMTC_MODEM_RC_INVALID_STACK_ID

Invalid stack_id

smtc_modem_dm_get_fport()

smtc_modem_return_code_t smtc_modem_dm_get_fport  (
                                    uint8_t*  dm_fport
                                    );
Brief

Get the Device Management LoRaWAN FPort

Parameters

[out]

dm_fport

The FPort on which the DM info is sent

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

Parameter dm_fport is NULL

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

smtc_modem_dm_get_info_fields()

smtc_modem_return_code_t smtc_modem_dm_get_info_fields  (
                                    uint8_t*  dm_fields_payload,
                                    uint8_t*   dm_field_length
                                    );
Brief

Get device management (DM) info fields.

Parameters

[in]

dm_fields_payload

The DM fields (defined in LoRa Basics™ Modem Device Management Field Codes)

[in]

dm_field_length

The DM field length

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

Parameters dm_fields_payload and/or dm_field_length are NULL

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

smtc_modem_dm_get_info_interval()

smtc_modem_return_code_t smtc_modem_dm_get_info_interval (
                                    smtc_modem_dm_info_interval_format_t*  format,
                                    uint8_t*    interval
                                     );
Brief

Get the interval between two DM info field messages.

Parameters

[out]

format

Reporting interval format

[out]

interval

Interval in unit defined in format

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

Parameters format and/or interval are NULL

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

smtc_modem_dm_get_user_data()

smtc_modem_return_code_t smtc_modem_dm_get_user_data  (
                                    uint8_t user_data[SMTC_MODEM_DM_USER_DATA_LENGTH]
                                     );
Brief

Get user-specific data to be reported by Device Management frames.

Parameters

[out]

user_data

User-specific data

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

Parameter user_data is NULL

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

smtc_modem_dm_set_fport()

smtc_modem_return_code_t smtc_modem_dm_set_fport  (
                                    uint8_t dm_fport
                                    );
Brief

Set the Device Management FPort of the LoRaWAN network.

Parameters

[in]

dm_fport

The FPort on which the DM info is sent. This value must be in the range [1:223]

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

Parameter dm_fport is out of the [1:223] range

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

smtc_modem_dm_set_info_fields()

smtc_modem_return_code_t smtc_modem_dm_set_info_fields (
                                    const uint8_t*  dm_fields_payload,
                                    uint8_t dm_field_length
                                     );
Brief

Set the DM info fields to be sent on a regular basis.

Remarks

The interval between two DM info field messages is defined with smtc_modem_dm_set_info_interval().

Parameters

[in]

dm_fields_payload

DM fields (defined in LoRa Basics™ Modem Device Management Field Codes)

[in]

dm_field_length

DM field length

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

Invalid or duplicated dm field code

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

smtc_modem_dm_set_info_interval()

smtc_modem_return_code_t smtc_modem_dm_set_info_interval (
                                    smtc_modem_dm_info_interval_format_t format,
                                    uint8_t  interval
                                     );
Brief

Set the interval between two DM info field messages.

Remarks

A value set to 0 disables the feature - no matter the format.

Parameters

[in]

format

The reporting interval format

[in]

interval

The interval in unit defined in format, from 0 to 63

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

Interval is not in the [0:63] range

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

smtc_modem_dm_set_user_data()

smtc_modem_return_code_t smtc_modem_dm_set_user_data (
                                    const uint8_t user_data[SMTC_MODEM_DM_USER_DATA_LENGTH]
                                     );
Brief

Set user-specific data to be reported by Device Management frames.

Remarks

This field will be sent only if it is selected in smtc_modem_dm_set_info_fields() or smtc_modem_dm_request_single_uplink().

Parameters

[in]

user_data

User-specific data

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

smtc_modem_factory_reset()

smtc_modem_return_code_t smtc_modem_factory_reset (void);
Brief

Reset the modem to its original state.

Remarks

Resets all modem-related non-volatile settings to their default values, then resets the MCU. Only LoRaWAN DevNonce is kept.

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

smtc_modem_file_upload_init()

smtc_modem_return_code_t smtc_modem_file_upload_init  (
                                    uint8_t stack_id,
                                    uint8_t  index,
                                    smtc_modem_file_upload_cipher_mode_t  cipher_mode,
                                    const uint8_t*   file,
                                    uint16_t  file_length,
                                    uint32_t  average_delay_s
                                     );
Brief

Create and initialize a file upload session.

Parameters

[in]

stack_id

The stack identifier

[in]

index

The index on which the upload is done

[in]

cipher_mode

The cipher mode

[in]

file

The file buffer

[in]

file_length

The file size

[in]

average_delay_s

The minimal delay between two file upload fragments, in seconds (from the end of an uplink to the start of the next one)

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

file_length is equal to 0 or greater than 2048 bytes, or “file” pointer is NULL

SMTC_MODEM_RC_BUSY

Modem is currently in test mode, or a file upload is already ongoing

SMTC_MODEM_RC_INVALID_STACK_ID

Invalid stack_id

smtc_modem_file_upload_reset()

smtc_modem_return_code_t smtc_modem_file_upload_reset  (
                                    uint8_t stack_id
                                    );
Brief

Reset the file upload session.

Remarks

This function will stop any ongoing file upload session.

Parameters

[in]

stack_id

The stack identifier

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_NOT_INIT

No file upload session currently running

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

SMTC_MODEM_RC_FAIL

Modem is not available (suspended, muted or not joined)

SMTC_MODEM_RC_INVALID_STACK_ID

Invalid stack_id

smtc_modem_file_upload_start()

smtc_modem_return_code_t smtc_modem_file_upload_start  (
                                    uint8_t stack_id
                                    );
Brief

Start the file upload to the LoRa Cloud™ Modem & Geolocation Services.

Parameters

[in]

stack_id

The stack identifier

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_BUSY

Modem is currently in test mode, or a file upload is already ongoing

SMTC_MODEM_RC_FAIL

Modem is not available (suspended, muted or not joined)

SMTC_MODEM_RC_BAD_SIZE

Total data sent does not match the declared Size value in smtc_modem_file_upload_init()

SMTC_MODEM_RC_INVALID_STACK_ID

Invalid stack_id

smtc_modem_get_available_datarates()

smtc_modem_return_code_t smtc_modem_get_available_datarates  (
                                    uint8_t stack_id,
                                    uint16_t*   available_datarates_mask
                                     );
Brief

Get the current available data rate with regards to Uplink ChMash and DwellTime.

Parameters

[in]

stack_id

The stack identifier

[out]

available_datarates_mask

The available data rates, described in a bit field

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

Parameter available_datarates_mask is NULL

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

SMTC_MODEM_RC_INVALID_STACK_ID

Invalid stack_id

smtc_modem_get_certification_mode()

smtc_modem_return_code_t smtc_modem_get_certification_mode  (
                                    uint8_t stack_id,
                                    bool*  enable
                                     );
Brief

Get the current state of the certification mode.

Parameters

[in]

stack_id

The stack identifier

[out]

enable

The certification mode state

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

Parameter enable is NULL

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

SMTC_MODEM_RC_INVALID_STACK_ID

Invalid stack_id

smtc_modem_get_charge()

smtc_modem_return_code_t smtc_modem_get_charge  (
                                    uint32_t*  charge_mah
                                    );
Brief

Get the total charge counter of the modem in mAh.

Parameters

[out]

charge_mah

The accumulated charge in mAh

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

Parameter charge_mah is NULL

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

smtc_modem_get_class()

smtc_modem_return_code_t smtc_modem_get_class  (
                                    uint8_t stack_id,
                                    smtc_modem_class_t*  lorawan_class
                                     );
Brief

Get the current class used by the LoRaWAN network.

Parameters

[in]

stack_id

The stack identifier

[out]

lorawan_class

The current LoRaWAN class

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

SMTC_MODEM_RC_INVALID_STACK_ID

Invalid stack_id

smtc_modem_get_crystal_error()

smtc_modem_return_code_t smtc_modem_get_crystal_error (
                                    uint32_t*  crystal_error_per_thousand
                                    );
Brief

Get the modem crystal error.

Parameters

[out]

crystal_error_per_thousand

The crystal error in “per thousand”

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

Parameter crystal_error_per_thousand is NULL

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

smtc_modem_get_deveui()

smtc_modem_return_code_t smtc_modem_get_deveui (
                                    uint8_t stack_id,
                                    uint8_t  deveui[SMTC_MODEM_EUI_LENGTH]
                                     );
Brief

Get the DevEUI.

Parameters

[in]

stack_id

The stack identifier

[out]

deveui

The current DevEUI

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

SMTC_MODEM_RC_INVALID_STACK_ID

Invalid stack_id

smtc_modem_get_duty_cycle_status()

smtc_modem_return_code_t smtc_modem_get_duty_cycle_status (
                                    int32_t*   duty_cycle_status_ms
                                     );
Brief

Get the current status of the duty cycle.

Remarks

If the returned value is positive, it is the time still available. A negative value indicates the time to wait until band availability.

Parameters

[out]

duty_cycle_status_ms

The status of the duty cycle in milliseconds

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

Parameter duty_cycle_status_ms is NULL

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

smtc_modem_get_event()

smtc_modem_return_code_t smtc_modem_get_event (
                                    smtc_modem_event_t*  event,
                                    uint8_t*   event_pending_count
                                     );
Brief

Get the modem event.

Remarks

This command can be used to retrieve pending events from the modem.

Parameters

[out]

event

Structure holding event-related information

[out]

event_pending_count

Number of pending event(s)

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

At least one of the following parameters is NULL: event or event_pending_count

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

smtc_modem_get_joineui()

smtc_modem_return_code_t smtc_modem_get_joineui  (
                                    uint8_t  stack_id,
                                    uint8_t  joineui[SMTC_MODEM_EUI_LENGTH]
                                     );
Brief

Get the JoinEUI.

Parameters

[in]

stack_id

The stack identifier

[out]

joineui

The current JoinEUI

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

SMTC_MODEM_RC_INVALID_STACK_ID

Invalid stack_id

smtc_modem_get_lorawan_version()

smtc_modem_return_code_t smtc_modem_get_lorawan_version (
                                    smtc_modem_lorawan_version_t*  lorawan_version
                                    );
Brief

Get the stack version used by the LoRaWAN network.

Parameters

[out]

lorawan_version

The LoRaWAN version

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

Parameter lorawan_version is NULL

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

smtc_modem_get_modem_version()

smtc_modem_return_code_t smtc_modem_get_modem_version (
                                    smtc_modem_version_t*  firmware_version
                                    );
Brief

Get the modem firmware version.

Parameters

[out]

firmware_version

The firmware version

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

Parameter firmware_version is NULL

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

smtc_modem_get_nb_trans()

smtc_modem_return_code_t smtc_modem_get_nb_trans  (
                                    uint8_t stack_id,
                                    uint8_t*   nb_trans
                                     );
Brief

Get the configured number of transmissions (nb_trans) in case of unconfirmed uplink.

Parameters

[in]

stack_id

The stack identifier

[out]

nb_trans

The number of transmissions

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

Parameter nb_trans is NULL

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

SMTC_MODEM_RC_INVALID_STACK_ID

Invalid stack_id

smtc_modem_get_network_frame_pending_status()

smtc_modem_return_code_t smtc_modem_get_network_frame_pending_status  (
                                    uint8_t stack_id,
                                    smtc_modem_frame_pending_bit_status_t* frame_pending_bit_status
                                     );
Brief

Get network frame pending status.

Remarks

This bit is set by the network when data are available and a downlink opportunity is required.

Parameters

[in]

stack_id

The stack identifier

[in]

frame_pending_bit_status

The frame pending bit status

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

Parameter frame_pending_bit_status is NULL

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

SMTC_MODEM_RC_INVALID_STACK_ID

Invalid stack_id

smtc_modem_get_network_type()

smtc_modem_return_code_t smtc_modem_get_network_type  (
                                    uint8_t stack_id,
                                    bool*   network_type
                                     );
Brief

Get the configured network type.

Parameters

[in]

stack_id

The stack identifier

[in]

network_type

The configuration to be applied (true: public network / false: private network)

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

Parameter network_type is NULL

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

SMTC_MODEM_RC_INVALID_STACK_ID

Invalid stack_id

smtc_modem_get_next_tx_max_payload()

smtc_modem_return_code_t smtc_modem_get_next_tx_max_payload  (
                                    uint8_t stack_id,
                                    uint8_t*   tx_max_payload_size
                                     );
Brief

Get the maximum payload size that can be used for the next uplink.

Remarks

This value depends on the regional parameters used by the LoRaWAN network for the next transmission using the current data rate.

Parameters

[in]

stack_id

The stack identifier

[out]

tx_max_payload_size

The maximum payload size in byte

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

Parameter tx_max_payload_size is NULL

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

SMTC_MODEM_RC_FAIL

Modem has not joined a network

SMTC_MODEM_RC_INVALID_STACK_ID

Invalid stack_id

smtc_modem_get_region()

smtc_modem_return_code_t smtc_modem_get_region  (
                                    uint8_t stack_id,
                                    smtc_modem_region_t*   region
                                     );
Brief

Get the current region of the LoRaWAN network.

Parameters

[in]

stack_id

The stack identifier

[out]

region

The current LoRaWAN region

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

Parameter region is NULL

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

SMTC_MODEM_RC_INVALID_STACK_ID

Invalid stack_id

smtc_modem_get_regional_params_version()

smtc_modem_return_code_t smtc_modem_get_regional_params_version (
                                    smtc_modem_lorawan_version_t*  regional_params_version
                                    );
Brief

Get the stack Regional Parameters version.

Parameters

[out]

regional_params_version

The stack regional parameters version

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

Parameter regional_params_version is NULL

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

smtc_modem_get_stack_state()

smtc_modem_return_code_t smtc_modem_get_stack_state  (
                                    uint8_t stack_id,
                                    smtc_modem_stack_state_t*   stack_state
                                     );
Brief

Get the current state of the stack.

Parameters

[in]

stack_id

The stack identifier

[out]

stack_state

The stack current state

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

Parameter stack_state is NULL

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

SMTC_MODEM_RC_INVALID_STACK_ID

Invalid stack_id

smtc_modem_get_status()

smtc_modem_return_code_t smtc_modem_get_status  (
                                    uint8_t stack_id,
                                    smtc_modem_status_mask_t*   status_mask
                                     );
Brief

Get the modem status.

Parameters

[in]

stack_id

The stack identifier

[out]

status_mask

The modem status defined in smtc_modem_status_mask_e

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

Parameter status_mask is NULL

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

SMTC_MODEM_RC_INVALID_STACK_ID

Invalid stack_id

smtc_modem_get_time()

smtc_modem_return_code_t smtc_modem_get_time  (
                                    uint32_t*   gps_time_s,
                                    uint32_t*   gps_fractional_s
                                     );
Brief

Get GPS epoch time.

Remarks

The returned time specifies the number of seconds elapsed since GPS epoch (00:00:00, Sunday 6th of January 1980).

Parameters

[out]

gps_time_s

The GPS time in seconds

[out]

gps_fractional_s

The GPS fractional second

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

Parameter gps_time_s or gps_fractional_s is NULL

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

SMTC_MODEM_RC_NO_TIME

No time available

smtc_modem_get_tx_power_offset_db()

smtc_modem_return_code_t smtc_modem_get_tx_power_offset_db  (
                                    uint8_t stack_id,
                                    int8_t*   tx_pwr_offset_db
                                     );
Brief

Get the Tx power offset in dB.

Parameters

[in]

stack_id

The stack identifier

[out]

tx_pwr_offset_db

The Tx power offset in dB

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

Parameter tx_pwr_offset_db is NULL

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

SMTC_MODEM_RC_INVALID_STACK_ID

Invalid stack_id

smtc_modem_init()

void smtc_modem_init (
                                  const ralk_t* radio,
                                  void(*)(void) callback
                                  );

Brief Initialize the soft modem and set the modem event chosen callback.

Remarks The callback is called each time a modem event is raised internally.

Parameters

[in]

callback

User event callback prototype

smtc_modem_join_network()

smtc_modem_return_code_t smtc_modem_join_network  (
                                    uint8_t stack_id
                                    );
Brief

Join the network.

Parameters

[in]

stack_id

The stack identifier

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors or modem has already joined the network

SMTC_MODEM_RC_BUSY

Modem is currently in test mode or in joining/joined state

SMTC_MODEM_RC_FAIL

Modem is not available (suspended or muted)

SMTC_MODEM_RC_INVALID_STACK_ID

Invalid stack_id

smtc_modem_lbt_get_parameters()

smtc_modem_return_code_t smtc_modem_lbt_get_parameters  (
                                    uint8_t     stack_id,
                                    uint32_t*   listening_duration_ms,
                                    int16_t*    threshold_dbm,
                                    uint32_t*   bw_hz
                                     );
Brief

Get the parameters of the Listen Before Talk feature.

Parameters

[in]

stack_id

The stack identifier

[out]

listening_duration_ms

The current listening duration in ms

[out]

threshold_dbm

The current Listen Before Talk threshold in dbm

[out]

bw_hz

The current Listen Before Talk bandwidth in Hertz

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

At least one pointer is NULL

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

SMTC_MODEM_RC_INVALID_STACK_ID

Invalid stack_id

smtc_modem_lbt_get_state()

smtc_modem_return_code_t smtc_modem_lbt_get_state  (
                                    uint8_t  stack_id,
                                    bool*   enabled
                                     );
Brief

Get the state of the Listen Before Talk feature.

Parameters

[in]

stack_id

The stack identifier

[out]

enabled

The current status of the Listen Before Talk feature (true: enabled, false: disabled)

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

Parameter enabled is NULL

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

SMTC_MODEM_RC_INVALID_STACK_ID

Invalid stack_id

smtc_modem_lbt_set_parameters()

smtc_modem_return_code_t smtc_modem_lbt_set_parameters  (
                                    uint8_t stack_id,
                                    uint32_t  listening_duration_ms,
                                    int16_t  threshold_dbm,
                                    uint32_t  bw_hz
                                     );
Brief

Set the parameters of the Listen Before Talk feature.

Parameters

[in]

stack_id

The stack identifier

[in]

listening_duration_ms

The listening duration in ms to be configured

[in]

threshold_dbm

The Listen Before Talk threshold in dbm to be configured

[in]

bw_hz

The Listen Before Talk bandwidth in Hertz to be configured

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

SMTC_MODEM_RC_INVALID_STACK_ID

Invalid stack_id

smtc_modem_lbt_set_state()

smtc_modem_return_code_t smtc_modem_lbt_set_state  (
                                    uint8_t  stack_id,
                                    bool  enable
                                     );
Brief

Enable or disable the Listen Before Talk feature.

Remarks

The configuration function smtc_modem_lbt_set_parameters() must be called before enabling the Listen Before Talk feature. Listen Before Talk is silently enabled if the feature is mandatory in a region selected with smtc_modem_set_region().

Parameters

[in]

stack_id

The stack identifier

[in]

enable

The status of the Listen Before Talk feature to set (true: enable, false: disable)

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

SMTC_MODEM_RC_INVALID_STACK_ID

Invalid stack_id

smtc_modem_leave_network()

smtc_modem_return_code_t smtc_modem_leave_network  (
                                    uint8_t stack_id
                                    );
Brief

Leave an already joined network or cancels on ongoing join process.

Parameters

[in]

stack_id

The stack identifier

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

SMTC_MODEM_RC_INVALID_STACK_ID

Invalid stack_id

smtc_modem_multicast_get_grp_config()

smtc_modem_return_code_t smtc_modem_multicast_get_grp_config  (
                                    uint8_t stack_id,
                                    smtc_modem_mc_grp_id_t  mc_grp_id,
                                    uint32_t*   mc_grp_addr
                                     );
Brief

Get the configuration of the chosen multicast group.

Parameters

[in]

stack_id

Stack identifier

[in]

mc_grp_id

Multicast group identifier

[out]

mc_grp_addr

Multicast group address

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

Group ID is not in acceptable range [0:3] or parameter mc_grp_addr is NULL

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

smtc_modem_multicast_get_session_status()

smtc_modem_return_code_t smtc_modem_multicast_get_session_status  (
                                    uint8_t    stack_id,
                                    smtc_modem_mc_grp_id_t  mc_grp_id,
                                    bool*   is_session_started,
                                    uint32_t*   freq,
                                    uint8_t*   dr
                                     );
Brief

Get a multicast session status for a chosen group.

Parameters

[in]

stack_id

Stack identifier

[in]

mc_grp_id

Multicast group identifier

[out]

is_session_started

Session status

[out]

freq

Session downlink frequency

[out]

dr

Session downlink data rate

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

Group ID is not in acceptable range [0:3] or a parameter is NULL

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

smtc_modem_multicast_set_grp_config()

smtc_modem_return_code_t smtc_modem_multicast_set_grp_config  (
                                    uint8_t  stack_id,
                                    smtc_modem_mc_grp_id_t  mc_grp_id,
                                    uint32_t  mc_grp_addr,
                                    const uint8_t  mc_nwk_skey[SMTC_MODEM_KEY_LENGTH],
                                    const uint8_t  mc_app_skey[SMTC_MODEM_KEY_LENGTH]
                                     );
Brief

Configure a multicast group.

Parameters

[in]

stack_id

Stack identifier

[in]

mc_grp_id

Mlticast group identifier

[in]

mc_grp_addr

Multicast group address

[in]

mc_nwk_skey

Multicast network session key for the group

[in]

mc_app_skey

Multicast application session key for the group

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

Group ID is not in acceptable range [0:3]

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

SMTC_MODEM_RC_FAIL

Error during cryptographic process; a running session already exists on this ID

smtc_modem_multicast_start_session()

smtc_modem_return_code_t smtc_modem_multicast_start_session  (
                                    uint8_t stack_id,
                                    mtc_modem_mc_grp_id_t  mc_grp_id,
                                    uint32_t  freq,
                                    uint8_t  dr
                                     );
Brief

Start a multicast session for a specific group.

Parameters

[in]

stack_id

Stack identifier

[in]

mc_grp_id

Multicast group identifier

[in]

freq

Downlink frequency for this session

[in]

dr

Downlink data rate for this session

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

Group ID is not in acceptable range [0:3]. Frequency or Data rate are not in acceptable range (according to current regional params). Frequency or Data rate are not compatible with an already running multicast session

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

SMTC_MODEM_RC_FAIL

This session is already started

smtc_modem_multicast_stop_all_sessions()

smtc_modem_return_code_t smtc_modem_multicast_stop_all_sessions  (
                                    uint8_t  stack_id
                                    );
Brief

Stop all started multicast sessions.

Parameters

[in]

stack_id

Stack identifier

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

smtc_modem_multicast_stop_session()

smtc_modem_return_code_t smtc_modem_multicast_stop_session  (
                                    uint8_t stack_id,
                                    smtc_modem_mc_grp_id_t  mc_grp_id
                                     );
Brief

Stop a multicast session for a chosen group.

Parameters

[in]

stack_id

Stack identifier

[in]

mc_grp_id

Multicast group identifier

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

Group ID is not in acceptable range [0:3]

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

smtc_modem_reset()

smtc_modem_return_code_t smtc_modem_reset (void)
Brief

Reset the modem.

Remarks

Resets modem transient state (including session information) by resetting the MCU. Device Management Port, Modem Region, and LoRaWAN DevNonce are kept.

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

smtc_modem_reset_charge()

smtc_modem_return_code_t smtc_modem_reset_charge (void)
Brief

Reset the total charge counter of the modem.

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

smtc_modem_resume_after_user_radio_access()

smtc_modem_return_code_t smtc_modem_resume_after_user_radio_access (void)
Brief

Allow the modem to get access to the radio.

Remarks

The user must call this function after performing operations requiring direct access to the radio (e.g. test modes). Otherwise, all modem-related tasks remain pending.

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

smtc_modem_run_engine()

uint32_t smtc_modem_run_engine (void)

Brief Run the modem engine.

Remarks This command must be called in the main loop. It returns an amount of ms after which the command must at least be called again.

Returns The time in ms after which the command must at least be called again.

smtc_modem_set_certification_mode()

smtc_modem_return_code_t smtc_modem_set_certification_mode  (
                                    uint8_t  stack_id,
                                    bool  enable
                                     );
Brief

Enable / disable the certification mode.

Parameters

[in]

stack_id

Stack identifier

[in]

enable

Certification mode state (default: disabled)

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

SMTC_MODEM_RC_INVALID_STACK_ID

Invalid stack_id

smtc_modem_set_class()

smtc_modem_return_code_t smtc_modem_set_class  (
                                    uint8_t  stack_id,
                                    smtc_modem_class_t  lorawan_class
                                     );
Brief

Set the class used by the LoRaWAN network.

Parameters

[in]

stack_id

Stack identifier

[in]

lorawan_class

LoRaWAN class to be configured

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

SMTC_MODEM_RC_INVALID_STACK_ID

Invalid stack_id

smtc_modem_set_crystal_error()

smtc_modem_return_code_t smtc_modem_set_crystal_error  (
                                    uint32_t  crystal_error_per_thousand
                                    );
Brief

Set modem crystal error.

Parameters

[in]

crystal_error_per_thousand

The crystal error in “per thousand”

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

Parameter crystal_error_per_thousand is not in [0:10] range

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

smtc_modem_set_deveui()

smtc_modem_return_code_t smtc_modem_set_deveui  (
                                    uint8_t  stack_id,
                                    const uint8_t  deveui[SMTC_MODEM_EUI_LENGTH]
                                     );
Brief

Set the DevEUI.

Parameters

[in]

stack_id

Stack identifier

[in]

deveui

DevEUI to be configured

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_BUSY

Modem is currently in test mode or in joining/joined state

SMTC_MODEM_RC_INVALID_STACK_ID

Invalid stack_id

smtc_modem_set_joineui()

smtc_modem_return_code_t smtc_modem_set_joineui  (
                                    uint8_t  stack_id,
                                    const uint8_t  joineui[SMTC_MODEM_EUI_LENGTH]
                                     );
Brief

Set the JoinEUI.

Parameters

[in]

stack_id

Stack identifier

[in]

joineui

JoinEUI to be configured

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_BUSY

Modem is currently in test mode or in joining/joined state

SMTC_MODEM_RC_INVALID_STACK_ID

Invalid stack_id

smtc_modem_set_nb_trans()

smtc_modem_return_code_t smtc_modem_set_nb_trans  (
                                    uint8_t  stack_id,
                                    uint8_t  nb_trans
                                     );
Brief

Set the number of transmissions (nb_trans) in case of unconfirmed uplink.

Parameters

[in]

stack_id

Stack identifier

[in]

nb_trans

Number of transmissions ( 0 < value < 16 )

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

Parameter nb_trans is not in [1:15] range, or current ADR profile is “Network controlled”

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

SMTC_MODEM_RC_INVALID_STACK_ID

Invalid stack_id

smtc_modem_set_network_type()

smtc_modem_return_code_t smtc_modem_set_network_type  (
                                    uint8_t  stack_id,
                                    bool  network_type
                                     );
Brief

Configure network type to private or public.

Parameters

[in]

stack_id

Stack identifier

[in]

network_type

Configuration to be applied (true: public network / false: private network)

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

Parameter network_type is NULL

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

SMTC_MODEM_RC_INVALID_STACK_ID

Invalid stack_id

smtc_modem_set_nwkkey()

smtc_modem_return_code_t smtc_modem_set_nwkkey  (
                                    uint8_t  stack_id,
                                    const uint8_t  nwkkey[SMTC_MODEM_KEY_LENGTH]
                                     );
Brief

Set the LoRaWAN v1.1.x Network Key (a.k.a. Application Key in LoRaWAN v1.0.x)

Parameters

[in]

stack_id

Stack identifier

[in]

nwkkey

Key to be configured

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_BUSY

Modem is currently in test mode or in joining/joined state

SMTC_MODEM_RC_INVALID_STACK_ID

Invalid stack_id

smtc_modem_set_region()

smtc_modem_return_code_t smtc_modem_set_region  (
                                    uint8_t  stack_id,
                                    smtc_modem_region_t  region
                                     );
Brief

Set the region used by the LoRaWAN network.

Parameters

[in]

stack_id

Stack identifier

[in]

region

LoRaWAN region to be configured

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

Chosen region is not supported

SMTC_MODEM_RC_BUSY

Modem is currently in test mode or in joining/joined state

SMTC_MODEM_RC_INVALID_STACK_ID

Invalid stack_id

smtc_modem_set_tx_power_offset_db()

smtc_modem_return_code_t smtc_modem_set_tx_power_offset_db  (
                                    uint8_t  stack_id,
                                    int8_t  tx_pwr_offset_db
                                     );
Brief

Set the Tx power offset in dB.

Parameters

[in]

stack_id

Stack identifier

[in]

tx_pwr_offset_db

Tx power offset in dB

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

Parameter tx_pwr_offset_db is out of range

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

SMTC_MODEM_RC_INVALID_STACK_ID

Invalid stack_id

smtc_modem_stream_add_data()

smtc_modem_return_code_t smtc_modem_stream_add_data  (
                                    uint8_t  stack_id,
                                    const uint8_t*   data,
                                    uint8_t  len
                                     );
Brief

Add data to the stream.

Remarks

If no stream has been initialized, open a new un-encrypted stream on the DM FPort with a redundancy ratio set to 110%.

Parameters

[in]

stack_id

Stack identifier

[in]

data

Data to be added to the stream

[in]

len

Number of bytes from data to be added to the stream

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

Data length is not in range [1-254] or parameter data is NULL

SMTC_MODEM_RC_BUSY

Modem is currently in test mode or the streaming buffer is full

SMTC_MODEM_RC_FAIL

Modem is not available (suspended, muted or not joined)

SMTC_MODEM_RC_INVALID_STACK_ID

Invalid stack_id

smtc_modem_stream_init()

smtc_modem_return_code_t smtc_modem_stream_init  (
                                    uint8_t  stack_id,
                                    uint8_t  fport,
                                    smtc_modem_stream_cipher_mode_t  cipher_mode,
                                     );
Brief

Create and initialize a data stream.

Parameters

[in]

stack_id

Stack identifier

[in]

fport

FPort on which the stream is sent. A value of 0 uses configured DM port

[in]

redundancy_ratio_percent

Stream redundancy ratio.

[in]

cipher_mode

Cipher mode

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

FPort is out of the [0:223] range

SMTC_MODEM_RC_BUSY

Modem is currently in test mode or the streaming buffer is not empty

SMTC_MODEM_RC_INVALID_STACK_ID

Invalid stack_id

smtc_modem_stream_status()

smtc_modem_return_code_t smtc_modem_stream_status  (
                                    uint8_t  stack_id,
                                    uint16_t*   pending,
                                    uint16_t*   free
                                     );
Brief

Return the current stream status.

Parameters

[in]

stack_id

Stack identifier

[out]

pending

Length of pending data for transmission

[out]

free

Length of free space in the buffer

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_NOT_INIT

No stream session is running

SMTC_MODEM_RC_INVALID

Parameters pending and/or free are NULL

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

SMTC_MODEM_RC_INVALID_STACK_ID

Invalid stack_id

smtc_modem_suspend_before_user_radio_access()

smtc_modem_return_code_t smtc_modem_suspend_before_user_radio_access (void)
Brief

Grant user radio access by suspending the modem and kill all current modem radio tasks.

Remarks

The user must call this command before performing operations requiring direct access to the radio (e.g. test modes). Otherwise, undefined behavior may occur.

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

smtc_modem_suspend_radio_communications()

smtc_modem_return_code_t smtc_modem_suspend_radio_communications (bool  suspend);
Brief

Suspend the radio communications initiated by the modem.

Parameters

[in]

suspend

Configuration to be applied (true: suspend communications / false: resume communications)

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

smtc_modem_time_get_alcsync_fport()

smtc_modem_return_code_t smtc_modem_time_get_alcsync_fport  (
                                    uint8_t*   alcsync_fport
                                    );
Brief

Get ALCSync service FPort.

Parameters

[out]

alcsync_fport

Clock Sync FPort

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

Parameter alcsync_fport is NULL

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

smtc_modem_time_get_sync_interval_s()

smtc_modem_return_code_t smtc_modem_time_get_sync_interval_s  (
                                    uint32_t*   sync_interval_s
                                    );
Brief

Get the interval between time synchronizations.

Parameters

[out]

sync_interval_s

The interval in seconds

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

Parameter sync_interval_s is NULL

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

smtc_modem_time_get_sync_invalid_delay_s()

smtc_modem_return_code_t smtc_modem_time_get_sync_invalid_delay_s  (
                                    uint32_t*   sync_invalid_delay_s
                                     );
Brief

Get the configured delay beyond which the time synchronization is no longer valid.

Parameters

[out]

sync_invalid_delay_s

Invalid delay, in seconds

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

Parameter sync_invalid_delay_s is NULL

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

smtc_modem_time_set_alcsync_fport()

smtc_modem_return_code_t smtc_modem_time_set_alcsync_fport  (
                                    uint8_t  alcsync_fport
                                    );
Brief

Set ALCSync service port.

Remarks

When using DM port as alcsync_fport, the ALCsync messages will be encapsulated into DM frames.

Parameters

[in]

alcsync_fport

The FPort for ALCSync messages. A value of 0, or a currently configured DM port, encapsulates it into DM messages

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

Parameter alcsync_fport is invalid: out of [0:223] range

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

smtc_modem_time_set_sync_interval_s()

smtc_modem_return_code_t smtc_modem_time_set_sync_interval_s (
                                    uint32_t  sync_interval_s
                                    );
Brief

Set the interval between time synchronizations.

Parameters

[in]

sync_interval_s

The interval, in seconds

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

Parameter sync_interval_s is invalid if it exceeds the delay beyond which the time synchronization is no longer considered valid by the modem. See smtc_modem_time_set_sync_invalid_delay_s() for further details.

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

smtc_modem_time_set_sync_invalid_delay_s()

smtc_modem_return_code_t smtc_modem_time_set_sync_invalid_delay_s  (
                                    uint32_t  sync_invalid_delay_s
                                    );
Brief

Set the delay beyond which the time synchronization is no longer considered valid by the modem.

Remarks

Modem will generate an SMTC_MODEM_EVENT_TIME event if no time synchronizations downlinks are received for a time period longer than sync_invalid_delay_s.

Parameters

[in]

sync_invalid_delay_s

The invalid delay, in seconds

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_INVALID

Parameter sync_invalid_delay_s is > 49 days

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

smtc_modem_time_start_sync_service()

smtc_modem_return_code_t smtc_modem_time_start_sync_service  (
                                    uint8_t stack_id,
                                    smtc_modem_time_sync_service_t sync_service
                                     );
Brief

Start a chosen time synchronization service.

Parameters

[in]

stack_id

Stack identifier

[in]

sync_service

Time synchronization service to use

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

SMTC_MODEM_RC_FAIL

A time synchronization service is already running

SMTC_MODEM_RC_INVALID_STACK_ID

Invalid stack_id

smtc_modem_time_stop_sync_service()

smtc_modem_return_code_t smtc_modem_time_stop_sync_service  (
                                    uint8_t stack_id
                                    );
Brief

Stop current time synchronization service.

Parameters

[in]

stack_id

Stack identifier

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

SMTC_MODEM_RC_FAIL

No time synchronization service is running

SMTC_MODEM_RC_INVALID_STACK_ID

Invalid stack_id

smtc_modem_time_trigger_sync_request()

smtc_modem_return_code_t smtc_modem_time_trigger_sync_request  (
                                    uint8_t  stack_id,
                                    smtc_modem_time_sync_service_t  sync_service
                                     );
Brief

Trigger an uplink requesting time, using the currently-activated service with smtc_modem_time_start_sync_service().

Parameters

[in]

stack_id

Stack identifier

[in]

sync_service

Time synchronization service to use

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

SMTC_MODEM_RC_FAIL

Modem is not available (suspended, muted, or not joined)

SMTC_MODEM_RC_INVALID_STACK_ID

Invalid stack_id

LoRa Basics™ Modem API LR1110 Extension

The following functions constitute the LoRa Basics™ Modem API LR1110 Extension.

smtc_modem_derive_keys()

smtc_modem_return_code_t smtc_modem_derive_keys()  (
                                    uint8_t  stack_id
                                     );
Brief

Derive keys if applicable.

Remarks

This command can only be used on a LoRa Basics Modem with an LR1110 radio.

Parameters

[in]

stack_id

Stack identifier

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_FAIL

Error deriving key

smtc_modem_get_chip_eui()

smtc_modem_return_code_t smtc_modem_get_chip_eui()  (
                                    uint8_t  stack_id,
                                    uint8_t  chip_eui[SMTC_MODEM_EUI_LENGTH]
                                     );
Brief

Get the modem Chip EUI if applicable.

Remarks

This command can only be used on a LoRa Basics Modem with an LR1110 radio. Derives application key from the saved dev_eui (default set to chip_eui) and saved join_eui.

Parameters

[in]

stack_id

Stack identifier

[out]

chip_eui*

8-byte Chip EUI number

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_BUSY

Modem is currently in test mode

smtc_modem_get_pin()

smtc_modem_return_code_t smtc_modem_get_pin()  (
                                    uint8_t  stack_id,
                                    uint8_t  chip_pin[SMTC_MODEM_PIN_LENGTH]
                                     );
Brief

Get the modem pin code, if applicable.

Remarks

This command can only be used on a LoRa Basics Modem with an LR1110 radio.

Parameters

[in]

stack_id

Stack identifier

[out]

chip_pin*

4-byte pin code

Returns

Modem return code as defined in smtc_modem_return_code_t.

Return values

SMTC_MODEM_RC_OK

Command executed without errors

SMTC_MODEM_RC_BUSY

Modem is currently in test mode