Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/lora-net/swdr001

Driver for LR11xx chip (LR1110 / LR1120 / LR1121)
https://github.com/lora-net/swdr001

fsk gnss-scanning lora lr-fhss lr1110 lr1120 lr1121 wifi-scanning

Last synced: about 2 months ago
JSON representation

Driver for LR11xx chip (LR1110 / LR1120 / LR1121)

Awesome Lists containing this project

README 

        
# 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 (LR1110/LR1120 only)

- GNSS Scan Scanning (LR1110/LR1120 only)

- Crypto engine

- RTToF (Ranging) (LR1110/LR1120 only)



### 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.



This also exposes features for Sigfox. Bluetooth®-Low-Energy-Beaconing-Compatibility is also provided in this component for LR1110/LR1120.



### LR-FHSS



This component provides LR-FHSS related functions.



### 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.



### RTToF (Ranging)



This component is used to configure and operate the device's LoRa Round-Trip Time of Flight (RTToF) feature.



## 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: systematic call by the driver



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: user-handled call



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.



### Mixer configuration



#### Description



The following firmware versions are affected:



- LR1120 firmware 0x0101



When the chip ends a reception in the 2.4 GHz band, a parameter is not reconfigured properly. This misconfiguration will prevent a subsequent GNSS scan from working properly.



It is important to note that if the chip enters one of the following state between the reception in the 2.4GHz band and the GNSS scan, the parameter is properly reconfigured and the limitation does not appear:



- sleep mode (with or without retention)

- Wi-Fi scan

- Reception in the sub-GHz band



### Workaround



The workaround is to set the bit 4 in the register `0x00F30024` when the chip ends a reception in the 2.4GHz band before launching a GNSS scan.



This workaround is not needed when using any LR1110 firmware version. Nevertheless, it does not prevent a LR1110 from working properly if the workaround is not deactivated.



#### Implementation 1: systematic call by the driver



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 GNSS scan mode:



- `lr11xx_gnss_scan`



This implementation can be disabled by defining the macro `LR11XX_DISABLE_MIXER_CFG_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: user-handled call



The second method requires the user to explicitly call the function `lr11xx_gnss_apply_mixer_cfg_workaround` when the chip ends a reception in the 2.4GHz if a GNSS scan is planned after, without going through one of the states specified in the description of this limitation.



This method requires the macro `LR11XX_DISABLE_MIXER_CFG_WORKAROUND` to be defined so the implementation 1 of the workaround (enabled by default) is disabled.