|
|
# Flora
|
|
|
|
|
|
Software for the [DPP2 LoRa Comboard](https://gitlab.ethz.ch/tec/public/dpp/-/wikis/Communication/DPP2LoRa) (STM32L4 MCU + SX126x radio) based on the [Dual Processor Platform (DPP)](https://gitlab.ethz.ch/tec/public/dpp/wikis/home) architecture developed by the [Computer Engineering Group (TEC)](https://tec.ee.ethz.ch/) 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
|
|
|
| App | Description | Status |
|
|
|
|-----------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------|-----------------|
|
|
|
| [Hello World](hello-world) | Simple hello world/blinky application that uses the flora-lib and is compatible with the baseboard. | stable |
|
|
|
| [eLWB](elwb) | [Event-triggered Low-Power Wireless Bus](https://dl.acm.org/doi/abs/10.5555/3108009.3108028) implementation | stable |
|
|
|
| [LWB](lwb) | A simplified version of the [Low-Power Wireless Bus](https://dl.acm.org/doi/abs/10.1145/2426656.2426658). | initial version |
|
|
|
| [Linktest](https://gitlab.ethz.ch/tec/research/dpp/software/communication_platforms/sx126x_lora/flora/linktest) | Point-to-point link test for running on FlockLab 2 (measures packet reception ratio, RSSI, and CRC errors). | stable |
|
|
|
|
|
|
**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**](https://www.st.com/en/development-tools/stm32cubeide.html): 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](https://www.flocklab.ethz.ch/).
|
|
|
* Shell script: e.g. `run_flocklab_test.sh`
|
|
|
* Python script (uses the [flocklab-tools](https://pypi.org/project/flocklab-tools/)): e.g. `run_flocklab_test.py`
|
|
|
|
|
|
|
|
|
## Software Development
|
|
|
|
|
|
### STM32CubeIDE
|
|
|
* All projects are created and edited using the [**STM32CubeIDE**](https://www.st.com/en/development-tools/stm32cubeide.html) (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](https://www.flocklab.ethz.ch/), together with the [DPP2 DevBoard](https://gitlab.ethz.ch/tec/public/dpp/-/wikis/Application/DevBoard), or together with the [BaseBoard](https://gitlab.ethz.ch/tec/public/dpp/-/wikis/Application/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
|
|
|
| STM32L433 Pin | DPP Pin | DPP Mode | DevBoard | FlockLab 2 Pin | FlockLab 2 Mode | BaseBoard | Comment |
|
|
|
|---------------|-----------|----------|----------|----------------|-----------------|------------------|----------------------------------------------------|
|
|
|
| PH3 (BOOT0) | COM_GPIO1 | I/O | DEBUG 7 | LED1 | trace | DPP_Colibri_WAKE | Connected to SX1262 RFDIO1 on FlockLab (MCU input) |
|
|
|
| PB3 (SWO) | COM_GPIO2 | I/O | DEBUG 8 | LED2 | trace | Colibri_EN | |
|
|
|
| PA13 (SWDIO) | COM_PROG2 | I/O | DEBUG 9 | LED3 | trace | | MCU GPIO output |
|
|
|
| PA3 | COM_TREQ | ? | | INT1 | trace | | MCU GPIO output |
|
|
|
| PA14 (SWCLK) | COM_PROG | ? | | INT2 | trace | | MCU GPIO output |
|
|
|
| PA0 | COM_IND | ? | | SIG1 | actuate | | MCU GPIO input |
|
|
|
| PA4 | APP_IND | ? | | SIG2 | actuate | | MCU GPIO input |
|
|
|
|
|
|
**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](https://gitlab.ethz.ch/tec/public/flocklab/wiki/-/wikis/Man/GpioAssignmentTargetAdapter)
|
|
|
|
|
|
## Radio Drivers & Protocol Layers
|
|
|
<img width="80%" src="figures/flora_radio_drivers.png" />
|
|
|
|
|
|
* [Semtech Reference Implementation](https://github.com/Lora-net/LoRaMac-node/tree/master/src/radio)
|
|
|
|
|
|
### Flora Modulations
|
|
|
Flora modulations as defined in `radio_constants.c`:
|
|
|
|
|
|
| Index | Modulation | Physical Bitrate | Range |
|
|
|
|-------|------------|------------------|-------------|
|
|
|
| 0 | LoRa SF12 | 293 bit/s | long-range |
|
|
|
| 1 | LoRa SF11 | 537 bit/s | ... |
|
|
|
| 2 | LoRa SF10 | 977 bit/s | ... |
|
|
|
| 3 | LoRa SF9 | 1758 bit/s | ... |
|
|
|
| 4 | LoRa SF8 | 3125 bit/s | ... |
|
|
|
| 5 | LoRa SF7 | 5469 bit/s | ... |
|
|
|
| 6 | LoRa SF6 | 9375 bit/s | ... |
|
|
|
| 7 | LoRa SF5 | 15625 bit/s | ... |
|
|
|
| 8 | FSK 125k | 125 kbit/s | ... |
|
|
|
| 9 | FSK 200k | 200 kbit/s | ... |
|
|
|
| 10 | FSK 250k | 250 kbit/s | short-range |
|
|
|
|
|
|
## 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](https://www.semtech.com/products/wireless-rf/lora-core/sx1262).
|
|
|
* `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: <!--- FIXME: add link once sx1262 lib is public -->
|
|
|
* 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
|
|
|
<img width="80%" src="figures/gloria_timing.png" />
|
|
|
|
|
|
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:
|
|
|
```C
|
|
|
__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:
|
|
|
```C
|
|
|
__HAL_PWR_CLEAR_FLAG(PWR_FLAG_WU);
|
|
|
```
|
|
|
|
|
|
### Radio Bandwidth
|
|
|
* `RadioSetRxConfig()` behavior
|
|
|
* flora-lib: RadioSetRxConfig expects double-sided bandwidth (DSB)
|
|
|
* [Reference implementation](https://github.com/Lora-net/LoRaMac-node/tree/master/src/radio): RadioSetRxConfig expects single-sided bandwidth (SSB)
|
|
|
* also see [issue 928](https://github.com/Lora-net/LoRaMac-node/issues/928)
|
|
|
|
|
|
### RTT (print to SWO)
|
|
|
DPP2 [DevBoard](https://gitlab.ethz.ch/tec/public/dpp/-/wikis/Application/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](https://www.segger.com/downloads/jlink/#J-LinkSoftwareAndDocumentationPack))
|
|
|
* 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](https://pypi.org/project/flocklab-tools/) Python package
|
|
|
|
|
|
Example:
|
|
|
```Python
|
|
|
from flocklab import Flocklab
|
|
|
fl = Flocklab()
|
|
|
|
|
|
value = fl.readSymbolValue(elfPath, symbName, signed=False)
|
|
|
fl.writeSymbolValue(elfPathPatched, symbName, symbReplace, signed=False)
|
|
|
```
|
|
|
|
|
|
### FAQ
|
|
|
|
|
|
#### What does 'Flora' mean?
|
|
|
The name Flora is a combination of flock and LoRa.
|
|
|
|
|
|
|
|
|
# License
|
|
|
See [License](LICENSE) file.
|
|
|
|
|
|
# Contact Information
|
|
|
Please contact us if you have feedback, proposals, bug reports, etc.
|
|
|
|
|
|
[Reto Da Forno](https://www.ee.ethz.ch/de/departement/personen-a-bis-z/person-detail.html?persid=147294)
|
|
|
Technical Staff
|
|
|
|
|
|
[Roman Trüb](https://ee.ethz.ch/de/departement/personen-a-bis-z/person-detail.MTc5NDgz.TGlzdC8zMjc5LC0xNjUwNTg5ODIw.html)
|
|
|
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
|
|
|
|
|
|
| Component | License | Location in repo | Contained in repo |
|
|
|
|-----------------------------------------------------------------------------------------------------|----------------------------------------------------------|--------------------------------------------------------------------|------------------------------------------|
|
|
|
| [cJSON](https://github.com/DaveGamble/cJSON) | MIT License | `/flora-lib/cli/cJSON` | yes |
|
|
|
| [SX126x Radio Drivers](https://github.com/Lora-net/LoRaMac-node/tree/master/src/radio) (by Semtech) | BSD-3-Clause | `/flora-lib/radio/semtech` | yes |
|
|
|
| [STM32CubeIDE generated code](https://www.st.com/en/development-tools/stm32cubeide.html) | Ultimate Liberty License SLA0044/SLA0048 or BSD 3-Clause | `/<app>/Drivers`, `/<app>/Startup`, `/<app>/Src`, and `/<app>/Inc` | partially (only files in `Src` and `Inc`) |
|
|
|
| [FreeRTOS](https://www.freertos.org/index.html) | MIT license | `/<app>/Middlewares` | no | |