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