Skip to content

MM How to implement a new Application

Jump to bottom
LoRaWanMiniMouse edited this page May 17, 2018 · 2 revisions

Introduction

This guide will describe how to implement a new application in MM source code. MM source code contain an application specific directory : UserCode. A basic application is given as example in appli.cpp file. The uplink message is built in this file. In case of application downlink , this file will be probably the best place to analyse/decode it.

The main.c manage the Lorawan process. For more details about the main files given in example in this MM stack, read the dedicated wiki page.

How to Create a Radio object :

Both sx1276, SX1261 radio are yet supported by MM. Radio directory contains the definition of the Radio Classes Example to create an object sx1276 :

SX1276  RadioUser( LORA_CS, LORA_RESET, TX_RX_IT, RX_TIMEOUT_IT);

the UserDefine.h file contains the pin declarations. Have to be set by the user according it board implementation.

How to Create a LoRaWanObject :

MM implementation uses C++ template class. At the declaration of a lorawan object user have to give as template parameter the radio type and the Region type, on the following example region Europe et radio sx1276.

LoraWanObject<LoraRegionsEU,SX1276> Lp( LoraWanKeys, &RadioUser, USERFLASHADRESS );

The LoRaWanObeject constructor require to set 3 parameters :

1.Set structure with provisioning parameters :

typedef struct sLoRaWanKeys {
    uint8_t *              LoRaMacNwkSKey;
    uint8_t *              LoRaMacAppSKey;
    uint8_t *              LoRaMacAppKey;
    uint8_t *              AppEui;
    uint8_t *              DevEui;    
    uint32_t               LoRaDevAddr;
    eDeviceTypeOTA_APB     OtaDevice;
}sLoRaWanKeys;

LoRaMacNwkSKey,LoRaMacAppSKey,LoRaDevAddr are required only in APB mode. AppEUI,DevEUI,LoRaMacAppKey are required only in OTA mode. Set the provisioning mode :

typedef enum {choice
    OTA_DEVICE,
    APB_DEVICE,
}eDeviceTypeOTA_APB;

2. Reference the radio object :

With the MM implementation , it is very simple to reuse the radio for other task than LoraWan stack (for more details referred to CrazyMain.) So it is convenient to declare an object radio in stand alone, to link this objet to the LoRaWanObject, just pass it adress as paramater of the LoRaWanObject constructor.
in this example : &ŔadioUser

3. Set Flash/EEPROM address :

MM store its LoRaWan context into the flash/eeprom in case of reset/power off. The user have to set the flash address. In our case : USERFLASHADRESS. Note : the size of the context in region dependent (number of channels). All LoRaWan parameters save in flash are contained in the structure define in the LoraMacDataStoreInFlash.h

struct sBackUpFlash
{    /*******************************************/
    /*      Update by Link ADR command         */
    /*******************************************/
    uint8_t      MacTxDataRate;
    uint8_t      MacTxPower;
    uint16_t     MacChMask; //@notereview remove
    uint8_t      MacNbTrans; 
    /********************************************/
    /*     Update by TxParamaSetupRequest       */
    /********************************************/
    uint32_t     MacRx2Frequency ; 
    uint8_t      MacRx2DataRate;
    uint8_t      MacRx1DataRateOffset;
    /********************************************/
    /*     Update by NewChannelReq command      */
    /********************************************/
    uint32_t     MacTxFrequency[16];//@note region dependant
    uint32_t     MacRx1Frequency[16];//@note region dependant
    uint8_t      MacMinDataRateChannel [16];
    uint8_t      MacMaxDataRateChannel [16];
    uint8_t      MacChannelIndexEnabled [16];
    uint16_t     MacChannelMask; //
    /********************************************/
    /*   Update by RXTimingSetupReq command     */
    /********************************************/
    int          MacRx1Delay;
    /********************************************/
    /*   Other Data To store                    */
    /********************************************/
    uint32_t     FcntUp;   
    uint32_t     FcntDwn;
    uint32_t     DevAddr;
    uint8_t      nwkSKey [16];
    uint8_t      appSKey [16];
    uint8_t      JoinedStatus;
    uint16_t     DevNonce;    
    uint8_t      NbOfReset;
    uint8_t      Reserved [7];
    uint32_t     CrcHigh;   
    uint32_t     CrcLow;    
} ;

Set Board Parameters :

In UserDefine.h, user have to set some parameters board/application dependent.

  1. Set Uart pins and activate debug trace :
#define DEBUG_TRACE    1      // set to 1 to activate debug traces
#define SERIAL_TX      USBTX  // Tx UART Pin Name
#define SERIAL_RX      USBRX  // Rx Uart Pin NAme
  1. Activate Low Power Mode :
#define LOW_POWER_MODE 0      // set to 1 to activate sleep mode , set to 0 to replace by wait functions (easier in debug mode)
  1. Configure Rx windows timing :
#define CRYSTAL_ERROR             3 // Crystal error of the MCU to fine adjust the Rx window for lorawan ( ex: set 3² for a crystal error = 0.3%)
#define BOARD_DELAY_RX_SETTING_MS 4 // Delay introduce by the mcu Have to fine tune to adjust the window Rx for LoRaWan

The timing (the opening time and the duration) of the receive windows is of capital importance to correctly receive downlinks. The timing is driven by 2 parameters set at compile time:

XTALerror : gives in ppm the maximum frequency error of the RTC oscillator (not the radio XTAL !!!). For example if the platform uses a 32.768kHz watch crystal for its time base with +/- 100ppm frequency error , then XTALerror=100. If the platform uses the MCU internal RC oscillator , then the error is more in the 1% range hence XTALerror=10000.

BOARD_DELAY_RX_SETTING_MS : The absolute delay in mSec between the wake-up timer event and the moment the radio actually is ready to start receiving.This delay is platform specific and is a function of the SPI speed, the MCU clock frequency, the MCU wake-up time,... Set the parameter CRYSTAL_ERROR with the value of XTALerror * 1000 (set 10 for internal rc oscillator)

  1. Configure Flash Update Period :
#define FLASH_UPDATE_PERIOD 256 // The Lorawan context is stored in memory with a period equal to FLASH_UPDATE_PERIOD packets transmitted

This parameters is dependent of the life cycle duration of the mcu memory, typically 10000 cycles for flash and 100000 for eeprom.

  1. Set Pa Boost Pin:

For sx127x radio , user can configure output Tx on Pa Boost pin (to achieve 20 dbm)

#define PA_BOOST_CONNECTED 1 //  Set to 1 to select Pa_boost outpin pin on the sx127x
Clone this wiki locally