LoRa Basics™ Modem User Manual v1.0 documentation

Command Sequences

This chapter describes the required sequences of commands to enable functionalities offered by LoRa Basics™ Modem.

Reset and Initialize the System

In order to reset the LoRa Basics Modem, the user first has to perform an initialization by calling smtc_modem_init(), where two parameters are requested:

  • The radio to be used (as of today, LR1110 is the only supported transceiver)

  • The callback to get the event from the Modem

After the first call to smtc_modem_run_engine(), the event SMTC_MODEM_EVENT_RESET is triggered to let the user know that the modem is now ready to use.

It is strongly recommended to not call any modem-related command between the initialization and the event. If you do, LoRa Basics Modem may have an undefined behaviour.

Get Version Information

Various information can be fetched from the API:

  • smtc_modem_get_modem_version() to get the LoRa Basics Modem version

  • smtc_modem_get_lorawan_version() to get the LoRaWAN® version implemented in LoRa Basics Modem

  • smtc_modem_get_regional_params_version() to get the LoRaWAN regional parameters version implemented in LoRa Basics Modem

Fetch an Event

The callback that is shared during initialization permits the user to be informed of incoming events. When the callback is called by LoRa Basics Modem, the user can retrieve the pending events by calling smtc_modem_get_event().

The user can unstack pending events with successive calls to smtc_modem_get_event() until SMTC_MODEM_EVENT_NONE is returned.

Join a LoRaWAN® network

Before initiating a join procedure, the user has to set some LoRaWAN® parameters - the order does not matter:

  • LoRaWAN region with smtc_modem_set_region() (can only be changed when the modem is not in joining or joined state)

  • LoRaWAN class with smtc_modem_set_class()

The user can configure the EUIs and key parameters with the following functions:

  • DevEUI with smtc_modem_set_deveui()

  • JoinEUI with smtc_modem_set_joineui()

  • AppKey with smtc_modem_set_nwkkey()

The user can also configure the type of network they are using - private or public - by calling smtc_modem_set_network_type()

Once all parameters are set, the user can start joining a LoRaWAN network by calling smtc_modem_join_network(). The user is informed of the evolution of the procedure via two events:

  • SMTC_MODEM_EVENT_JOINED: a join accept was received; the join procedure is over

  • SMTC_MODEM_EVENT_JOINFAIL: nothing was received after the join request; the join procedure keeps going

The user can cancel an ongoing join procedure or leave an already-joined network by calling smtc_modem_leave_network().

Send Data Over LoRaWAN

The user can send a standard uplink, while being connected, with the following functions:

  • smtc_modem_request_uplink()

  • smtc_modem_request_emergency_uplink() to send data with the highest priority, while getting rid of a duty cycle restriction

  • smtc_modem_request_empty_uplink() to send an empty payload with an optional FPort field; can be used to create a downlink opportunity

Manage a LoRaWAN Connection Lifecycle

Once a LoRaWAN network is joined, the user can configure several parameters while being connected:

  • The ADR profile by calling smtc_modem_adr_set_profile()

  • The connection timeout thresholds by calling smtc_modem_connection_timeout_set_thresholds()

  • The number of transmissions for each unconfirmed uplink by calling smtc_modem_set_nb_trans()

Note

All the functions mentioned above can also be called before joining a network.

It is also possible to get information about the connection: * The current status of the duty cycle limitation, if any, by calling smtc_modem_get_duty_cycle_status() * The current status of the connection timeouts by calling smtc_modem_connection_timeout_get_current_values() * The maximum size of the next uplink by calling smtc_modem_get_next_tx_max_payload() * The available datarates by calling smtc_modem_get_available_datarates()

The user can also request a link check by calling smtc_modem_lorawan_request_link_check().

Get Time from the Network Server or Application Server

The user can configure LoRa Basics Modem to perform an automatic time synchronization:

  • Configure the interval between two time requests with smtc_modem_time_set_sync_interval_s()

  • Configure the delay since the last synchronization to consider the time as not valid anymore with smtc_modem_time_set_sync_invalid_delay_s()

  • (Optional) Configure the ALCsync port with smtc_modem_time_set_alcsync_fport() if the service to be used is SMTC_MODEM_TIME_ALC_SYNC

The user must ensure that the interval is lower than the desynchronization delay. This delay takes into account the maximal time deviation tolerated by the targeted application and the clock drift.

Once all parameters are set, the user can select and start the time synchronization service by calling smtc_modem_time_start_sync_service(). It can be stopped anytime by calling smtc_modem_time_stop_sync_service().

If SMTC_MODEM_TIME_MAC_SYNC is set with smtc_modem_time_start_sync_service(), an event is triggered in the following case:

  • When a time synchronization is successful (status set to SMTC_MODEM_EVENT_TIME_VALID)

If SMTC_MODEM_TIME_ALC_SYNC is set with smtc_modem_time_start_sync_service(), an event is triggered in the following cases:

  • When a time synchronization is successful (status set to SMTC_MODEM_EVENT_TIME_VALID)

  • When a time synchronization is not successful and the local time is not synchronized (status set to SMTC_MODEM_EVENT_TIME_NOT_VALID)

If SMTC_MODEM_TIME_MAC_SYNC is set with smtc_modem_time_trigger_sync_request(), an event is triggered in the following cases:

  • When a time synchronization is successful (status set to SMTC_MODEM_EVENT_TIME_VALID)

  • When a time synchronization is not successful and the local time is not synchronized (status set to SMTC_MODEM_EVENT_TIME_NOT_VALID)

  • When a time synchronization request does not get an answer but the local time is still synchronized (status set to SMTC_MODEM_EVENT_TIME_VALID_BUT_NOT_SYNC)

The user can fetch the current time by calling smtc_modem_get_time(). Before a time synchronization is performed, it returns SMTC_MODEM_RC_NO_TIME.

The user can request a time synchronization besides those sent on a periodic basis by calling smtc_modem_time_trigger_sync_request(). This is only compatible with SMTC_MODEM_TIME_MAC_SYNC for now.

Send Information with the Device Management Services

Before initiating a periodic information report, the user has to set several parameters; the order does not matter:

  • LoRaWAN FPort, with smtc_modem_dm_set_fport()

  • Fields to be reported, with smtc_modem_dm_set_info_fields()

  • (Optional) User data to be reported, with smtc_modem_dm_set_user_data() - useful only if SMTC_MODEM_DM_FIELD_APP_STATUS is part of the user_data parameter given to smtc_modem_dm_set_info_fields()

  • Interval between two periodic information reports, with smtc_modem_dm_set_info_interval()

If the user modifies the interval between two periodic device management information reports, it cancels the next planned uplink and schedules a new one that will be sent after the new chosen interval.

The user can request a device management information report besides those sent on periodic basis by calling smtc_modem_dm_request_single_uplink() where fields different from the ones set with smtc_modem_dm_set_info_fields() can be reported.

Update the Almanac with Device Management Services

The field SMTC_MODEM_DM_FIELD_ALMANAC_STATUS has a specific behaviour in device managemement services. When enabled, either with smtc_modem_dm_set_info_fields() or smtc_modem_dm_request_single_uplink(), it sends the current state of the almanac to the LoRa Cloud™ Modem & Geolocation Services, which can decide to trigger an incremental update if needed.

The event SMTC_MODEM_EVENT_ALMANAC_UPDATE is triggered when an update is done.

This service is only compatible with LR1110 transceivers.

Send Data with the Stream Service

The user can stream data and let LoRa Basics Modem deal with MTU limits.

Before initiating a stream, the user has to set several parameters by calling smtc_modem_stream_init():

  • LoRaWAN FPort

  • Encryption mode

  • Redundancy ratio

Once the configuration is done, the user can add data to the stream buffer by calling smtc_modem_stream_add_data(). It is recommended to check the free space in the buffer with smtc_modem_stream_status() before adding data.

The event SMTC_MODEM_EVENT_STREAMDONE is triggered when the last byte of the stream buffer is sent. This event is triggered for information purposes; there is no need to wait for it before adding data to the stream buffer.

Send Data with the File Upload Service

The user can send up to 2048 bytes (called a file) and let LoRa Basics Modem deal with MTU limits.

Before initiating a file upload, the user has to set several parameters by calling smtc_modem_file_upload_init():

  • Application index

  • Encryption mode

  • File to be sent and its size

  • Delay between two fragment uploads

Once the configuration is done, the user can start the transfer by calling smtc_modem_file_upload_start(). The user can abort the transfer by calling smtc_modem_file_upload_reset().

The event SMTC_MODEM_EVENT_UPLOADDONE is triggered when:

  • The LoRa Cloud Modem & Geolocation Services acknowledges the reception with a dedicated downlink message (status set to SMTC_MODEM_EVENT_UPLOADDONE_SUCCESSFUL)

  • No acknowledgment is received after the last upload (status set to SMTC_MODEM_EVENT_UPLOADDONE_ABORTED)

Configure a Timer

LoRa Basics Modem offers the possibility to configure a timer that can trigger SMTC_MODEM_EVENT_ALARM event.

To start a timer, the user has to call smtc_modem_alarm_start_timer(). It can be stopped by calling smtc_modem_alarm_clear_timer(). A call to smtc_modem_alarm_get_remaining_time() returns the remaining time, in seconds, before the event is triggered.

Interleave Direct Radio Access

It is possible to prevent LoRa Basics Modem from accessing the transceiver and let the application have direct access to it without being interrupted.

This can be done through two functions:

  • smtc_modem_suspend_before_user_radio_access() - to be called before any direct access to the transceiver

  • smtc_modem_resume_after_user_radio_access() - to be called after the last direct access to the transceiver

Note

As soon as smtc_modem_suspend_before_user_radio_access() is called, LoRa Basics Modem will not perform any radio-related operation until smtc_modem_resume_after_user_radio_access() is called. For instance, class B or C operations - if enabled - cannot be performed.