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_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 DM status.

Remarks

The content is independent from the configuration set with smtc_modem_dm_set_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	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 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_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

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_FAIL	Modem is not available (suspended, muted or not joined)
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_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 uplink to the LoRaWAN network.

Remarks

This has higher priority than all other services, and does not take duty cycle restrictions into account. It can be used to signal an alarm condition (e.g. smoke alarm) in real time, but it should be used with caution!

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	Parameter fport is out of the [1:223] range or equal to dm_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 an uplink to the LoRaWAN network without payload, and an optional FPort.

Remarks

Can be used to create downlink opportunities or heartbeat without involving message routing to the AS.

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	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	Parameter fport is out of the [1;223] range or is equal to dm_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_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 an uplink to the LoRaWAN network.

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	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	Parameter fport is out of the [1:223] range or is equal to dm_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

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