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