Quick-Start Guide

Table of Contents

• Overview
• Initialization
• Over-The-Air Activation (OTAA)
• Activation By Personalization (ABP)
• Region Selection

---

Overview

This quick start guide provides a short introduction into important operations of the LoRaMAC layer. Full examples for the different device classes are available in the example section.

---

Initialization

The initialization function of the LoRaMAC layer is LoRaMacInitialization( LoRaMacPrimitives_t *primitives, LoRaMacCallback_t *callbacks, LoRaMacRegion_t region ). The function has three parameters, LoRaMacPrimitives_t, LoRaMacCallback_t and LoRaMacRegion_t. The LoRaMAC layer utilizes primitives and callbacks, which must be provided by the upper layer. The data structure LoRaMacPrimitives_t contains function pointers to the Confirm and Indication primitives. The LoRaMAC layer will call the primitives to provide operation status information to the upper layers. The data structure LoRaMacCallback_t contains function pointers to procedures that should provide information for the LoRaMAC layer. E.g. the battery level of the device. The data type LoRaMacRegion_t specifies on which region the LoRaMAC layer shall operate.

The following code snippet provides an example for the initialization:

static void McpsConfirm( McpsConfirm_t *mcpsConfirm )
{
  // Implementation of the MCPS-Confirm primitive
}
 
static void McpsIndication( McpsIndication_t *mcpsIndication )
{
  // Implementation of the MCPS-Indication primitive
}
 
static void MlmeConfirm( MlmeConfirm_t *mlmeConfirm )
{
  // Implementation of the MLME-Confirm primitive
}
 
static void MlmeIndication( MlmeIndication_t *mlmeIndication )
{
  // Implementation of the MLME-Indication primitive
}
 
static void OnMacProcessNotify( void )
{
  // Mac notification. Process run function
}
 
LoRaMacPrimitives_t LoRaMacPrimitives;
LoRaMacCallback_t LoRaMacCallbacks;
LoRaMacStatus_t Status;
 
int main( void )
{
  LoRaMacPrimitives.MacMcpsConfirm = McpsConfirm;
  LoRaMacPrimitives.MacMcpsIndication = McpsIndication;
  LoRaMacPrimitives.MacMlmeConfirm = MlmeConfirm;
  LoRaMacPrimitives.MacMlmeIndication = MlmeIndication;
  LoRaMacCallbacks.GetBatteryLevel = BoardGetBatteryLevel;
  LoRaMacCallbacks.GetTemperatureLevel = NULL; // apply board specific temperature reading
  LoRaMacCallbacks.NvmContextChange = NvmCtxMgmtEvent;
  LoRaMacCallbacks.MacProcessNotify = OnMacProcessNotify;
  // Initialization for the region EU868
  Status = LoRaMacInitialization( &LoRaMacPrimitives, &LoRaMacCallbacks, LORAMAC_REGION_EU868 );
 
  if( Status == LORAMAC_STATUS_OK )
  {
    // Initialization successful
  }
}

---

Over-The-Air Activation (OTAA)

The LoRaMAC layer provides a MLME-Request to perform the over-the-air activation (LoRaMacMlmeRequest( MlmeReq_t *mlmeRequest )). The LoRaMAC layer creates the join-request message and reports the status of the operation with the MacMlmeConfirm primitive. Please note that the credentials are stored in the file se-identity.h for the related secure element.

The following code snippet provides an example:

 
static void MlmeConfirm( MlmeConfirm_t *mlmeConfirm )
{
    if( mlmeConfirm->Status == LORAMAC_EVENT_INFO_STATUS_OK )
    {
        switch( mlmeConfirm->MlmeRequest )
        {
            case MLME_JOIN:
            {
                // Status is OK, node has joined the network
                break;
            }
            case MLME_LINK_CHECK:
            {
                // Check DemodMargin
                // Check NbGateways
                break;
            }
            default:
                break;
        }
    }
}
 
int main( void )
{
  MlmeReq_t mlmeReq;
  LoRaMacStatus_t status;
 
  // This comment is a placeholder for the initialization of the LoRaMAC layer
 
  // Setup the request type
  mlmeReq.Type = MLME_JOIN;
 
  // Fill the join parameters
  mlmeReq.Req.Join.Datarate = DR_0;
 
  status = LoRaMacMlmeRequest( &mlmeReq );
 
  if( status == LORAMAC_STATUS_OK )
  {
    // Join request was send successfully
  }
}

---

Activation By Personalization (ABP)

The activation by personalization procedure requires to store important information on the LoRaMAC node:

• LoRaWAN version
• Network Identifier
• Device Address
• Activation

The application must configure those parameters to perform a personalized activation. In addition, the application has to enable the LoRaWAN network itself. Please note that the credentials are stored in the file se-identity.h for the related secure element.

The following code snippet provides an example:

int main( void )
{
  MibRequestConfirm_t mibReq;
  LoRaMacStatus_t status;
  uint32_t DevAddr;
 
  // This comment is a placeholder for the initialization of the LoRaMAC layer
 
  // Choose a random device address
  DevAddr = randr( 0, 0x01FFFFFF );
 
  mibReq.Type = MIB_ABP_LORAWAN_VERSION;
  mibReq.Param.AbpLrWanVersion.Value = 0x01000300;
  if( LoRaMacMibSetRequestConfirm( &mibReq ) != LORAMAC_STATUS_OK )
    return;
 
  mibReq.Type = MIB_NET_ID;
  mibReq.Param.NetID = 0x000000;
  if( LoRaMacMibSetRequestConfirm( &mibReq ) != LORAMAC_STATUS_OK )
    return;
 
  mibReq.Type = MIB_DEV_ADDR;
  mibReq.Param.DevAddr = DevAddr;
  if( LoRaMacMibSetRequestConfirm( &mibReq ) != LORAMAC_STATUS_OK )
    return;
 
  mibReq.Type = MIB_NETWORK_ACTIVATION;
  mibReq.Param.NetworkActivation = ACTIVATION_TYPE_ABP;
  if( LoRaMacMibSetRequestConfirm( &mibReq ) != LORAMAC_STATUS_OK )
    return;
 
  // LoRaWAN node has joined the network
}

---

Region Selection

The LoRaMAC Stack supports different regional setups. In general, it is possible to specify multiple regions such that it is possible to switch between them during runtime. A specific region can be enabled by defining the related symbol in the preprocessor options. E.g. to enable the EU868 region, please define REGION_EU868. If the LoRaMAC layer shall support more than one region at once, please define the corresponding symbol in addition.

The following symbols are supported:

• REGION_EU868
• REGION_US915
• REGION_CN779
• REGION_RU864
• REGION_EU433
• REGION_AU915
• REGION_CN470
• REGION_AS923
• REGION_KR920
• REGION_IN865

When multiple regions are selected during the build of the LoRaWAN Stack, it is possible to switch the region during runtime. To perform a region switch it is necessary to initialize the LoRaWAN Stack with the function LoRaMacInitialization( LoRaMacPrimitives_t *primitives, LoRaMacCallback_t *callbacks, LoRaMacRegion_t region ) again. When the node performs a switch of the region, the LoRaWAN Stack will restore all default values.

---