LoRa Basics™ Modem User Manual v3.2 documentation
LoRa Basics™ Modem API Reference¶
LoRa Basics™ Modem Event Codes Definitions¶
When the LoRa Basics™ Modem (LBM) is initialized, a callback function is passed to the smtc_modem_init(...)
function. This callback is
used to signal that a new asynchronous event has occurred. The following event types are used in LBM.
Events |
Description |
---|---|
SMTC_MODEM_EVENT_RESET |
Modem has been reset |
SMTC_MODEM_EVENT_ALARM |
Alarm timer expired |
SMTC_MODEM_EVENT_JOINED |
Network successfully joined |
SMTC_MODEM_EVENT_TXDONE |
Frame transmitted |
SMTC_MODEM_EVENT_DOWNDATA |
Downlink data received |
SMTC_MODEM_EVENT_UPLOADDONE |
File upload completed |
SMTC_MODEM_EVENT_SETCONF |
Configuration was changed by Device Management |
SMTC_MODEM_EVENT_MUTE |
Modem muted / un-muted by Device Management |
SMTC_MODEM_EVENT_STREAMDONE |
Stream upload completed (stream data buffer depleted) |
SMTC_MODEM_EVENT_JOINFAIL |
Attempt to join network failed |
SMTC_MODEM_EVENT_TIME |
Update on time happened (synced or invalid) |
SMTC_MODEM_EVENT_TIMEOUT_ADR_CHANGED |
ADR profile was switched to network controlled |
SMTC_MODEM_EVENT_NEW_LINK_ADR |
New link ADR requested by network |
SMTC_MODEM_EVENT_LINK_CHECK |
Link Check answered by network |
SMTC_MODEM_EVENT_ALMANAC_UPDATE |
An almanac update has been received |
SMTC_MODEM_EVENT_USER_RADIO_ACCESS |
Radio callback when user uses the radio by itself |
SMTC_MODEM_EVENT_CLASS_B_PING_SLOT_INFO |
Ping Slot Info answered by network. |
SMTC_MODEM_EVENT_CLASS_B_STATUS |
Downlink class B is ready or not. |
SMTC_MODEM_EVENT_MIDDLEWARE_1 |
Reserved for Middleware. |
SMTC_MODEM_EVENT_MIDDLEWARE_2 |
Reserved for Middleware. |
SMTC_MODEM_EVENT_MIDDLEWARE_3 |
Reserved for Middleware. |
SMTC_MODEM_EVENT_NONE |
No event available |
Note
Events can be retrieved through the function smtc_modem_get_event(...)
.
LoRa Basics™ Modem Device Management Fields¶
LBM periodically sends status messages that update the device record in the LoRa Cloud™
Modem & Geolocation Services. The fields that are to be included in these status messages can be read and
adjusted through the smtc_modem_dm_get_info_fields(...)
and smtc_modem_dm_set_info_fields(...)
functions.
The following table lists the names of the Device Management fields that can be reported to the LoRa Cloud
Modem and Geolocation Services.
Field |
Description |
---|---|
SMTC_MODEM_DM_FIELD_STATUS |
Modem status |
SMTC_MODEM_DM_FIELD_CHARGE |
Charge counter [mAh] |
SMTC_MODEM_DM_FIELD_VOLTAGE |
Supply voltage [1/50 V] |
SMTC_MODEM_DM_FIELD_TEMPERATURE |
Junction temperature [deg Celsius] |
SMTC_MODEM_DM_FIELD_SIGNAL |
RSSI and SNR of the last downlink |
SMTC_MODEM_DM_FIELD_UP_TIME |
Duration since last reset [h] |
SMTC_MODEM_DM_FIELD_RX_TIME |
Duration since last downlink [h] |
SMTC_MODEM_DM_FIELD_ADR_MODE |
ADR profile (0-3) |
SMTC_MODEM_DM_FIELD_JOIN_EUI |
Join EUI |
SMTC_MODEM_DM_FIELD_INTERVAL |
Reporting interval [values 0-63, units s/m/h/d] |
SMTC_MODEM_DM_FIELD_REGION |
Regulatory region |
SMTC_MODEM_DM_FIELD_RST_COUNT |
Modem reset count |
SMTC_MODEM_DM_FIELD_DEV_EUI |
Device EUI |
SMTC_MODEM_DM_FIELD_SESSION |
Session id / join nonce |
SMTC_MODEM_DM_FIELD_CHIP_EUI |
Chip EUI |
SMTC_MODEM_DM_FIELD_APP_STATUS |
Application-specific status |
SMTC_MODEM_DM_FIELD_ALMANAC_STATUS |
Almanac status |
Note
Additionally to the periodic status reporting, the LoRa Cloud Modem & Geolocation Services can explicitly request a status update by means of a GetInfo downlink. However, these requests are handled internally by the LBM and are therefore not exposed by the API to the application.
LoRa Basics™ Modem API Return Codes¶
The LBM API functions return a value of type
smtc_modem_return_code_t
called the Return Code. The Return Code
signals the result of the functions execution. The following table lists the
Return Codes used in the LBM API.
Return Code |
Description |
---|---|
SMTC_MODEM_RC_OK |
Command executed without errors |
SMTC_MODEM_RC_NOT_INIT |
Command not initialized |
SMTC_MODEM_RC_INVALID |
Command parameters invalid |
SMTC_MODEM_RC_BUSY |
Command cannot be executed now |
SMTC_MODEM_RC_FAIL |
Command execution failed |
SMTC_MODEM_RC_BAD_SIZE |
Size check failed |
SMTC_MODEM_RC_NO_TIME |
No time available |
SMTC_MODEM_RC_INVALID_STACK_ID |
Invalid stack_id parameter |
Note
Command output values must not be read if the Return Code differs from SMTC_MODEM_RC_OK
.
LoRa Basics™ Modem Datarate Profiles¶
The following table lists the available datarate profiles.
Return Code |
Description |
---|---|
SMTC_MODEM_ADR_PROFILE_NETWORK_CONTROLLED |
Network Server controlled for static devices |
SMTC_MODEM_ADR_PROFILE_MOBILE_LONG_RANGE |
Long range distribution for mobile devices |
SMTC_MODEM_ADR_PROFILE_MOBILE_LOW_POWER |
Low power distribution for mobile devices |
SMTC_MODEM_ADR_PROFILE_CUSTOM |
User defined distribution |
LoRa Basics™ Modem API Functions¶
LBM 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 LBM API.
smtc_modem_abort_extended_uplink()¶
smtc_modem_return_code_t smtc_modem_abort_extended_uplink (
uint8_t stack_id,
uint8_t extended_uplink_id
)
- Brief
This feature is introduced for future libraries and functions, it is NOT recommended for the user to call this function. This feature requires a special compilation option to be activated.
- Parameters
[in]
stack_id
Stack identifier
[in]
extended_uplink_id
ID of the queue for extended uplink should be equal to 1 or 2
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
Extended_uplink_id not equal to 1 or 2
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_FAIL
Modem is not available (suspended, muted or not joined)
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_adr_get_profile()¶
smtc_modem_return_code_t smtc_modem_adr_get_profile (
uint8_t stack_id,
smtc_modem_adr_profile_t* adr_profile
)
- Brief
Get the current adaptative data rate (ADR) profile.
- Remarks
Valid datarate profiles are listed in table 7.4.
- Parameters
[in]
stack_id
Stack identifier
[out]
adr_profile
Current ADR profile
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
Parameter adr_profile is NULL
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_adr_set_profile()¶
smtc_modem_return_code_t smtc_modem_adr_set_profile (
uint8_t stack_id,
smtc_modem_adr_profile_t* adr_profile
const uint8_t adr_custom_data[SMTC_MODEM_CUSTOM_ADR_DATA_LENGTH]
)
- Brief
Set the adaptative data rate (ADR) profile.
- Remarks
If SMTC_MODEM_ADR_PROFILE_CUSTOM is selected, custom data are taken into account. Valid datarate profiles are listed in table 7.4.
- Parameters
[in]
stack_id
Stack identifier
[in]
adr_profile
ADR profile to be configured
[in]
adr_custom_data
Definition of the custom ADR profile
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
One or more invalid parameter
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_alarm_clear_timer()¶
smtc_modem_return_code_t smtc_modem_alarm_clear_timer (void)
- Brief
Stop and clear the alarm timer.
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_NOT_INIT
No alarm timer currently running
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
smtc_modem_alarm_get_remaining_time()¶
smtc_modem_return_code_t smtc_modem_alarm_get_remaining_time (
uint32_t* remaining_time_in_s
)
- Brief
Get the number of seconds remaining before the alarm triggers an event.
- Parameters
[out]
remaining_time_in_s
Number of seconds remaining before the alarm triggers an event
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_NOT_INIT
No alarm timer currently running
SMTC_MODEM_RC_INVALID
Parameter remaining_time_in_s is NULL
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
smtc_modem_alarm_start_timer()¶
smtc_modem_return_code_t smtc_modem_alarm_start_timer (
uint32_t alarm_timer_in_s
)
- Brief
Set and start the alarm timer.
- Parameters
[in]
alarm_timer_in_s
The alarm timer in seconds
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
smtc_modem_class_b_get_ping_slot_periodicity()¶
smtc_modem_return_code_t smtc_modem_class_b_get_ping_slot_periodicity (
uint8_t stack_id,
smtc_modem_class_b_ping_slot_periodicity_t* ping_slot_periodicity
)
- Brief
Get Class B Ping Slot Periodicity.
- Parameters
[in]
stack_id
Stack identifier
[out]
ping_slot_periodicity
Ping slot periodicity
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
ping_slot_periodicity is NULL
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_class_b_set_ping_slot_periodicity()¶
smtc_modem_return_code_t smtc_modem_class_b_set_ping_slot_periodicity (
uint8_t stack_id,
smtc_modem_class_b_ping_slot_periodicity_t ping_slot_periodicity
)
- Brief
Set Class B Ping Slot Periodicity.
- Parameters
[in]
stack_id
Stack identifier
[in]
ping_slot_periodicity
Ping slot periodicity
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_connection_timeout_get_current_values()¶
smtc_modem_return_code_t smtc_modem_connection_timeout_get_current_values (
uint8_t stack_id,
uint16_t* nb_of_uplinks_before_network_controlled,
uint16_t* nb_of_uplinks_before_reset
)
- Brief
Get the current status of the connection timeouts.
- Parameters
[in]
stack_id
Stack identifier
[out]
nb_of_uplinks_before_network_controlled
Number of remaining uplinks without downlink before the ADR profile switches to network-controlled
[out]
nb_of_uplinks_before_reset
Number of remaining uplinks without downlink before reset
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
Parameter nb_of_uplinks_before_network_controlled and/or nb_of_uplinks_before_reset is NULL
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_connection_timeout_get_thresholds()¶
smtc_modem_return_code_t smtc_modem_connection_timeout_get_thresholds (
uint8_t stack_id,
uint16_t* nb_of_uplinks_before_network_controlled,
uint16_t* nb_of_uplinks_before_reset
)
- Brief
Get the configured connection timeout thresholds.
- Parameters
[in]
stack_id
Stack identifier
[out]
nb_of_uplinks_before_network_controlled
Number of uplinks without downlinks before the ADR profile switches to network-controlled
[out]
nb_of_uplinks_before_reset
Number of uplinks without downlinks before reset
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
Parameter nb_of_uplinks_before_network_controlled and/or nb_of_uplinks_before_reset is NULL
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_connection_timeout_set_thresholds()¶
smtc_modem_return_code_t smtc_modem_connection_timeout_set_thresholds (
uint8_t stack_id,
uint16_t nb_of_uplinks_before_network_controlled,
uint16_t nb_of_uplinks_before_reset
)
- Brief
Set the connection timeout thresholds.
- Remarks
The value 0 deactivates the command. It is recommended to have nb_of_uplinks_before_network_controlled smaller than nb_of_uplink_before_reset.
- Parameters
[in]
stack_id
Stack identifier
[out]
nb_of_uplinks_before_network_controlled
Number of uplinks without downlink before the ADR profile switches to network-controlled
[out]
nb_of_uplinks_before_reset
Number of uplinks without downlink before reset
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_d2d_class_b_get_tx_max_payload()¶
smtc_modem_return_code_t smtc_modem_d2d_class_b_get_tx_max_payload (
uint8_t stack_id,
smtc_modem_mc_grp_id_t mc_grp_id,
uint8_t* tx_max_payload_size
)
- Brief
Get the maximum payload size that can be used for a device to device uplink on chosen multicast group.
- Parameters
[in]
stack_id
Stack identifier
[in]
mc_grp_id
The multicast group identifier
[out]
tx_max_payload_size
The maximum payload size in byte
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
tx_max_payload_size is NULL
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_FAIL
Modem is not available (suspended, muted or not joined) or no multicast session is running on this group id
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_d2d_class_b_request_uplink()¶
smtc_modem_return_code_t smtc_modem_d2d_class_b_request_uplink (
uint8_t stack_id,
smtc_modem_mc_grp_id_t mc_grp_id,
smtc_modem_d2d_class_b_uplink_config_t * d2d_config,
uint8_t fport,
const uint8_t* payload,
uint8_t payload_length
)
- Brief
Request a device-to-device uplink.
- Remarks
The uplink will be sent as soon as possible in the first available ping slot according to chosen ping_slots_mask. It will be repeated nb_rep times in following acceptable slots.
- Parameters
[in]
stack_id
Stack identifier
[in]
mc_grp_id
The multicast group identifier
[in]
d2d_config
The device to device specific uplink configuration structure
[in]
fport
The LoRaWAN FPort on which the uplink is done
[in]
payload
The data to be sent
[in]
payload_length
The number of bytes from payload to be sent
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
fport is out of the [1:223] range
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_FAIL
Modem is not available (suspended, muted or not joined) or no multicast session is running on this group id
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_dm_get_fport()¶
smtc_modem_return_code_t smtc_modem_dm_get_fport (
uint8_t* dm_fport
)
- Brief
Get the Device Management (DM) LoRaWAN® FPort.
- Parameters
[out]
dm_fport
LoRaWAN® FPort on which the DM info is sent
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
Parameter dm_fport is NULL
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
smtc_modem_dm_get_info_fields()¶
smtc_modem_return_code_t smtc_modem_dm_get_info_fields (
uint8_t* dm_fields_payload,
uint8_t* dm_field_length
)
- Brief
Get the Device Management (DM) info fields.
- Parameters
[in]
dm_fields_payload
DM info fields (see Table 7.2 - Device Management Fields)
[in]
dm_field_length
DM info field length
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
Parameter dm_fields_payload and/or dm_field_length is NULL
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
smtc_modem_dm_get_info_interval()¶
smtc_modem_return_code_t smtc_modem_dm_get_info_interval (
smtc_modem_dm_info_interval_format_t* format,
uint8_t* interval
)
- Brief
Get the interval between two Device Management (DM) info field messages.
- Parameters
[out]
format
Reporting interval format
[out]
interval
Interval in unit defined in format
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
Parameter format and/or interval is NULL
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
smtc_modem_dm_get_user_data()¶
smtc_modem_return_code_t smtc_modem_dm_get_user_data (
uint8_t user_data[SMTC_MODEM_DM_USER_DATA_LENGTH]
)
- Brief
Get user-specific data to be reported by Device Management (DM) frames.
- Parameters
[out]
user_data
User-specific data
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
Parameter user_data is NULL
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
smtc_modem_dm_request_single_uplink()¶
smtc_modem_return_code_t smtc_modem_dm_request_single_uplink (
const uint8_t* dm_fields_payload,
uint8_t dm_field_length
)
- Brief
Request an immediate Device Management (DM) status.
- Remarks
The content is independent from the configuration set with smtc_modem_dm_set_info_fields().
- Parameters
[in]
dm_fields_payload
DM info fields (see DM info fields codes)
[in]
dm_field_length
DM info field length
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
Invalid or duplicated field code or parameter dm_fields_payload is NULL
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_FAIL
Modem is not available (suspended, muted or not joined)
smtc_modem_dm_set_fport()¶
smtc_modem_return_code_t smtc_modem_dm_set_fport (
uint8_t dm_fport
)
- Brief
Set the Device Management (DM) LoRaWAN FPort.
- Parameters
[in]
dm_fport
LoRaWAN FPort on which the DM info is sent. This value must be in the range [1:223]
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
Parameter dm_fport is out of the [1:223] range
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
smtc_modem_dm_set_info_fields()¶
smtc_modem_return_code_t smtc_modem_dm_set_info_fields (
const uint8_t* dm_fields_payload,
uint8_t dm_field_length
)
- Brief
Set the Device Management (DM) info fields to be sent on a regular basis.
- Remarks
The interval between two DM info field messages is defined with smtc_modem_dm_set_info_interval().
- Parameters
[in]
dm_fields_payload
DM info fields (see DM info fields codes)
[in]
dm_field_length
DM info field length
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
Invalid or duplicated DM info fields
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
smtc_modem_dm_set_info_interval()¶
smtc_modem_return_code_t smtc_modem_dm_set_info_interval (
smtc_modem_dm_info_interval_format_t format,
uint8_t interval
)
- Brief
Set the interval between two Device Management (DM) info field messages.
- Remarks
An interval value set to 0 disables the feature - no matter the format.
- Parameters
[in]
format
Reporting interval format
[in]
interval
Interval in unit defined in format, from 0 to 63
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
Parameter interval is not in the [0:63] range.
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
smtc_modem_dm_set_user_data()¶
smtc_modem_return_code_t smtc_modem_dm_set_user_data (
const uint8_t user_data[SMTC_MODEM_DM_USER_DATA_LENGTH]
)
- Brief
Set user-specific data to be reported by Device Management (DM) frames.
- Remarks
This field will be sent only if it is selected in smtc_modem_dm_set_info_fields() or smtc_modem_dm_request_single_uplink().
- Parameters
[in]
user_data
User-specific data
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
smtc_modem_factory_reset()¶
smtc_modem_return_code_t smtc_modem_factory_reset (void)
- Brief
Reset the modem to its original state.
- Remarks
Resets all modem-related non-volatile settings to their default values, then resets the MCU. Only LoRaWAN DevNonce is kept.
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
smtc_modem_file_upload_init()¶
smtc_modem_return_code_t smtc_modem_file_upload_init (
uint8_t stack_id,
uint8_t index,
smtc_modem_file_upload_cipher_mode_t cipher_mode,
const uint8_t* file,
uint16_t file_length,
uint32_t average_delay_s
)
- Brief
Create and initialize a file upload session.
- Parameters
[in]
stack_id
Stack identifier
[in]
index
Index on which the upload is done
[in]
cipher_mode
Cipher mode
[in]
file
File buffer
[in]
file_length
File size in bytes
[in]
average_delay_s
The minimal delay between two file upload fragments in seconds (from the end of an uplink to the start of the next one)
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
file_length is equal to 0 or greater than 8192 bytes, or file pointer is NULL
SMTC_MODEM_RC_BUSY
Modem is currently in test mode or a file upload is already ongoing
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_file_upload_reset()¶
smtc_modem_return_code_t smtc_modem_file_upload_reset (
uint8_t stack_id
)
- Brief
Reset the file upload session.
- Remarks
This function will stop any ongoing file upload session.
- Parameters
[in]
stack_id
Stack identifier
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_NOT_INIT
No file upload session currently running
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_file_upload_start()¶
smtc_modem_return_code_t smtc_modem_file_upload_start (
uint8_t stack_id
)
- Brief
Start the file upload session.
- Parameters
[in]
stack_id
Stack identifier
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_BUSY
Modem is currently in test mode or a file upload is already ongoing
SMTC_MODEM_RC_FAIL
Modem is not available (suspended, muted or not joined)
SMTC_MODEM_RC_BAD_SIZE
Total data sent does not match the declared file_length value in smtc_modem_file_upload_init()
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_get_adr_ack_limit_delay()¶
smtc_modem_return_code_t smtc_modem_get_adr_ack_limit_delay (
uint8_t stack_id
uint8_t * adr_ack_limit,
uint8_t * adr_ack_delay
)
- Brief
Get the configured LoRaWan stack ADR ACK limit and ADR ACK delay in regards to ADR fallback if no downlink are received.
- Parameters
[in]
stack_id
Stack identifier
[out]
adr_ack_limit
ADR ACK limit
[out]
adr_ack_delay
ADR ACK delay
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
adr_ack_limit or adr_ack_delay are NULL
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_get_available_datarates()¶
smtc_modem_return_code_t smtc_modem_get_available_datarates (
uint8_t stack_id,
uint16_t* available_datarates_mask
)
- Brief
Get the current available Datarate in regards to Uplink ChMash and DwellTime.
- Parameters
[in]
stack_id
Stack identifier
[out]
available_datarates_mask
The available data rates, described in a bit field
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
available_datarates_mask is NULL
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_get_certification_mode()¶
smtc_modem_return_code_t smtc_modem_get_certification_mode (
uint8_t stack_id,
bool* enable
)
- Brief
Get the current state of the certification mode.
- Parameters
[in]
stack_id
Stack identifier
[out]
enable
Certification mode state
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
Parameter enable is NULL
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_get_charge()¶
smtc_modem_return_code_t smtc_modem_get_charge (
uint32_t* charge_mah
)
- Brief
Get the total charge counter of the modem in mAh.
- Parameters
[out]
charge_mah
Accumulated charge in mAh
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
Parameter charge_mah is NULL
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
smtc_modem_get_class()¶
smtc_modem_return_code_t smtc_modem_get_class (
uint8_t stack_id,
smtc_modem_class_t* lorawan_class
)
- Brief
Get the current LoRaWAN network class.
- Parameters
[in]
stack_id
Stack identifier
[out]
lorawan_class
Current LoRaWAN class
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_get_crystal_error_ppm()¶
smtc_modem_return_code_t smtc_modem_get_crystal_error (
uint32_t* crystal_error_ppm
)
- Brief
Get the modem crystal error.
- Parameters
[out]
crystal_error_ppm
Crystal error in ppm
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
crystal_error_ppm is NULL
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
smtc_modem_get_deveui()¶
smtc_modem_return_code_t smtc_modem_get_deveui (
uint8_t stack_id,
uint8_t deveui[SMTC_MODEM_EUI_LENGTH]
)
- Brief
Get the DevEUI.
- Parameters
[in]
stack_id
Stack identifier
[out]
deveui
Current DevEUI
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_get_duty_cycle_status()¶
smtc_modem_return_code_t smtc_modem_get_duty_cycle_status (
int32_t* duty_cycle_status_ms
)
- Brief
Get the current status of the duty cycle.
- Remarks
If the returned value is positive, it is the time still available. A negative value indicates the time to wait until band availability.
- Parameters
[out]
duty_cycle_status_ms
Status of the duty cycle in milliseconds
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
Parameter duty_cycle_status_ms is NULL
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
smtc_modem_get_event()¶
smtc_modem_return_code_t smtc_modem_get_event (
smtc_modem_event_t* event,
uint8_t* event_pending_count
)
- Brief
Get the modem event.
- Remarks
This command can be used to retrieve pending events from the modem.
- Parameters
[out]
event
Structure holding event-related information
[out]
event_pending_count
Number of pending event(s)
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
event or event_pending_count are NULL
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
smtc_modem_get_joineui()¶
smtc_modem_return_code_t smtc_modem_get_joineui (
uint8_t stack_id,
uint8_t joineui[SMTC_MODEM_EUI_LENGTH]
)
- Brief
Get the JoinEUI.
- Parameters
[in]
stack_id
Stack identifier
[out]
joineui
Current JoinEUI
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_get_lorawan_version()¶
smtc_modem_return_code_t smtc_modem_get_lorawan_version (
smtc_modem_lorawan_version_t* lorawan_version
)
- Brief
Get the LoRaWAN stack network.
- Parameters
[out]
lorawan_version
The LoRaWAN version
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
lorawan_version is NULL
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
smtc_modem_get_modem_version()¶
smtc_modem_return_code_t smtc_modem_get_modem_version (
smtc_modem_version_t* firmware_version
)
- Brief
Get the modem firmware version.
- Parameters
[out]
firmware_version
Firmware version
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
firmware_version is NULL
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
smtc_modem_get_nb_trans()¶
smtc_modem_return_code_t smtc_modem_get_nb_trans (
uint8_t stack_id,
uint8_t* nb_trans
)
- Brief
Get the configured number of transmissions in case of unconfirmed uplink.
- Parameters
[in]
stack_id
Stack identifier
[out]
nb_trans
Number of transmissions
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
nb_trans is NULL
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_get_network_frame_pending_status()¶
smtc_modem_return_code_t smtc_modem_get_network_frame_pending_status (
uint8_t stack_id,
smtc_modem_frame_pending_bit_status_t* frame_pending_bit_status
)
- Brief
Get network frame pending status.
- Remarks
This bit is set by the network when data is available and a downlink opportunity is required.
- Parameters
[in]
stack_id
Stack identifier
[in]
frame_pending_bit_status
Frame pending bit status
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
frame_pending_bit_status is NULL
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_get_network_type()¶
smtc_modem_return_code_t smtc_modem_get_network_type (
uint8_t stack_id,
bool* network_type
)
- Brief
Get the configured network type.
- Parameters
[in]
stack_id
Stack identifier
[in]
network_type
Current configuration (true: public network / false: private network)
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
network_type is NULL
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_get_next_tx_max_payload()¶
smtc_modem_return_code_t smtc_modem_get_next_tx_max_payload (
uint8_t stack_id,
uint8_t* tx_max_payload_size
)
- Brief
Get the maximum payload size that can be used for the next uplink.
- Remarks
This value depends on the LoRaWAN regional parameters for the next transmission using the current data rate.
- Parameters
[in]
stack_id
Stack identifier
[out]
tx_max_payload_size
Maximum payload size in byte
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
Parameter tx_max_payload_size is NULL
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_FAIL
Modem has not joined a network
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_get_region()¶
smtc_modem_return_code_t smtc_modem_get_region (
uint8_t stack_id,
smtc_modem_region_t* region
)
- Brief
Get the current LoRaWAN region.
- Parameters
[in]
stack_id
Stack identifier
[out]
region
Current LoRaWAN region
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
region is NULL
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_get_regional_params_version()¶
smtc_modem_return_code_t smtc_modem_get_regional_params_version (
smtc_modem_lorawan_version_t* regional_params_version
)
- Brief
Get the stack Regional Parameters version.
- Parameters
[out]
regional_params_version
The stack regional parameters version
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
regional_params_version is NULL
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
smtc_modem_get_stack_state()¶
smtc_modem_return_code_t smtc_modem_get_stack_state (
uint8_t stack_id,
smtc_modem_stack_state_t* stack_state
)
- Brief
Get the current state of the stack.
- Parameters
[in]
stack_id
Stack identifier
[out]
stack_state
Stack current state
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
stack_state is NULL
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_get_status()¶
smtc_modem_return_code_t smtc_modem_get_status (
uint8_t stack_id,
smtc_modem_status_mask_t* status_mask
)
- Brief
Get the modem status.
- Parameters
[in]
stack_id
Stack identifier
[out]
status_mask
Modem status (see smtc_modem_status_mask_e)
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
status_mask is NULL
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_get_time()¶
smtc_modem_return_code_t smtc_modem_get_time (
uint32_t* gps_time_s,
uint32_t* gps_fractional_s
)
- Brief
Get GPS epoch time - number of seconds elapsed since GPS epoch (00:00:00, Sunday 6th of January 1980).
- Parameters
[out]
gps_time_s
GPS time in seconds
[out]
gps_fractional_s
GPS fractional seconds
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
gps_time_s or gps_fractional_s is NULL
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_NO_TIME
No time available
smtc_modem_get_tx_power_offset_db()¶
smtc_modem_return_code_t smtc_modem_get_tx_power_offset_db (
uint8_t stack_id,
int8_t* tx_pwr_offset_db
)
- Brief
Get the Tx power offset in dB.
- Parameters
[in]
stack_id
Stack identifier
[out]
tx_pwr_offset_db
Tx power offset in dB
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
tx_pwr_offset_db is NULL
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_increment_event_middleware()¶
smtc_modem_return_code_t smtc_modem_increment_event_middleware (
uint8_t event_type,
uint8_t status
)
- Brief
Increment a middleware asynchronous event.
- Parameters
[in]
event_type
Type of asynchronous message
[in]
status
Status of asynchronous message
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
event_type isn’t a middleware event type
smtc_modem_init()¶
void smtc_modem_init (
const ralk_t* radio,
void(*)(void) event_callback
)
- Brief
Init the soft modem and set the modem event chosen callback.
- Remarks
The callback will be called each time a modem event is raised internally.
- Parameters
[in]
event_callback
User event callback prototype
smtc_modem_join_network()¶
smtc_modem_return_code_t smtc_modem_join_network (
uint8_t stack_id
)
- Brief
Join the network.
- Parameters
[in]
stack_id
Stack identifier
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors or modem has already joined the network
SMTC_MODEM_RC_BUSY
Modem is currently in test mode or in joining/joined state
SMTC_MODEM_RC_FAIL
Modem is not available (suspended or muted)
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_lbt_get_parameters()¶
smtc_modem_return_code_t smtc_modem_lbt_get_parameters (
uint8_t stack_id,
uint32_t* listening_duration_ms,
int16_t* threshold_dbm,
uint32_t* bw_hz
)
- Brief
Get the parameters of the Listen Before Talk (LBT) feature.
- Parameters
[in]
stack_id
Stack identifier
[out]
listening_duration_ms
Current listening duration in ms
[out]
threshold_dbm
Current LBT threshold in dbm
[out]
bw_hz
Current LBT bandwidth in Hertz
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
At least one parameter is NULL
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_lbt_get_state()¶
smtc_modem_return_code_t smtc_modem_lbt_get_state (
uint8_t stack_id,
bool* enabled
)
- Brief
Get the state of the Listen Before Talk (LBT) feature.
- Parameters
[in]
stack_id
Stack identifier
[out]
enabled
Current status of the LBT feature (true: enabled, false: disabled)
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
enabled is NULL
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_lbt_set_parameters()¶
smtc_modem_return_code_t smtc_modem_lbt_set_parameters (
uint8_t stack_id,
uint32_t listening_duration_ms,
int16_t threshold_dbm,
uint32_t bw_hz
)
- Brief
Set the parameters of the Listen Before Talk (LBT) feature.
- Parameters
[in]
stack_id
Stack identifier
[in]
listening_duration_ms
Listening duration in ms to be configured
[in]
threshold_dbm
LBT threshold in dbm to be configured
[in]
bw_hz
LBT bandwidth in Hertz to be configured
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_lbt_set_state()¶
smtc_modem_return_code_t smtc_modem_lbt_set_state (
uint8_t stack_id,
bool enable
)
- Brief
Enable or disable the Listen Before Talk (LBT) feature.
- Remarks
The configuration function smtc_modem_lbt_set_parameters() must be called before enabling the LBT feature. LBT is silently enabled if the feature is mandatory in a region selected with smtc_modem_set_region().
- Parameters
[in]
stack_id
Stack identifier
[in]
enable
Status of the LBT feature to set (true: enable, false: disable)
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_leave_network()¶
smtc_modem_return_code_t smtc_modem_leave_network (
uint8_t stack_id
)
- Brief
Leave an already joined network or cancels on ongoing join process.
- Parameters
[in]
stack_id
Stack identifier
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_lorawan_class_b_request_ping_slot_info()¶
smtc_modem_return_code_t smtc_modem_lorawan_class_b_request_ping_slot_info (
uint8_t stack_id
)
- Brief
Request a Ping Slot Info MAC command to the network.
- Parameters
[in]
stack_id
Stack identifier
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_FAIL
Modem is not available (suspended, muted or not joined)
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_lorawan_get_lost_connection_counter()¶
smtc_modem_return_code_t smtc_modem_lorawan_get_lost_connection_counter (
uint8_t stack_id,
uint16_t * lost_connection_cnt
)
- Brief
Get the current value of the lost connection counter.
- Remarks
The counter is incremented after any uplink and is only reset when a valid downlink is received from Network Server.
- Parameters
[in]
stack_id
Stack identifier
[out]
lost_connection_cnt
Lost connection counter current value
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
lost_connection_cnt is NULL
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_lorawan_request_link_check()¶
smtc_modem_return_code_t smtc_modem_lorawan_request_link_check (
uint8_t stack_id
)
- Brief
Request a Link Check Req MAC command to the network.
- Remarks
The request will be sent in a new uplink frame.
- Parameters
[in]
stack_id
Stack identifier
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_FAIL
Modem is not available (suspended, muted or not joined)
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_multicast_class_b_get_session_status()¶
smtc_modem_return_code_t smtc_modem_multicast_class_b_get_session_status (
uint8_t stack_id,
smtc_modem_mc_grp_id_t mc_grp_id,
bool * is_session_started,
bool * is_session_waiting_for_beacon,
uint32_t * freq,
uint8_t * dr,
smtc_modem_class_b_ping_slot_periodicity_t * ping_slot_periodicity
)
- Brief
Get class B multicast session status for a chosen group.
- Parameters
[in]
stack_id
Stack identifier
[in]
mc_grp_id
Multicast group identifier
[out]
is_session_started
Session status
[out]
is_session_waiting_for_beacon
Session beacon waiting status
[out]
dr
Session downlink datarate
[out]
freq
Session downlink frequency
[out]
ping_slot_periodicity
Session ping slot periodicity
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
mc_grp_id is not in the range [0:3] or a parameter is NULL
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_multicast_class_b_start_session()¶
smtc_modem_return_code_t smtc_modem_multicast_class_b_start_session(
uint8_t stack_id,
smtc_modem_mc_grp_id_t mc_grp_id,
uint32_t freq,
uint8_t dr,
smtc_modem_class_b_ping_slot_periodicity_t ping_slot_periodicity
)
- Brief
Start class B multicast session for a specific group.
- Parameters
[in]
stack_id
Stack identifier
[in]
mc_grp_id
Multicast group identifier
[in]
freq
Downlink frequency for this session
[in]
dr
Downlink datarate for this session
[in]
ping_slot_periodicity
Ping slot periodicity for this session
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
mc_grp_id is not in the range [0:3] freq or dr are not in acceptable range (according to current regional params)
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_FAIL
This session is already started or modem is not in class B
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_multicast_class_b_stop_all_sessions()¶
smtc_modem_return_code_t smtc_modem_multicast_class_b_stop_all_sessions(
uint8_t stack_id
)
- Brief
Stop all started class B multicast sessions.
- Parameters
[in]
stack_id
Stack identifier
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_multicast_class_b_stop_session()¶
smtc_modem_return_code_t smtc_modem_multicast_class_b_stop_session(
uint8_t stack_id,
smtc_modem_mc_grp_id_t mc_grp_id
)
- Brief
Stop class B multicast session for a chosen group.
- Parameters
[in]
stack_id
Stack identifier
[in]
mc_grp_id
Multicast group identifier
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
mc_grp_id is not in the range [0:3]
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_multicast_class_c_get_session_status()¶
smtc_modem_return_code_t smtc_modem_multicast_class_c_get_session_status(
uint8_t stack_id,
smtc_modem_mc_grp_id_t mc_grp_id,
bool * is_session_started,
uint32_t * freq,
uint8_t * dr
)
- Brief
Get class C multicast session status for a chosen group.
- Parameters
[in]
stack_id
Stack identifier
[in]
mc_grp_id
Multicast group identifier
[out]
is_session_started
Session status
[out]
freq
Downlink frequency in Hz for this session
[out]
dr
Downlink datarate for this session
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
mc_grp_id is not in the range [0:3] or a parameter is NULL
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_multicast_class_c_start_session()¶
smtc_modem_return_code_t smtc_modem_multicast_class_c_start_session(
uint8_t stack_id,
smtc_modem_mc_grp_id_t mc_grp_id,
uint32_t * freq,
uint8_t * dr
)
- Brief
Start class C multicast session for a specific group.
- Parameters
[in]
stack_id
Stack identifier
[in]
mc_grp_id
Multicast group identifier
[in]
freq
Downlink frequency in Hz for this session
[in]
dr
Downlink datarate for this session
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
mc_grp_id is not in the range [0:3]. freq or dr are not in acceptable range (according to current regional params). freq or dr are not compatible with an already running multicast session.
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_FAIL
This session is already started or modem is not in class C
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_multicast_class_c_stop_all_sessions()¶
smtc_modem_return_code_t smtc_modem_multicast_class_c_stop_all_sessions(
uint8_t stack_id
)
- Brief
Stop all started class C multicast sessions.
- Parameters
[in]
stack_id
Stack identifier
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_multicast_class_c_stop_session()¶
smtc_modem_return_code_t smtc_modem_multicast_class_c_stop_session(
uint8_t stack_id,
smtc_modem_mc_grp_id_t mc_grp_id
)
- Brief
Stop class C multicast session for a chosen group.
- Parameters
[in]
stack_id
Stack identifier
[in]
mc_grp_id
Multicast group identifier
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
mc_grp_id is not in the range [0:3] or a parameter is NULL
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_multicast_get_grp_config()¶
smtc_modem_return_code_t smtc_modem_multicast_get_grp_config (
uint8_t stack_id,
smtc_modem_mc_grp_id_t mc_grp_id,
uint32_t* mc_grp_addr
)
- Brief
Get the configuration of the chosen multicast group.
- Parameters
[in]
stack_id
Stack identifier
[in]
mc_grp_id
Multicast group identifier
[out]
mc_grp_addr
Multicast group address
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
mc_grp_id is not in the range [0:3] or parameter mc_grp_addr is NULL
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_multicast_set_grp_config()¶
smtc_modem_return_code_t smtc_modem_multicast_set_grp_config (
uint8_t stack_id,
smtc_modem_mc_grp_id_t mc_grp_id,
uint32_t mc_grp_addr,
const uint8_t mc_nwk_skey[SMTC_MODEM_KEY_LENGTH],
const uint8_t mc_app_skey[SMTC_MODEM_KEY_LENGTH]
)
- Brief
Configure a multicast group.
- Parameters
[in]
stack_id
Stack identifier
[in]
mc_grp_id
Multicast group identifier
[in]
mc_grp_addr
Multicast group address
[in]
mc_nwk_skey
Multicast network session key for the group
[in]
mc_app_skey
Multicast application session key for the group
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
mc_grp_id is not in the range [0:3]
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_FAIL
Error during crypto process or a running session already exists on this id
smtc_modem_request_emergency_uplink()¶
smtc_modem_return_code_t smtc_modem_request_emergency_uplink (
uint8_t stack_id,
uint8_t fport,
bool confirmed,
const uint8_t* payload,
uint8_t payload_length
)
- Brief
Request an immediate LoRaWAN uplink.
- Remarks
It has higher priority than all other services and is not subject to duty cycle restrictions, if any LoRaWAN NbTrans parameter can be set in mobiles and custom ADR modes with smtc_modem_set_nb_trans()
- Parameters
[in]
stack_id
Stack identifier
[in]
fport
LoRaWAN FPort on which the uplink is done
[in]
confirmed
Message type (true: confirmed, false: unconfirmed)
[in]
payload
Data to be sent
[in]
payload_length
Number of bytes from payload to be sent
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
fport is out of the [1:223] range or equal to the DM LoRaWAN FPort
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_FAIL
Modem is not available (suspended, muted or not joined)
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_request_empty_uplink()¶
smtc_modem_return_code_t smtc_modem_request_empty_uplink (
uint8_t stack_id,
bool send_fport,
uint8_t fport,
bool confirmed
)
- Brief
Request a LoRaWAN uplink without payload, and an optional FPort.
- Remarks
It can be used to create downlink opportunities / heartbeat without routing messages to an application server
- Parameters
[in]
stack_id
Stack identifier
[in]
send_fport
Add the FPort to the payload (true: add the FPort, false: send without FPort)
[in]
fport
The LoRaWAN FPort on which the uplink is done, if used
[in]
confirmed
Message type (true: confirmed, false: unconfirmed)
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
fport is out of the [1:223] range or equal to the DM LoRaWAN FPort
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_FAIL
Modem is not available (suspended, muted or not joined)
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_request_extended_uplink()¶
smtc_modem_return_code_t smtc_modem_request_extended_uplink(
uint8_t stack_id,
uint8_t f_port,
bool confirmed,
const uint8_t * payload,
uint8_t payload_length,
uint8_t extended_uplink_id,
void(*)(void) lbm_notification_callback
)
- Brief
Request a LoRaWAN extended uplink.
- Remarks
This feature is introduced for future libraries and functions, it is NOT recommended for the user to call this function. This feature requires a special compilation option to be activated.
- Parameters
[in]
stack_id
Stack identifier
[in]
fport
LoRaWAN FPort on which the uplink is done
[in]
confirmed
Message type (true: confirmed, false: unconfirmed)
[in]
payload
Data to be sent
[in]
payload_length
Number of bytes from payload to be sent
[in]
extended_uplink_id
ID of the queue for extended uplink should be equal to 1 or 2
[in]
lbm_notification_callback
Notification callback (to notify middleware when tx is finished)
- Returns
Modem return code as defined in smtc_modem_return_code_t
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
Parameter fport is out of the [1:223] range or equal to dm_fport, or extended_uplink_id not equal to 1 or 2
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_FAIL
Modem is not available (suspended, muted or not joined)
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_request_uplink()¶
smtc_modem_return_code_t smtc_modem_request_uplink (
uint8_t stack_id,
uint8_t fport,
bool confirmed,
const uint8_t* payload,
uint8_t payload_length
)
- Brief
Request a LoRaWAN uplink.
- Remarks
LoRaWAN NbTrans parameter can be set in mobiles and custom ADR modes with smtc_modem_set_nb_trans().
- Parameters
[in]
stack_id
Stack identifier
[in]
fport
The LoRaWAN FPort on which the uplink is done
[in]
confirmed
Message type (true: confirmed, false: unconfirmed)
[in]
payload
Data to be sent
[in]
payload_length
Number of bytes from payload to be sent
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
fport is out of the [1:223] range or equal to the DM LoRaWAN FPort
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_FAIL
Modem is not available (suspended, muted or not joined)
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_reset()¶
smtc_modem_return_code_t smtc_modem_reset (void)
- Brief
Reset the modem.
- Remarks
Resets modem transient state (including session information) by resetting the MCU. Device Management Port, Modem Region and LoRaWAN Devnonce are kept.
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
smtc_modem_reset_charge()¶
smtc_modem_return_code_t smtc_modem_reset_charge (void)
- Brief
Reset the total charge counter of the modem.
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
smtc_modem_resume_after_user_radio_access()¶
smtc_modem_return_code_t smtc_modem_resume_after_user_radio_access (void)
- Brief
Release user radio access and resume modem features (scheduler and radio access).
- Remarks
The user must call this function after performing operations requiring a direct access to the radio (e.g. test modes). Otherwise, all modem-related tasks remain pending.
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
smtc_modem_rp_abort_user_radio_access_task()¶
smtc_modem_return_code_t smtc_modem_rp_abort_user_radio_access_task( uint8_t user_task_id )
- Brief
Abort a user task in radio planner.
- Parameters
[in]
user_task_id
ID of the user task to abort
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
smtc_modem_rp_add_user_radio_access_task()¶
smtc_modem_return_code_t smtc_modem_rp_add_user_radio_access_task (
smtc_modem_rp_task_t * rp_task
)
- Brief
Add a user task in radio planner.
- Parameters
[in]
rp_task
Structure holding radio planner task information
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_FAIL
A user task is already running in radio planner
smtc_modem_run_engine()¶
uint32_t smtc_modem_run_engine (void)
- Brief
Run the modem engine.
- Remarks
This function must be called in main loop.
- Returns
The time in ms after which the function must at least be called again.
smtc_modem_set_adr_ack_limit_delay()¶
smtc_modem_return_code_t smtc_modem_set_adr_ack_limit_delay(
uint8_t stack_id,
uint8_t adr_ack_limit,
uint8_t adr_ack_delay
)
- Brief
Set the LoRaWAN stack ADR ACK limit and ADR ACK delay regarding the ADR fallback if no downlink is received.
- Parameters
[in]
stack_id
Stack identifier
[in]
adr_ack_limit
ADR ACK limit. Accepted value: ( adr_ack_limit > 1 ) && ( adr_ack_limit < 128 )
[in]
adr_ack_delay
ADR ACK delay. Accepted value: ( adr_ack_delay > 1 ) && ( adr_ack_delay < 128 )
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
adr_ack_limit and adr_ack_delay are not in the range [2:127]
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_set_certification_mode()¶
smtc_modem_return_code_t smtc_modem_set_certification_mode (
uint8_t stack_id,
bool enable
)
- Brief
Enable / disable the certification mode.
- Parameters
[in]
stack_id
Stack identifier
[in]
enable
Certification mode state (default: disabled)
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_set_class()¶
smtc_modem_return_code_t smtc_modem_set_class (
uint8_t stack_id,
smtc_modem_class_t lorawan_class
)
- Brief
Set the class used by the LoRaWAN network.
- Parameters
[in]
stack_id
Stack identifier
[in]
lorawan_class
The LoRaWAN class to be configured
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_INVALID
LoRaWAN class is not in an acceptable range
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_FAIL
For Class B only: no time is available or modem is not joined
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid “stack_id”
smtc_modem_set_crystal_error_ppm()¶
smtc_modem_return_code_t smtc_modem_set_crystal_error_ppm (
uint32_t crystal_error_ppm
)
- Brief
Set modem crystal error.
- Parameters
[in]
crystal_error_ppm
Crystal error in ppm
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
smtc_modem_set_deveui()¶
smtc_modem_return_code_t smtc_modem_set_deveui (
uint8_t stack_id,
const uint8_t deveui[SMTC_MODEM_EUI_LENGTH]
)
- Brief
Set the DevEUI.
- Parameters
[in]
stack_id
Stack identifier
[in]
deveui
DevEUI to be configured
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_BUSY
Modem is currently in test mode or in joining/joined state
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_set_joineui()¶
smtc_modem_return_code_t smtc_modem_set_joineui (
uint8_t stack_id,
const uint8_t joineui[SMTC_MODEM_EUI_LENGTH]
)
- 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 allowed 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
nb_trans is not in [1:15] range or 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 LoRaWAN 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_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 (aka 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 LoRaWAN region.
- 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
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 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
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 smtc_modem_stream_init is not called beforehand, the stream uses 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
len is not in range [1-254] or 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,
uint8_t redundancy_ratio_percent
)
- Brief
Create and initialize a data stream.
- Parameters
[in]
stack_id
Stack identifier
[in]
fport
LoRaWAN FPort on which the stream is sent (0 forces the DM LoRaWAN FPort)
[in]
redundancy_ratio_percent
The stream redundancy ratio.
[in]
cipher_mode
The 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
pending 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 killing all current modem radio tasks.
- Remarks
The user must call this command before performing operations requiring a 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
The 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 LoRaWAN FPort.
- Parameters
[out]
alcsync_fport
FPort for ALCsync 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
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
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
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
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 LoRaWAN port.
- Remarks
When using Device Management (DM) port for alcsync_fport, ALCSync messages are encapsulated into DM frames.
- Parameters
[in]
alcsync_fport
LoRaWAN FPort for ALCSync 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
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 two time synchronization messages.
- Remarks
sync_interval_s has to be lower than the value set with smtc_modem_time_set_sync_invalid_delay_s(). The default value is set to 36 hours (129600 seconds).
- Parameters
[in]
sync_interval_s
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
sync_interval_s is invalid
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
sync_invalid_delay_s has to be higher than the value set with smtc_modem_time_set_sync_interval_s(). The default value is set to 49 days (4233600 seconds). Modem will generate a SMTC_MODEM_EVENT_TIME event if there are no time synchronizations for more time than this “invalid delay”.
- Parameters
[in]
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
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
)
- Brief
Trigger a single uplink requesting time using current enabled 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
Modem is not available (suspended, muted or not joined) or no time synchronization service is running
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
LoRa Basics™ Modem API LR11xx Extension¶
The following functions constitute the LBM API LR11xx Extension.
smtc_modem_derive_keys()¶
smtc_modem_return_code_t smtc_modem_derive_keys() (
uint8_t stack_id
)
- Brief
Derive keys.
- Remarks
This command can only be used with LR11xx radio. Derives the application key using the stored dev_eui (default set to chip_eui) and stored join_eui.
- Parameters
[in]
stack_id
Stack identifier
- Returns
Modem return code as defined in smtc_modem_return_code_t.
- Return values
SMTC_MODEM_RC_OK
Command executed without errors
SMTC_MODEM_RC_BUSY
Modem is currently in test mode
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
smtc_modem_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.
- Remarks
This command can only be used with LR11xx radio.
- Parameters
[in]
stack_id
Stack identifier
[out]
chip_eui
8-byte chip EUI
- Returns
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_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.
- Remarks
This command can only be used on a Basic Modem with LR11xx 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
SMTC_MODEM_RC_INVALID_STACK_ID
Invalid stack_id
LoRa Basics™ Modem API Test Functions¶
The following functions are useful when developing tests for regulatory conformance, certification, and functional testing.
smtc_modem_test_direct_radio_read()¶
smtc_modem_return_code_t smtc_modem_test_direct_radio_read (
uint8_t * command,
uint16_t command_length,
uint8_t * data,
uint16_t data_length
)
- Brief
Direct access to radio command read.
- Parameters
[in]
command
Pointer to the buffer to be transmitted
[in]
command_length
Buffer size to be transmitted
[out]
data
Pointer to the buffer to be received
[in]
data_length
Buffer size to be received
- Returns
Modem return code as defined in smtc_modem_return_code_t.
smtc_modem_test_direct_radio_write()¶
smtc_modem_return_code_t smtc_modem_test_direct_radio_write (
uint8_t * command,
uint16_t command_length,
uint8_t * data,
uint16_t data_length
)
- Brief
Direct access to radio command write.
- Parameters
[in]
command
Pointer to the buffer to be transmitted
[in]
command_length
Buffer size to be transmitted
[in]
data
Pointer to the buffer to be received
[in]
data_length
Buffer size to be received
- Returns
Modem return code as defined in smtc_modem_return_code_t.
smtc_modem_test_duty_cycle_app_activate()¶
smtc_modem_return_code_t smtc_modem_test_duty_cycle_app_activate (
bool status
)
- Brief
Enable / disable the applicative dutycycle.
- Parameters
[in]
status
0: disable, 1: enable
- Returns
Modem return code as defined in smtc_modem_return_code_t.
smtc_modem_test_get_nb_rx_packets()¶
smtc_modem_return_code_t smtc_modem_test_get_nb_rx_packets ( uint32_t * nb_rx_packets )
- Brief
Read number of received packets during test RX continue.
- Parameters
[out]
nb_rx_packets
Number of received packets in RX Continue
- Returns
Modem return code as defined in smtc_modem_return_code_t.
smtc_modem_test_get_rssi()¶
smtc_modem_return_code_t smtc_modem_test_get_rssi (
int8_t * rssi
)
- Brief
Get RSSI result (to be called when test rssi is finished).
- Remarks
Returns the computed RSSI.
- Parameters
[out]
rssi
rssi + 64
- Returns
Modem return code as defined in smtc_modem_return_code_t.
smtc_modem_test_nop()¶
smtc_modem_return_code_t smtc_modem_test_nop ( void )
- Brief
Perform no operation. This function can be used to terminate an ongoing continuous operation.
- Remarks
Abort the radio planner task.
- Returns
Modem return code as defined in smtc_modem_return_code_t.
smtc_modem_test_radio_reset()¶
smtc_modem_return_code_t smtc_modem_test_radio_reset ( void )
- Brief
Reset the Radio for test purpose.
- Returns
Modem return code as defined in smtc_modem_return_code_t.
smtc_modem_test_rssi()¶
smtc_modem_return_code_t smtc_modem_test_rssi (
uint32_t frequency_hz,
smtc_modem_test_bw_t bw,
uint16_t time_ms
)
- Brief
Test mode RSSI.
- Remarks
Measure continuously the RSSI during a chosen time and give an average value.
- Parameters
[in]
frequency_hz
Frequency in Hz
[in]
bw
Bandwidth following smtc_modem_test_bw_t definition
[in]
time_ms
Test duration in ms (1 rssi every 10 ms)
- Returns
Modem return code as defined in smtc_modem_return_code_t.
smtc_modem_test_rx_continuous()¶
smtc_modem_return_code_t smtc_modem_test_rx_continuous (
uint32_t frequency_hz,
smtc_modem_test_sf_t sf,
smtc_modem_test_bw_t bw,
smtc_modem_test_cr_t cr
)
- Brief
Put modem in Test RX continuous mode.
- Remarks
Continuously receive packets.
- Parameters
[in]
frequency_hz
Frequency in Hz
[in]
sf
Spreading factor following smtc_modem_test_sf_t definition
[in]
bw
Bandwidth following smtc_modem_test_bw_t definition
[in]
cr
Coding rate following smtc_modem_test_cr_t definition
- Returns
Modem return code as defined in smtc_modem_return_code_t.
smtc_modem_test_start()¶
smtc_modem_return_code_t smtc_modem_test_start ( void )
- Brief
Put modem in test mode.
- Remarks
No other modem commands can be handled during modem test mode
- Returns
Modem return code as defined in smtc_modem_return_code_t.
smtc_modem_test_stop()¶
smtc_modem_return_code_t smtc_modem_test_stop ( void )
- Brief
Exit modem test mode.
- Remarks
Exit test mode and perform a reset of modem.
- Returns
Modem return code as defined in smtc_modem_return_code_t.
smtc_modem_test_tx()¶
smtc_modem_return_code_t smtc_modem_test_tx (
uint8_t * payload,
uint8_t payload_length,
uint32_t frequency_hz,
int8_t tx_power_dbm,
smtc_modem_test_sf_t sf,
smtc_modem_test_bw_t bw,
smtc_modem_test_cr_t cr,
uint32_t preamble_size,
bool continuous_tx
)
- Brief
Test mode TX single or continuous.
- Remarks
Transmit a single packet or continuously transmit packets as fast as possible.
- Parameters
[in]
payload
Payload that will be sent. If NULL a randomly generated payload_length msg will be sent
[in]
payload_length
Length of the payload
[in]
frequency_hz
Frequency in Hz
[in]
tx_power_dbm
Power in dBm
[in]
sf
Spreading factor following smtc_modem_test_sf_t definition
[in]
bw
Bandwidth following smtc_modem_test_bw_t definition
[in]
cr
Coding rate following smtc_modem_test_cr_t definition
[in]
preamble_size
Size of the preamble
[in]
continuous_tx
false: single transmission / true: continuous transmission
- Returns
Modem return code as defined in smtc_modem_return_code_t.
smtc_modem_test_tx_cw()¶
smtc_modem_return_code_t smtc_modem_test_tx_cw (
uint32_t frequency_hz,
int8_t tx_power_dbm
)
- Brief
Test mode transmit a continuous wave.
- Parameters
[in]
frequency_hz
Frequency in Hz
[in]
tx_power_dbm
Power in dbm
- Returns
Modem return code as defined in smtc_modem_return_code_t.
Table of Contents
- Introduction
- LoRa Basics Modem Architecture
- LoRa Basics Modem Integration with LoRa Cloud
- LoRa Basics Modem Options
- Developing an Application with LoRa Basics™ Modem
- Porting
- Radio Selection
- Reset and Initialize the System
- Get Version Information
- Fetch an Event
- Join a LoRaWAN® Network
- LoRaWAN® Class B
- LoRaWAN® Multicast
- Send Data Over LoRaWAN
- Receive Data Over LoRaWAN
- Manage a LoRaWAN Connection Lifecycle
- Get Time from the Network Server or Application Server
- Send Information with the Device Management Services
- Update the Almanac with Device Management Services
- Send Data with the Stream Service
- Send Data with the File Upload Service
- Configure a Timer
- Interleave Direct Radio Access
- Known Limitations
- LoRa Basics™ Modem API Reference
- LoRa Basics™ Modem Event Codes Definitions
- LoRa Basics™ Modem Device Management Fields
- LoRa Basics™ Modem API Return Codes
- LoRa Basics™ Modem Datarate Profiles
- LoRa Basics™ Modem API Functions
- smtc_modem_abort_extended_uplink()
- 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_class_b_get_ping_slot_periodicity()
- smtc_modem_class_b_set_ping_slot_periodicity()
- smtc_modem_connection_timeout_get_current_values()
- smtc_modem_connection_timeout_get_thresholds()
- smtc_modem_connection_timeout_set_thresholds()
- smtc_modem_d2d_class_b_get_tx_max_payload()
- smtc_modem_d2d_class_b_request_uplink()
- 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_adr_ack_limit_delay()
- smtc_modem_get_available_datarates()
- smtc_modem_get_certification_mode()
- smtc_modem_get_charge()
- smtc_modem_get_class()
- smtc_modem_get_crystal_error_ppm()
- 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_increment_event_middleware()
- 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_class_b_request_ping_slot_info()
- smtc_modem_lorawan_get_lost_connection_counter()
- smtc_modem_lorawan_request_link_check()
- smtc_modem_multicast_class_b_get_session_status()
- smtc_modem_multicast_class_b_start_session()
- smtc_modem_multicast_class_b_stop_all_sessions()
- smtc_modem_multicast_class_b_stop_session()
- smtc_modem_multicast_class_c_get_session_status()
- smtc_modem_multicast_class_c_start_session()
- smtc_modem_multicast_class_c_stop_all_sessions()
- smtc_modem_multicast_class_c_stop_session()
- smtc_modem_multicast_get_grp_config()
- smtc_modem_multicast_set_grp_config()
- smtc_modem_request_emergency_uplink()
- smtc_modem_request_empty_uplink()
- smtc_modem_request_extended_uplink()
- smtc_modem_request_uplink()
- smtc_modem_reset()
- smtc_modem_reset_charge()
- smtc_modem_resume_after_user_radio_access()
- smtc_modem_rp_abort_user_radio_access_task()
- smtc_modem_rp_add_user_radio_access_task()
- smtc_modem_run_engine()
- smtc_modem_set_adr_ack_limit_delay()
- smtc_modem_set_certification_mode()
- smtc_modem_set_class()
- smtc_modem_set_crystal_error_ppm()
- 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 LR11xx Extension
- LoRa Basics™ Modem API Test Functions
- smtc_modem_test_direct_radio_read()
- smtc_modem_test_direct_radio_write()
- smtc_modem_test_duty_cycle_app_activate()
- smtc_modem_test_get_nb_rx_packets()
- smtc_modem_test_get_rssi()
- smtc_modem_test_nop()
- smtc_modem_test_radio_reset()
- smtc_modem_test_rssi()
- smtc_modem_test_rx_continuous()
- smtc_modem_test_start()
- smtc_modem_test_stop()
- smtc_modem_test_tx()
- smtc_modem_test_tx_cw()
- Revision History