Developing an Application with LoRa Basics™ Modem¶

Porting¶

The following items must be implemented before starting to develop an application:

• The driver Hardware Abstraction Layer (HAL) corresponding to the selected transceiver

• The Radio Abstraction Layer (RAL) Board Support Package (BSP) corresponding to the selected transceiver

• The LoRa Basics Modem Hardware Abstraction Layer corresponding to the selected MCU

Please refer to the LoRa Basics™ Modem Porting Guide for further details.

Radio Selection¶

LoRa Basics Modem includes support for multiple transceivers. The driver for the specific transceiver used in a solution must be instantiated through a call to one of the following macros:

• RALF_LR11XX_INSTANTIATE( ctx )

• RALF_SX126X_INSTANTIATE( ctx )

• RALF_SX128X_INSTANTIATE( ctx )

The call to one of the above macros establishes the link between the RAL and the specific driver used in the solution.

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 required:

• The radio to be used

• 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.

The application must call smtc_modem_run_engine periodically to advance the modem state machine.

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 joining or joined)

• 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().

LoRaWAN® Class B¶

Before enabling LoRaWAN Class B, LoRa Basics Modem has to be connected to a network in class A.

Once a network is joined, the two following actions have to be performed - the order does not matter:

• Enable the time synchronization service by calling smtc_modem_time_start_sync_service() with SMTC_MODEM_TIME_MAC_SYNC parameter

• Configure the ping slot periodicity by calling smtc_modem_class_b_set_ping_slot_periodicity() and request an update of the parameter to the LoRaWAN Network Server by calling smtc_modem_lorawan_class_b_request_ping_slot_info()

As soon as both events SMTC_MODEM_EVENT_TIME (with a status different from SMTC_MODEM_EVENT_TIME_NOT_VALID) and SMTC_MODEM_EVENT_CLASS_B_PING_SLOT_INFO (with a status equal to SMTC_MODEM_EVENT_CLASS_B_PING_SLOT_ANSWERED) are received, it is possible to switch to Class B by calling smtc_modem_set_class() with SMTC_MODEM_CLASS_B parameter.

LoRa Basics Modem is effectively in Class B when the event SMTC_MODEM_EVENT_CLASS_B_STATUS (with a status equal to SMTC_MODEM_EVENT_CLASS_B_READY) is received. The stack has acquired a beacon and started to open ping slots.

Class B downlinks are available through the event SMTC_MODEM_EVENT_DOWNDATA with status SMTC_MODEM_EVENT_DOWNDATA_WINDOW_RXB.

LoRaWAN® Multicast¶

Up to 4 multicast groups can be configured by calling smtc_modem_multicast_set_grp_config() with the following parameters for each group to be configured:

• ID

• Address

• Network session key

• Application session key

It is possible to read back the group address of a given group ID by calling smtc_modem_multicast_get_grp_config().

All active multicast sessions have to be stopped before switching to class A (see hereafter to know how to stop a multicast session).

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 ignoring 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

Receive Data Over LoRaWAN¶

When a downlink is received that contains data for the application, the event SMTC_MODEM_EVENT_DOWNDATA is triggered with the payload - if any. There are also the following metadata:

• RSSI

• SNR

• Reception window

• FPort

• FPending bit

• Frequency

• Datarate

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

It is also possible to get information about the connection:

• Current status of the duty cycle limitation, if any, by calling smtc_modem_get_duty_cycle_status()

• Current status of the connection timeouts by calling smtc_modem_connection_timeout_get_current_values()

• Maximum size of the next uplink by calling smtc_modem_get_next_tx_max_payload()

• Available datarates by calling smtc_modem_get_available_datarates()

• Number of consecutive uplinks without downlink by calling smtc_modem_lorawan_get_lost_connection_counter()

The user can also request a link check by calling smtc_modem_lorawan_request_link_check(). This is a MAC command that will be responded to using a link check answer.

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. It is advised to configure the interval before starting the service. If done after, the first interval is set to 36 hours - the configured value is taken into account only for the next interval.

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

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_trigger_sync_request() is called, 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().

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 newly 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 & LR1120 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 configured, 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 8180 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