[IOTCELL-279] Using Application provided EventQueue

The EventQueue thread in LoRaMac.cpp is disbanded and the LoRaWAN
protocol is redesigned to store a pointer for an application
provided EventQueue. It means that now the stack runs in the
same thread as application. Application provided EventQueue is used
to defer ISRs from radio driver and timer callbacks as well as the
application events are queued to the same event loop.

Author: Hasnain Virk

features/lorawan/LoRaWANInterface.cpp

@@ -21,6 +21,8 @@
 
 #include "lorawan/LoRaWANInterface.h"
 
+using namespace events;
+
 inline LoRaWANStack& stk_obj()
 {
     return LoRaWANStack::get_lorawan_stack();
@@ -40,9 +42,13 @@ LoRaWANInterface::~LoRaWANInterface()
 {
 }
 
-lora_mac_status_t LoRaWANInterface::initialize()
+lora_mac_status_t LoRaWANInterface::initialize(EventQueue *queue)
 {
-    return stk_obj().initialize_mac_layer();
+    if(!queue) {
+        return LORA_MAC_STATUS_PARAMETER_INVALID;
+    }
+
+    return stk_obj().initialize_mac_layer(queue);
 }
 
 lora_mac_status_t LoRaWANInterface::connect()

features/lorawan/LoRaWANInterface.h

@@ -40,9 +40,11 @@ class LoRaWANInterface: public LoRaWANBase {
      *
      * You must call this first to be able to use the LoRa stack.
      *
-     * \return         0 on success, a negative error code on failure.
+     * @param ev_queue A pointer to EventQueue provided by the application.
+     *
+     * @return         0 on success, a negative error code on failure.
      */
-    virtual lora_mac_status_t initialize();
+    virtual lora_mac_status_t initialize(events::EventQueue *ev_queue) ;
 
     /** Connect OTAA or ABP using Mbed-OS config system
      *

features/lorawan/LoRaWANStack.cpp

@@ -26,6 +26,7 @@ SPDX-License-Identifier: BSD-3-Clause
 #include <string.h>
 #include <stdlib.h>
 #include "platform/Callback.h"
+#include "events/EventQueue.h"
 #include "lorawan/LoRaWANStack.h"
 #if defined(FEATURE_COMMON_PAL)
 #include "mbed_trace.h"
@@ -77,6 +78,7 @@ SPDX-License-Identifier: BSD-3-Clause
 #endif //MBED_CONF_LORA_PHY
 
 using namespace mbed;
+using namespace events;
 
 /**
  * Helper function prototypes
@@ -129,7 +131,7 @@ lora_mac_status_t LoRaWANStack::set_application_port(uint8_t port)
  ****************************************************************************/
 LoRaWANStack::LoRaWANStack()
 : _device_current_state(DEVICE_STATE_NOT_INITIALIZED), _mac_handlers(NULL),
-  _num_retry(1), _duty_cycle_on(LORAWAN_DUTYCYCLE_ON)
+  _num_retry(1), _queue(NULL), _duty_cycle_on(LORAWAN_DUTYCYCLE_ON)
 {
 #ifdef MBED_CONF_LORA_APP_PORT
     // is_port_valid() is not virtual, so we can call it in constructor
@@ -173,7 +175,7 @@ radio_events_t *LoRaWANStack::bind_radio_driver(LoRaRadio& radio)
     lora_phy.set_radio_instance(radio);
     return _mac_handlers;
 }
-lora_mac_status_t LoRaWANStack::initialize_mac_layer()
+lora_mac_status_t LoRaWANStack::initialize_mac_layer(EventQueue *queue)
 {
     if (DEVICE_STATE_NOT_INITIALIZED != _device_current_state)
     {
@@ -188,6 +190,9 @@ lora_mac_status_t LoRaWANStack::initialize_mac_layer()
 
     tr_debug("Initializing MAC layer");
 
+    //store a pointer to Event Queue
+    _queue = queue;
+
     // Allocate memory for compliance test
     _compliance_test.app_data_buffer = compliance_test_buffer;
 
@@ -196,7 +201,7 @@ lora_mac_status_t LoRaWANStack::initialize_mac_layer()
     LoRaMacPrimitives.MacMcpsIndication = callback(this, &LoRaWANStack::mcps_indication);
     LoRaMacPrimitives.MacMlmeConfirm = callback(this, &LoRaWANStack::mlme_confirm);
     LoRaMacCallbacks.TxNextPacketTimerEvent = callback(this, &LoRaWANStack::on_tx_next_packet_timer_event);
-    LoRaMacInitialization(&LoRaMacPrimitives, &LoRaMacCallbacks, lora_phy);
+    LoRaMacInitialization(&LoRaMacPrimitives, &LoRaMacCallbacks, &lora_phy, queue);
 
     mib_req.type = LORA_MIB_ADR;
     mib_req.param.adr_enable = LORAWAN_ADR_ON;
@@ -394,7 +399,7 @@ void LoRaWANStack::on_tx_next_packet_timer_event(void)
 
 lora_mac_status_t LoRaWANStack::set_confirmed_msg_retry(uint8_t count)
 {
-    if (count > MAX_CONFIRMED_MSG_RETRIES) {
+    if (count >= MAX_CONFIRMED_MSG_RETRIES) {
         return LORA_MAC_STATUS_PARAMETER_INVALID;
     }
 
@@ -1046,7 +1051,7 @@ void LoRaWANStack::mlme_confirm_handler(lora_mac_mlme_confirm_t *mlme_confirm)
                 // Join attempt failed.
                 set_device_state(DEVICE_STATE_IDLE);
                 lora_state_machine();
-                _events(JOIN_FAILURE);
+                _queue->call(_events, JOIN_FAILURE);
             }
             break;
         case LORA_MLME_LINK_CHECK:
@@ -1127,14 +1132,14 @@ void LoRaWANStack::mcps_confirm_handler(lora_mac_mcps_confirm_t *mcps_confirm)
 
         // If sending timed out, we have a special event for that
         if (mcps_confirm->status == LORA_EVENT_INFO_STATUS_TX_TIMEOUT) {
-            _events(TX_TIMEOUT);
+            _queue->call(_events, TX_TIMEOUT);
             return;
         } if (mcps_confirm->status == LORA_EVENT_INFO_STATUS_RX2_TIMEOUT) {
             tr_debug("Did not receive Ack");
         }
 
         // Otherwise send a general TX_ERROR event
-        _events(TX_ERROR);
+        _queue->call(_events, TX_ERROR);
         return;
     }
 
@@ -1154,7 +1159,7 @@ void LoRaWANStack::mcps_confirm_handler(lora_mac_mcps_confirm_t *mcps_confirm)
     // data rate plus frame counter.
     _lw_session.uplink_counter = mcps_confirm->uplink_counter;
     _tx_msg.tx_ongoing = false;
-    _events(TX_DONE);
+    _queue->call(_events, TX_DONE);
 }
 
 /** MCPS-Indication event function
@@ -1170,7 +1175,7 @@ void LoRaWANStack::mcps_indication_handler(lora_mac_mcps_indication_t *mcps_indi
     }
 
     if (mcps_indication->status != LORA_EVENT_INFO_STATUS_OK) {
-        _events(RX_ERROR);
+        _queue->call(_events, RX_ERROR);
         return;
     }
 
@@ -1219,7 +1224,7 @@ void LoRaWANStack::mcps_indication_handler(lora_mac_mcps_indication_t *mcps_indi
                     // This may never happen as both radio and MAC are limited
                     // to the size 255 bytes
                     tr_debug("Cannot receive more than buffer capacity!");
-                    _events(RX_ERROR);
+                    _queue->call(_events, RX_ERROR);
                     return;
                 } else {
                     _rx_msg.type = LORAMAC_RX_MCPS_INDICATION;
@@ -1233,7 +1238,7 @@ void LoRaWANStack::mcps_indication_handler(lora_mac_mcps_indication_t *mcps_indi
                 // Notify application about received frame..
                 tr_debug("Received %d bytes", _rx_msg.rx_message.mcps_indication.buffer_size);
                 _rx_msg.receive_ready = true;
-                _events(RX_DONE);
+                _queue->call(_events, RX_DONE);
             } else {
                 // Invalid port, ports 0, 224 and 225-255 are reserved.
             }
@@ -1800,7 +1805,7 @@ lora_mac_status_t LoRaWANStack::lora_state_machine()
             _lw_session.active = false;
 
             tr_debug("LoRaWAN protocol has been shut down.");
-            _events(DISCONNECTED);
+            _queue->call(_events, DISCONNECTED);
             status = LORA_MAC_STATUS_DEVICE_OFF;
             break;
         case DEVICE_STATE_NOT_INITIALIZED:
@@ -1842,7 +1847,7 @@ lora_mac_status_t LoRaWANStack::lora_state_machine()
             // Session is now active
             _lw_session.active = true;
             // Tell the application that we are connected
-            _events(CONNECTED);
+            _queue->call(_events, CONNECTED);
             break;
         case DEVICE_STATE_ABP_CONNECTING:
             /*
@@ -1874,7 +1879,7 @@ lora_mac_status_t LoRaWANStack::lora_state_machine()
             status = LORA_MAC_STATUS_OK;
             // Session is now active
             _lw_session.active = true;
-            _events(CONNECTED);
+            _queue->call(_events, CONNECTED);
             break;
         case DEVICE_STATE_SEND:
             // If a transmission is ongoing, don't interrupt
@@ -1890,11 +1895,11 @@ lora_mac_status_t LoRaWANStack::lora_state_machine()
                         break;
                     case LORA_MAC_STATUS_CRYPTO_FAIL:
                         tr_error("Crypto failed. Clearing TX buffers");
-                        _events(TX_CRYPTO_ERROR);
+                        _queue->call(_events, TX_CRYPTO_ERROR);
                         break;
                     default:
                         tr_error("Failure to schedule TX!");
-                        _events(TX_SCHEDULING_ERROR);
+                        _queue->call(_events, TX_SCHEDULING_ERROR);
                         break;
                 }
             }

features/lorawan/LoRaWANStack.h

@@ -27,6 +27,7 @@ SPDX-License-Identifier: BSD-3-Clause
 #define LORAWANSTACK_H_
 
 #include <stdint.h>
+#include "events/EventQueue.h"
 #include "platform/Callback.h"
 #include "platform/NonCopyable.h"
 #include "lorawan/system/LoRaWANTimer.h"
@@ -59,14 +60,14 @@ class LoRaWANStack: private mbed::NonCopyable<LoRaWANStack> {
     radio_events_t *bind_radio_driver(LoRaRadio& radio);
 
     /** End device initialization.
-     *
-     * \return                 0 on success, a negative error code on failure.
+     * @param queue            A pointer to an EventQueue passed from the application.
+     * @return                 LORA_MAC_STATUS_OK on success, a negative error code on failure.
      */
-    lora_mac_status_t initialize_mac_layer();
+    lora_mac_status_t initialize_mac_layer(events::EventQueue *queue);
 
     /** Sets all callbacks of the LoRaWAN interface.
      *
-     * \param *event_cb        An event structure representing all possible callbacks.
+     * @param *event_cb        An event structure representing all possible callbacks.
      */
     void set_lora_event_cb(mbed::Callback<void(lora_events_t)> event_cb);
 
@@ -418,6 +419,7 @@ class LoRaWANStack: private mbed::NonCopyable<LoRaWANStack> {
     lora_mac_rx_message_t _rx_msg;
     uint8_t _app_port;
     uint8_t _num_retry;
+    events::EventQueue *_queue;
     bool _duty_cycle_on;
 };