Release v1.1.0

Author: smtc-bot

CHANGELOG.md

@@ -4,6 +4,12 @@ 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).
 
+## [v1.1.0] - 2025-10-15
+
+### Added
+
+- The toolchain supports building with compile-time parameters given on command-line
+
 ## [v1.0.0] - 2024-09-19
 
 First release

Inc/apps/apps_utilities.h

@@ -78,6 +78,14 @@ extern "C" {
  */
 void print_hex_buffer( const uint8_t* buffer, uint8_t size );
 
+/**
+ * @brief Prints the provided buffer as ASCII characters
+ *
+ * @param [in] buffer Buffer to be printed
+ * @param [in] size Buffer size to be printed
+ */
+void print_ascii_buffer( const uint8_t* buffer, uint16_t size );
+
 /**
  * @brief Prints the LoRaWAN keys
  *

Inc/apps/common_app_configuration.h

@@ -0,0 +1,116 @@
+/**
+ * @file      common_app_configuration.h
+ *
+ * @brief     App configuration common to all apps
+ *
+ * The Clear BSD License
+ * Copyright Semtech Corporation 2024. 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.
+ */
+
+#ifndef COMMON_APP_CONFIGURATION_H
+#define COMMON_APP_CONFIGURATION_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*
+ * -----------------------------------------------------------------------------
+ * --- DEPENDENCIES ------------------------------------------------------------
+ */
+
+/*
+ * -----------------------------------------------------------------------------
+ * --- PUBLIC MACROS -----------------------------------------------------------
+ */
+
+/**
+ * @brief Watchdog counter reload value during sleep (The period must be lower than MCU watchdog period (here 20s))
+ */
+#ifndef WATCHDOG_RELOAD_PERIOD_MS
+#define WATCHDOG_RELOAD_PERIOD_MS 20000
+#endif  // WATCHDOG_RELOAD_PERIOD_MS
+
+/*!
+ * @brief User application data buffer size
+ */
+#ifndef LORAWAN_APP_DATA_MAX_SIZE
+#define LORAWAN_APP_DATA_MAX_SIZE 242
+#endif  // LORAWAN_APP_DATA_MAX_SIZE
+
+/*!
+ * @brief LoRaWAN regulatory region.
+ * One of:
+ * LR1121_LORAWAN_REGION_AS923_GRP1
+ * LR1121_LORAWAN_REGION_AS923_GRP2
+ * LR1121_LORAWAN_REGION_AS923_GRP3
+ * LR1121_LORAWAN_REGION_AS923_GRP4
+ * LR1121_LORAWAN_REGION_AU915
+ * LR1121_LORAWAN_REGION_CN470
+ * LR1121_LORAWAN_REGION_EU868
+ * LR1121_LORAWAN_REGION_IN865
+ * LR1121_LORAWAN_REGION_KR920
+ * LR1121_LORAWAN_REGION_RU864
+ * LR1121_LORAWAN_REGION_US915
+ */
+#ifndef LORAWAN_REGION_USED
+#define LORAWAN_REGION_USED LR1121_LORAWAN_REGION_EU868
+#endif  // LORAWAN_REGION_USED
+
+/**
+ * @brief Periodical uplink alarm delay in seconds
+ */
+#ifndef PERIODICAL_UPLINK_DELAY_S
+#define PERIODICAL_UPLINK_DELAY_S 30
+#endif  // PERIODICAL_UPLINK_DELAY_S
+
+
+
+
+/*
+ * -----------------------------------------------------------------------------
+ * --- PUBLIC CONSTANTS --------------------------------------------------------
+ */
+
+/*
+ * -----------------------------------------------------------------------------
+ * --- PUBLIC TYPES ------------------------------------------------------------
+ */
+
+/*
+ * -----------------------------------------------------------------------------
+ * --- PUBLIC FUNCTIONS PROTOTYPES ---------------------------------------------
+ */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif  // COMMON_APP_CONFIGURATION_H
+
+/* --- EOF ------------------------------------------------------------------ */

Inc/apps/lorawan_commissioning/lorawan_commissioning.h

@@ -58,7 +58,9 @@ extern "C" {
  * @brief Use internal credential
  * @remark By setting true the credentials defined in this document will not be used
  */
+#ifndef USE_LR11XX_CREDENTIALS
 #define USE_LR11XX_CREDENTIALS false
+#endif  // USE_LR11XX_CREDENTIALS
 
 /**
  * @brief IEEE Organizationally Unique Identifier ( OUI ) (big endian)
@@ -72,37 +74,46 @@ extern "C" {
  * @remark In this application the value is automatically generated by calling
  *         lr1110_modem_get_dev_eui function
  */
+
+#ifndef LORAWAN_DEVICE_EUI
 #define LORAWAN_DEVICE_EUI                     \
     {                                          \
         IEEE_OUI, 0x00, 0x00, 0x00, 0x00, 0x12 \
     }
+#endif  // LORAWAN_DEVICE_EUI
 #define LORAWAN_DEVICE_EUI_LEN 8
 
 /**
  * @brief App/Join server IEEE EUI (big endian)
  */
+#ifndef LORAWAN_JOIN_EUI
 #define LORAWAN_JOIN_EUI                               \
     {                                                  \
         0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x34 \
     }
+#endif  // LORAWAN_JOIN_EUI
 #define LORAWAN_JOIN_EUI_LEN 8
 
 /**
  * @brief loRaWAN Network Key (big endian)
  */
+#ifndef LORAWAN_NWK_KEY
 #define LORAWAN_NWK_KEY                                                                                \
     {                                                                                                  \
         0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x56 \
     }
+#endif  // LORAWAN_NWK_KEY
 #define LORAWAN_NWK_KEY_LEN 16
 
 /**
  * @brief loRaWAN Application Key (big endian)
  */
+#ifndef LORAWAN_APP_KEY
 #define LORAWAN_APP_KEY                                                                                \
     {                                                                                                  \
         0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x78 \
     }
+#endif  // LORAWAN_APP_KEY
 #define LORAWAN_APP_KEY_LEN 16
 
 /*

Inc/boards/board-config.h

@@ -44,6 +44,8 @@ extern "C" {
  * --- DEPENDENCIES ------------------------------------------------------------
  */
 
+#include "lr1121_modem_system_types.h"
+
 /*
  * -----------------------------------------------------------------------------
  * --- PUBLIC MACROS -----------------------------------------------------------
@@ -54,10 +56,44 @@ extern "C" {
  * --- PUBLIC CONSTANTS --------------------------------------------------------
  */
 
+/*
+ * -----------------------------------------------------------------------------
+ * --- TCXO CONFIGURATION ------------------------------------------------------
+ */
+
+/**
+ * @brief Indicates whether the board includes a TCXO (Temperature Compensated Crystal Oscillator).
+ * 
+ * Define this macro to 1 if the board has a TCXO connected and requires IO initialization.
+ * Defaults to 0 (no TCXO) if not defined elsewhere.
+ */
+#ifndef TCXO_ON_BOARD
+#define TCXO_ON_BOARD 0
+#endif
+
+/**
+ * @brief Defines the supply voltage for the TCXO.
+ * 
+ * Available values:
+ * - LR1121_MODEM_SYSTEM_TCXO_CTRL_1_6V (0x00) - Supply voltage = 1.6V
+ * - LR1121_MODEM_SYSTEM_TCXO_CTRL_1_7V (0x01) - Supply voltage = 1.7V
+ * - LR1121_MODEM_SYSTEM_TCXO_CTRL_1_8V (0x02) - Supply voltage = 1.8V
+ * - LR1121_MODEM_SYSTEM_TCXO_CTRL_2_2V (0x03) - Supply voltage = 2.2V
+ * - LR1121_MODEM_SYSTEM_TCXO_CTRL_2_4V (0x04) - Supply voltage = 2.4V
+ * - LR1121_MODEM_SYSTEM_TCXO_CTRL_2_7V (0x05) - Supply voltage = 2.7V
+ * - LR1121_MODEM_SYSTEM_TCXO_CTRL_3_0V (0x06) - Supply voltage = 3.0V
+ * - LR1121_MODEM_SYSTEM_TCXO_CTRL_3_3V (0x07) - Supply voltage = 3.3V
+ */
+#ifndef BOARD_TCXO_SUPPLY_VOLTAGE
+#define BOARD_TCXO_SUPPLY_VOLTAGE LR1121_MODEM_SYSTEM_TCXO_CTRL_1_8V
+#endif
+
 /**
  * @brief Defines the time required for the TCXO to wakeup [ms].
  */
-#define BOARD_TCXO_WAKEUP_TIME 5
+#ifndef BOARD_TCXO_WAKEUP_TIME
+#define BOARD_TCXO_WAKEUP_TIME 8
+#endif
 
 /**
  * @brief Board MCU pins definitions

README.md

@@ -2,7 +2,9 @@
 
 ## 1. Description
 
-The LR1121 modem application example project contains several simple examples highlighting LoRa Basic Modem-E features.
+The LR1121 modem application example project contains several simple examples highlighting LoRa Basic Modem-E features.  
+This version of the examples supports LoRa Basics™ Modem-E **v2.0.2**.
+
 
 ### 1.1. Simple LoRaWAN Class A application
 
@@ -41,18 +43,48 @@ The example applications are designed to run with the LR1121 Evaluation Kit hard
 * NUCLEO-L476RG development board
 * LR1121 shield
 
+This project supports both versions of the LR1121 shield **with TCXO or without TCXO**
+
+### 2.1. TCXO Configuration
+
+To enable support for TCXO-based shields, you must modify the TCXO configuration macros in the [board-config.h](Inc/boards/board-config.h) file:
+
+**Basic TCXO Enable/Disable:**
+- Set `TCXO_ON_BOARD` to `1` if your shield includes a TCXO, or leave it as `0` (default) for non-TCXO boards.
+
+**Advanced TCXO Parameters (configurable when `TCXO_ON_BOARD = 1`):**
+- `BOARD_TCXO_SUPPLY_VOLTAGE`: Configure the TCXO supply voltage. Available options:
+  - `LR1121_MODEM_SYSTEM_TCXO_CTRL_1_6V` (1.6V)
+  - `LR1121_MODEM_SYSTEM_TCXO_CTRL_1_7V` (1.7V)
+  - `LR1121_MODEM_SYSTEM_TCXO_CTRL_1_8V` (1.8V) - **Default**
+  - `LR1121_MODEM_SYSTEM_TCXO_CTRL_2_2V` (2.2V)
+  - `LR1121_MODEM_SYSTEM_TCXO_CTRL_2_4V` (2.4V)
+  - `LR1121_MODEM_SYSTEM_TCXO_CTRL_2_7V` (2.7V)
+  - `LR1121_MODEM_SYSTEM_TCXO_CTRL_3_0V` (3.0V)
+  - `LR1121_MODEM_SYSTEM_TCXO_CTRL_3_3V` (3.3V)
+
+- `BOARD_TCXO_WAKEUP_TIME`: Configure the TCXO wakeup time in milliseconds (default: 8ms)
+
+**Example configuration for a 3.3V TCXO with 10ms wakeup time:**
+```c
+#define TCXO_ON_BOARD 1
+#define BOARD_TCXO_SUPPLY_VOLTAGE LR1121_MODEM_SYSTEM_TCXO_CTRL_3_3V
+#define BOARD_TCXO_WAKEUP_TIME 10
+```
+
 ## 3. Usage
 
 Connect the NUCLEO board to a host PC via a USB cable. The USB connection will provide power for the LR1121 Evaluation Kit as well as serve as a serial communication link for the example application.
 
 Use a terminal application configured with the following settings:
+
 - Speed: 921600 baud
 - Data bits: 8s
 - Stop bits: 1
 - Parity: None
 
 Applications use the serial link to display information messages.  
-Modem keys are defined in [lorawan_comissioning.h](Inc/apps/lorawan_commissioning/lorawan_commissioning.h).  
+Modem keys are defined in [lorawan_commissioning.h](Inc/apps/lorawan_commissioning/lorawan_commissioning.h).
 To use the LR1121 modem production keys, update the USE_LR11XX_CREDENTIALS definition
 
 ## 4. Build & Install
@@ -61,13 +93,49 @@ To build the example application for the STM32L476RG controller of the NUCLEO de
 
 To build the example applications with the GNU Arm Embedded Toolchain:
 
-
 1. Run `make` from the `gcc` directory with the target application name as an argument:
 
 ```
 $ make APP=lorawan
 ```
 
+It is possible to provide additional compile-time definition through usage of `EXTRAFLAGS` make argument as follows:
+
+```
+$ make APP=lorawan EXTRAFLAGS='-D<TOKEN>=<VALUE>'
+```
+
+Where `<TOKEN>` is a macro name to configure with `<VALUE>`, for instance:
+
+```bash
+$ make APP=lorawan EXTRAFLAGS='-DLORAWAN_REGION_USED=LR1121_LORAWAN_REGION_EU868'
+```
+
+**Example: Building with TCXO configuration:**
+```bash
+$ make APP=lorawan EXTRAFLAGS='-DTCXO_ON_BOARD=1 -DBOARD_TCXO_SUPPLY_VOLTAGE=LR1121_MODEM_SYSTEM_TCXO_CTRL_3_3V -DBOARD_TCXO_WAKEUP_TIME=10'
+```
+
+Here is the list of configurable tokens:
+
+**Application Configuration:**
+* `WATCHDOG_RELOAD_PERIOD_MS`
+* `LORAWAN_APP_DATA_MAX_SIZE`
+* `LORAWAN_REGION_USED`
+* `PERIODICAL_UPLINK_DELAY_S`
+
+**LoRaWAN Credentials:**
+* `USE_LR11XX_CREDENTIALS`
+* `LORAWAN_DEVICE_EUI`
+* `LORAWAN_JOIN_EUI`
+* `LORAWAN_NWK_KEY`
+* `LORAWAN_APP_KEY`
+
+**TCXO Configuration:**
+* `TCXO_ON_BOARD` (set to 1 to enable TCXO support)
+* `BOARD_TCXO_SUPPLY_VOLTAGE` (e.g., `LR1121_MODEM_SYSTEM_TCXO_CTRL_3_3V`)
+* `BOARD_TCXO_WAKEUP_TIME` (wakeup time in milliseconds)
+
 Note: The supported application names are `lorawan`, `certification`, `class_b`, `multicast` and `fuota`.
 
 2. The application binary file, for example `lorawan.bin`, is created in the `gcc/build` directory.