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 #ifndef LORAWANINTERFACE_H_
00019 #define LORAWANINTERFACE_H_
00020 
00021 #include "platform/Callback.h"
00022 #include "lorawan/LoRaWANStack.h"
00023 #include "lorawan/LoRaRadio.h"
00024 #include "lorawan/LoRaWANBase.h"
00025 
00026 class LoRaWANInterface: public LoRaWANBase {
00027 
00028 public:
00029 
00030     /** Constructs a LoRaWANInterface using the LoRaWANStack instance underneath.
00031      *
00032      * Currently, LoRaWANStack is a singleton and you should only
00033      * construct a single instance of LoRaWANInterface.
00034      *
00035      */
00036     LoRaWANInterface(LoRaRadio& radio);
00037 
00038     virtual ~LoRaWANInterface();
00039 
00040     /** Initialize the LoRa stack.
00041      *
00042      * You must call this first to be able to use the LoRa stack.
00043      *
00044      * @param ev_queue A pointer to EventQueue provided by the application.
00045      *
00046      * @return         0 on success, a negative error code on failure.
00047      */
00048     virtual lorawan_status_t initialize(events::EventQueue *ev_queue);
00049 
00050     /** Connect OTAA or ABP using Mbed-OS config system
00051      *
00052      * Connect by Over The Air Activation or Activation By Personalization.
00053      * You need to configure the connection properly via the Mbed OS configuration
00054      * system.
00055      *
00056      * When connecting via OTAA, the return code for success (LORAWAN_STATUS_CONNECT_IN_PROGRESS) is negative.
00057      * However, this is not a real error. It tells you that the connection is in progress and you will
00058      * be notified of the completion via an event. By default, after the Join Accept message
00059      * is received, base stations may provide the node with a CF-List that replaces
00060      * all user-configured channels except the Join/Default channels. A CF-List can
00061      * configure a maximum of five channels other than the default channels.
00062      *
00063      * In case of ABP, the CONNECTED event is posted before the call to `connect()` returns.
00064      * To configure more channels, we recommend that you use the `set_channel_plan()` API after the connection.
00065      * By default, the PHY layers configure only the mandatory Join channels. The retransmission back-off restrictions
00066      * on these channels are severe and you may experience long delays or even failures in the confirmed traffic.
00067      * If you add more channels, the aggregated duty cycle becomes much more relaxed as compared to the Join (default) channels only.
00068      *
00069      * **NOTES ON RECONNECTION:**
00070      * Currently, the Mbed OS LoRaWAN implementation does not support non-volatile
00071      * memory storage. Therefore, the state and frame counters cannot be restored after
00072      * a power cycle. However, if you use the `disconnect()` API to shut down the LoRaWAN
00073      * protocol, the state and frame counters are saved. Connecting again would try to
00074      * restore the previous session. According to the LoRaWAN 1.0.2 specification, the frame counters are always reset
00075      * to zero for OTAA and a new Join request lets the network server know
00076      * that the counters need a reset. The same is said about the ABP but there
00077      * is no way to convey this information to the network server. For a network
00078      * server, an ABP device is always connected. That's why storing the frame counters
00079      * is important, at least for ABP. That's why we try to restore frame counters from
00080      * session information after a disconnection.
00081      *
00082      * @return         LORAWAN_STATUS_OK or LORAWAN_STATUS_CONNECT_IN_PROGRESS
00083      *                 on success, or a negative error code on failure.
00084      */
00085     virtual lorawan_status_t connect();
00086 
00087     /** Connect OTAA or ABP with parameters
00088      *
00089      * All connection parameters are chosen by the user and provided in the
00090      * data structure passed down.
00091      *
00092      * When connecting via OTAA, the return code for success (LORAWAN_STATUS_CONNECT_IN_PROGRESS) is negative.
00093      * However, this is not a real error. It tells you that connection is in progress and you will
00094      * be notified of completion via an event. By default, after Join Accept message
00095      * is received, base stations may provide the node with a CF-List which replaces
00096      * all user-configured channels except the Join/Default channels. A CF-List can
00097      * configure a maximum of five channels other than the default channels.
00098      *
00099      * In case of ABP, the CONNECTED event is posted before the call to `connect()` returns.
00100      * To configure more channels, we recommend that you use the `set_channel_plan()` API after the connection.
00101      * By default, the PHY layers configure only the mandatory Join
00102      * channels. The retransmission back-off restrictions on these channels
00103      * are severe and you may experience long delays or even
00104      * failures in the confirmed traffic. If you add more channels, the aggregated duty
00105      * cycle becomes much more relaxed as compared to the Join (default) channels only.
00106      *
00107      * **NOTES ON RECONNECTION:**
00108      * Currently, the Mbed OS LoRaWAN implementation does not support non-volatile
00109      * memory storage. Therefore, the state and frame counters cannot be restored after
00110      * a power cycle. However, if you use the `disconnect()` API to shut down the LoRaWAN
00111      * protocol, the state and frame counters are saved. Connecting again would try to
00112      * restore the previous session. According to the LoRaWAN 1.0.2 specification, the frame counters are always reset
00113      * to zero for OTAA and a new Join request lets the network server know
00114      * that the counters need a reset. The same is said about the ABP but there
00115      * is no way to convey this information to the network server. For a network
00116      * server, an ABP device is always connected. That's why storing the frame counters
00117      * is important, at least for ABP. That's why we try to restore frame counters from
00118      * session information after a disconnection.
00119      *
00120      * @param connect  Options for an end device connection to the gateway.
00121      *
00122      * @return        LORAWAN_STATUS_OK or LORAWAN_STATUS_CONNECT_IN_PROGRESS,
00123      *                a negative error code on failure.
00124      */
00125     virtual lorawan_status_t connect(const lorawan_connect_t &connect);
00126 
00127     /** Disconnect the current session.
00128      *
00129      * @return         LORAWAN_STATUS_DEVICE_OFF on successfully shutdown.
00130      */
00131     virtual lorawan_status_t disconnect();
00132 
00133     /** Validate the connectivity with the network.
00134      *
00135      * Application may use this API to submit a request to the stack for
00136      * validation of its connectivity to a Network Server. Under the hood, this
00137      * API schedules a Link Check Request command (LinkCheckReq) for the network
00138      * server and once the response, i.e., LinkCheckAns MAC command is received
00139      * from the Network Server, user provided method is called.
00140      *
00141      * One way to use this API may be the validation of connectivity after a long
00142      * deep sleep. Mbed LoRaWANStack piggy-backs the MAC commands with data
00143      * frame payload so the application needs to try sending something and the Network
00144      * Server may respond during the RX slots.
00145      *
00146      * This API is usable only when the 'link_check_resp' callback is set by
00147      * the application. See add_lora_app_callbacks API. If the above mentioned
00148      * callback is not set, a LORAWAN_STATUS_PARAMETER_INVALID error is thrown.
00149      *
00150      * First parameter to callback function is the demodulation margin and
00151      * the second parameter is the number of gateways that successfully received
00152      * the last request.
00153      *
00154      * A 'Link Check Request' MAC command remains set for every subsequent
00155      * transmission, until/unless application explicitly turns it off using
00156      * remove_link_check_request() API.
00157      *
00158      * @return          LORAWAN_STATUS_OK on successfully queuing a request, or
00159      *                  a negative error code on failure.
00160      *
00161      */
00162     virtual lorawan_status_t add_link_check_request();
00163 
00164     /** Removes link check request sticky MAC command.
00165      *
00166      * Any already queued request may still get entertained. However, no new
00167      * requests will be made.
00168      */
00169     virtual void remove_link_check_request();
00170 
00171     /** Sets up a particular data rate
00172      *
00173      * `set_datarate()` first verifies whether the data rate given is valid or not.
00174      * If it is valid, the system sets the given data rate to the channel.
00175      *
00176      * @param data_rate   The intended data rate, for example DR_0 or DR_1.
00177      *                    Please note, that the macro DR_* can mean different
00178      *                    things in different regions.
00179      * @return            LORAWAN_STATUS_OK if everything goes well, otherwise
00180      *                    a negative error code.
00181      */
00182     virtual lorawan_status_t set_datarate(uint8_t data_rate);
00183 
00184     /** Enables adaptive data rate (ADR).
00185      *
00186      * The underlying LoRaPHY and LoRaMac layers handle the data rate automatically
00187      * for the user, based upon the radio conditions (network congestion).
00188      *
00189      * @return          LORAWAN_STATUS_OK or negative error code otherwise.
00190      */
00191     virtual lorawan_status_t enable_adaptive_datarate();
00192 
00193     /** Disables adaptive data rate.
00194      *
00195      * When adaptive data rate (ADR) is disabled, you can either set a certain
00196      * data rate or the MAC layer selects a default value.
00197      *
00198      * @return          LORAWAN_STATUS_OK or negative error code otherwise.
00199      */
00200     virtual lorawan_status_t disable_adaptive_datarate();
00201 
00202     /** Sets up the retry counter for confirmed messages.
00203      *
00204      * Valid for confirmed messages only.
00205      *
00206      * The number of trials to transmit the frame, if the LoRaMAC layer did not
00207      * receive an acknowledgment. The MAC performs a data rate adaptation as in
00208      * the LoRaWAN Specification V1.0.2, chapter 18.4, table on page 64.
00209      *
00210      * Note, that if number of retries is set to 1 or 2, MAC will not decrease
00211      * the datarate, if the LoRaMAC layer did not receive an acknowledgment.
00212      *
00213      * @param count     The number of retries for confirmed messages.
00214      *
00215      * @return          LORAWAN_STATUS_OK or a negative error code.
00216      */
00217     virtual lorawan_status_t set_confirmed_msg_retries(uint8_t count);
00218 
00219     /** Sets the channel plan.
00220      *
00221      * You can provide a list of channels with appropriate parameters filled
00222      * in. However, this list is not absolute. The stack applies a CF-List whenever
00223      * available, which means that the network can overwrite your channel
00224      * frequency settings right after Join Accept is received. You may try
00225      * to set up any channel or channels after that, and if the channel requested
00226      * is already active, the request is silently ignored. A negative error
00227      * code is returned if there is any problem with parameters.
00228      *
00229      * Please note that this API can also be used to add a single channel to the
00230      * existing channel plan.
00231      *
00232      * There is no reverse mechanism in the 1.0.2 specification for a node to request
00233      * a particular channel. Only the network server can initiate such a request.
00234      * You need to ensure that the corresponding base station supports the channel or channels being added.
00235      *
00236      * If your list includes a default channel (a channel where Join Requests
00237      * are received) you cannot fully configure the channel parameters.
00238      * Either leave the channel settings to default or check your
00239      * corresponding PHY layer implementation. For example, LoRaPHYE868.
00240      *
00241      * @param channel_plan      The channel plan to set.
00242      *
00243      * @return                  LORAWAN_STATUS_OK on success, a negative error
00244      *                          code on failure.
00245      */
00246     virtual lorawan_status_t set_channel_plan(const lorawan_channelplan_t &channel_plan);
00247 
00248     /** Gets the channel plans from the LoRa stack.
00249      *
00250      * Once you have selected a particular PHY layer, a set of channels
00251      * is automatically activated. Right after connecting, you can use this API
00252      * to see the current plan. Otherwise, this API returns the channel
00253      * plan that you have set using `set_channel_plan()`.
00254      *
00255      * @param  channel_plan     The current channel plan information.
00256      *
00257      * @return                  LORAWAN_STATUS_OK on success, a negative error
00258      *                          code on failure.
00259      */
00260     virtual lorawan_status_t get_channel_plan(lorawan_channelplan_t &channel_plan);
00261 
00262     /** Removes an active channel plan.
00263      *
00264      * You cannot remove default channels (the channels the base stations are listening to).
00265      * When a plan is abolished, only the non-default channels are removed.
00266      *
00267      * @return                  LORAWAN_STATUS_OK on success, a negative error
00268      *                          code on failure.
00269      */
00270     virtual lorawan_status_t remove_channel_plan();
00271 
00272     /** Removes a single channel.
00273      *
00274      * You cannot remove default channels (the channels the base stations are listening to).
00275      *
00276      * @param    index          The channel index.
00277      *
00278      * @return                  LORAWAN_STATUS_OK on success, a negative error
00279      *                          code on failure.
00280      */
00281     virtual lorawan_status_t remove_channel(uint8_t index);
00282 
00283     /** Send message to gateway
00284      *
00285      * @param port              The application port number. Port numbers 0 and 224
00286      *                          are reserved, whereas port numbers from 1 to 223
00287      *                          (0x01 to 0xDF) are valid port numbers.
00288      *                          Anything out of this range is illegal.
00289      *
00290      * @param data              A pointer to the data being sent. The ownership of the
00291      *                          buffer is not transferred. The data is copied to the
00292      *                          internal buffers.
00293      *
00294      * @param length            The size of data in bytes.
00295      *
00296      * @param flags             A flag used to determine what type of
00297      *                          message is being sent, for example:
00298      *
00299      *                          MSG_UNCONFIRMED_FLAG = 0x01
00300      *                          MSG_CONFIRMED_FLAG = 0x02
00301      *                          MSG_MULTICAST_FLAG = 0x04
00302      *                          MSG_PROPRIETARY_FLAG = 0x08
00303      *                          MSG_MULTICAST_FLAG and MSG_PROPRIETARY_FLAG can be
00304      *                          used in conjunction with MSG_UNCONFIRMED_FLAG and
00305      *                          MSG_CONFIRMED_FLAG depending on the intended use.
00306      *
00307      *                          MSG_PROPRIETARY_FLAG|MSG_CONFIRMED_FLAG mask will set
00308      *                          a confirmed message flag for a proprietary message.
00309      *                          MSG_CONFIRMED_FLAG and MSG_UNCONFIRMED_FLAG are
00310      *                          mutually exclusive.
00311      *
00312      *
00313      * @return                  The number of bytes sent, or
00314      *                          LORAWAN_STATUS_WOULD_BLOCK if another TX is
00315      *                          ongoing, or a negative error code on failure.
00316      */
00317     virtual int16_t send(uint8_t port, const uint8_t* data, uint16_t length,
00318                          int flags);
00319 
00320     /** Receives a message from the Network Server.
00321      *
00322      * @param port              The application port number. Port numbers 0 and 224
00323      *                          are reserved, whereas port numbers from 1 to 223
00324      *                          (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
00328      *                          stored.
00329      *
00330      * @param length            The size of data in bytes
00331      *
00332      * @param flags             A flag is used to determine what type of
00333      *                          message is being sent, for example:
00334      *
00335      *                          MSG_UNCONFIRMED_FLAG = 0x01,
00336      *                          MSG_CONFIRMED_FLAG = 0x02
00337      *                          MSG_MULTICAST_FLAG = 0x04,
00338      *                          MSG_PROPRIETARY_FLAG = 0x08
00339      *
00340      *                          MSG_MULTICAST_FLAG and MSG_PROPRIETARY_FLAG can be
00341      *                          used in conjunction with MSG_UNCONFIRMED_FLAG and
00342      *                          MSG_CONFIRMED_FLAG depending on the intended use.
00343      *
00344      *                          MSG_PROPRIETARY_FLAG|MSG_CONFIRMED_FLAG mask will set
00345      *                          a confirmed message flag for a proprietary message.
00346      *
00347      *                          MSG_CONFIRMED_FLAG and MSG_UNCONFIRMED_FLAG are
00348      *                          not mutually exclusive, i.e., the user can subscribe to
00349      *                          receive both CONFIRMED AND UNCONFIRMED messages at
00350      *                          the same time.
00351      *
00352      * @return                  It could be one of these:
00353      *                             i)   0 if there is nothing else to read.
00354      *                             ii)  Number of bytes written to user buffer.
00355      *                             iii) LORAWAN_STATUS_WOULD_BLOCK if there is
00356      *                                  nothing available to read at the moment.
00357      *                             iv)  A negative error code on failure.
00358      */
00359     virtual int16_t receive(uint8_t port, uint8_t* data, uint16_t length,
00360                             int flags);
00361 
00362     /** Add application callbacks to the stack.
00363        *
00364        * 'lorawan_app_callbacks' is a structure that holds pointers to the application
00365        * provided methods which are needed to be called in response to certain
00366        * requests. The structure is default constructed to set all pointers to NULL.
00367        * So if the user does not provide the pointer, a response will not be posted.
00368        * However, the 'lorawan_events' callback is mandatory to be provided as it
00369        * contains essential events.
00370        *
00371        * Events that can be posted to user via 'lorawan_events' are:
00372        *
00373        * CONNECTED            - When the connection is complete
00374        * DISCONNECTED         - When the protocol is shut down in response to disconnect()
00375        * TX_DONE              - When a packet is sent
00376        * TX_TIMEOUT,          - When stack was unable to send packet in TX window
00377        * TX_ERROR,            - A general TX error
00378        * TX_CRYPTO_ERROR,     - If MIC fails, or any other crypto relted error
00379        * TX_SCHEDULING_ERROR, - When stack is unable to schedule packet
00380        * RX_DONE,             - When there is something to receive
00381        * RX_TIMEOUT,          - Not yet mapped
00382        * RX_ERROR             - A general RX error
00383        *
00384        * Other responses to certain standard requests are an item for the future.
00385        * For example, a link check request could be sent whenever the device tries
00386        * to send a message and if the network server responds with a link check resposne,
00387        * the stack notifies the application be calling the appropriate method. For example,
00388        * 'link_check_resp' callback could be used to collect a response for a link check
00389        * request MAC command and the result is thus transported to the application
00390        * via callback function provided.
00391        *
00392        * As can be seen from declaration, mbed::Callback<void(uint8_t, uint8_t)> *link_check_resp)
00393        * carries two parameters. First one is Demodulation Margin and the second one
00394        * is number of gateways involved in the path to network server.
00395        *
00396        * An example of using this API with a latch onto 'lorawan_events' could be:
00397        *
00398        * LoRaWANInterface lorawan(radio);
00399        * lorawan_app_callbacks cbs;
00400        * static void my_event_handler();
00401        *
00402        * int main()
00403        * {
00404        * lorawan.initialize(&queue);
00405        *  cbs.events = mbed::callback(my_event_handler);
00406        *  lorawan.add_app_callbacks(&cbs);
00407        *  lorawan.connect();
00408        * }
00409        *
00410        * static void my_event_handler(lora_events_t events)
00411        * {
00412        *  switch(events) {
00413        *      case CONNECTED:
00414        *          //do something
00415        *          break;
00416        *      case DISCONNECTED:
00417        *          //do something
00418        *          break;
00419        *      case TX_DONE:
00420        *          //do something
00421        *          break;
00422        *      default:
00423        *          break;
00424        *  }
00425        * }
00426        *
00427        * @param callbacks         A pointer to the structure containing application
00428        *                          callbacks.
00429        */
00430     virtual lorawan_status_t add_app_callbacks(lorawan_app_callbacks_t *callbacks);
00431 
00432 private:
00433     bool _link_check_requested;
00434 };
00435 
00436 #endif /* LORAWANINTERFACE_H_ */