Release v2.1.0

CHANGELOG.md

@@ -0,0 +1,29 @@
+# LR11xx driver 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).
+
+## [v2.1.0] 2022-03-28
+
+### Added
+
+* [radio] `lr11xx_radio_apply_high_acp_workaround()` function
+* [radio] `lr11xx_radio_set_rssi_calibration()` function
+* [radio] `LR11XX_RADIO_LORA_BW_200`, `LR11XX_RADIO_LORA_BW_400` and `LR11XX_RADIO_LORA_BW_800` entries to `lr11xx_radio_lora_bw_t`
+* [radio] `LR11XX_RADIO_GFSK_PKT_VAR_LEN_SX128X_COMP` entry in `lr11xx_radio_gfsk_pkt_len_modes_t` to support compatibility with SX128x
+* [radio] `LR11XX_RADIO_GFSK_DC_FREE_WHITENING_SX128X_COMP` entry in `lr11xx_radio_gfsk_dc_free_t` to support compatibility with SX128x
+* [GNSS] `lr1110_gnss_get_consumption` function
+* [Wi-Fi] `lr1110_wifi_get_consumption` function
+* [Wi-Fi] `lr11xx_wifi_are_scan_mode_result_format_compatible` function
+
+### Changed
+
+* [radio] Call to `lr11xx_radio_apply_high_acp_workaround()` in `lr11xx_radio_set_tx_with_timeout_in_rtc_step()`, `lr11xx_radio_set_rx_with_timeout_in_rtc_step()`, `lr11xx_radio_set_cad()` and `lr11xx_radio_set_tx_infinite_preamble()` (can be removed by defining `LR11XX_DISABLE_HIGH_ACP_WORKAROUND`)
+* [Wi-Fi] Define type `lr11xx_wifi_country_code_str_t` for Wi-Fi country code data and update `lr11xx_wifi_extended_full_result_t` and `lr11xx_wifi_country_code_t` to use it.
+
+## [v1.0.0] Unreleased
+
+### Added
+
+* [all] Initial version - based on LR1110 driver v7.0.0

LICENSE.txt

@@ -0,0 +1,30 @@
+License for the code produced by Semtech contained in this project
+------------------------------------------------------------------
+
+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.

README.md

@@ -0,0 +1,101 @@
+# LR11xx driver
+
+This package proposes an implementation in C of the driver for **LR11XX** radio component.
+
+## Components
+
+The driver is split in several components:
+
+- Bootloader
+- Register / memory access
+- System configuration
+- Radio
+- Wi-Fi Passive Scanning
+- GNSS Scan Scanning
+- Crypto engine
+
+### Bootloader
+
+This component is used to update the firmware.
+
+### Register / memory access
+
+This component is used to read / write data from registers or internal memory.
+
+### System configuration
+
+This component is used to interact with system-wide parameters like clock sources, integrated RF switches, etc.
+
+### Radio
+
+This component is used to send / receive data through the different modems (LoRa and GFSK) or perform a LoRa CAD (Channel Activity Detection). Parameters like power amplifier selection, output power and fallback modes are also accessible through this component.
+
+### Wi-Fi Passive Scanning
+
+This component is used to configure and initiate the passive scanning of the Wi-Fi signals that can be shared to request a geolocation.
+
+### GNSS Scanning
+
+This component is used to configure and initiate the acquisition of GNSS signals that can be shared to request a geolocation.
+
+### Crypto engine
+
+This component is used to set and derive keys in the internal keychain and perform cryptographic operations with the integrated hardware accelerator.
+
+## Structure
+
+Each component is based on different files:
+
+- lr11xx_component.c: implementation of the functions related to component
+- lr11xx_component.h: declarations of the functions related to component
+- lr11xx_component_types.h: type definitions related to components
+
+## HAL
+
+The HAL (Hardware Abstraction Layer) is a collection of functions that the user shall implement to write platform-dependent calls to the host. The list of functions is the following:
+
+- lr11xx_hal_reset()
+- lr11xx_hal_wakeup()
+- lr11xx_hal_write()
+- lr11xx_hal_read()
+- lr11xx_hal_direct_read()
+
+## LR11xx firmware known limitations
+
+### High ACP (Adjacent Channel Power)
+
+#### Description
+
+When the chip wakes up from sleep mode with retention, a parameter is not reconfigured properly. This misconfiguration can lead to an unexpectedly high adjacent channel power in all subsequent transmissions.
+
+The issue appears only in LoRa modulation, for all bandwidths except for 500kHz and 800kHz.
+
+The following firmware versions are affected:
+
+- LR1110 firmware from 0x0303 to 0x0307
+- LR1120 firmware 0x0101
+
+### Workaround
+
+The workaround is to reset the bit 30 in the register `0x00F30054` when the chip wakes up from sleep mode with retention.
+
+This workaround does not solve the case where `LR11XX_RADIO_MODE_SLEEP` is configured with `lr11xx_radio_auto_tx_rx` and the chip is set to Rx mode. This is dues to the fact that the workaround cannot be applied before the subsequent transmission, automatically launched by the chip after waking up from sleep mode with retention.
+
+#### Implementation 1
+
+The first implementation - enabled by default in the driver - adds an implicit call updating the parameter to each function that could set the chip in transmission - directly or not -:
+
+- `lr11xx_radio_set_tx_with_timeout_in_rtc_step`
+- `lr11xx_radio_set_tx_infinite_preamble`
+- `lr11xx_radio_set_rx_with_timeout_in_rtc_step` - in case `lr11xx_radio_auto_tx_rx` has been enabled
+- `lr11xx_radio_set_cad` - in case `LR11XX_RADIO_CAD_EXIT_MODE_TX` has been set with `lr11xx_radio_set_cad_params`
+
+This implementation can be disabled by defining the macro `LR11XX_DISABLE_HIGH_ACP_WORKAROUND`. This disabling will be useful when, in the future, a new firmware integrating a fix is released and does not require the workaround anymore.
+
+The main advantage of this implementation is that it is transparent to the user who only needs to update the driver without changing its application. The main drawback is that the implicit call is done systematically even when not required.
+
+#### Implementation 2
+
+The second method requires the user to explicitly call the function `lr11xx_radio_apply_high_acp_workaround` when the chip wakes up from sleep mode with retention (note: to ease the implementation, it can be called when the chip wakes up from any sleep mode).
+
+This method requires the macro `LR11XX_DISABLE_HIGH_ACP_WORKAROUND` to be defined so the implementation 1 of the workaround (enabled by default) is disabled.

src/CMakeLists.txt

@@ -0,0 +1,43 @@
+# @file
+#
+# @brief Sets CMake target_sources and target_include_directories
+#
+# --- The Clear BSD License ---
+# Copyright Semtech Corporation 2021. 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.
+
+include(lr11xx_driver_module.cmake)
+
+target_sources(${LR11XX_DRIVER_MODULE_TARGET}
+  PRIVATE
+  ${LR11XX_DRIVER_MODULE_C_SOURCES}
+)
+
+target_include_directories(${LR11XX_DRIVER_MODULE_TARGET}
+  PUBLIC
+  ${LR11XX_DRIVER_MODULE_C_INCLUDES}
+)