Merge pull request #7445 from hasnainvirk/issue_7230

LoRaWAN: Remedy for issue #7230

Author: Cruz Monrreal

features/lorawan/LoRaWANBase.h

@@ -41,8 +41,14 @@ class LoRaWANBase {
      * Connect by Over The Air Activation or Activation By Personalization.
      * The connection type is selected at the setup.
      *
-     * @return         LORAWAN_STATUS_OK on success, a negative error code on
-     *                 failure.
+     * @return    For ABP:  If everything goes well, LORAWAN_STATUS_OK is returned for first call followed by
+     *                      a 'CONNECTED' event. Otherwise a negative error code is returned.
+     *                      Any subsequent call will return LORAWAN_STATUS_ALREADY_CONNECTED and no event follows.
+     *
+     *            For OTAA: When a JoinRequest is sent, LORAWAN_STATUS_CONNECT_IN_PROGRESS is returned for the first call.
+     *                      Any subsequent call will return either LORAWAN_STATUS_BUSY (if the previous request for connection
+     *                      is still underway) or LORAWAN_STATUS_ALREADY_CONNECTED (if a network was already joined successfully).
+     *                      A 'CONNECTED' event is sent to the application when the JoinAccept is received.
      */
     virtual lorawan_status_t connect() = 0;
 
@@ -53,8 +59,15 @@ class LoRaWANBase {
      * You need to define the parameters in the main application.
      *
      * @param connect       Options how end-device will connect to gateway
-     * @return              LORAWAN_STATUS_OK on success, negative error code
-     *                      on failure
+     *
+     * @return    For ABP:  If everything goes well, LORAWAN_STATUS_OK is returned for first call followed by
+     *                      a 'CONNECTED' event. Otherwise a negative error code is returned.
+     *                      Any subsequent call will return LORAWAN_STATUS_ALREADY_CONNECTED and no event follows.
+     *
+     *            For OTAA: When a JoinRequest is sent, LORAWAN_STATUS_CONNECT_IN_PROGRESS is returned for the first call.
+     *                      Any subsequent call will return either LORAWAN_STATUS_BUSY (if the previous request for connection
+     *                      is still underway) or LORAWAN_STATUS_ALREADY_CONNECTED (if a network was already joined successfully).
+     *                      A 'CONNECTED' event is sent to the application when the JoinAccept is received.
      */
     virtual lorawan_status_t connect(const lorawan_connect_t &connect) = 0;
 

features/lorawan/LoRaWANInterface.h

@@ -73,7 +73,6 @@ class LoRaWANInterface: public LoRaWANBase {
      * all user-configured channels except the Join/Default channels. A CF-List can
      * configure a maximum of five channels other than the default channels.
      *
-     * In case of ABP, the CONNECTED event is posted before the call to `connect()` returns.
      * To configure more channels, we recommend that you use the `set_channel_plan()` API after the connection.
      * By default, the PHY layers configure only the mandatory Join channels. The retransmission back-off restrictions
      * on these channels are severe and you may experience long delays or even failures in the confirmed traffic.
@@ -92,8 +91,14 @@ class LoRaWANInterface: public LoRaWANBase {
      * is important, at least for ABP. That's why we try to restore frame counters from
      * session information after a disconnection.
      *
-     * @return         LORAWAN_STATUS_OK or LORAWAN_STATUS_CONNECT_IN_PROGRESS
-     *                 on success, or a negative error code on failure.
+     * @return    For ABP:  If everything goes well, LORAWAN_STATUS_OK is returned for first call followed by
+     *                      a 'CONNECTED' event. Otherwise a negative error code is returned.
+     *                      Any subsequent call will return LORAWAN_STATUS_ALREADY_CONNECTED and no event follows.
+     *
+     *            For OTAA: When a JoinRequest is sent, LORAWAN_STATUS_CONNECT_IN_PROGRESS is returned for the first call.
+     *                      Any subsequent call will return either LORAWAN_STATUS_BUSY (if the previous request for connection
+     *                      is still underway) or LORAWAN_STATUS_ALREADY_CONNECTED (if a network was already joined successfully).
+     *                      A 'CONNECTED' event is sent to the application when the JoinAccept is received.
      */
     virtual lorawan_status_t connect();
 
@@ -109,7 +114,6 @@ class LoRaWANInterface: public LoRaWANBase {
      * all user-configured channels except the Join/Default channels. A CF-List can
      * configure a maximum of five channels other than the default channels.
      *
-     * In case of ABP, the CONNECTED event is posted before the call to `connect()` returns.
      * To configure more channels, we recommend that you use the `set_channel_plan()` API after the connection.
      * By default, the PHY layers configure only the mandatory Join
      * channels. The retransmission back-off restrictions on these channels
@@ -132,8 +136,14 @@ class LoRaWANInterface: public LoRaWANBase {
      *
      * @param connect  Options for an end device connection to the gateway.
      *
-     * @return        LORAWAN_STATUS_OK or LORAWAN_STATUS_CONNECT_IN_PROGRESS,
-     *                a negative error code on failure.
+     * @return    For ABP:  If everything goes well, LORAWAN_STATUS_OK is returned for first call followed by
+     *                      a 'CONNECTED' event. Otherwise a negative error code is returned.
+     *                      Any subsequent call will return LORAWAN_STATUS_ALREADY_CONNECTED and no event follows.
+     *
+     *            For OTAA: When a JoinRequest is sent, LORAWAN_STATUS_CONNECT_IN_PROGRESS is returned for the first call.
+     *                      Any subsequent call will return either LORAWAN_STATUS_BUSY (if the previous request for connection
+     *                      is still underway) or LORAWAN_STATUS_ALREADY_CONNECTED (if a network was already joined successfully).
+     *                      A 'CONNECTED' event is sent to the application when the JoinAccept is received.
      */
     virtual lorawan_status_t connect(const lorawan_connect_t &connect);
 

features/lorawan/LoRaWANStack.cpp

@@ -44,6 +44,7 @@ SPDX-License-Identifier: BSD-3-Clause
 #define CONNECTED_FLAG              0x00000004
 #define USING_OTAA_FLAG             0x00000008
 #define TX_DONE_FLAG                0x00000010
+#define CONN_IN_PROGRESS_FLAG       0x00000020
 
 using namespace mbed;
 using namespace events;
@@ -156,6 +157,14 @@ lorawan_status_t LoRaWANStack::connect()
         return LORAWAN_STATUS_NOT_INITIALIZED;
     }
 
+    if (_ctrl_flags & CONN_IN_PROGRESS_FLAG) {
+        return LORAWAN_STATUS_BUSY;
+    }
+
+    if (_ctrl_flags & CONNECTED_FLAG) {
+        return LORAWAN_STATUS_ALREADY_CONNECTED;
+    }
+
     lorawan_status_t status = _loramac.prepare_join(NULL, MBED_CONF_LORA_OVER_THE_AIR_ACTIVATION);
 
     if (LORAWAN_STATUS_OK != status) {
@@ -171,6 +180,14 @@ lorawan_status_t LoRaWANStack::connect(const lorawan_connect_t &connect)
         return LORAWAN_STATUS_NOT_INITIALIZED;
     }
 
+    if (_ctrl_flags & CONN_IN_PROGRESS_FLAG) {
+        return LORAWAN_STATUS_BUSY;
+    }
+
+    if (_ctrl_flags & CONNECTED_FLAG) {
+        return LORAWAN_STATUS_ALREADY_CONNECTED;
+    }
+
     if (!(connect.connect_type == LORAWAN_CONNECTION_OTAA)
             && !(connect.connect_type == LORAWAN_CONNECTION_ABP)) {
         return LORAWAN_STATUS_PARAMETER_INVALID;
@@ -825,6 +842,8 @@ int LoRaWANStack::convert_to_msg_flag(const mcps_type_t type)
 
 lorawan_status_t LoRaWANStack::handle_connect(bool is_otaa)
 {
+    _ctrl_flags |= CONN_IN_PROGRESS_FLAG;
+
     if (is_otaa) {
         tr_debug("Initiating OTAA");
 
@@ -1150,30 +1169,23 @@ void LoRaWANStack::process_joining_state(lorawan_status_t &op_status)
 
 void LoRaWANStack::process_connected_state()
 {
+    _ctrl_flags |= CONNECTED_FLAG;
+    _ctrl_flags &= ~CONN_IN_PROGRESS_FLAG;
+
     if (_ctrl_flags & USING_OTAA_FLAG) {
         tr_debug("OTAA Connection OK!");
     }
 
     _lw_session.active = true;
     send_event_to_application(CONNECTED);
-    _ctrl_flags |= CONNECTED_FLAG;
 
     _device_current_state = DEVICE_STATE_IDLE;
 }
 
 void LoRaWANStack::process_connecting_state(lorawan_status_t &op_status)
 {
-    if (_device_current_state != DEVICE_STATE_IDLE
-            && _device_current_state != DEVICE_STATE_SHUTDOWN) {
-        op_status = LORAWAN_STATUS_BUSY;
-        return;
-    }
-
-    if (_ctrl_flags & CONNECTED_FLAG) {
-        tr_debug("Already connected");
-        op_status = LORAWAN_STATUS_OK;
-        return;
-    }
+    MBED_ASSERT(_device_current_state == DEVICE_STATE_IDLE ||
+                _device_current_state == DEVICE_STATE_SHUTDOWN);
 
     _device_current_state = DEVICE_STATE_CONNECTING;
 

features/lorawan/LoRaWANStack.h

@@ -88,78 +88,29 @@ class LoRaWANStack: private mbed::NonCopyable<LoRaWANStack> {
 
     /** Connect OTAA or ABP using Mbed-OS config system
      *
-     * Connect by Over The Air Activation or Activation By Personalization.
-     * You need to configure the connection properly via the Mbed OS configuration
-     * system.
-     *
-     * When connecting via OTAA, the return code for success (LORAWAN_STATUS_CONNECT_IN_PROGRESS) is negative.
-     * However, this is not a real error. It tells you that the connection is in progress and you will
-     * be notified of the completion via an event. By default, after the Join Accept message
-     * is received, base stations may provide the node with a CF-List that replaces
-     * all user-configured channels except the Join/Default channels. A CF-List can
-     * configure a maximum of five channels other than the default channels.
-     *
-     * In case of ABP, the CONNECTED event is posted before the call to `connect()` returns.
-     * To configure more channels, we recommend that you use the `set_channel_plan()` API after the connection.
-     * By default, the PHY layers configure only the mandatory Join channels. The retransmission back-off restrictions
-     * on these channels are severe and you may experience long delays or even failures in the confirmed traffic.
-     * If you add more channels, the aggregated duty cycle becomes much more relaxed as compared to the Join (default) channels only.
-     *
-     * **NOTES ON RECONNECTION:**
-     * Currently, the Mbed OS LoRaWAN implementation does not support non-volatile
-     * memory storage. Therefore, the state and frame counters cannot be restored after
-     * a power cycle. However, if you use the `disconnect()` API to shut down the LoRaWAN
-     * protocol, the state and frame counters are saved. Connecting again would try to
-     * restore the previous session. According to the LoRaWAN 1.0.2 specification, the frame counters are always reset
-     * to zero for OTAA and a new Join request lets the network server know
-     * that the counters need a reset. The same is said about the ABP but there
-     * is no way to convey this information to the network server. For a network
-     * server, an ABP device is always connected. That's why storing the frame counters
-     * is important, at least for ABP. That's why we try to restore frame counters from
-     * session information after a disconnection.
-     *
-     * @return         LORAWAN_STATUS_OK or LORAWAN_STATUS_CONNECT_IN_PROGRESS
-     *                 on success, or a negative error code on failure.
+     * @return    For ABP:  If everything goes well, LORAWAN_STATUS_OK is returned for first call followed by
+     *                      a 'CONNECTED' event. Otherwise a negative error code is returned.
+     *                      Any subsequent call will return LORAWAN_STATUS_ALREADY_CONNECTED and no event follows.
+     *
+     *            For OTAA: When a JoinRequest is sent, LORAWAN_STATUS_CONNECT_IN_PROGRESS is returned for the first call.
+     *                      Any subsequent call will return either LORAWAN_STATUS_BUSY (if the previous request for connection
+     *                      is still underway) or LORAWAN_STATUS_ALREADY_CONNECTED (if a network was already joined successfully).
+     *                      A 'CONNECTED' event is sent to the application when the JoinAccept is received.
      */
     lorawan_status_t connect();
 
     /** Connect OTAA or ABP with parameters
-     *
-     * All connection parameters are chosen by the user and provided in the
-     * data structure passed down.
-     *
-     * When connecting via OTAA, the return code for success (LORAWAN_STATUS_CONNECT_IN_PROGRESS) is negative.
-     * However, this is not a real error. It tells you that connection is in progress and you will
-     * be notified of completion via an event. By default, after Join Accept message
-     * is received, base stations may provide the node with a CF-List which replaces
-     * all user-configured channels except the Join/Default channels. A CF-List can
-     * configure a maximum of five channels other than the default channels.
-     *
-     * In case of ABP, the CONNECTED event is posted before the call to `connect()` returns.
-     * To configure more channels, we recommend that you use the `set_channel_plan()` API after the connection.
-     * By default, the PHY layers configure only the mandatory Join
-     * channels. The retransmission back-off restrictions on these channels
-     * are severe and you may experience long delays or even
-     * failures in the confirmed traffic. If you add more channels, the aggregated duty
-     * cycle becomes much more relaxed as compared to the Join (default) channels only.
-     *
-     * **NOTES ON RECONNECTION:**
-     * Currently, the Mbed OS LoRaWAN implementation does not support non-volatile
-     * memory storage. Therefore, the state and frame counters cannot be restored after
-     * a power cycle. However, if you use the `disconnect()` API to shut down the LoRaWAN
-     * protocol, the state and frame counters are saved. Connecting again would try to
-     * restore the previous session. According to the LoRaWAN 1.0.2 specification, the frame counters are always reset
-     * to zero for OTAA and a new Join request lets the network server know
-     * that the counters need a reset. The same is said about the ABP but there
-     * is no way to convey this information to the network server. For a network
-     * server, an ABP device is always connected. That's why storing the frame counters
-     * is important, at least for ABP. That's why we try to restore frame counters from
-     * session information after a disconnection.
      *
      * @param connect  Options for an end device connection to the gateway.
      *
-     * @return        LORAWAN_STATUS_OK or LORAWAN_STATUS_CONNECT_IN_PROGRESS,
-     *                a negative error code on failure.
+     * @return    For ABP:  If everything goes well, LORAWAN_STATUS_OK is returned for first call followed by
+     *                      a 'CONNECTED' event. Otherwise a negative error code is returned.
+     *                      Any subsequent call will return LORAWAN_STATUS_ALREADY_CONNECTED and no event follows.
+     *
+     *            For OTAA: When a JoinRequest is sent, LORAWAN_STATUS_CONNECT_IN_PROGRESS is returned for the first call.
+     *                      Any subsequent call will return either LORAWAN_STATUS_BUSY (if the previous request for connection
+     *                      is still underway) or LORAWAN_STATUS_ALREADY_CONNECTED (if a network was already joined successfully).
+     *                      A 'CONNECTED' event is sent to the application when the JoinAccept is received.
      */
     lorawan_status_t connect(const lorawan_connect_t &connect);
 

features/lorawan/lorastack/mac/LoRaMac.cpp

@@ -814,9 +814,11 @@ lorawan_status_t LoRaMac::send_join_request()
     status = prepare_frame(&mac_hdr, &fctrl, 0, NULL, 0);
 
     if (status == LORAWAN_STATUS_OK) {
-        status = schedule_tx();
+        if (schedule_tx() == LORAWAN_STATUS_OK) {
+            status = LORAWAN_STATUS_CONNECT_IN_PROGRESS;
+        }
     } else {
-        tr_error("Retransmission: error %d", status);
+        tr_error("Couldn't send a JoinRequest: error %d", status);
     }
 
     return status;

features/lorawan/lorawan_types.h

@@ -98,10 +98,11 @@ typedef enum lorawan_status {
 #if defined(LORAWAN_COMPLIANCE_TEST)
     LORAWAN_STATUS_COMPLIANCE_TEST_ON = -1019,     /**< Compliance test - is on-going */
 #endif
-    LORAWAN_STATUS_DUTYCYCLE_RESTRICTED = -1020,
-    LORAWAN_STATUS_NO_CHANNEL_FOUND = -1021,
-    LORAWAN_STATUS_NO_FREE_CHANNEL_FOUND = -1022,
-    LORAWAN_STATUS_METADATA_NOT_AVAILABLE = -1023
+    LORAWAN_STATUS_DUTYCYCLE_RESTRICTED = -1020,   /**< Transmission will continue after duty cycle backoff*/
+    LORAWAN_STATUS_NO_CHANNEL_FOUND = -1021,       /**< None of the channels is enabled at the moment*/
+    LORAWAN_STATUS_NO_FREE_CHANNEL_FOUND = -1022,  /**< None of the enabled channels is ready for another TX (duty cycle limited)*/
+    LORAWAN_STATUS_METADATA_NOT_AVAILABLE = -1023, /**< Meta-data after an RX or TX is stale*/
+    LORAWAN_STATUS_ALREADY_CONNECTED = -1024              /**< The device has already joined a network*/
 } lorawan_status_t;
 
 /** The lorawan_connect_otaa structure.