Merge pull request #6910 from hasnainvirk/metadata

LoRaWAN: Adding acquisition of metadata, backoff and a cancel_send() API

Author: Cruz Monrreal

features/lorawan/LoRaWANBase.h

@@ -337,6 +337,71 @@ class LoRaWANBase {
      *                          or other negative error code if request failed.
      */
     virtual lorawan_status_t set_device_class(device_class_t device_class) = 0;
+
+    /** Get hold of TX meta-data
+     *
+     * Use this method to acquire any TX meta-data related to previous
+     * transmission.
+     * TX meta-data is only available right after the transmission is completed.
+     * In other words, you can check for TX meta-data right after receiving the
+     * TX_DONE event.
+     *
+     * @param    metadata    the inbound structure that will be filled if the meta-data
+     *                       is available.
+     *
+     * @return               LORAWAN_STATUS_OK if the meta-data is available, otherwise
+     *                       LORAWAN_STATUS_METADATA_NOT_AVAILABLE is returned.
+     */
+    virtual lorawan_status_t get_tx_metadata(lorawan_tx_metadata &metadata) = 0;
+
+    /** Get hold of RX meta-data
+     *
+     * Use this method to acquire any RX meta-data related to current
+     * reception.
+     * RX meta-data is only available right after the reception is completed.
+     * In other words, you can check for RX meta-data right after receiving the
+     * RX_DONE event.
+     *
+     * @param    metadata    the inbound structure that will be filled if the meta-data
+     *                       is available.
+     *
+     * @return               LORAWAN_STATUS_OK if the meta-data is available, otherwise
+     *                       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;
+
+    /** Cancel outgoing transmission
+     *
+     * This API is used to cancel any outstanding transmission in the TX pipe.
+     * If an event for transmission is not already queued at the end of backoff timer,
+     * the system can cancel the outstanding outgoing packet. Otherwise, the system is
+     * busy sending and can't be held back.
+     *
+     * @return              LORAWAN_STATUS_OK if the sending is cancelled.
+     *                      LORAWAN_STATUS_BUSY otherwise.
+     *
+     */
+    virtual lorawan_status_t cancel_sending(void) = 0;
 };
 
 #endif /* LORAWAN_BASE_H_ */

features/lorawan/LoRaWANInterface.cpp

@@ -122,6 +122,30 @@ int16_t LoRaWANInterface::send(uint8_t port, const uint8_t* data, uint16_t lengt
     return _lw_stack.handle_tx(port, data, length, flags);
 }
 
+lorawan_status_t LoRaWANInterface::cancel_sending(void)
+{
+    Lock lock(*this);
+    return _lw_stack.stop_sending();
+}
+
+lorawan_status_t LoRaWANInterface::get_tx_metadata(lorawan_tx_metadata &metadata)
+{
+    Lock lock(*this);
+    return _lw_stack.acquire_tx_metadata(metadata);
+}
+
+lorawan_status_t LoRaWANInterface::get_rx_metadata(lorawan_rx_metadata &metadata)
+{
+    Lock lock(*this);
+    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

@@ -436,6 +436,72 @@ class LoRaWANInterface: public LoRaWANBase {
      */
     virtual lorawan_status_t set_device_class(const device_class_t device_class);
 
+    /** Get hold of TX meta-data
+     *
+     * Use this method to acquire any TX meta-data related to previous
+     * transmission.
+     * TX meta-data is only available right after the transmission is completed.
+     * In other words, you can check for TX meta-data right after receiving the
+     * TX_DONE event.
+     *
+     * @param    metadata    the inbound structure that will be filled if the meta-data
+     *                       is available.
+     *
+     * @return               LORAWAN_STATUS_OK if the meta-data is available, otherwise
+     *                       LORAWAN_STATUS_METADATA_NOT_AVAILABLE is returned.
+     */
+    virtual lorawan_status_t get_tx_metadata(lorawan_tx_metadata &metadata);
+
+    /** Get hold of RX meta-data
+     *
+     * Use this method to acquire any RX meta-data related to current
+     * reception.
+     * RX meta-data is only available right after the reception is completed.
+     * In other words, you can check for RX meta-data right after receiving the
+     * RX_DONE event.
+     *
+     * @param    metadata    the inbound structure that will be filled if the meta-data
+     *                       is available.
+     *
+     * @return               LORAWAN_STATUS_OK if the meta-data is available, otherwise
+     *                       LORAWAN_STATUS_METADATA_NOT_AVAILABLE is returned.
+     */
+    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);
+
+    /** Cancel outgoing transmission
+     *
+     * This API is used to cancel any outstanding transmission in the TX pipe.
+     * If an event for transmission is not already queued at the end of backoff timer,
+     * the system can cancel the outstanding outgoing packet. Otherwise, the system is
+     * busy sending and can't be held back. The system will not try to re-send if the
+     * outgoing message was a CONFIRMED message even if the ack is not received.
+     *
+     * @return              LORAWAN_STATUS_OK if the sending is cancelled.
+     *                      LORAWAN_STATUS_BUSY otherwise.
+     *
+     */
+    virtual lorawan_status_t cancel_sending(void);
+
     void lock(void) { _lw_stack.lock(); }
     void unlock(void) { _lw_stack.unlock(); }