Porting Guide

Table of Contents

• Repository Structure
• Porting To Another Hardware Platform
• RX Window Calculation
• RX Window Calibration

---

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 )
{
  MibRequestConfirm_t mibReq;
 
  // This comment is a placeholder for the initialization of the LoRaMAC layer
 
  // Update the DEFAULT_SYSTEM_MAX_RX_ERROR
  mibReq.Type = MIB_SYSTEM_MAX_RX_ERROR;
  mibReq.Param.SystemMaxRxError = 15;
  if( LoRaMacMibSetRequestConfirm( &mibReq ) != LORAMAC_STATUS_OK )
    return;
 
  // Update the DEFAULT_MIN_RX_SYMBOLS.
  mibReq.Type = MIB_MIN_RX_SYMBOLS;
  mibReq.Param.MinRxSymbols = 8;
  if( LoRaMacMibSetRequestConfirm( &mibReq ) != LORAMAC_STATUS_OK )
    return;
}

---