Flora

Software for the DPP2 LoRa Comboard (STM32L4 MCU + SX126x radio) based on the Dual Processor Platform (DPP) architecture developed by the Computer Engineering Group (TEC) at ETH Zurich.

Flora Software

The flora software consists of the following components:

• Flora Library: The flora-lib (C code) is a library of software components shared by multiple projects (flora apps). It contains radio drivers, protocol implementations, utilities, etc.
• Flora Apps: Projects based on the flora-lib. See list below for details.
• SX1262 Python Library: The sx1262 Python library implements a model of the SX1262 radio chip. For example it allows to calculate the time-on-air (ToA) for LoRa or FSK transmissions.

Flora Apps

NOTE: The Status information is indicative only and in no way provides any guarantees regarding the state of the software. All software must be considered experimental, since in most cases no exhaustive testing has been performed.

Clone, Compile, Run

1. Select one of the flora apps (see list above)
2. Clone project (including submodules):
   git clone --recursive <git url>
3. Open the project in the STM32CubeIDE: File > Open Projects from File System
4. Create auto-generated files with STM32CubeIDE
   1. In STM32CubeIDE, open the project's .ioc file by double clicking (this may take a moment)
   2. Generate the auto-generated code: Project > Generate Code
      (or click the "Device Configuration Tool Code Generation" (button with yellow cog wheel))
   3. Wait until the code generation has finished (check status in lower right corner of the IDE window!)
5. Make sure that all configuration parameters in the project's config file Inc/app_config.h are set according to your needs.
6. Compile the code by selecting:
   Project > Build Project
7. Flash the code by selecting (NOTE: this step requires a JLink debug probe connected to the sx126x (dpp2lora) comboard):
   Run > Debug

Run Tests on FlockLab 2

• Some of the flora apps provide scripts to run tests on the FlockLab 2 testbed.
  • Shell script: e.g. run_flocklab_test.sh
  • Python script (uses the flocklab-tools): e.g. run_flocklab_test.py

Software Development

STM32CubeIDE

• All projects are created and edited using the STM32CubeIDE (combination of former Atollic TrueStudio and STM32CubeMX)
  • Based on eclipse
  • Main config of IDE project is stored in .cproject file
  • Config of architecture (GPIOs etc.) are stored in .ioc file.

Coding Conventions

• Application configuration is stored in app_config.h (no further includes allowed in this file).
  • Source files should only include main.h, which itself includes app_config.h.
• Drivers and Middlewares: All files in the Middlewares and Drivers directory in the root of each flora app project must not be modified manually as they are auto-generated by STM32CubeIDE.
• User Code Sections: All files which include sections starting with USER CODE BEGIN and end with USER CODE END must only be modified inside these user code sections. The rest of the code is auto-generated by the STM32CubeIDE and will be overwritten once the settings in STM32CubeIDE are modified and the code is generated again.
• ioc File: The .ioc config file must be modified only by using the STM32CubeIDE software!

Platforms

• DEVKIT: Development Kit (Nucleo L476RG + SX126xDVK1xAS)
• COMBOARD: DPP2 LoRa communication board (e.g. used on FlockLab 2 testbed, together with the DPP2 DevBoard, or together with the BaseBoard)

Peripherals

• USART1: Serial communication over USB
• SysTick: FreeRTOS
• TIM1: SYS (HAL Delay)
• TIM2: System Time (incl. timing of radio)
• TIM15: (spare timer)
• TIM16: PWM of breathing status LED
• LPTIM1: Time-triggered wake-up from low-power mode
• SPI1: BOLT
• SPI2: SX1262 Radio

FreeRTOS Real-Time OS

• We use FreeRTOS provided by STM32CubeIDE
• FreeRTOS settings are configured in STM32CubeIDE in the .ioc file and by automatically generating the files inside STM32CubeIDE.
• FreeRTOS tasks are NOT created and managed by STM32CubeIDE in the .ioc file. They are manually created in the "USER CODE" sections inside the genrated files. Each task should live in its own .c file in the Src directory of the flora app.

Pin Mapping

NOTES:

• On FlockLab 2
  • Tracing pins INT2 and LED3 are shared with the SWD debug interface and can therefore not be used when forwarding the debug session.
  • Tracing pin LED2 is shared with the SWO pin and must be configured in SWO mode if data tracing is enabled.
  • Tracing pin LED1 is connected to the RFDIO1 pin of the SX1262 radio. As a consequence, PA15 must be configured as an input pin on FlockLab.
• Also see FlockLab 2 Pin Mapping

Radio Drivers & Protocol Layers

• Semtech Reference Implementation

Flora Modulations

Flora modulations as defined in radio_constants.c:

Timing

SX1262 Time-on-Air (ToA)

Calculation of the time-on-air (ToA) of a packet is not straight-forward since the duration depends on many parameters and conditions. Options to determine the ToA:

• Formula for calculating the ToA of LoRa packets is given in the SX1262 datasheet.
• flora-lib (C code) provides the following methods:
  • gloria_get_toa(): uses current modulation setting of gloria_interface, output in us
  • gloria_get_toa_sl(): uses provided modulation index, output in us
  • radio_get_toa(): uses provided modulation index, output in us
  • radio_get_toa_hs(): uses provided modulation index, output hs_timer ticks
  • radio_get_toa_arb(): arbitrary radio config, output in us
• sx1262 (Python library):
  • for flora modulations according to radio_constants.c: use flora_toa(modIdx, phyPlLen)
  • for arbitrary radio settings: use the LoraConfig and FskConfig classes

Gloria Timing

Relations:

• slot_time = slotOverhead + toa(mod, msgSize)
• reconstructed_marker = last_sync_ts - txSync - slot_index*slot_time - floodInitOverhead(mod)
• current_tx_marker = reconstructed_marker + floodInitOverhead(mod) + slot_index*slot_time

Misc

Low Power Modes - Troubleshooting

STOP2 Consumption too high

Problem: Power consumption is too high if put radio to sleep and MCU to STOP2 (around 800 uA instead of around 5 uA)
Solution: Make sure that the interrupt status flag of GPIO EXTI interrupt (PC13, RF_DIO1) is cleared before entering STOP2:

__HAL_GPIO_EXTI_CLEAR_IT(GPIO_PIN_13);

STANDBY & SHUTDOWN not successfully entered

Problem: MCU wakes up immediately after entering STANDBY or SHUTDOWN mode when a message was sent with the radio before entering STANDBY or SHUTDOWN mode.
Solution: Clear interrupt status flags of all WAKEUP lines:

__HAL_PWR_CLEAR_FLAG(PWR_FLAG_WU);

Radio Bandwidth

• RadioSetRxConfig() behavior
  • flora-lib: RadioSetRxConfig expects double-sided bandwidth (DSB)
  • Reference implementation: RadioSetRxConfig expects single-sided bandwidth (SSB)
  • also see issue 928

RTT (print to SWO)

DPP2 DevBoard needs a hardware fix to enable RTT / SWO print debug output (wire between SWO pin from COM JTAG and COM_GPIO2 pin from DEBUG header). In addition SWO_ENABLE needs to be set to 1 in app_config.h. In addition, in the SWO settings in the STM32CubeIDE, port 0 needs to be selected/checked!

Generate Binary or Hex image

Binary

• In Project Properties > C/C++ Build > Settings > Build Steps > Post-build Steps add the following command
  arm-none-eabi-objcopy -O binary <project name>.elf <project name>.bin
• If used in terminal, binutils-arm-none-eabi package needs to be installed

Hex

• In Project Properties > C/C++ Build > Settings > Build Steps > Post-build Steps add the following command
  arm-none-eabi-objcopy -O ihex <project name>.elf <project name>.hex
• If used in terminal, binutils-arm-none-eabi package needs to be installed

Flash with JLink Tools

• Install Segger "J-Link Software and Documentation Pack" (link)
• Use the JRunExe
./JRunExe' -device STM32L433CC -if SWD -speed 4000 <image name>.elf
• NOTE: Using the JLinkExe tool was not successful so far (except on FlockLab2 with hex file) because erase command always fails

Binary Patching Using flocklab-tools

• flocklab-tools Python package

Example:

from flocklab import Flocklab
fl = Flocklab()

value = fl.readSymbolValue(elfPath, symbName, signed=False)
fl.writeSymbolValue(elfPathPatched, symbName, symbReplace, signed=False)

DPP Guides

Guides in DPP wiki contain further infos about:

• Access serial output (UART) of the DPP2 ComBoard (on DevBoard)
• A guide to low-power modes

FAQ

What does 'Flora' mean?

The name Flora is a combination of flock and LoRa.

License

See License file.

How to Cite

• ETH Zurich Library Entry
• BibTeX:

  @misc{flora2021,
    author = {Trüb, Roman and Da Forno, Reto and Wegmann, Markus and Keller, Michael and Biri, Andreas and Gatschet, Tobias and Kuonen, Tobias},
    publisher = {ETH Zurich},
    title = {{Flora Software}},
    year = {2021},
    doi={10.5905/ethz-1007-403},
    url={https://eth.swisscovery.slsp.ch/permalink/41SLSP_ETH/lshl64/alma99117766552205503}
  }

Contact Information

Please contact us if you have feedback, proposals, bug reports, etc.

Reto Da Forno
Technical Staff

Roman Trüb
PhD Student

Contributors

• Roman Trüb: PhD student
• Reto Da Forno: Technical staff
• Markus Wegmann: Master thesis FS2018
• Michael Keller: Semester thesis FS2018, Master thesis HS2018
• Andreas Biri: PhD student
• Tobias Gatschet: Master thesis HS2019
• Tobias Kuonen: Master thesis HS2020

Third-Party Software