LoRaWANInterface.h

00001 /**
00002  * Copyright (c) 2017, Arm Limited and affiliates.
00003  * SPDX-License-Identifier: Apache-2.0
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License");
00006  * you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  *     http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS,
00013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 
00018 /** @addtogroup LoRaWAN
00019  * Mbed OS LoRaWAN Stack
00020  *  @{
00021  */
00022 
00023 #ifndef LORAWANINTERFACE_H_
00024 #define LORAWANINTERFACE_H_
00025 
00026 #include "platform/Callback.h"
00027 #include "platform/ScopedLock.h"
00028 #include "events/EventQueue.h"
00029 #include "LoRaWANStack.h"
00030 #include "LoRaRadio.h"
00031 #include "lorawan_types.h"
00032 
00033 // Forward declaration of LoRaPHY class
00034 class LoRaPHY;
00035 
00036 /** LoRaWANInterface Class
00037  * A network interface for LoRaWAN
00038  */
00039 class LoRaWANInterface {
00040 
00041 public:
00042 
00043     /** Constructs a LoRaWANInterface using the LoRaWANStack instance underneath.
00044      *
00045      * Currently, LoRaWANStack is a singleton and you should only
00046      * construct a single instance of LoRaWANInterface.
00047      *
00048      * LoRaWANInterface will construct PHY based on "lora.phy" setting in mbed_app.json.
00049      *
00050      * @param radio A reference to radio object
00051      */
00052     LoRaWANInterface(LoRaRadio &radio);
00053 
00054     /** Constructs a LoRaWANInterface using the user provided PHY object.
00055 
00056      * @param radio A reference to radio object
00057      * @param phy   A reference to PHY object
00058      */
00059     LoRaWANInterface(LoRaRadio &radio, LoRaPHY &phy);
00060 
00061     ~LoRaWANInterface();
00062 
00063     /** Initialize the LoRa stack.
00064      *
00065      * You must call this before using the LoRa stack.
00066      *
00067      * @param queue A pointer to EventQueue provided by the application.
00068      *
00069      * @return         LORAWAN_STATUS_OK on success, a negative error code on failure:
00070      *                 LORAWAN_STATUS_PARAMETER_INVALID is NULL queue is given.
00071      */
00072     lorawan_status_t initialize(events::EventQueue *queue);
00073 
00074     /** Connect OTAA or ABP using the Mbed OS config system
00075      *
00076      * Connect by Over The Air Activation or Activation By Personalization.
00077      * You need to configure the connection properly using the Mbed OS configuration system.
00078      *
00079      * When connecting through OTAA, the return code for success (LORAWAN_STATUS_CONNECT_IN_PROGRESS)
00080      * is negative. However, this is not a real error. It tells you that the connection is in progress,
00081      * and an event will notify you of the completion. By default, after the Join Accept message is
00082      * received, base stations may provide the node with a CF-List that replaces all user-configured
00083      * channels except the Join/Default channels. A CF-List can configure a maximum of five channels
00084      * other than the default channels.
00085      *
00086      * To configure more channels, we recommend that you use the `set_channel_plan()` API after the connection.
00087      * By default, the PHY layers configure only the mandatory Join channels. The retransmission back-off
00088      * restrictions on these channels are severe, and you may experience long delays or even failures
00089      * in the confirmed traffic. If you add more channels, the aggregated duty cycle becomes much more
00090      * relaxed as compared to the Join (default) channels only.
00091      *
00092      * **NOTES ON RECONNECTION:**
00093      * Currently, the Mbed OS LoRaWAN implementation does not support non-volatile memory storage.
00094      * Therefore, the state and frame counters cannot be restored after a power cycle. However,
00095      * if you use the `disconnect()` API to shut down the LoRaWAN protocol, the state and frame
00096      * counters are saved. Connecting again restores the previous session. According to the LoRaWAN
00097      * 1.0.2 specification, the frame counters are always reset to 0 for OTAA, and a new Join request
00098      * lets the network server know that the counters need a reset. The same is said about the ABP,
00099      * but there is no way to convey this information to the network server. For a network server,
00100      * an ABP device is always connected. That's why storing the frame counters is important for ABP.
00101      * That's why we restore frame counters from session information after a disconnection.
00102      *
00103      * @return    Common:   LORAWAN_STATUS_NOT_INITIALIZED   if system is not initialized with initialize(),
00104      *                      LORAWAN_STATUS_PARAMETER_INVALID if connection parameters are invalid.
00105      *
00106      *            For ABP:  If everything goes well, LORAWAN_STATUS_OK is returned for first call
00107      *                      followed by a 'CONNECTED' event. Otherwise a negative error code is returned:
00108      *                      Any subsequent call will return LORAWAN_STATUS_ALREADY_CONNECTED and no event follows.
00109      *
00110      *            For OTAA: When a JoinRequest is sent, LORAWAN_STATUS_CONNECT_IN_PROGRESS is returned for
00111      *                      the first call. Any subsequent call will return either LORAWAN_STATUS_BUSY
00112      *                      (if the previous request for connection is still underway) or
00113      *                      LORAWAN_STATUS_ALREADY_CONNECTED (if a network was already joined successfully).
00114      *                      A 'CONNECTED' event is sent to the application when the JoinAccept is received.
00115      */
00116     lorawan_status_t connect();
00117 
00118     /** Connect OTAA or ABP with parameters
00119      *
00120      * All connection parameters are chosen by you and provided in the data structure passed down.
00121      *
00122      * When connecting using OTAA, the return code for success (LORAWAN_STATUS_CONNECT_IN_PROGRESS)
00123      * is negative. However, this is not a real error. It tells you that connection is in progress,
00124      * and an event will notify you of completion. By default, after Join Accept message is received,
00125      * base stations may provide the node with a CF-List that replaces all user-configured channels
00126      * except the Join/Default channels. A CF-List can configure a maximum of five channels other
00127      * than the default channels.
00128      *
00129      * To configure more channels, we recommend that you use the `set_channel_plan()` API after
00130      * the connection. By default, the PHY layers configure only the mandatory Join channels.
00131      * The retransmission back-off restrictions on these channels are severe, and you may experience
00132      * long delays or even failures in the confirmed traffic. If you add more channels, the aggregated
00133      * duty cycle becomes much more relaxed as compared to the Join (default) channels only.
00134      *
00135      * **NOTES ON RECONNECTION:**
00136      * Currently, the Mbed OS LoRaWAN implementation does not support non-volatile memory storage.
00137      * Therefore, the state and frame counters cannot be restored after a power cycle. However,
00138      * if you use the `disconnect()` API to shut down the LoRaWAN protocol, the state and frame
00139      * counters are saved. Connecting again restores the previous session. According to the LoRaWAN
00140      * 1.0.2 specification, the frame counters are always reset to zero for OTAA, and a new Join
00141      * request lets the network server know that the counters need a reset. The same is said about
00142      * the ABP, but there is no way to convey this information to the network server. For a network
00143      * server, an ABP device is always connected. That's why storing the frame counters is important
00144      * for ABP. That's why we restore frame counters from session information after a disconnection.
00145      *
00146      * @param connect  Options for an end device connection to the gateway.
00147      *
00148      * @return    Common:   LORAWAN_STATUS_NOT_INITIALIZED   if system is not initialized with initialize(),
00149      *                      LORAWAN_STATUS_PARAMETER_INVALID if connection parameters are invalid.
00150      *
00151      *            For ABP:  If everything goes well, LORAWAN_STATUS_OK is returned for first call followed
00152      *                      by a 'CONNECTED' event. Otherwise a negative error code is returned.
00153      *                      Any subsequent call will return LORAWAN_STATUS_ALREADY_CONNECTED and no event follows.
00154      *
00155      *            For OTAA: When a JoinRequest is sent, LORAWAN_STATUS_CONNECT_IN_PROGRESS is returned for the
00156      *                      first call. Any subsequent call will return either LORAWAN_STATUS_BUSY
00157      *                      (if the previous request for connection is still underway) or LORAWAN_STATUS_ALREADY_CONNECTED
00158      *                      (if a network was already joined successfully).
00159      *                      A 'CONNECTED' event is sent to the application when the JoinAccept is received.
00160      */
00161     lorawan_status_t connect(const lorawan_connect_t &connect);
00162 
00163     /** Disconnect the current session.
00164      *
00165      * @return         LORAWAN_STATUS_DEVICE_OFF on success, a negative error code on failure:
00166      *                 LORAWAN_STATUS_NOT_INITIALIZED if system is not initialized with initialize(),
00167      */
00168     lorawan_status_t disconnect();
00169 
00170     /** Validate the connectivity with the network.
00171      *
00172      * Application may use this API to submit a request to the stack for validation of its connectivity
00173      * to a Network Server. Under the hood, this API schedules a Link Check Request command (LinkCheckReq)
00174      * for the network server and once the response, i.e., LinkCheckAns MAC command is received from
00175      * the Network Server, user provided method is called.
00176      *
00177      * One way to use this API may be the validation of connectivity after a long deep sleep.
00178      * Mbed LoRaWANStack follows the MAC commands with data frame payload, so the application needs
00179      * to send something, and the Network Server may respond during the RX slots.
00180      *
00181      * This API is usable only when the application sets the 'link_check_resp' callback.
00182      * See add_lora_app_callbacks API. If the above mentioned callback is not set,
00183      * a LORAWAN_STATUS_PARAMETER_INVALID error is thrown.
00184      *
00185      * The first parameter to callback function is the demodulation margin, and the second parameter
00186      * is the number of gateways that successfully received the last request.
00187      *
00188      * A 'Link Check Request' MAC command remains set for every subsequent transmission, until/unless
00189      * the application explicitly turns it off using the remove_link_check_request() API.
00190      *
00191      * @return          LORAWAN_STATUS_OK on successfully queuing a request, or
00192      *                  a negative error code on failure:
00193      *                  LORAWAN_STATUS_NOT_INITIALIZED   if system is not initialized with initialize(),
00194      *                  LORAWAN_STATUS_PARAMETER_INVALID if link_check_resp callback method is not set.
00195      *
00196      */
00197     lorawan_status_t add_link_check_request();
00198 
00199     /** Removes link check request sticky MAC command.
00200      *
00201      * Any already queued request may still be completed. However, no new requests will be made.
00202      */
00203     void remove_link_check_request();
00204 
00205     /** Sets up a particular data rate
00206      *
00207      * @param data_rate   The intended data rate, for example DR_0 or DR_1.
00208      *                    Please note that the macro DR_* can mean different things in different regions.
00209      * @return            LORAWAN_STATUS_OK if everything goes well, otherwise a negative error code:
00210      *                    LORAWAN_STATUS_NOT_INITIALIZED   if system is not initialized with initialize(),
00211      *                    LORAWAN_STATUS_PARAMETER_INVALID if ADR is enabled or invalid data rate is given
00212      */
00213     lorawan_status_t set_datarate(uint8_t data_rate);
00214 
00215     /** Enables adaptive data rate (ADR)
00216      *
00217      * The underlying LoRaPHY and LoRaMac layers handle the data rate automatically
00218      * based on the radio conditions (network congestion).
00219      *
00220      * @return             LORAWAN_STATUS_OK on success, negative error code on failure:
00221      *                     LORAWAN_STATUS_NOT_INITIALIZED if system is not initialized with initialize()
00222      */
00223     lorawan_status_t enable_adaptive_datarate();
00224 
00225     /** Disables adaptive data rate
00226      *
00227      * When adaptive data rate (ADR) is disabled, either you can set a certain
00228      * data rate, or the MAC layer selects a default value.
00229      *
00230      * @return             LORAWAN_STATUS_OK on success, negative error code on failure:
00231      *                     LORAWAN_STATUS_NOT_INITIALIZED if system is not initialized with initialize()
00232      */
00233     lorawan_status_t disable_adaptive_datarate();
00234 
00235     /** Sets up the retry counter for confirmed messages.
00236      *
00237      * Valid for confirmed messages only.
00238      *
00239      * The number of trials to transmit the frame, if the LoRaMAC layer did not receive an
00240      * acknowledgment. The MAC performs a data rate adaptation as in the LoRaWAN Specification
00241      * V1.0.2, chapter 18.4, table on page 64.
00242      *
00243      * Note that if the number of retries is set to 1 or 2, MAC does not decrease the data rate,
00244      * if the LoRaMAC layer did not receive an acknowledgment.
00245      *
00246      * @param count     The number of retries for confirmed messages.
00247      *
00248      * @return          LORAWAN_STATUS_OK or a negative error code on failure:
00249      *                  LORAWAN_STATUS_NOT_INITIALIZED   if system is not initialized with initialize()
00250      *                  LORAWAN_STATUS_PARAMETER_INVALID if count >= 255
00251      */
00252     lorawan_status_t set_confirmed_msg_retries(uint8_t count);
00253 
00254     /** Sets the channel plan.
00255      *
00256      * You can provide a list of channels with appropriate parameters filled in. However,
00257      * this list is not absolute. The stack applies a CF-List whenever available, which means
00258      * that the network can overwrite your channel frequency settings right after Join Accept
00259      * is received. You may try to set up any channel or channels after that, and if the channel
00260      * requested is already active, the request is silently ignored. A negative error code is
00261      * returned if there is any problem with parameters.
00262      *
00263      * Please note that you can also use this API to add a single channel to the existing channel plan.
00264      *
00265      * There is no reverse mechanism in the 1.0.2 specification for a node to request a particular
00266      * channel. Only the network server can initiate such a request.
00267      * You need to ensure that the corresponding base station supports the channel or channels being added.
00268      *
00269      * If your list includes a default channel (a channel where Join Requests are received),
00270      * you cannot fully configure the channel parameters. Either leave the channel settings to default,
00271      * or check your corresponding PHY layer implementation. For example, LoRaPHYE868.
00272      *
00273      * @param channel_plan      The channel plan to set.
00274      *
00275      * @return              LORAWAN_STATUS_OK on success, a negative error code on failure:
00276      *                      LORAWAN_STATUS_NOT_INITIALIZED   if system is not initialized with initialize(),
00277      *                      LORAWAN_STATUS_PARAMETER_INVALID if number of channels is exceeding the PHY limit,
00278      *                      LORAWAN_STATUS_DATARATE_INVALID  if invalid data rate is given,
00279      *                      LORAWAN_STATUS_FREQUENCY_INVALID if invalid frequency is given,
00280      *                      LORAWAN_STATUS_FREQ_AND_DR_INVALID if invalid data rate and freqency are given,
00281      *                      LORAWAN_STATUS_BUSY              if TX currently ongoing,
00282      *                      LORAWAN_STATUS_SERVICE_UNKNOWN   if custom channel plans are disabled in PHY
00283      */
00284     lorawan_status_t set_channel_plan(const lorawan_channelplan_t &channel_plan);
00285 
00286     /** Gets the channel plans from the LoRa stack.
00287      *
00288      * Once you have selected a particular PHY layer, a set of channels is automatically activated.
00289      * Right after connecting, you can use this API to see the current plan. Otherwise, this API
00290      * returns the channel plan that you have set using `set_channel_plan()`.
00291      *
00292      * @param  channel_plan     The current channel plan information.
00293      *
00294      * @return              LORAWAN_STATUS_OK on success, a negative error code on failure:
00295      *                      LORAWAN_STATUS_NOT_INITIALIZED if system is not initialized with initialize(),
00296      *                      LORAWAN_STATUS_SERVICE_UNKNOWN if custom channel plans are disabled in PHY
00297      */
00298     lorawan_status_t get_channel_plan(lorawan_channelplan_t &channel_plan);
00299 
00300     /** Removes an active channel plan.
00301      *
00302      * You cannot remove default channels (the channels the base stations are listening to).
00303      * When a plan is abolished, only the non-default channels are removed.
00304      *
00305      * @return              LORAWAN_STATUS_OK on success, negative error code on failure
00306      *                      LORAWAN_STATUS_NOT_INITIALIZED   if system is not initialized with initialize(),
00307      *                      LORAWAN_STATUS_BUSY              if TX currently ongoing,
00308      *                      LORAWAN_STATUS_SERVICE_UNKNOWN   if custom channel plans are disabled in PHY
00309      */
00310     lorawan_status_t remove_channel_plan();
00311 
00312     /** Removes a single channel.
00313      *
00314      * You cannot remove default channels (the channels the base stations are listening to).
00315      *
00316      * @param    index      The channel index.
00317      *
00318      * @return              LORAWAN_STATUS_OK on success, negative error code on failure:
00319      *                      LORAWAN_STATUS_NOT_INITIALIZED   if system is not initialized with initialize(),
00320      *                      LORAWAN_STATUS_PARAMETER_INVALID if invalid channel index is given,
00321      *                      LORAWAN_STATUS_BUSY              if TX currently ongoing,
00322      *                      LORAWAN_STATUS_SERVICE_UNKNOWN   if custom channel plans are disabled in PHY
00323      */
00324     lorawan_status_t remove_channel(uint8_t index);
00325 
00326     /** Send message to gateway
00327      *
00328      * @param port          The application port number. Port numbers 0 and 224 are reserved,
00329      *                      whereas port numbers from 1 to 223 (0x01 to 0xDF) are valid port numbers.
00330      *                      Anything out of this range is illegal.
00331      *
00332      * @param data          A pointer to the data being sent. The ownership of the buffer is not transferred.
00333      *                      The data is copied to the internal buffers.
00334      *
00335      * @param length        The size of data in bytes.
00336      *
00337      * @param flags         A flag used to determine what type of message is being sent, for example:
00338      *
00339      *                      MSG_UNCONFIRMED_FLAG = 0x01
00340      *                      MSG_CONFIRMED_FLAG   = 0x02
00341      *                      MSG_MULTICAST_FLAG   = 0x04
00342      *                      MSG_PROPRIETARY_FLAG = 0x08
00343      *
00344      *                      All flags are mutually exclusive, and MSG_MULTICAST_FLAG cannot be set.
00345      *
00346      * @return              The number of bytes sent, or a negative error code on failure:
00347      *                      LORAWAN_STATUS_NOT_INITIALIZED   if system is not initialized with initialize(),
00348      *                      LORAWAN_STATUS_NO_ACTIVE_SESSIONS if connection is not open,
00349      *                      LORAWAN_STATUS_WOULD_BLOCK       if another TX is ongoing,
00350      *                      LORAWAN_STATUS_PORT_INVALID      if trying to send to an invalid port (e.g. to 0)
00351      *                      LORAWAN_STATUS_PARAMETER_INVALID if NULL data pointer is given or flags are invalid.
00352      */
00353     int16_t send(uint8_t port, const uint8_t *data, uint16_t length, int flags);
00354 
00355     /** Receives a message from the Network Server on a specific port.
00356      *
00357      * @param port          The application port number. Port numbers 0 and 224 are reserved,
00358      *                      whereas port numbers from 1 to 223 (0x01 to 0xDF) are valid port numbers.
00359      *                      Anything out of this range is illegal.
00360      *
00361      * @param data          A pointer to buffer where the received data will be stored.
00362      *
00363      * @param length        The size of data in bytes.
00364      *
00365      * @param flags         A flag is used to determine what type of message is being sent, for example:
00366      *
00367      *                      MSG_UNCONFIRMED_FLAG = 0x01
00368      *                      MSG_CONFIRMED_FLAG   = 0x02
00369      *                      MSG_MULTICAST_FLAG   = 0x04
00370      *                      MSG_PROPRIETARY_FLAG = 0x08
00371      *
00372      *                      All flags can be used in conjunction with one another depending on the intended
00373      *                      use case or reception expectation.
00374      *
00375      *                      For example, MSG_CONFIRMED_FLAG and MSG_UNCONFIRMED_FLAG are
00376      *                      not mutually exclusive. In other words, the user can subscribe to
00377      *                      receive both CONFIRMED AND UNCONFIRMED messages at the same time.
00378      *
00379      * @return              It could be one of these:
00380      *                       i)   0 if there is nothing else to read.
00381      *                       ii)  Number of bytes written to user buffer.
00382      *                       iii) A negative error code on failure:
00383      *                       LORAWAN_STATUS_NOT_INITIALIZED   if system is not initialized with initialize(),
00384      *                       LORAWAN_STATUS_NO_ACTIVE_SESSIONS if connection is not open,
00385      *                       LORAWAN_STATUS_WOULD_BLOCK        if there is nothing available to read at the moment,
00386      *                       LORAWAN_STATUS_PARAMETER_INVALID  if NULL data or length is given,
00387      *                       LORAWAN_STATUS_WOULD_BLOCK        if incorrect port or flags are given,
00388      */
00389     int16_t receive(uint8_t port, uint8_t *data, uint16_t length, int flags);
00390 
00391     /** Receives a message from the Network Server on any port.
00392      *
00393      * @param data          A pointer to buffer where the received data will be stored.
00394      *
00395      * @param length        The size of data in bytes
00396      *
00397      * @param port          Return the number of port from which message was received.
00398      *
00399      * @param flags         Return flags to determine what type of message was received.
00400      *                      MSG_UNCONFIRMED_FLAG = 0x01
00401      *                      MSG_CONFIRMED_FLAG   = 0x02
00402      *                      MSG_MULTICAST_FLAG   = 0x04
00403      *                      MSG_PROPRIETARY_FLAG = 0x08
00404      *
00405      * @return              It could be one of these:
00406      *                       i)   0 if there is nothing else to read.
00407      *                       ii)  Number of bytes written to user buffer.
00408      *                       iii) A negative error code on failure:
00409      *                       LORAWAN_STATUS_NOT_INITIALIZED   if system is not initialized with initialize(),
00410      *                       LORAWAN_STATUS_NO_ACTIVE_SESSIONS if connection is not open,
00411      *                       LORAWAN_STATUS_PARAMETER_INVALID if NULL data or length is given,
00412      *                       LORAWAN_STATUS_WOULD_BLOCK if there is nothing available to read at the moment.
00413      */
00414     int16_t receive(uint8_t *data, uint16_t length, uint8_t &port, int &flags);
00415 
00416     /** Add application callbacks to the stack.
00417      *
00418      * An example of using this API with a latch onto 'lorawan_events' could be:
00419      *
00420      *\code
00421      *  LoRaWANInterface lorawan(radio);
00422      *  lorawan_app_callbacks_t cbs;
00423      *  static void my_event_handler();
00424      *
00425      *  int main()
00426      *  {
00427      *      lorawan.initialize();
00428      *      cbs.lorawan_events = mbed::callback(my_event_handler);
00429      *      lorawan.add_app_callbacks(&cbs);
00430      *      lorawan.connect();
00431      *  }
00432      *
00433      *  static void my_event_handler(lorawan_event_t event)
00434      *  {
00435      *      switch(event) {
00436      *          case CONNECTED:
00437      *              //do something
00438      *              break;
00439      *          case DISCONNECTED:
00440      *              //do something
00441      *              break;
00442      *          case TX_DONE:
00443      *              //do something
00444      *              break;
00445      *          default:
00446      *              break;
00447      *      }
00448      *  }
00449      *
00450      *\endcode
00451      *
00452      * @param callbacks     A pointer to the structure containing application callbacks.
00453      *
00454      * @return              LORAWAN_STATUS_OK on success, a negative error code on failure:
00455      *                      LORAWAN_STATUS_NOT_INITIALIZED   if system is not initialized with initialize(),
00456      *                      LORAWAN_STATUS_PARAMETER_INVALID if events callback is not set
00457      */
00458     lorawan_status_t add_app_callbacks(lorawan_app_callbacks_t *callbacks);
00459 
00460     /** Change device class
00461      *
00462      * Change current device class.
00463      *
00464      * @param    device_class   The device class
00465      *
00466      * @return              LORAWAN_STATUS_OK on success or other negative error code if request failed:
00467      *                      LORAWAN_STATUS_NOT_INITIALIZED if system is not initialized with initialize(),
00468      *                      LORAWAN_STATUS_UNSUPPORTED if requested class is not supported
00469      */
00470     lorawan_status_t set_device_class(device_class_t device_class);
00471 
00472     /** Get hold of TX meta-data
00473      *
00474      * Use this method to acquire any TX meta-data related to previous transmission.
00475      * TX meta-data is only available right after the transmission is completed.
00476      * In other words, you can check for TX meta-data right after receiving the TX_DONE event.
00477      *
00478      * @param    metadata   the inbound structure that will be filled if the meta-data is available.
00479      *
00480      * @return              LORAWAN_STATUS_OK if the meta-data is available,
00481      *                      otherwise other negative error code if request failed:
00482      *                      LORAWAN_STATUS_NOT_INITIALIZED if system is not initialized with initialize(),
00483      *                      LORAWAN_STATUS_METADATA_NOT_AVAILABLE if the meta-data is not available
00484      */
00485     lorawan_status_t get_tx_metadata(lorawan_tx_metadata &metadata);
00486 
00487     /** Get hold of RX meta-data
00488      *
00489      * Use this method to acquire any RX meta-data related to current reception.
00490      * RX meta-data is only available right after the reception is completed.
00491      * In other words, you can check for RX meta-data right after receiving the RX_DONE event.
00492      *
00493      * @param    metadata   the inbound structure that will be filled if the meta-data is available.
00494      *
00495      * @return              LORAWAN_STATUS_OK if the meta-data is available,
00496      *                      otherwise other negative error code if request failed:
00497      *                      LORAWAN_STATUS_NOT_INITIALIZED if system is not initialized with initialize(),
00498      *                      LORAWAN_STATUS_METADATA_NOT_AVAILABLE if the meta-data is not available
00499      */
00500     lorawan_status_t get_rx_metadata(lorawan_rx_metadata &metadata);
00501 
00502     /** Get hold of backoff time
00503      *
00504      * In the TX path, because of automatic duty cycling, the transmission is delayed by a certain
00505      * amount of time, which is the backoff time. While the system schedules application data to be sent,
00506      * the application can inquire about how much time is left in the actual transmission to happen.
00507      *
00508      * The system will provide you with a backoff time only if the application data is in the TX pipe.
00509      * If however, the event is already queued for the transmission, this API returns a
00510      * LORAWAN_STATUS_METADATA_NOT_AVAILABLE error code.
00511      *
00512      * @param    backoff    the inbound integer that will carry the backoff time if it is available.
00513      *
00514      * @return              LORAWAN_STATUS_OK if the meta-data is available,
00515      *                      otherwise other negative error code if request failed:
00516      *                      LORAWAN_STATUS_NOT_INITIALIZED if system is not initialized with initialize(),
00517      *                      LORAWAN_STATUS_METADATA_NOT_AVAILABLE if the meta-data is not available
00518      */
00519     lorawan_status_t get_backoff_metadata(int &backoff);
00520 
00521     /** Cancel outgoing transmission
00522      *
00523      * This API is used to cancel any outstanding transmission in the TX pipe.
00524      * If an event for transmission is not already queued at the end of backoff timer,
00525      * the system can cancel the outstanding outgoing packet. Otherwise, the system is
00526      * busy sending and can't be held back. The system will not try to resend if the
00527      * outgoing message was a CONFIRMED message even if the ack is not received.
00528      *
00529      * @return              LORAWAN_STATUS_OK if the sending is canceled, otherwise
00530      *                      other negative error code if request failed:
00531      *                      LORAWAN_STATUS_NOT_INITIALIZED if system is not initialized with initialize(),
00532      *                      LORAWAN_STATUS_BUSY if the send cannot be canceled
00533      *                      LORAWAN_STATUS_NO_OP if the operation cannot be completed (nothing to cancel)
00534      */
00535     lorawan_status_t cancel_sending(void);
00536 
00537     /** Provides exclusive access to the stack.
00538      *
00539      * Use only if the stack is being run in it's own separate thread.
00540      */
00541     void lock(void)
00542     {
00543         _lw_stack.lock();
00544     }
00545 
00546     /** Releases exclusive access to the stack.
00547      *
00548      * Use only if the stack is being run in it's own separate thread.
00549      */
00550     void unlock(void)
00551     {
00552         _lw_stack.unlock();
00553     }
00554 
00555 private:
00556     /** ScopedLock object
00557      *
00558      * RAII style exclusive access
00559      */
00560     typedef mbed::ScopedLock<LoRaWANInterface> Lock;
00561 
00562     /** LoRaWANStack object
00563      *
00564      * Handle for the LoRaWANStack class
00565      */
00566     LoRaWANStack _lw_stack;
00567 
00568     /** PHY object if created by LoRaWANInterface
00569      *
00570      * PHY object if LoRaWANInterface has created it.
00571      * If PHY object is provided by the application, this pointer is NULL.
00572      */
00573     LoRaPHY *_default_phy;
00574 };
00575 
00576 #endif /* LORAWANINTERFACE_H_ */
00577 /** @}*/