Adding acquisition of backoff time value

This API enables the application to get hold of remaining time after which
the transmission will take place. User can query the backoff time whenever
there is a packet in the TX pipe. If the event for the backoff expiry is
already queued, the stack does not provide backoff metadata.

Author: Hasnain Virk

features/lorawan/LoRaWANBase.h

@@ -369,6 +369,26 @@ class LoRaWANBase {
      *                       LORAWAN_STATUS_METADATA_NOT_AVAILABLE is returned.
      */
     virtual lorawan_status_t get_rx_metadata(lorawan_rx_metadata& metadata) = 0;
+
+    /** Get hold of backoff time
+     *
+     * In the TX path, because of automatic duty cycling, the transmission is delayed
+     * by a certain amount of time which is the backoff time. While the system schedules
+     * application data to be sent, the application can inquire about how much time is
+     * left in the actual transmission to happen.
+     *
+     * The system will provide you with a backoff time only if the application data is
+     * in the TX pipe. If however, the event is already queued for the transmission, this
+     * API returns a LORAWAN_STATUS_METADATA_NOT_AVAILABLE error code.
+     *
+     * @param    backoff    the inbound integer that will be carry the backoff time if it
+     *                      is available.
+     *
+     * @return              LORAWAN_STATUS_OK if the meta-data regarding backoff is available,
+     *                      otherwise LORAWAN_STATUS_METADATA_NOT_AVAILABLE is returned.
+     *
+     */
+    virtual lorawan_status_t get_backoff_metadata(int& backoff) = 0;
 };
 
 #endif /* LORAWAN_BASE_H_ */

features/lorawan/LoRaWANInterface.cpp

@@ -134,6 +134,12 @@ lorawan_status_t LoRaWANInterface::get_rx_metadata(lorawan_rx_metadata& metadata
     return _lw_stack.acquire_rx_metadata(metadata);
 }
 
+lorawan_status_t LoRaWANInterface::get_backoff_metadata(int& backoff)
+{
+    Lock lock(*this);
+    return _lw_stack.acquire_backoff_metadata(backoff);
+}
+
 int16_t LoRaWANInterface::receive(uint8_t port, uint8_t* data, uint16_t length, int flags)
 {
     Lock lock(*this);

features/lorawan/LoRaWANInterface.h

@@ -468,6 +468,26 @@ class LoRaWANInterface: public LoRaWANBase {
      */
     virtual lorawan_status_t get_rx_metadata(lorawan_rx_metadata& metadata);
 
+    /** Get hold of backoff time
+     *
+     * In the TX path, because of automatic duty cycling, the transmission is delayed
+     * by a certain amount of time which is the backoff time. While the system schedules
+     * application data to be sent, the application can inquire about how much time is
+     * left in the actual transmission to happen.
+     *
+     * The system will provide you with a backoff time only if the application data is
+     * in the TX pipe. If however, the event is already queued for the transmission, this
+     * API returns a LORAWAN_STATUS_METADATA_NOT_AVAILABLE error code.
+     *
+     * @param    backoff    the inbound integer that will be carry the backoff time if it
+     *                      is available.
+     *
+     * @return              LORAWAN_STATUS_OK if the meta-data regarding backoff is available,
+     *                      otherwise LORAWAN_STATUS_METADATA_NOT_AVAILABLE is returned.
+     *
+     */
+    virtual lorawan_status_t get_backoff_metadata(int& backoff);
+
     void lock(void) { _lw_stack.lock(); }
     void unlock(void) { _lw_stack.unlock(); }
 

features/lorawan/LoRaWANStack.cpp

@@ -446,6 +446,19 @@ lorawan_status_t LoRaWANStack::acquire_rx_metadata(lorawan_rx_metadata& metadata
     return LORAWAN_STATUS_METADATA_NOT_AVAILABLE;
 }
 
+lorawan_status_t LoRaWANStack::acquire_backoff_metadata(int& backoff)
+{
+    int id = _loramac.get_backoff_timer_event_id();
+
+    if (_loramac.get_backoff_timer_event_id() > 0) {
+        backoff = _queue->time_left(id);
+        return LORAWAN_STATUS_OK;
+    }
+
+    backoff = -1;
+    return LORAWAN_STATUS_METADATA_NOT_AVAILABLE;
+}
+
 /*****************************************************************************
  * Interrupt handlers                                                        *
  ****************************************************************************/

features/lorawan/LoRaWANStack.h

@@ -403,6 +403,18 @@ class LoRaWANStack: private mbed::NonCopyable<LoRaWANStack> {
      */
     lorawan_status_t acquire_rx_metadata(lorawan_rx_metadata& metadata);
 
+    /** Acquire backoff meta-data
+     *
+     * Get hold of backoff time after which the transmission will take place.
+     *
+     * @param    backoff     A reference to the inbound integer which will be
+     *                       filled with any backoff meta-data if available.
+     *
+     * @return               LORAWAN_STATUS_OK if successful,
+     *                       LORAWAN_STATUS_METADATA_NOT_AVAILABLE otherwise
+     */
+    lorawan_status_t acquire_backoff_metadata(int& backoff);
+
     void lock(void) { _loramac.lock(); }
     void unlock(void) { _loramac.unlock(); }
 

features/lorawan/lorastack/mac/LoRaMac.cpp

@@ -1008,6 +1008,11 @@ lorawan_status_t LoRaMac::send(loramac_mhdr_t *machdr, const uint8_t fport,
     return status;
 }
 
+int LoRaMac::get_backoff_timer_event_id(void)
+{
+    return _params.timers.backoff_timer.timer_id;
+}
+
 lorawan_status_t LoRaMac::schedule_tx()
 {
     channel_selection_params_t next_channel;

features/lorawan/lorastack/mac/LoRaMac.h

@@ -442,6 +442,11 @@ class LoRaMac {
      */
     void set_batterylevel_callback(mbed::Callback<uint8_t(void)> battery_level);
 
+    /**
+     * Returns the event ID of backoff timer.
+     */
+    int get_backoff_timer_event_id(void);
+
     /**
      * These locks trample through to the upper layers and make
      * the stack thread safe.