LoRaWAN overview

LoRaWAN is a technology designed for low-power battery powered devices. These devices operate in an unlicensed spectrum, creating high density wide-area networks.

Arm Mbed OS provides a native network stack for LoRaWAN, which can run on any Mbed Enabled device with a LoRa radio onboard.

The LoRaWANInterface provides a C++ API for connecting to the internet over a LoRa network.

Usage

To bring up the Mbed LoRaWAN stack, consider the following progression:

1. An EventQueue object:

// construct an event queue
EventQueue ev_queue(NUM_EVENTS * EVENTS_EVENT_SIZE);

2. A LoRaRadio object:

// construct a LoRadio object
SX1272_LoRaRadio radio(PIN_NAMES ... );

3. Instantiate LoRaWANInterface, and pass LoRaRadio object:

LoRaWANInterface lorawan(radio) ;

4. Initialize mac layer and pass EventQueue object:

lorawan.initialize(&ev_queue);

5. Set up the event callback:

lorawan_app_callbacks_t callbacks
callbacks.events = mbed::callback(YOUR_EVENT_HANDLER);
lorawan.add_app_callbacks(&callbacks);

6. Add network credentials (security keys) and any configurations:

lorawan_connect_t connection;

connection.connect_type = LORAWAN_CONNECTION_OTAA;
connection.connection_u.otaa.app_eui = YOUR_APP_EUI_KEY;
connection.connection_u.otaa.dev_eui = YOUR_DEV_EUI_KEY;
connection.connection_u.otaa.app_key = YOUR_APP_KEY;
connection.connection_u.otaa.nb_trials = MBED_CONF_LORA_NB_TRIALS;

lorawan.connect(connection);

Owing to the fact that most of the LoRaWAN devices are simple telemetry devices, the stack and its operation need to be as simple as possible. That's why the Mbed LoRaWAN stack is event driven.

Network events and callbacks

Here is the list of possible events that you can post from the stack to the application:

The application must attach an event handler to the stack. The LoRaWANInterface provides an API to attach various callbacks to the stacks. One such callback is the event handler callback.

Application callbacks

The Mbed LoRaWAN stack currently maps 3 different callbacks:

Event handler

An example of attaching your event handler to the stack:

void your_event_handler(lorawan_event_t event)
{
    switch (event) {
        case CONNECTED:
        //do something
            break;
        case DISCONNECTED:
            break;
	....
	....
    }
}
lorawan_app_callbacks_t callbacks;

callbacks.events = mbed::callback(your_event_handler);
//lorawan is the LoRaWANInterface object
lorawan.add_app_callbacks(&callbacks);

Link check response handler

Link check request is a MAC command defined by the LoRaWAN specification. To receive the response of this MAC command, set the link_check_resp callback.

void your_link_check_response(uint8_t demod_margin, uint8_t num_gw)
{
	//demod_margin is the demodulation margin
	// num_gw represents the number of gateways involved in the path
}

callbacks.link_check_resp = mbed::callback(your_link_check_response);
lorawan.add_app_callbacks(&callbacks);

Battery level handler

The battery level callback is different from others. The direction of this callback is from the application to the stack. In other words, it provides information to the stack. The application is reponsible for letting the stack know about the current battery level.

uint8_t your_battery_level()
{
	return battery_level;
}

callbacks.battery_level = mbed::callback(your_battery_level);
lorawan.add_app_callbacks(&callbacks);

Error codes

All operations on LoRaWANInterface return an error code lorawan_status_t that reflects success or failure of the operation.

Below is the list of error codes and their description.

You can find the API documentation for the LoRaWANInterface and LoRaRadio classes below:

• LoRaWANInterface API docs: The class that provides APIs for LoRaWAN network stack.
• LoRaRadio API docs: The class that provides pure virtual APIs to implement a LoRa radio driver.