File structure

The firmware is based on the nRF SDK from Nordic Semiconductor and the LMiC library from IBM Research. As a rule of thumb you should look into the nRF SDK if you want to use the one of the peripherals on the nRF52 (ADC, RTC clock, AES chip, NFC, BLE).

Configuration files

The first directory you want to look at is the config difrectory. This holds the major configuration of the firmware, LoRa and nRF52.

LoRa configuration

lora_config.h holds #define statements for the device’s LoRa config. If you use OTAA devices set the LORAWAN_OTAA flag to 1 and modify the LORAWAN_DEVICE_EUI, LORAWAN_APP_KEY and LORAWAN_APP_EUI values accordingly:

#define LORAWAN_DEVICE_EUI { 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 }
#define LORAWAN_APP_KEY { 0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xFF, 0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xFF, 0xAA, 0xBB, 0xCC, 0xDD }
#define LORAWAN_APP_EUI { 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08 }

ABP devices needs the parameters LORAWAN_DEVICE_ADDRESS, LORAWAN_NWKSKEY and LORAWAN_APPSKEY:

#define LORAWAN_DEVICE_ADDRESS (uint32_t) 0x01020304
#define LORAWAN_NWKSKEY { 0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xFF, 0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xFF, 0xAA, 0xBB, 0xCC, 0xDD }
#define LORAWAN_APPSKEY { 0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xFF, 0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xFF, 0xAA, 0xBB, 0xCC, 0xDD }

Board configuration

The file nrf52_pins.h declares the pins used by the firmware. This is where you configure which board you are using. The board type is set by commenting and uncommenting the following two lines (this is the EE02 configuration):

// Use this #define if you are using the nRF52 DK
//#define NRF52_DK
// Use this #define if you are using EE-02 with a programming cable or EE-04
#define EE02

nRF52 configuration

The nRF52 configuration can be found in the nrf_drv_config.h file. The specifics can be found on the Nordic Semiconductors Infocenter documentation site.

Jobs

The LMiC program structure centers around jobs that are launched at regular intervals. They are running single-threaded so they should terminate as soon as possible. As long as a job is running you won’t be able to send or receive LoRa packets.

There’s several (sample) jobs implemented: * Reading battery status (battery_job.c) * GPS fix (gps_job.c) * IMU (imu_job.c) * LoRa send and receive (lora_job.c) * Power switching with TPS22994 (power_job.c)

A job is declared as a callback function and scheduled with os_setCallback (which runs at once) or os_setTimedCallback (which runs after specified time period):

static osjob_t repeating_job;

static void repeat_func(osjob_t* job) {
    NRF_LOG("I'm running now!\n");
    os_setTimedCallback(job, os_getTime() + sec2osticks(30), repeat_func);
}

void init_repeat(void) {
  os_setCallback(&repeating_job, repeat_func);
}

If you omit the call to os_setTimedCallback at the end of the job it will run only once.