Release v3.1.7

Author: Rafael Baquero

CHANGELOG.md

@@ -0,0 +1,53 @@
+# LoRa Basics Modem Library changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [v3.1.7] 2022-04-22
+
+### Added
+
+* AS923 (3 sub regions included), IN865, KR920, RU864, AU915 Regional Parameters
+* Class B support
+* Class B Multicast support (up to 4 sessions)
+* Class C Multicast support (up to 4 sessions)
+* LR-FHSS Support (enabled with compilation option: `RP_VERSION=RP2_103`)
+* Support of SX1261 and SX1262 radios
+* Added commands:
+  * New connectivity check function: smtc_modem_lorawan_get_lost_connection_counter
+  * Makefile: add Regional Parameters option to choose to compile the code for RP2_101 or RP2_103
+  * [smtc_modem_hal]:
+    * `smtc_modem_hal_assert(expr)` macro
+    * `smtc_modem_hal_assert_fail()` function
+    * `smtc_modem_hal_get_time_in_100us()` function
+    * `smtc_modem_hal_get_radio_irq_timestamp_in_100us()` function
+  * In `SMTC_MODEM_EVENT_DOWNDATA` event status: added new class B reception windows, fpending bit status, reception frequency and datarate
+  * Middleware API for geolocation
+* Add basic example to provide an easy start point on Nucleo L476 board
+
+### Changed
+
+* `smtc_modem_set_crystal_error` renamed to `smtc_modem_set_crystal_error_ppm` and now takes real ppm (previously was ppt)
+* `smtc_modem_get_stack_state`: Added a new stack state `SMTC_MODEM_STACK_STATE_TX_WAIT` when stack is between retransmissions
+* `smtc_modem_time_trigger_sync_request` function does not take `sync_service` parameter anymore, now it will use the current enabled time synchronization service
+* [smtc_modem_hal]: 
+  * `smtc_modem_hal_irq_is_radio_irq_pending()` function has been replaced with `smtc_modem_hal_radio_irq_clear_pending()`. Now modem only asks to clear radio pending irq
+* LR1110 driver was renamed to LR11xx driver and now also supports LR1120 radio
+* Updated to latest version of SX126x and LR11xx driver
+* An `ALMANAC_UPDATE` event is generated if "Almanac force update" is received.
+* File upload size can be now up to 8k
+* Remove -2dB default tx power offset (now it is 0) and manage EIRP to ERP conversion in LoRaWAN stack
+* `smtc_modem_connection_timeout_get_thresholds`: Default internal value of `nb_of_uplinks_before_network_controlled` is now 0 (before was 255). Result: the mobile to static automatic switching service is now deactivated by default.
+
+### Fixed
+
+* Corrected `Fcnt_down` msb management
+* `smtc_modem_derive_keys` now takes user defined EUIs into account
+* AU915: when dwell time was on, the returned max payload sizes were incorrect. This has been corrected
+* Corrected bug in `smtc_modem_reset_charge`
+* Internal join nonce value is now initialized to FFFFFF to avoid dropping the first join accept message
+
+## [v2.1.0] 2021-11-03
+
+Initial release

LICENSE.txt

@@ -0,0 +1,27 @@
+The Clear BSD License
+Copyright Semtech Corporation 2022. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted (subject to the limitations in the disclaimer
+below) provided that the following conditions are met:
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+    * Neither the name of the Semtech corporation nor the
+      names of its contributors may be used to endorse or promote products
+      derived from this software without specific prior written permission.
+
+NO EXPRESS OR IMPLIED LICENSES TO ANY PARTY'S PATENT RIGHTS ARE GRANTED BY
+THIS LICENSE. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
+CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT
+NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SEMTECH CORPORATION BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

LICENSES.txt

@@ -0,0 +1,136 @@
+Semtech's software made available with this LICENSES.txt file
+includes or is provided with certain third-party components that
+are subject to separate terms and conditions specified by
+applicable third-party licenses (“Third-Party Components”).
+These Third-Party Components and applicable licenses are set
+forth in this LICENSES.txt file.
+
+Your access and use of all Third-Party Components are at all times
+governed by the applicable third-party licenses.
+
+
+Semtech Corporation
+-------------------
+
+The Clear BSD License
+Copyright Semtech Corporation 2022. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted (subject to the limitations in the disclaimer
+below) provided that the following conditions are met:
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+    * Neither the name of the Semtech corporation nor the
+      names of its contributors may be used to endorse or promote products
+      derived from this software without specific prior written permission.
+
+NO EXPRESS OR IMPLIED LICENSES TO ANY PARTY'S PATENT RIGHTS ARE GRANTED BY
+THIS LICENSE. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
+CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT
+NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SEMTECH CORPORATION BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.
+
+
+STMicroelectronics (STM32L4 HAL)
+------------------------------------------
+
+This software component is licensed by ST under BSD 3-Clause license,
+the "License"; You may not use this file except in compliance with the
+License. You may obtain a copy of the License at:
+                       opensource.org/licenses/BSD-3-Clause
+
+
+STMicroelectronics (CMSIS Device)
+------------------------------
+
+This software component is licensed by ST under Apache License, Version 2.0,
+the "License"; You may not use this file except in compliance with the
+License. You may obtain a copy of the License at:
+                       opensource.org/licenses/Apache-2.0
+
+
+Arm Limited (CMSIS)
+-------------------
+
+Licensed under the Apache License, Version 2.0 (the License); you may
+not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an AS IS BASIS, WITHOUT
+WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+AES - Issue: 09/09/2006
+-----------------------
+
+Copyright (c) 1998-2008, Brian Gladman, Worcester, UK. All rights reserved.
+
+LICENSE TERMS
+
+The redistribution and use of this software (with or without changes)
+is allowed without the payment of fees or royalties provided that:
+
+ 1. source code distributions include the above copyright notice, this
+    list of conditions and the following disclaimer;
+
+ 2. binary distributions include the above copyright notice, this list
+    of conditions and the following disclaimer in their documentation;
+
+ 3. the name of the copyright holder is not used to endorse products
+    built using this software without specific written permission.
+
+DISCLAIMER
+
+This software is provided 'as is' with no explicit or implied warranties
+in respect of its properties, including, but not limited to, correctness
+and/or fitness for purpose.
+
+
+CMAC
+----
+
+Copyright (C) 2009 Lander Casado, Philippas Tsigas
+
+All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files
+(the "Software"), to deal with the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+Redistributions of source code must retain the above copyright notice,
+this list of conditions and the following disclaimers. Redistributions in
+binary form must reproduce the above copyright notice, this list of
+conditions and the following disclaimers in the documentation and/or
+other materials provided with the distribution.
+
+In no event shall the authors or copyright holders be liable for any special,
+incidental, indirect or consequential damages of any kind, or any damages
+whatsoever resulting from loss of use, data or profits, whether or not
+advised of the possibility of damage, and on any theory of liability,
+arising out of or in connection with the use or performance of this software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS WITH THE SOFTWARE

Makefile

@@ -20,16 +20,6 @@ PERF_TEST=no
 # Crypto management
 CRYPTO ?= SOFT
 
-# For LR1110 tranceiver
-# - CHINA_DEMO -> Use Regional Parameters 1.0
-# - HYBRID_CHINA -> RP 1.0, single channel
-CHINA_DEMO ?= no
-HYBRID_CHINA ?= no
-
-ifeq ($(HYBRID_CHINA),yes)
-CHINA_DEMO = yes
-endif
-
 # Compile with coverage analysis support
 COVERAGE ?= no
 
@@ -47,22 +37,26 @@ RADIO ?= nc
 
 # Trace prints
 MODEM_TRACE ?= yes
+MODEM_DEEP_TRACE ?= no
 
 # GNSS
 USE_GNSS ?= yes
 
+# TB bypass
+BYPASS_JOIN_DUTY_CYCLE?= no
 
+# Middleware advanced access
+MIDDLEWARE?= no
 
-ifeq ($(MODEM_APP),EXAMPLE_LR1110_DEMO)
-override USE_GNSS = yes
+ifeq ($(MODEM_APP),HW_MODEM)
+override BYPASS_JOIN_DUTY_CYCLE = yes
 endif
 
-
 #-----------------------------------------------------------------------------
 # default action: print help
 #-----------------------------------------------------------------------------
 help:
-	$(call echo_help_b, "Available TARGETs:	sx128x	lr1110	sx1261	sx1262")
+	$(call echo_help_b, "Available TARGETs:	sx128x	lr1110	lr1120	sx1261	sx1262")
 	$(call echo_help, "")
 	$(call echo_help_b, "-------------------------------- Clean -------------------------------------")
 	$(call echo_help, " * make clean_<TARGET>             : clean basic_modem for a given target")
@@ -84,15 +78,17 @@ help:
 	$(call echo_help, " *                                  - KR_920")
 	$(call echo_help, " *                                  - RU_864")
 	$(call echo_help, " *                                  - US_915")
+	$(call echo_help, " *                                  - WW_2G4 (to be used only for lr1120 and sx128x targets)")
+	$(call echo_help, " * RP_VERSION=xxx                  : choose wich regional paramerter version should be compiled (default: RP2_101) ")
+	$(call echo_help, " *                                  - RP2_101")
+	$(call echo_help, " *                                  - RP2_103 (LR-FHSS support)")
 	$(call echo_help, " * CRYPTO=xxx                      : choose which crypto should be compiled (default: SOFT)")
 	$(call echo_help, " *                                  - SOFT")
-	$(call echo_help, " *                                  - LR1110 (only for lr1110 target)")
-	$(call echo_help, " *                                  - LR1110_WITH_CREDENTIALS (only for lr1110 target)")
+	$(call echo_help, " *                                  - LR11XX (only for lr1110 and lr1120 targets)")
+	$(call echo_help, " *                                  - LR11XX_WITH_CREDENTIALS (only for lr1110 and lr1120 targets)")
 	$(call echo_help, " * MODEM_TRACE=yes/no              : choose to enable or disable modem trace print (default: trace is ON)")
-	$(call echo_help, " * HYBRID_CHINA=yes                : only for lr1110 target: build hybrid china with monochannel region")
-	$(call echo_help, " * CHINA_DEMO=yes                  : only for lr1110 target: build with full China RP_1_0 region")
-	$(call echo_help, " * USE_GNSS=yes/no                 : only for lr1110 target: choose to enable or disable use of gnss (default: gnss is ON)")
-	$(call echo_help, " * BYPASS=yes                      : build target using lorawan bypass")
+	$(call echo_help, " * USE_GNSS=yes/no                 : only for lr1110 and lr1120 targets: choose to enable or disable use of gnss (default: gnss is ON)")
+	$(call echo_help, " * MIDDLEWARE=yes                  : build target for middleware advanced access")
 	$(call echo_help_b, "-------------------- Optional makefile parameters --------------------------")
 	$(call echo_help, " * MULTITHREAD=no                  : Disable multithreaded build")
 	$(call echo_help, " * COVERAGE=xxx                    : build target with coverage instrumentation for specific subsystems:")
@@ -107,7 +103,11 @@ help:
 # Makefile include selection
 #-----------------------------------------------------------------------------
 ifeq ($(RADIO),lr1110)
--include makefiles/lr1110.mk
+-include makefiles/lr11xx.mk
+endif
+
+ifeq ($(RADIO),lr1120)
+-include makefiles/lr11xx.mk
 endif
 
 ifeq ($(RADIO),sx1261)
@@ -129,7 +129,7 @@ endif
 .PHONY: FORCE
 FORCE:
 
-all: basic_modem_sx128x basic_modem_lr1110 basic_modem_sx1261 basic_modem_sx1262
+all: basic_modem_sx128x basic_modem_lr1110 basic_modem_lr1120 basic_modem_sx1261 basic_modem_sx1262
 
 #-----------------------------------------------------------------------------
 # Clean
@@ -143,6 +143,9 @@ clean_sx128x:
 clean_lr1110:
 	$(MAKE) clean_target RADIO=lr1110
 
+clean_lr1120:
+	$(MAKE) clean_target RADIO=lr1120
+
 clean_sx1261:
 	$(MAKE) clean_target RADIO=sx1261
 
@@ -158,6 +161,9 @@ basic_modem_sx128x:
 basic_modem_lr1110:
 	$(MAKE) basic_modem RADIO=lr1110 $(MTHREAD_FLAG)
 
+basic_modem_lr1120:
+	$(MAKE) basic_modem RADIO=lr1120 $(MTHREAD_FLAG)
+
 basic_modem_sx1261:
 	$(MAKE) basic_modem RADIO=sx1261 $(MTHREAD_FLAG)
 

README.md

@@ -10,16 +10,27 @@ The LoRaWAN version that is currently implemented in LoRa Basics Modem is v1.0.4
 
 LoRa Basics Modem supports the following LoRaWAN regions:
 
-* EU868
-* US915
-* CN470_RP_1_0
+* AS_923 (AS923-1, AS923-2, AS923-3)
+* AU_915
+* CN_470
+* CN_470_RP_1_0
+* EU_868
+* IN_865
+* KR_920
+* RU_864
+* US_915
+
+### LoRaWAN regional parameters
+
+Default regional parameters version supported by LoRa Basics Modem is rp2-1.0.1. It is possible to switch to rp2-1.0.3 at compile time.
 
 ### LoRaWAN class
 
 LoRa Basics Modem supports the following LoRaWAN classes:
 
 * Class A
-* Class C
+* Class B (with up to 4 multicast sessions)
+* Class C (with up to 4 multicast sessions)
 
 ## LoRa Basics Modem services
 
@@ -49,10 +60,21 @@ The Hardware Abstraction Layer of LoRa Basics Modem is defined in the `smtc_mode
 LoRa Basics Modem supports the following transceivers:
 
 * LR1110 with firmware 0x0307.
+* SX1261
+* SX1262
+
+## Known Limitations
+
+* [LFU] In case LoRa Basics Modem is acting in US915 region with datarate DR0, files smaller than 13 bytes are not properly sent and cannot be econstructed on LoRa Cloud side
+* [LFU] LoRa Basics Modem does not reject files with a size between 8181 and 8192 bytes while they cannot be sent properly
+* [charge] Values returned by `smtc_modem_get_charge()` for regions CN470 and CN470_RP1 are not accurate
+* [charge] Values returned by `smtc_modem_get_charge()` for the LR-FHSS based datarate are not accurate
+* [LBT] On LR1110 target, sometimes the LBT pre-hook can be outdated and aborted which leads to no uplink issued (this is due to a radio reset called before starting LBT operation which adds the LR1110 boot delay before any LBT actions) - as workaround, the call to `ral_init()` can be removed from `smtc_modem_core/lr1mac/src/services/smtc_lbt.c`
+* [ADR] When a MAC command `link_adr_req` with a new channel mask is received, it is rejected if the custom datarate profile is enabled and configured with the highest datarate of the corresponding region - as a workaround, make sure there is at least one datarate different from the highest possible one in the custom ADR list
 
 ## Disclaimer
 
-This software has been extensively tested when targeting LR1110 for the EU868, US915, and CN470_RP_1_0 LoRaWAN regions. For all other combinations of features this software shall be considered an Engineering Sample.
+This software has been extensively tested when targeting LR1110 / SX1261 / SX1262 for LoRaWAN regions mentioned in [this paragraph](#lorawan-region). For all other combinations of features this software shall be considered an Engineering Sample.
 
 All customers wanting to leverage LoRa Basics Modem for 2.4GHz running with SX1280 transceiver must still refer to the [release v1.0.1](https://github.com/lorabasics/lorabasicsmodem/releases/tag/v1.0.1) for which Semtech provides technical customer support.
 

lora_basics_modem_version.h

@@ -55,9 +55,9 @@ extern "C" {
  * -----------------------------------------------------------------------------
  * --- PUBLIC TYPES ------------------------------------------------------------
  */
-#define LORA_BASICS_MODEM_FW_VERSION_MAJOR 2
+#define LORA_BASICS_MODEM_FW_VERSION_MAJOR 3
 #define LORA_BASICS_MODEM_FW_VERSION_MINOR 1
-#define LORA_BASICS_MODEM_FW_VERSION_PATCH 0
+#define LORA_BASICS_MODEM_FW_VERSION_PATCH 7
 
 /*
  * -----------------------------------------------------------------------------