LoRa Basics™ Modem API Reference¶

smtc_modem_abort_extended_uplink()¶

smtc_modem_return_code_t smtc_modem_abort_extended_uplink (
                                     uint8_t stack_id,
                                     uint8_t extended_uplink_id
                                     )

Brief

This feature is introduced for future libraries and functions, it is NOT recommended for the user to call this function. This feature requires a special compilation option to be activated.

Parameters

[in]	stack_id	Stack identifier
[in]	extended_uplink_id	ID of the queue for extended uplink should be equal to 1 or 2

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	Extended_uplink_id not equal to 1 or 2
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_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 adaptative data rate (ADR) profile.

Remarks

Valid datarate profiles are listed in table 7.4.

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 adaptative data rate (ADR) profile.

Remarks

If SMTC_MODEM_ADR_PROFILE_CUSTOM is selected, custom data are taken into account. Valid datarate profiles are listed in table 7.4.

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 parameter
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 the 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

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.

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_class_b_get_ping_slot_periodicity()¶

smtc_modem_return_code_t smtc_modem_class_b_get_ping_slot_periodicity  (
                                    uint8_t stack_id,
                                    smtc_modem_class_b_ping_slot_periodicity_t* ping_slot_periodicity
                                    )

Brief

Get Class B Ping Slot Periodicity.

Parameters

[in]	stack_id	Stack identifier
[out]	ping_slot_periodicity	Ping slot periodicity

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	ping_slot_periodicity is NULL
SMTC_MODEM_RC_BUSY	Modem is currently in test mode
SMTC_MODEM_RC_INVALID_STACK_ID	Invalid stack_id

smtc_modem_class_b_set_ping_slot_periodicity()¶

smtc_modem_return_code_t smtc_modem_class_b_set_ping_slot_periodicity  (
                                    uint8_t stack_id,
                                    smtc_modem_class_b_ping_slot_periodicity_t ping_slot_periodicity
                                    )

Brief

Set Class B Ping Slot Periodicity.

Parameters

[in]	stack_id	Stack identifier
[in]	ping_slot_periodicity	Ping slot periodicity

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_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 the 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	Parameter nb_of_uplinks_before_network_controlled and/or nb_of_uplinks_before_reset is 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	Number of uplinks without downlinks before the 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	Parameter nb_of_uplinks_before_network_controlled and/or nb_of_uplinks_before_reset is 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	Number of uplinks without downlink before the ADR profile switches to network-controlled
[out]	nb_of_uplinks_before_reset	Number of 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_BUSY	Modem is currently in test mode
SMTC_MODEM_RC_INVALID_STACK_ID	Invalid stack_id

smtc_modem_d2d_class_b_get_tx_max_payload()¶

smtc_modem_return_code_t smtc_modem_d2d_class_b_get_tx_max_payload  (
                                     uint8_t stack_id,
                                     smtc_modem_mc_grp_id_t mc_grp_id,
                                     uint8_t* tx_max_payload_size
                                     )

Brief

Get the maximum payload size that can be used for a device to device uplink on chosen multicast group.

Parameters

[in]	stack_id	Stack identifier
[in]	mc_grp_id	The multicast group 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	tx_max_payload_size is NULL
SMTC_MODEM_RC_BUSY	Modem is currently in test mode
SMTC_MODEM_RC_FAIL	Modem is not available (suspended, muted or not joined) or no multicast session is running on this group id
SMTC_MODEM_RC_INVALID_STACK_ID	Invalid stack_id

smtc_modem_d2d_class_b_request_uplink()¶

smtc_modem_return_code_t smtc_modem_d2d_class_b_request_uplink  (
                                     uint8_t stack_id,
                                     smtc_modem_mc_grp_id_t mc_grp_id,
                                     smtc_modem_d2d_class_b_uplink_config_t * d2d_config,
                                     uint8_t fport,
                                     const uint8_t* payload,
                                     uint8_t payload_length
                                     )

Brief

Request a device-to-device uplink.

Remarks

The uplink will be sent as soon as possible in the first available ping slot according to chosen ping_slots_mask. It will be repeated nb_rep times in following acceptable slots.

Parameters

[in]	stack_id	Stack identifier
[in]	mc_grp_id	The multicast group identifier
[in]	d2d_config	The device to device specific uplink configuration structure
[in]	fport	The LoRaWAN FPort on which the uplink is done
[in]	payload	The data to be sent
[in]	payload_length	The number of bytes from payload to be 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	fport is out of the [1:223] range
SMTC_MODEM_RC_BUSY	Modem is currently in test mode
SMTC_MODEM_RC_FAIL	Modem is not available (suspended, muted or not joined) or no multicast session is running on this group id
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 (DM) LoRaWAN® FPort.

Parameters

[out]

dm_fport

LoRaWAN® 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 the Device Management (DM) info fields.

Parameters

[in]	dm_fields_payload	DM info fields (see Table 7.2 - Device Management Fields)
[in]	dm_field_length	DM info 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	Parameter dm_fields_payload and/or dm_field_length is 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 Device Management (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	Parameter format and/or interval is 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 (DM) 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_request_single_uplink()¶

smtc_modem_return_code_t smtc_modem_dm_request_single_uplink (
                                    const uint8_t*  dm_fields_payload,
                                    uint8_t  dm_field_length
                                     )

Brief

Request an immediate Device Management (DM) status.

Remarks

The content is independent from the configuration set with smtc_modem_dm_set_info_fields().

Parameters

[in]	dm_fields_payload	DM info fields (see DM info fields codes)
[in]	dm_field_length	DM info 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 field code or parameter dm_fields_payload is NULL
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_dm_set_fport()¶

smtc_modem_return_code_t smtc_modem_dm_set_fport  (
                                    uint8_t dm_fport
                                    )

Brief

Set the Device Management (DM) LoRaWAN FPort.

Parameters

[in]

dm_fport

LoRaWAN 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 Device Management (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 info fields (see DM info fields codes)
[in]	dm_field_length	DM info 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 info fields
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 Device Management (DM) info field messages.

Remarks

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

Parameters

[in]	format	Reporting interval format
[in]	interval	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	Parameter 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 (DM) 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	Stack identifier
[in]	index	Index on which the upload is done
[in]	cipher_mode	Cipher mode
[in]	file	File buffer
[in]	file_length	File size in bytes
[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 8192 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

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_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 session.

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 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 file_length value in smtc_modem_file_upload_init()
SMTC_MODEM_RC_INVALID_STACK_ID	Invalid stack_id

smtc_modem_get_adr_ack_limit_delay()¶

smtc_modem_return_code_t smtc_modem_get_adr_ack_limit_delay  (
                                    uint8_t stack_id
                                    uint8_t * adr_ack_limit,
                                    uint8_t * adr_ack_delay
                                    )

Brief

Get the configured LoRaWan stack ADR ACK limit and ADR ACK delay in regards to ADR fallback if no downlink are received.

Parameters

[in]	stack_id	Stack identifier
[out]	adr_ack_limit	ADR ACK limit
[out]	adr_ack_delay	ADR ACK delay

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	adr_ack_limit or adr_ack_delay are NULL
SMTC_MODEM_RC_BUSY	Modem is currently in test mode
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 Datarate in regards to Uplink ChMash and DwellTime.

Parameters

[in]	stack_id	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	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	Stack identifier
[out]	enable	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

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 LoRaWAN network class.

Parameters

[in]	stack_id	Stack identifier
[out]	lorawan_class	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_ppm()¶

smtc_modem_return_code_t smtc_modem_get_crystal_error (
                                    uint32_t*  crystal_error_ppm
                                    )

Brief

Get the modem crystal error.

Parameters

[out]

crystal_error_ppm

Crystal error in ppm

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	crystal_error_ppm 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	Stack identifier
[out]	deveui	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

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	event or event_pending_count are NULL
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	Stack identifier
[out]	joineui	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 LoRaWAN stack 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	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

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	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 in case of unconfirmed uplink.

Parameters

[in]	stack_id	Stack identifier
[out]	nb_trans	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	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 is available and a downlink opportunity is required.

Parameters

[in]	stack_id	Stack identifier
[in]	frame_pending_bit_status	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	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	Stack identifier
[in]	network_type	Current configuration (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	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 LoRaWAN regional parameters for the next transmission using the current data rate.

Parameters

[in]	stack_id	Stack identifier
[out]	tx_max_payload_size	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 LoRaWAN region.

Parameters

[in]	stack_id	Stack identifier
[out]	region	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	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	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	Stack identifier
[out]	stack_state	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	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	Stack identifier
[out]	status_mask	Modem status (see 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	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 - number of seconds elapsed since GPS epoch (00:00:00, Sunday 6th of January 1980).

Parameters

[out]	gps_time_s	GPS time in seconds
[out]	gps_fractional_s	GPS fractional 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	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	Stack identifier
[out]	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	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_increment_event_middleware()¶

smtc_modem_return_code_t smtc_modem_increment_event_middleware       (
                                                      uint8_t        event_type,
                                                      uint8_t        status
                                                      )

Brief

Increment a middleware asynchronous event.

Parameters

[in]	event_type	Type of asynchronous message
[in]	status	Status of asynchronous message

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	event_type isn’t a middleware event type

smtc_modem_init()¶

void smtc_modem_init (
                                  const ralk_t* radio,
                                  void(*)(void) event_callback
                                  )

Brief

Init the soft modem and set the modem event chosen callback.

Remarks

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

Parameters

[in]

event_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

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 (LBT) feature.

Parameters

[in]	stack_id	Stack identifier
[out]	listening_duration_ms	Current listening duration in ms
[out]	threshold_dbm	Current LBT threshold in dbm
[out]	bw_hz	Current LBT 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 parameter 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 (LBT) feature.

Parameters

[in]	stack_id	Stack identifier
[out]	enabled	Current status of the LBT 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	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 (LBT) feature.

Parameters

[in]	stack_id	Stack identifier
[in]	listening_duration_ms	Listening duration in ms to be configured
[in]	threshold_dbm	LBT threshold in dbm to be configured
[in]	bw_hz	LBT 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 (LBT) feature.

Remarks

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

Parameters

[in]	stack_id	Stack identifier
[in]	enable	Status of the LBT 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

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_lorawan_class_b_request_ping_slot_info()¶

smtc_modem_return_code_t smtc_modem_lorawan_class_b_request_ping_slot_info   (
                                                         uint8_t     stack_id
                                                         )

Brief

Request a Ping Slot Info MAC command to the network.

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	Modem is not available (suspended, muted or not joined)
SMTC_MODEM_RC_INVALID_STACK_ID	Invalid stack_id

smtc_modem_lorawan_get_lost_connection_counter()¶

smtc_modem_return_code_t smtc_modem_lorawan_get_lost_connection_counter      (
                                                            uint8_t  stack_id,
                                                            uint16_t *       lost_connection_cnt
                                                            )

Brief

Get the current value of the lost connection counter.

Remarks

The counter is incremented after any uplink and is only reset when a valid downlink is received from Network Server.

Parameters

[in]	stack_id	Stack identifier
[out]	lost_connection_cnt	Lost connection counter current value

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	lost_connection_cnt is NULL
SMTC_MODEM_RC_BUSY	Modem is currently in test mode
SMTC_MODEM_RC_INVALID_STACK_ID	Invalid stack_id

smtc_modem_lorawan_request_link_check()¶

smtc_modem_return_code_t smtc_modem_lorawan_request_link_check  (
                                    uint8_t stack_id
                                    )

Brief

Request a Link Check Req MAC command to the network.

Remarks

The request will be sent in a new uplink frame.

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	Modem is not available (suspended, muted or not joined)
SMTC_MODEM_RC_INVALID_STACK_ID	Invalid stack_id

smtc_modem_multicast_class_b_get_session_status()¶

smtc_modem_return_code_t smtc_modem_multicast_class_b_get_session_status (
                                                   uint8_t   stack_id,
                                                   smtc_modem_mc_grp_id_t    mc_grp_id,
                                                   bool *    is_session_started,
                                                   bool *    is_session_waiting_for_beacon,
                                                   uint32_t *        freq,
                                                   uint8_t *         dr,
                                                   smtc_modem_class_b_ping_slot_periodicity_t *      ping_slot_periodicity
                                                   )

Brief

Get class B 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]	is_session_waiting_for_beacon	Session beacon waiting status
[out]	dr	Session downlink datarate
[out]	freq	Session downlink frequency
[out]	ping_slot_periodicity	Session ping slot periodicity

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	mc_grp_id is not in the range [0:3] or a parameter is NULL
SMTC_MODEM_RC_BUSY	Modem is currently in test mode
SMTC_MODEM_RC_INVALID_STACK_ID	Invalid stack_id

smtc_modem_multicast_class_b_start_session()¶

smtc_modem_return_code_t smtc_modem_multicast_class_b_start_session(
                        uint8_t      stack_id,
                        smtc_modem_mc_grp_id_t       mc_grp_id,
                        uint32_t freq,
                        uint8_t dr,
                        smtc_modem_class_b_ping_slot_periodicity_t   ping_slot_periodicity
                        )

Brief

Start class B 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 datarate for this session
[in]	ping_slot_periodicity	Ping slot periodicity 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	mc_grp_id is not in the range [0:3] freq or dr are not in acceptable range (according to current regional params)
SMTC_MODEM_RC_BUSY	Modem is currently in test mode
SMTC_MODEM_RC_FAIL	This session is already started or modem is not in class B
SMTC_MODEM_RC_INVALID_STACK_ID	Invalid stack_id

smtc_modem_multicast_class_b_stop_all_sessions()¶

smtc_modem_return_code_t smtc_modem_multicast_class_b_stop_all_sessions(
                                                         uint8_t stack_id
                                                         )

Brief

Stop all started class B 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_RC_INVALID_STACK_ID	Invalid stack_id

smtc_modem_multicast_class_b_stop_session()¶

smtc_modem_return_code_t smtc_modem_multicast_class_b_stop_session(
                                       uint8_t stack_id,
                                       smtc_modem_mc_grp_id_t        mc_grp_id
                                       )

Brief

Stop class B 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	mc_grp_id is not in the range [0:3]
SMTC_MODEM_RC_BUSY	Modem is currently in test mode
SMTC_MODEM_RC_INVALID_STACK_ID	Invalid stack_id

smtc_modem_multicast_class_c_get_session_status()¶

smtc_modem_return_code_t smtc_modem_multicast_class_c_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 class C 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	Downlink frequency in Hz for this session
[out]	dr	Downlink datarate 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	mc_grp_id is not in the range [0:3] or a parameter is NULL
SMTC_MODEM_RC_BUSY	Modem is currently in test mode
SMTC_MODEM_RC_INVALID_STACK_ID	Invalid stack_id

smtc_modem_multicast_class_c_start_session()¶

smtc_modem_return_code_t smtc_modem_multicast_class_c_start_session(
                                                   uint8_t stack_id,
                                                   smtc_modem_mc_grp_id_t    mc_grp_id,
                                                   uint32_t *        freq,
                                                   uint8_t *         dr
                                                   )

Brief

Start class C multicast session for a specific group.

Parameters

[in]	stack_id	Stack identifier
[in]	mc_grp_id	Multicast group identifier
[in]	freq	Downlink frequency in Hz for this session
[in]	dr	Downlink datarate 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	mc_grp_id is not in the range [0:3]. freq or dr are not in acceptable range (according to current regional params). freq or dr 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 or modem is not in class C
SMTC_MODEM_RC_INVALID_STACK_ID	Invalid stack_id

smtc_modem_multicast_class_c_stop_all_sessions()¶

smtc_modem_return_code_t smtc_modem_multicast_class_c_stop_all_sessions(
                                                         uint8_t stack_id
                                                         )

Brief

Stop all started class C 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_RC_INVALID_STACK_ID	Invalid stack_id

smtc_modem_multicast_class_c_stop_session()¶

smtc_modem_return_code_t smtc_modem_multicast_class_c_stop_session(
                                                      uint8_t stack_id,
                                                      smtc_modem_mc_grp_id_t         mc_grp_id
                                                      )

Brief

Stop class C 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	mc_grp_id is not in the range [0:3] or a parameter is NULL
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	mc_grp_id is not in the range [0:3] or parameter mc_grp_addr is NULL
SMTC_MODEM_RC_BUSY	Modem is currently in test mode
SMTC_MODEM_RC_INVALID_STACK_ID	Invalid stack_id

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	Multicast 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	mc_grp_id is not in the range [0:3]
SMTC_MODEM_RC_BUSY	Modem is currently in test mode
SMTC_MODEM_RC_FAIL	Error during crypto process or a running session already exists on this id

smtc_modem_request_emergency_uplink()¶

smtc_modem_return_code_t smtc_modem_request_emergency_uplink  (
                                    uint8_t stack_id,
                                    uint8_t  fport,
                                    bool  confirmed,
                                    const uint8_t*   payload,
                                    uint8_t  payload_length
                                    )

Brief

Request an immediate LoRaWAN uplink.

Remarks

It has higher priority than all other services and is not subject to duty cycle restrictions, if any LoRaWAN NbTrans parameter can be set in mobiles and custom ADR modes with smtc_modem_set_nb_trans()

Parameters

[in]	stack_id	Stack identifier
[in]	fport	LoRaWAN FPort on which the uplink is done
[in]	confirmed	Message type (true: confirmed, false: unconfirmed)
[in]	payload	Data to be sent
[in]	payload_length	Number of bytes from payload to be 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	fport is out of the [1:223] range or equal to the DM LoRaWAN FPort
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_request_empty_uplink()¶

smtc_modem_return_code_t smtc_modem_request_empty_uplink (
                                    uint8_t  stack_id,
                                    bool  send_fport,
                                    uint8_t  fport,
                                    bool  confirmed
                                    )

Brief

Request a LoRaWAN uplink without payload, and an optional FPort.

Remarks

It can be used to create downlink opportunities / heartbeat without routing messages to an application server

Parameters

[in]	stack_id	Stack identifier
[in]	send_fport	Add the FPort to the payload (true: add the FPort, false: send without FPort)
[in]	fport	The LoRaWAN FPort on which the uplink is done, if used
[in]	confirmed	Message type (true: confirmed, false: unconfirmed)

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 [1:223] range or equal to the DM LoRaWAN FPort
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_request_extended_uplink()¶

smtc_modem_return_code_t smtc_modem_request_extended_uplink(
                                                   uint8_t stack_id,
                                                   uint8_t   f_port,
                                                   bool      confirmed,
                                                   const uint8_t *   payload,
                                                   uint8_t   payload_length,
                                                   uint8_t   extended_uplink_id,
                                                   void(*)(void)     lbm_notification_callback
                                                   )

Brief

Request a LoRaWAN extended uplink.

Remarks

This feature is introduced for future libraries and functions, it is NOT recommended for the user to call this function. This feature requires a special compilation option to be activated.

Parameters

[in]	stack_id	Stack identifier
[in]	fport	LoRaWAN FPort on which the uplink is done
[in]	confirmed	Message type (true: confirmed, false: unconfirmed)
[in]	payload	Data to be sent
[in]	payload_length	Number of bytes from payload to be sent
[in]	extended_uplink_id	ID of the queue for extended uplink should be equal to 1 or 2
[in]	lbm_notification_callback	Notification callback (to notify middleware when tx is finished)

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 fport is out of the [1:223] range or equal to dm_fport, or extended_uplink_id not equal to 1 or 2
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_request_uplink()¶

smtc_modem_return_code_t smtc_modem_request_uplink  (
                                    uint8_t  stack_id,
                                    uint8_t  fport,
                                    bool  confirmed,
                                    const uint8_t*   payload,
                                    uint8_t  payload_length
                                    )

Brief

Request a LoRaWAN uplink.

Remarks

LoRaWAN NbTrans parameter can be set in mobiles and custom ADR modes with smtc_modem_set_nb_trans().

Parameters

[in]	stack_id	Stack identifier
[in]	fport	The LoRaWAN FPort on which the uplink is done
[in]	confirmed	Message type (true: confirmed, false: unconfirmed)
[in]	payload	Data to be sent
[in]	payload_length	Number of bytes from payload to be 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	fport is out of the [1:223] range or equal to the DM LoRaWAN FPort
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_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

Release user radio access and resume modem features (scheduler and radio access).

Remarks

The user must call this function after performing operations requiring a 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_rp_abort_user_radio_access_task()¶

smtc_modem_return_code_t smtc_modem_rp_abort_user_radio_access_task( uint8_t user_task_id )

Brief

Abort a user task in radio planner.

Parameters

[in]

user_task_id

ID of the user task to abort

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_rp_add_user_radio_access_task()¶

smtc_modem_return_code_t smtc_modem_rp_add_user_radio_access_task    (
                                       smtc_modem_rp_task_t *        rp_task
                                       )

Brief

Add a user task in radio planner.

Parameters

[in]

rp_task

Structure holding radio planner task information

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 user task is already running in radio planner

smtc_modem_run_engine()¶

uint32_t smtc_modem_run_engine (void)

Brief

Run the modem engine.

Remarks

This function must be called in main loop.

Returns

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

smtc_modem_set_adr_ack_limit_delay()¶

smtc_modem_return_code_t smtc_modem_set_adr_ack_limit_delay(
                                                      uint8_t stack_id,
                                                      uint8_t adr_ack_limit,
                                                      uint8_t adr_ack_delay
                                                      )

Brief

Set the LoRaWAN stack ADR ACK limit and ADR ACK delay regarding the ADR fallback if no downlink is received.

Parameters

[in]	stack_id	Stack identifier
[in]	adr_ack_limit	ADR ACK limit. Accepted value: ( adr_ack_limit > 1 ) && ( adr_ack_limit < 128 )
[in]	adr_ack_delay	ADR ACK delay. Accepted value: ( adr_ack_delay > 1 ) && ( adr_ack_delay < 128 )

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	adr_ack_limit and adr_ack_delay are not in the range [2:127]
SMTC_MODEM_RC_BUSY	Modem is currently in test mode
SMTC_MODEM_RC_INVALID_STACK_ID	Invalid stack_id

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	The 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_INVALID	LoRaWAN class is not in an acceptable range
SMTC_MODEM_RC_BUSY	Modem is currently in test mode
SMTC_MODEM_RC_FAIL	For Class B only: no time is available or modem is not joined
SMTC_MODEM_RC_INVALID_STACK_ID	Invalid “stack_id”

smtc_modem_set_crystal_error_ppm()¶

smtc_modem_return_code_t smtc_modem_set_crystal_error_ppm  (
                                    uint32_t  crystal_error_ppm
                                    )

Brief

Set modem crystal error.

Parameters

[in]

crystal_error_ppm

Crystal error in ppm

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_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]
                                    )