LoRaMAC  4.5.2
Documentation of the API
Porting Guide

Repository Structure

The repository comes with the following directories on top level:

Directory Description
cmake CMake scripts and helpers
doc Documentation
src Source code

The most important directory is the 'src' directory:

Directory Description
apps Application examples
boards Contains board specific implementations of hardware platform drivers
mac The LoRaMAC sources
peripherals This directory contains drivers for peripherals which are available on some hardware platforms
radio The radio driver implementations
system Generic abstraction layer for the different hardware platforms

Porting To Another Hardware Platform

In general, the motivation is to provide a simple and well defined project structure to allow a fast an easy porting to another platform. This project comes with several examples of hardware platforms, e.g. the LoRaMote or the MoteII. The hardware platform implementations are available at the directory 'src/boards'. If you want to add a new hardware platform, you have to perform the following tasks:

  • Add a new directory at 'src/boards' with the specific hardware platform name
  • Implement at least the following drivers respectively files according to your platform:
    • board.c/.h
    • gpio-board.c/.h
    • pinName-board.h
    • pinName-ioe.h
    • rtc-board.c/.h
    • spi-board.c/.h
    • sx1272-board.c/.h
  • You may need to adapt the implementations of the generic abstraction layer in directory 'src/system'
  • You may need to add a new standard peripheral library for your platform into the directory 'src/boards/mcu'. This includes the file 'utilities.c'

RX Window Calculation

The RX window calculation is implemented according to chapter 3.1.2 of the following documents:

https://www.semtech.com/uploads/documents/SX1272_settings_for_LoRaWAN_v2.0.pdf or https://www.semtech.com/uploads/documents/SX1276_settings_for_LoRaWAN_v2.0.pdf

Downlink start: T = Tx + 1s (+/- 20 us)
|
TRxEarly | TRxLate
| | |
| | +---+---+---+---+---+---+---+---+
| | | Latest Rx window |
| | +---+---+---+---+---+---+---+---+
| | |
+---+---+---+---+---+---+---+---+
| Earliest Rx window |
+---+---+---+---+---+---+---+---+
|
+---+---+---+---+---+---+---+---+
Downlink preamble 8 symbols | | | | | | | | |
+---+---+---+---+---+---+---+---+

TRxLate = DEFAULT_MIN_RX_SYMBOLS * tSymbol - RADIO_WAKEUP_TIME

TRxEarly = 8 - DEFAULT_MIN_RX_SYMBOLS * tSymbol - RxWindowTimeout - RADIO_WAKEUP_TIME

TRxLate - TRxEarly = 2 * DEFAULT_SYSTEM_MAX_RX_ERROR

RxOffset = ( TRxLate + TRxEarly ) / 2

RxWindowTimeout = ( 2 * DEFAULT_MIN_RX_SYMBOLS - 8 ) * tSymbol + 2 * DEFAULT_SYSTEM_MAX_RX_ERROR

RxOffset = 4 * tSymbol - RxWindowTimeout / 2 - RADIO_WAKE_UP_TIME

Minimal value of RxWindowTimeout must be 5 symbols which implies that the system always tolerates at least an error of 1.5 * tSymbol.


RX Window Calibration

The LoRaMAC stack supports a runtime calibration of the RX window timing. As described in section RX Window Calculation, the RX window timing especially depends on DEFAULT_SYSTEM_MAX_RX_ERROR and DEFAULT_MIN_RX_SYMBOLS. The related MIB types are MIB_SYSTEM_MAX_RX_ERROR and MIB_MIN_RX_SYMBOLS.

The following code snippet shows how to update those values during runtime:

int main( void )
{
// This comment is a placeholder for the initialization of the LoRaMAC layer
// Update the DEFAULT_SYSTEM_MAX_RX_ERROR
mibReq.Param.SystemMaxRxError = 15;
return;
// Update the DEFAULT_MIN_RX_SYMBOLS.
mibReq.Param.MinRxSymbols = 8;
return;
}

MibRequestConfirm_t::Type
Mib_t Type
Definition: LoRaMac.h:2242
MibRequestConfirm_t::Param
MibParam_t Param
Definition: LoRaMac.h:2247
MibParam_t::MinRxSymbols
uint8_t MinRxSymbols
Definition: LoRaMac.h:2110
MIB_MIN_RX_SYMBOLS
Definition: LoRaMac.h:1701
MibRequestConfirm_t
Definition: LoRaMac.h:2237
MIB_SYSTEM_MAX_RX_ERROR
Definition: LoRaMac.h:1696
LORAMAC_STATUS_OK
Definition: LoRaMac.h:2274
LoRaMacMibSetRequestConfirm
LoRaMacStatus_t LoRaMacMibSetRequestConfirm(MibRequestConfirm_t *mibSet)
LoRaMAC MIB-Set.
MibParam_t::SystemMaxRxError
uint32_t SystemMaxRxError
Definition: LoRaMac.h:2104