Release v2.0.0

Author: Matthieu Antoine

CHANGELOG.md

@@ -5,6 +5,15 @@ 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).
 
+## [2.0.0] - 2023-03-06
+
+### Added
+
+- SX126x support
+- LR1121 support
+- SMTC HAL MCU - simplified MCU hardware abstration layer to ease porting on another platform
+- Shield interface - library to get specificities related to each LR11xx / SX126x shield
+
 ## [1.0.0] - 2022-04-07
 
 ### Added

LICENSES.txt

@@ -43,7 +43,7 @@ License. You may obtain a copy of the License at:
 
 
 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

README.md

@@ -1,95 +1,34 @@
-# LR11xx SDK
+# SWSD003
 
-The LR11xx SDK contains several simple examples for LR11xx transceivers.
+This SDK contain several simple examples for SX126x and LR11XX chip families.
 
 ## Examples
 
-### Radio
+For a detailed description of the available examples and their configuration, refer to the corresponding README file depending on chip family:
 
-| Name                 | Description                                                     | Documentation                                 |
-| -------------------- | --------------------------------------------------------------- | --------------------------------------------- |
-| CAD                  | Perform a Channel Activity Detection (CAD) - LoRa only          | [README](apps/cad/README.md)                  |
-| PER                  | Perform a Packet Error Rate (PER) test - both Tx and Rx roles   | [README](apps/per/README.md)                  |
-| Ping pong            | Launch an exchange between two devices                          | [README](apps/ping-pong/README.md)            |
-| Sprectral scan       | Get inst-RSSI values in RX mode to form a heat map              | [README](apps/spectral_scan/README.md)        |
-| Spectrum display     | Get inst-RSSI values in RX mode to form a dyamic spectrum curve | [README](apps/spectrum_display/README.md)     |
-| Tx continuous wave   | Configure the chip to transmit a single tone                    | [README](apps/tx_cw/README.md)                |
-| Tx infinite preamble | Configure the chip to transmit an infinite preamble             | [README](apps/tx_infinite_preamble/README.md) |
+- **SX126X**: [SX126X readme](sx126x/README.md)
+- **LR11XX**: [LR11XX readme](lr11xx/README.md)
 
-A demonstration of the LR-FHSS capability of the chip can be found [here](https://github.com/Lora-net/SWDM001).
-
-### Geolocation
-
-| Name                   | Description                   | Documentation                 |
-| ---------------------- | ----------------------------- | ----------------------------- |
-| GNSS - Assisted scan   | Perform GNSS assisted scans   | [README](apps/gnss/README.md) |
-| GNSS - Autonomous scan | Perform GNSS autonomous scans | [README](apps/gnss/README.md) |
-| Wi-Fi passive scan     | Perform Wi-Fi passive scans   | [README](apps/wifi/README.md) |
-
-## Configuration
-
-Each example has its own set of parameters - see `apps/<example>/main_<example>.h`.
-
-There is also [a common configuration file](apps/common/apps_configuration.h) where parameters can be set, among which:
-
-* Packet type
-* RF frequency
-* Output power
-* Packet and modulation parameters for different modulations
-
-## Requirements
-
-### Supported boards
-
-This SDK is developed on the ST Microeletronic [NUCLEO-L476RG development board](https://www.st.com/en/evaluation-tools/nucleo-l476rg.html)
-
-### Supported shields
-
-The list of compatible Semtech LR1110 shields is:
-
-| Shield       | PCB                                                   | Frequency matching |
-| ------------ | ----------------------------------------------------- | ------------------ |
-| LR1110MB1DIS | PCB_E655V01A - GNSS with LNA for Passive GNSS Antenna | 868/915MHz         |
-| LR1110MB1DJS | PCB_E656V01A - GNSS without LNA                       | 868/915MHz         |
-| LR1110MB1GIS | PCB_E655V01A - GNSS with LNA for Passive GNSS Antenna | 490MHz             |
-| LR1110MB1GJS | PCB_E656V01A - GNSS without LNA                       | 490MHz             |
-
-The list of compatible Semtech LR1120 shields is:
-
-| Shield       | PCB                                                   | Frequency matching |
-| ------------ | ----------------------------------------------------- | ------------------ |
-| LR1120MB1DIS | PCB_E655V01A - GNSS with LNA for Passive GNSS Antenna | 868/915MHz         |
-| LR1120MB1DJS | PCB_E656V01A - GNSS without LNA                       | 868/915MHz         |
-| LR1120MB1GIS | PCB_E655V01A - GNSS with LNA for Passive GNSS Antenna | 490MHz             |
-| LR1120MB1GJS | PCB_E656V01A - GNSS without LNA                       | 490MHz             |
-
-### Firmware
-
-This SDK requires the transceiver to run the following version
-
-* LR1110: firmware version ([0x0307](https://github.com/Lora-net/radio_firmware_images/tree/master/lr1110/transceiver))
-* LR1120: firmware version ([0x0101](https://github.com/Lora-net/radio_firmware_images/tree/master/lr1120/transceiver))
-
-To update the transceiver with the desired firmware version, please use [the updater tool application](https://github.com/Lora-net/lr1110_updater_tool/).
-
-### Toolchain
-
-Each example can be compiled with the following toolchains:
-
-* [Keil MDK ARM](https://www2.keil.com/mdk5) - Keil project file available in `apps/<example>/MDK-ARM/`
-* [GNU Arm Embedded toolchain](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm) - makefile available in `apps/<example>/makefile/`
+The readme files also provide the compatible products, along with hardware and software requirements.
 
 ## Getting started
 
 ### Configure
 
 Before starting to build an example, check the parameters in both the common and the example-specific configuration files.
+The common parameters can be found in `<chip family>/common/apps_configuration.h` while the example specific configuration file is located in the example folder. For example, the `per` example finds its configuration in `<chip_family>/apps/per/main_per.h`
 
 ### Build
 
+In this section:
+- `<chip_family>` is:
+  - `sx126x` for SX126X examples
+  - `lr11xx` for LR11XX examples
+- `<example>`: is the name of the selected example. Refer to corresponding README file of the chip family for possible values
+
 #### Keil MDK ARM
 
-Each example is delivered with a Keil project file - see `apps/<example>/MDK-ARM/lr11xx-sdk_<example>.uvprojx`.
+Each example is delivered with a Keil project file - see `<chip_family>/apps/<example>/MDK-ARM/<chip_family>-sdk_<example>.uvprojx`.
 
 To build a project:
 
@@ -100,11 +39,13 @@ To build a project:
 
 Each project has different targets ([Keil manual](https://www.keil.com/support/man/docs/uv4/uv4_ca_projtargfilegr.htm)), each one allowing to choose the shield the example is compiled for.
 
-The name of the targets is taken from the column `shield` of the table available [here](#supported-shields).
+The name of the targets is taken from the column `shield` of the supported shields table available in the chip family READMEs:
+- for SX126X:  [here](sx126x/README.md#supported-shields)
+- for LR11XX:  [here](lr11xx/README.md#supported-shields)
 
 #### GNU Arm embedded toolchain
 
-Examples are built from their respective subfolder in the `apps` directory. For instance, the makefile for the `per` example is available in `apps/per/makefile/Makefile`.
+Examples are built from their respective subfolder in the `apps` directory. For instance, the makefile for the `per` example for LR11XX is available in `lr11xx/apps/per/makefile/Makefile`.
 
 Build settings, compile time and configuration options are specified in the project's Makefile.
 
@@ -115,17 +56,30 @@ Here are the parameters available at compile time:
 | Parameter    | Description                              | Default value |
 | ------------ | ---------------------------------------- | ------------- |
 | TARGET_BOARD | Board for which the example is compiled  | NUCLEO_L476RG |
-| RADIO_SHIELD | Shield for which the example is compiled | LR1120MB1DIS  |
+| RADIO_SHIELD | Shield for which the example is compiled | **lr11xx**: LR1120MB1DIS, **sx126x**: SX1262MB1CAS  |
 
-For instance, to build the project `per` with LR1110MB1GJS shield:
-
-To build a project, simply run make
+For instance, to build the project `per` with LR1110MB1GJS shield simply run make as follows
 
 ```shell
-$ cd $SDK_FOLDER/apps/per/makefile
+$ cd $SDK_FOLDER/lr11xx/apps/per/makefile
 $ make RADIO_SHIELD=LR1110MB1GJS
 ```
 
+##### Command line configuration
+
+Additional configuration flags can be passed from command line to compiler with `EXTRAFLAGS` argument.
+This is dedicated to define macros that can be defined like the following:
+
+```bash
+$ make EXTRAFLAGS='-D<MACRO>=<VALUE>'
+```
+
+Where `<MACRO>` is the macro name to set and `<VALUE>` is the value to set for this macro.
+Not all macro can be redefined through this way. Refer to the README of examples for the list of macro that can be redefined.
+
+Note that when using the configuration on command line, `make` cannot detect a change in configuration on next build.
+Therefore `make clean` must be invoked before calling a new `make` with a different configuration
+
 ### Load
 
 After a project is built, it can be loaded onto a device.
@@ -147,3 +101,22 @@ For instance, using stty on Linux with a device available in `/dev/ttyACM0`:
 ```shell
 $ stty -echo raw speed 921600 < /dev/ttyACM0 && cat /dev/ttyACM0
 ```
+
+## Requirements
+
+Additional requirements specific to chip family are provided in the corresponding README file.
+
+### Supported toolchains
+
+Each example can be compiled with the following toolchains:
+
+* [Keil MDK ARM](https://www2.keil.com/mdk5) - Keil project file available in `<chip_family>/apps/<example>/MDK-ARM/`
+* [GNU Arm Embedded toolchain](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm) - makefile available in `<chip_family>/apps/<example>/makefile/`
+
+## Known limitations
+
+### Channel Activity Detection accuracy
+
+The Channel Activity Detection (CAD) may expose false negative or false positive detection.
+The parameters for CAD configuration needs adaptation relative to context usage.
+Refer to the application notes available on [LoRa Developer Portal](https://lora-developers.semtech.com/documentation/product-documents/) and [Semtech website](https://www.semtech.com/) relative to CAD performances.