LoRa Basics™ Modem User Manual v3.2 documentation
Introduction¶
LoRa Basics™ Modem is an easy-to-use software library that simplifies the development of LoRaWAN® end-nodes. By using LoRa Basics Modem in their solution, developers can work through an event driven interface, at a high level of abstraction without needing to delve into the details of the LoRaWAN protocol.
LoRa Basics Modem allows developers to seamlessly integrate the services provided by LoRa Cloud™ into their applications. LoRa Basics Modem can be used to generate messages compatible with the LoRa Cloud Modem & Geolocation Services, including periodic Device Management messages.
Scope¶
This document describes the LoRa Basics Modem library (SWL2001). This version of the document pertains to version 3.2.4 of the library.
It should be read in conjunction with:
LoRa Basics Modem SDK User Manual and associated SDK (SWSD001)
LoRa Basics Modem Porting Guide
Supported Transceivers¶
This version of LoRa Basics Modem supports the following transceivers:
LR1110 with firmware 0x0307.
LR1120 with firmware 0x0101.
SX1261.
SX1262.
SX1280.
SX1281.
New Features and Changes¶
The following new features and changes have been introduced since version 3.1.7 of the LoRa Basics Modem library.
New Features¶
AS923 group 4 Regional Parameters.
WW2G4 Regional Parameters for LoRaWAN protocol emulation.
SX128x radio support.
Changes¶
Added a new MCU_FLAGS option to the Makefile to make LoRa Basics Modem completely MCU agnostic.
LoRa Basics Modem library now uses the latest version of the LR11xx driver, v2.1.1.
SX126x driver was updated to the latest version, v2.1.0.
The PA configuration process in the example application was updated.
The ral_lr11xx_bsp_get_rssi_calibration_table workaround was removed from the example application as the LR11xx driver update makes it obsolete.
Bugs Fixed¶
LoRa Basics Modem now properly rejects files with a size between 8181 and 8192 bytes when using LFU.
Fixed an issue with the LFU service regarding encryption of files with size greater than 4080 bytes.
Fixed an issue with the radio interruption timestamp in the radio planner.
Corrected an issue regarding an outdated and aborted LBT pre-hook on LR11xx targets which resulted in no uplink.
Removed log print when uplinking on FSK to avoid adding delay on scheduled tasks.
When a link_adr_req MAC command with a new channel mask is received, it is now accepted if the custom datarate profile is enabled and configured with the highest datarate of the corresponding region.
The Large File Upload and stream services are properly reset when a rejoin request is received from the Modem and Geolocation Services.
Fixed the stack start and stop addresses in the example application stm32l476rgtx_flash.ld file.
Fixed hal_rtc_get_time_ms so that it returns a full range value.
A comprehensive list of changes is provided in the changelog file of the library.
Example Application¶
LoRa Basics Modem includes an example which serves to illustrate the use of the library and can also be used as a starting point when developing an application. This application is defined in the file utilities/user_app/main_examples/main_exti.c. The example application joins the LoRaWAN network and remains in sleep mode until the user button is pressed, at which time it makes a temperature measurement and sends an uplink with the measured value.
The application was developed for use in a Nucleo L476RG development board and supports the LR1110, LR1120, SX1261, SX1262, SX1280, and SX1281 transceivers.
To compile the example, perform the following steps:
Edit file utilities/user_app/main_examples/example_options.h:
Replace the values of USER_LORAWAN_DEVICE_EUI, USER_LORAWAN_JOIN_EUI, and USER_LORAWAN_APP_KEY with the correct values for your device and network.
Replace the value of MODEM_EXAMPLE_REGION by the value corresponding to your region.
In the utilities directory, issue the command make <TARGET> where target will be either sx128x, lr1110, lr1120, sx1261, or sx1262 depending on your transceiver.
Plug in the Nucleo L476RG board.
Drag the file utilities/build_<TARGET>/app_<TARGET>.bin to the NODE_L476RG storage device.
The example application outputs informational messages through the UART. These messages can be viewed by means of a terminal emulator using the serial parameters: 921600 baud, 8 data bits, no parity and 1 stop bit (921600 8N1).
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