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
LoRa Basics™ Modem User Manual v1.0 documentation
Table of Contents
- LoRa Basics™ Modem Events Definitions
- LoRa Basics™ Modem Device Management Field Codes
- LoRa Basics™ Modem API return codes
- LoRa Basics™ Modem API
- smtc_modem_adr_get_profile()
- smtc_modem_adr_set_profile()
- smtc_modem_alarm_clear_timer()
- smtc_modem_alarm_get_remaining_time()
- smtc_modem_alarm_start_timer()
- smtc_modem_connection_timeout_get_current_values()
- smtc_modem_connection_timeout_get_thresholds()
- smtc_modem_connection_timeout_set_thresholds()
- smtc_modem_dm_get_fport()
- smtc_modem_dm_get_info_fields()
- smtc_modem_dm_get_info_interval()
- smtc_modem_dm_get_user_data()
- smtc_modem_dm_request_single_uplink()
- smtc_modem_dm_set_fport()
- smtc_modem_dm_set_info_fields()
- smtc_modem_dm_set_info_interval()
- smtc_modem_dm_set_user_data()
- smtc_modem_factory_reset()
- smtc_modem_file_upload_init()
- smtc_modem_file_upload_reset()
- smtc_modem_file_upload_start()
- smtc_modem_get_available_datarates()
- smtc_modem_get_certification_mode()
- smtc_modem_get_charge()
- smtc_modem_get_class()
- smtc_modem_get_crystal_error()
- smtc_modem_get_deveui()
- smtc_modem_get_duty_cycle_status()
- smtc_modem_get_event()
- smtc_modem_get_joineui()
- smtc_modem_get_lorawan_version()
- smtc_modem_get_modem_version()
- smtc_modem_get_nb_trans()
- smtc_modem_get_network_frame_pending_status()
- smtc_modem_get_network_type()
- smtc_modem_get_next_tx_max_payload()
- smtc_modem_get_region()
- smtc_modem_get_regional_params_version()
- smtc_modem_get_stack_state()
- smtc_modem_get_status()
- smtc_modem_get_time()
- smtc_modem_get_tx_power_offset_db()
- smtc_modem_init()
- smtc_modem_join_network()
- smtc_modem_lbt_get_parameters()
- smtc_modem_lbt_get_state()
- smtc_modem_lbt_set_parameters()
- smtc_modem_lbt_set_state()
- smtc_modem_leave_network()
- smtc_modem_lorawan_request_link_check()
- smtc_modem_multicast_get_grp_config()
- smtc_modem_multicast_get_session_status()
- smtc_modem_multicast_set_grp_config()
- smtc_modem_multicast_start_session()
- smtc_modem_multicast_stop_all_sessions()
- smtc_modem_multicast_stop_session()
- smtc_modem_request_emergency_uplink()
- smtc_modem_request_empty_uplink()
- smtc_modem_request_uplink()
- smtc_modem_reset()
- smtc_modem_reset_charge()
- smtc_modem_resume_after_user_radio_access()
- smtc_modem_run_engine()
- smtc_modem_set_certification_mode()
- smtc_modem_set_class()
- smtc_modem_set_crystal_error()
- smtc_modem_set_deveui()
- smtc_modem_set_joineui()
- smtc_modem_set_nb_trans()
- smtc_modem_set_network_type()
- smtc_modem_set_nwkkey()
- smtc_modem_set_region()
- smtc_modem_set_tx_power_offset_db()
- smtc_modem_stream_add_data()
- smtc_modem_stream_init()
- smtc_modem_stream_status()
- smtc_modem_suspend_before_user_radio_access()
- smtc_modem_suspend_radio_communications()
- smtc_modem_time_get_alcsync_fport()
- smtc_modem_time_get_sync_interval_s()
- smtc_modem_time_get_sync_invalid_delay_s()
- smtc_modem_time_set_alcsync_fport()
- smtc_modem_time_set_sync_interval_s()
- smtc_modem_time_set_sync_invalid_delay_s()
- smtc_modem_time_start_sync_service()
- smtc_modem_time_stop_sync_service()
- smtc_modem_time_trigger_sync_request()
- LoRa Basics™ Modem API LR1110 Extension
- Command Sequences
- Porting