Merge pull request #6059 from hasnainvirk/pr_branch

Enabling LoRaWAN technology in Mbed-OS 5.8

Author: cmonr

features/netsocket/LoRaRadio.h renamed to features/lorawan/LoRaRadio.h

@@ -18,6 +18,9 @@
 #ifndef LORARADIO_H_
 #define LORARADIO_H_
 
+#include "platform/Callback.h"
+#include "PinNames.h"
+
 /**
  * Structure to hold RF controls for LoRa Radio.
  * SX1276 have an extra control for the crystal (used in DOSCO-L072CZ)
@@ -131,17 +134,18 @@ typedef struct radio_settings {
  *
  */
 typedef struct radio_events {
-    /*  Tx Done callback prototype.
-     *
+    /**
+     * Callback when Transmission is done
      */
-    void (*tx_done) (void);
+    mbed::Callback<void()> tx_done;
 
-    /*  Tx Timeout callback prototype.
-     *
+    /**
+     * Callback when Transmission is timed out
      */
-    void (*tx_timeout) (void);
+    mbed::Callback<void()> tx_timeout;
 
-    /*  Rx Done callback prototype.
+    /**
+     * Rx Done callback prototype.
      *
      *  @param payload Received buffer pointer.
      *  @param size    Received buffer size.
@@ -150,29 +154,31 @@ typedef struct radio_events {
      *                     FSK : N/A (set to 0)
      *                     LoRa: SNR value in dB
      */
-    void (*rx_done) (uint8_t *payload, uint16_t size, int16_t rssi, int8_t snr);
+    mbed::Callback<void(uint8_t *payload, uint16_t size, int16_t rssi, int8_t snr)> rx_done;
 
-    /*  Rx Timeout callback prototype.
-     *
+    /**
+     * Callback when Reception is timed out
      */
-    void (*rx_timeout) (void);
+    mbed::Callback<void()> rx_timeout;
 
-    /*  Rx Error callback prototype.
-     *
+    /**
+     * Callback when Reception ends up in error
      */
-    void (*rx_error) (void);
+    mbed::Callback<void()> rx_error;
 
-    /*  FHSS Change Channel callback prototype.
-     *
-     *  @param current_channel   The index number of the current channel.
-     */
-    void (*fhss_change_channel) (uint8_t current_channel);
+   /**
+    * FHSS Change Channel callback prototype.
+    *
+    *  @param current_channel   The index number of the current channel.
+    */
+    mbed::Callback<void(uint8_t current_channel)> fhss_change_channel;
 
-    /*  CAD Done callback prototype.
+    /**
+     * CAD Done callback prototype.
      *
-     *  @param channel_activity_detected    Channel activity detected during the CAD.
+     *  @param channel_busy    True, if Channel activity detected.
      */
-    void (*cad_done) (bool channel_activity_detected);
+    mbed::Callback<void(bool channel_busy)> cad_done;
 } radio_events_t;
 
 /**

features/netsocket/LoRaWANBase.h renamed to features/lorawan/LoRaWANBase.h

@@ -31,20 +31,20 @@ class LoRaWANBase {
      *
      * @param queue A pointer to EventQueue provided by the application.
      *
-     * @return         LORA_MAC_STATUS_OK on success, a negative error code on
+     * @return         LORAWAN_STATUS_OK on success, a negative error code on
      *                 failure.
      */
-    virtual lora_mac_status_t initialize(events::EventQueue *queue) = 0;
+    virtual lorawan_status_t initialize(events::EventQueue *queue) = 0;
 
     /** Connect OTAA or ABP by setup.
      *
      * Connect by Over The Air Activation or Activation By Personalization.
      * The connection type is selected at the setup.
      *
-     * @return         LORA_MAC_STATUS_OK on success, a negative error code on
+     * @return         LORAWAN_STATUS_OK on success, a negative error code on
      *                 failure.
      */
-    virtual lora_mac_status_t connect() = 0;
+    virtual lorawan_status_t connect() = 0;
 
     /** Connect OTAA or ABP by parameters
      *
@@ -53,46 +53,78 @@ class LoRaWANBase {
      * You need to define the parameters in the main application.
      *
      * @param connect       Options how end-device will connect to gateway
-     * @return              LORA_MAC_STATUS_OK on success, negative error code
+     * @return              LORAWAN_STATUS_OK on success, negative error code
      *                      on failure
      */
-    virtual lora_mac_status_t connect(const lorawan_connect_t &connect) = 0;
+    virtual lorawan_status_t connect(const lorawan_connect_t &connect) = 0;
 
     /** Disconnects the current session.
      *
-     * @return         LORA_MAC_STATUS_OK on success, a negative error code on failure.
+     * @return         LORAWAN_STATUS_OK on success, a negative error code on failure.
      */
-    virtual lora_mac_status_t disconnect() = 0;
+    virtual lorawan_status_t disconnect() = 0;
+
+    /** Validate the connectivity with the network.
+     *
+     * Application may use this API to submit a request to the stack for
+     * validation of its connectivity to a Network Server. Under the hood, this
+     * API schedules a Link Check Request command (LinkCheckReq) for the network
+     * server and once the response, i.e., LinkCheckAns MAC command is received
+     * from the Network Server, user provided method is called.
+     *
+     * This API is usable only when the link check response is callback set by
+     * the application. See add_lora_app_callbacks API. If the above mentioned
+     * callback is not set, a LORAWAN_STATUS_PARAMETER_INVALID error is thrown.
+     *
+     * First parameter to callback function is the demodulation margin and
+     * the second parameter is the number of gateways that successfully received
+     * the last request.
+     *
+     * A 'Link Check Request' MAC command remains set for every subsequent
+     * transmission, until/unless application explicitly turns it off using
+     * remove_link_check_request() API.
+     *
+     * @return          LORAWAN_STATUS_OK on successfully queuing a request, or
+     *                  a negative error code on failure.
+     *
+     */
+    virtual lorawan_status_t add_link_check_request() = 0;
+
+    /** Detaches Link Request MAC command.
+     *
+     * Removes sticky MAC command for link check request.
+     */
+    virtual void remove_link_check_request() = 0;
 
     /** Sets up a particular data rate of choice
      *
      * @param data_rate   Intended data rate e.g., DR_0, DR_1 etc.
      *                    Caution is advised as the macro DR_* can mean different
      *                    things while being in a different region.
-     * @return            LORA_MAC_STATUS_OK if everything goes well, otherwise
+     * @return            LORAWAN_STATUS_OK if everything goes well, otherwise
      *                    a negative error code.
      */
-    virtual lora_mac_status_t set_datarate(uint8_t data_rate) = 0;
+    virtual lorawan_status_t set_datarate(uint8_t data_rate) = 0;
 
     /** Enables adaptive data rate (ADR)
      *
      * Underlying LoRaPHY and LoRaMac layers handle the data rate automatically
      * for the user based upon radio conditions (network congestion).
      *
-     * @return             LORA_MAC_STATUS_OK on success, negative error code
+     * @return             LORAWAN_STATUS_OK on success, negative error code
      *                     on failure.
      */
-    virtual lora_mac_status_t enable_adaptive_datarate() = 0;
+    virtual lorawan_status_t enable_adaptive_datarate() = 0;
 
     /** Disables adaptive data rate
      *
      * When adaptive data rate (ADR) is disabled, user can either set a certain
      * data rate or the Mac layer will choose a default value.
      *
-     * @return             LORA_MAC_STATUS_OK on success, negative error code
+     * @return             LORAWAN_STATUS_OK on success, negative error code
      *                     on failure.
      */
-    virtual lora_mac_status_t disable_adaptive_datarate() = 0;
+    virtual lorawan_status_t disable_adaptive_datarate() = 0;
 
     /** Sets up retry counter for confirmed messages
      *
@@ -108,36 +140,36 @@ class LoRaWANBase {
      *
      * @param count     number of retries for confirmed messages
      *
-     * @return          LORA_MAC_STATUS_OK or a negative error code
+     * @return          LORAWAN_STATUS_OK or a negative error code
      */
-    virtual lora_mac_status_t set_confirmed_msg_retries(uint8_t count) = 0;
+    virtual lorawan_status_t set_confirmed_msg_retries(uint8_t count) = 0;
 
     /** Sets channel plan
      *
      * @param channel_plan  The defined channel plans to be set.
      * @return              0 on success, a negative error code on failure.
      */
-    virtual lora_mac_status_t set_channel_plan(const lora_channelplan_t &channel_plan) = 0;
+    virtual lorawan_status_t set_channel_plan(const lorawan_channelplan_t &channel_plan) = 0;
 
     /** Gets the current channel plan.
      *
      * @param  channel_plan     The current channel information.
      *
-     * @return                  LORA_MAC_STATUS_OK on success, a negative error
+     * @return                  LORAWAN_STATUS_OK on success, a negative error
      *                          code on failure.
      */
-    virtual lora_mac_status_t get_channel_plan(lora_channelplan_t &channel_plan) = 0;
+    virtual lorawan_status_t get_channel_plan(lorawan_channelplan_t &channel_plan) = 0;
 
     /** Removes currently active channel plan
      *
      * Default channels (channels where Base Stations are listening) are not
      * allowed to be removed. So when a plan is abolished, only non-default
      * channels are removed.
      *
-     * @return                  LORA_MAC_STATUS_OK on success, negative error
+     * @return                  LORAWAN_STATUS_OK on success, negative error
      *                          code on failure
      */
-    virtual lora_mac_status_t remove_channel_plan() = 0;
+    virtual lorawan_status_t remove_channel_plan() = 0;
 
     /** Removes a given single channel
      *
@@ -146,10 +178,10 @@ class LoRaWANBase {
      *
      * @param    index          The channel index
      *
-     * @return                  LORA_MAC_STATUS_OK on success, negative error
+     * @return                  LORAWAN_STATUS_OK on success, negative error
      *                          code on failure
      */
-    virtual lora_mac_status_t remove_channel(uint8_t index) = 0;
+    virtual lorawan_status_t remove_channel(uint8_t index) = 0;
 
     /** Send message to gateway
      *
@@ -182,7 +214,7 @@ class LoRaWANBase {
      *
      *
      * @return                  The number of bytes sent, or
-     *                          LORA_MAC_STATUS_WOULD_BLOCK if another TX is
+     *                          LORAWAN_STATUS_WOULD_BLOCK if another TX is
      *                          ongoing, or a negative error code on failure.
      */
     virtual int16_t send(uint8_t port, const uint8_t* data,
@@ -223,7 +255,7 @@ class LoRaWANBase {
      * @return                  It could be one of these:
      *                             i)   0 if there is nothing else to read.
      *                             ii)  Number of bytes written to user buffer.
-     *                             iii) LORA_MAC_STATUS_WOULD_BLOCK if there is
+     *                             iii) LORAWAN_STATUS_WOULD_BLOCK if there is
      *                                  nothing available to read at the moment.
      *                             iv)  A negative error code on failure.
      */
@@ -298,7 +330,7 @@ class LoRaWANBase {
      * @param callbacks         A pointer to the structure containing application
      *                          callbacks.
      */
-    virtual lora_mac_status_t add_app_callbacks(lorawan_app_callbacks_t *callbacks) = 0;
+    virtual lorawan_status_t add_app_callbacks(lorawan_app_callbacks_t *callbacks) = 0;
 };
 
 #endif /* LORAWAN_BASE_H_ */