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
00035      *                 failure.
00036      */
00037     virtual lorawan_status_t initialize(events::EventQueue *queue) = 0;
00038 
00039     /** Connect OTAA or ABP by setup.
00040      *
00041      * Connect by Over The Air Activation or Activation By Personalization.
00042      * The connection type is selected at the setup.
00043      *
00044      * @return         LORAWAN_STATUS_OK on success, a negative error code on
00045      *                 failure.
00046      */
00047     virtual lorawan_status_t connect() = 0;
00048 
00049     /** Connect OTAA or ABP by parameters
00050      *
00051      * Connect by Over The Air Activation or Activation By Personalization.
00052      * The connection type is selected using the parameters.
00053      * You need to define the parameters in the main application.
00054      *
00055      * @param connect       Options how end-device will connect to gateway
00056      * @return              LORAWAN_STATUS_OK on success, negative error code
00057      *                      on failure
00058      */
00059     virtual lorawan_status_t connect(const lorawan_connect_t &connect) = 0;
00060 
00061     /** Disconnects the current session.
00062      *
00063      * @return         LORAWAN_STATUS_OK on success, a negative error code on failure.
00064      */
00065     virtual lorawan_status_t disconnect() = 0;
00066 
00067     /** Validate the connectivity with the network.
00068      *
00069      * Application may use this API to submit a request to the stack for
00070      * validation of its connectivity to a Network Server. Under the hood, this
00071      * API schedules a Link Check Request command (LinkCheckReq) for the network
00072      * server and once the response, i.e., LinkCheckAns MAC command is received
00073      * from the Network Server, user provided method is called.
00074      *
00075      * This API is usable only when the link check response is callback set by
00076      * the application. See add_lora_app_callbacks API. If the above mentioned
00077      * callback is not set, a LORAWAN_STATUS_PARAMETER_INVALID error is thrown.
00078      *
00079      * First parameter to callback function is the demodulation margin and
00080      * the second parameter is the number of gateways that successfully received
00081      * the last request.
00082      *
00083      * A 'Link Check Request' MAC command remains set for every subsequent
00084      * transmission, until/unless application explicitly turns it off using
00085      * remove_link_check_request() API.
00086      *
00087      * @return          LORAWAN_STATUS_OK on successfully queuing a request, or
00088      *                  a negative error code on failure.
00089      *
00090      */
00091     virtual lorawan_status_t add_link_check_request() = 0;
00092 
00093     /** Detaches Link Request MAC command.
00094      *
00095      * Removes sticky MAC command for link check request.
00096      */
00097     virtual void remove_link_check_request() = 0;
00098 
00099     /** Sets up a particular data rate of choice
00100      *
00101      * @param data_rate   Intended data rate e.g., DR_0, DR_1 etc.
00102      *                    Caution is advised as the macro DR_* can mean different
00103      *                    things while being in a different region.
00104      * @return            LORAWAN_STATUS_OK if everything goes well, otherwise
00105      *                    a negative error code.
00106      */
00107     virtual lorawan_status_t set_datarate(uint8_t data_rate) = 0;
00108 
00109     /** Enables adaptive data rate (ADR)
00110      *
00111      * Underlying LoRaPHY and LoRaMac layers handle the data rate automatically
00112      * for the user based upon radio conditions (network congestion).
00113      *
00114      * @return             LORAWAN_STATUS_OK on success, negative error code
00115      *                     on failure.
00116      */
00117     virtual lorawan_status_t enable_adaptive_datarate() = 0;
00118 
00119     /** Disables adaptive data rate
00120      *
00121      * When adaptive data rate (ADR) is disabled, user can either set a certain
00122      * data rate or the Mac layer will choose a default value.
00123      *
00124      * @return             LORAWAN_STATUS_OK on success, negative error code
00125      *                     on failure.
00126      */
00127     virtual lorawan_status_t disable_adaptive_datarate() = 0;
00128 
00129     /** Sets up retry counter for confirmed messages
00130      *
00131      * Valid only for confirmed messages.
00132      *
00133      * Number of trials to transmit the frame, if the LoRaMAC layer did not
00134      * receive an acknowledgment. The MAC performs a data-rate adaptation,
00135      * according to the LoRaWAN Specification V1.0.2, chapter 18.4, according
00136      * to the table on page 64.
00137      *
00138      * Note, that if the number of trials is set to 1 or 2, the MAC will not decrease
00139      * the datarate, in case the LoRaMAC layer did not receive an acknowledgment.
00140      *
00141      * @param count     number of retries for confirmed messages
00142      *
00143      * @return          LORAWAN_STATUS_OK or a negative error code
00144      */
00145     virtual lorawan_status_t set_confirmed_msg_retries(uint8_t count) = 0;
00146 
00147     /** Sets channel plan
00148      *
00149      * @param channel_plan  The defined channel plans to be set.
00150      * @return              0 on success, a negative error code on failure.
00151      */
00152     virtual lorawan_status_t set_channel_plan(const lorawan_channelplan_t &channel_plan) = 0;
00153 
00154     /** Gets the current channel plan.
00155      *
00156      * @param  channel_plan     The current channel information.
00157      *
00158      * @return                  LORAWAN_STATUS_OK on success, a negative error
00159      *                          code on failure.
00160      */
00161     virtual lorawan_status_t get_channel_plan(lorawan_channelplan_t &channel_plan) = 0;
00162 
00163     /** Removes currently active channel plan
00164      *
00165      * Default channels (channels where Base Stations are listening) are not
00166      * allowed to be removed. So when a plan is abolished, only non-default
00167      * channels are removed.
00168      *
00169      * @return                  LORAWAN_STATUS_OK on success, negative error
00170      *                          code on failure
00171      */
00172     virtual lorawan_status_t remove_channel_plan() = 0;
00173 
00174     /** Removes a given single channel
00175      *
00176      * Default channels (channels where Base Stations are listening) are not
00177      * allowed to be removed.
00178      *
00179      * @param    index          The channel index
00180      *
00181      * @return                  LORAWAN_STATUS_OK on success, negative error
00182      *                          code on failure
00183      */
00184     virtual lorawan_status_t remove_channel(uint8_t index) = 0;
00185 
00186     /** Send message to gateway
00187      *
00188      * @param port              The application port number. Port numbers 0 and 224
00189      *                          are reserved, whereas port numbers from 1 to 223
00190      *                          (0x01 to 0xDF) are valid port numbers.
00191      *                          Anything out of this range is illegal.
00192      *
00193      * @param data              A pointer to the data being sent. The ownership of the
00194      *                          buffer is not transferred. The data is copied to the
00195      *                          internal buffers.
00196      *
00197      * @param length            The size of data in bytes.
00198      *
00199      * @param flags             A flag used to determine what type of
00200      *                          message is being sent, for example:
00201      *
00202      *                          MSG_UNCONFIRMED_FLAG = 0x01
00203      *                          MSG_CONFIRMED_FLAG = 0x02
00204      *                          MSG_MULTICAST_FLAG = 0x04
00205      *                          MSG_PROPRIETARY_FLAG = 0x08
00206      *                          MSG_MULTICAST_FLAG and MSG_PROPRIETARY_FLAG can be
00207      *                          used in conjunction with MSG_UNCONFIRMED_FLAG and
00208      *                          MSG_CONFIRMED_FLAG depending on the intended use.
00209      *
00210      *                          MSG_PROPRIETARY_FLAG|MSG_CONFIRMED_FLAG mask will set
00211      *                          a confirmed message flag for a proprietary message.
00212      *                          MSG_CONFIRMED_FLAG and MSG_UNCONFIRMED_FLAG are
00213      *                          mutually exclusive.
00214      *
00215      *
00216      * @return                  The number of bytes sent, or
00217      *                          LORAWAN_STATUS_WOULD_BLOCK if another TX is
00218      *                          ongoing, or a negative error code on failure.
00219      */
00220     virtual int16_t send(uint8_t port, const uint8_t* data,
00221                          uint16_t length, int flags) = 0;
00222 
00223     /** Receives a message from the Network Server on a specific port.
00224      *
00225      * @param port              The application port number. Port numbers 0 and 224
00226      *                          are reserved, whereas port numbers from 1 to 223
00227      *                          (0x01 to 0xDF) are valid port numbers.
00228      *                          Anything out of this range is illegal.
00229      *
00230      * @param data              A pointer to buffer where the received data will be
00231      *                          stored.
00232      *
00233      * @param length            The size of data in bytes.
00234      *
00235      * @param flags             A flag is used to determine what type of
00236      *                          message is being sent, for example:
00237      *
00238      *                          MSG_UNCONFIRMED_FLAG = 0x01,
00239      *                          MSG_CONFIRMED_FLAG = 0x02
00240      *                          MSG_MULTICAST_FLAG = 0x04,
00241      *                          MSG_PROPRIETARY_FLAG = 0x08
00242      *
00243      *                          MSG_MULTICAST_FLAG and MSG_PROPRIETARY_FLAG can be
00244      *                          used in conjunction with MSG_UNCONFIRMED_FLAG and
00245      *                          MSG_CONFIRMED_FLAG depending on the intended use.
00246      *
00247      *                          MSG_PROPRIETARY_FLAG|MSG_CONFIRMED_FLAG mask will set
00248      *                          a confirmed message flag for a proprietary message.
00249      *
00250      *                          MSG_CONFIRMED_FLAG and MSG_UNCONFIRMED_FLAG are
00251      *                          not mutually exclusive, i.e., the user can subscribe to
00252      *                          receive both CONFIRMED AND UNCONFIRMED messages at
00253      *                          the same time.
00254      *
00255      * @return                  It could be one of these:
00256      *                             i)   0 if there is nothing else to read.
00257      *                             ii)  Number of bytes written to user buffer.
00258      *                             iii) LORAWAN_STATUS_WOULD_BLOCK if there is
00259      *                                  nothing available to read at the moment.
00260      *                             iv)  A negative error code on failure.
00261      */
00262     virtual int16_t receive(uint8_t port, uint8_t* data, uint16_t length, int flags) = 0;
00263 
00264     /** Receives a message from the Network Server from any port.
00265      *
00266      * @param data              A pointer to buffer where the received data will be
00267      *                          stored.
00268      *
00269      * @param length            The size of data in bytes
00270      *
00271      * @param port              Return the number of port to which message was received.
00272      *
00273      * @param flags             Return flags to determine what type of message was received.
00274      *                          MSG_UNCONFIRMED_FLAG = 0x01
00275      *                          MSG_CONFIRMED_FLAG = 0x02
00276      *                          MSG_MULTICAST_FLAG = 0x04
00277      *                          MSG_PROPRIETARY_FLAG = 0x08
00278      *
00279      * @return                  It could be one of these:
00280      *                             i)   0 if there is nothing else to read.
00281      *                             ii)  Number of bytes written to user buffer.
00282      *                             iii) LORAWAN_STATUS_WOULD_BLOCK if there is
00283      *                                  nothing available to read at the moment.
00284      *                             iv)  A negative error code on failure.
00285      */
00286     virtual int16_t receive(uint8_t* data, uint16_t length, uint8_t& port, int& flags) = 0;
00287 
00288     /** Add application callbacks to the stack.
00289      *
00290      * An example of using this API with a latch onto 'lorawan_events' could be:
00291      *
00292      * LoRaWANInterface lorawan(radio);
00293      * lorawan_app_callbacks_t cbs;
00294      * static void my_event_handler();
00295      *
00296      * int main()
00297      * {
00298      * lorawan.initialize();
00299      *  cbs.lorawan_events = mbed::callback(my_event_handler);
00300      *  lorawan.add_app_callbacks(&cbs);
00301      *  lorawan.connect();
00302      * }
00303      *
00304      * static void my_event_handler(lorawan_event_t event)
00305      * {
00306      *  switch(event) {
00307      *      case CONNECTED:
00308      *          //do something
00309      *          break;
00310      *      case DISCONNECTED:
00311      *          //do something
00312      *          break;
00313      *      case TX_DONE:
00314      *          //do something
00315      *          break;
00316      *      default:
00317      *          break;
00318      *  }
00319      * }
00320      *
00321      * @param callbacks         A pointer to the structure containing application
00322      *                          callbacks.
00323      *
00324      * @return                  LORAWAN_STATUS_OK on success, a negative error
00325      *                          code on failure.
00326      */
00327     virtual lorawan_status_t add_app_callbacks(lorawan_app_callbacks_t *callbacks) = 0;
00328 
00329     /** Change device class
00330      *
00331      * Change current device class.
00332      *
00333      * @param    device_class   The device class
00334      *
00335      * @return                  LORAWAN_STATUS_OK on success,
00336      *                          LORAWAN_STATUS_UNSUPPORTED is requested class is not supported,
00337      *                          or other negative error code if request failed.
00338      */
00339     virtual lorawan_status_t set_device_class(device_class_t device_class) = 0;
00340 };
00341 
00342 #endif /* LORAWAN_BASE_H_ */