Nicolas Borla
BBR 1 Ebene
mbed-os/features/lorawan/LoRaWANInterface.h@0:fbdae7e6d805, 2018-05-14 (annotated)
- Committer:
- borlanic
- Date:
- Mon May 14 11:29:06 2018 +0000
- Revision:
- 0:fbdae7e6d805
BBR
Who changed what in which revision?
| User | Revision | Line number | New contents of line |
|---|---|---|---|
| borlanic | 0:fbdae7e6d805 | 1 | /** |
| borlanic | 0:fbdae7e6d805 | 2 | * Copyright (c) 2017, Arm Limited and affiliates. |
| borlanic | 0:fbdae7e6d805 | 3 | * SPDX-License-Identifier: Apache-2.0 |
| borlanic | 0:fbdae7e6d805 | 4 | * |
| borlanic | 0:fbdae7e6d805 | 5 | * Licensed under the Apache License, Version 2.0 (the "License"); |
| borlanic | 0:fbdae7e6d805 | 6 | * you may not use this file except in compliance with the License. |
| borlanic | 0:fbdae7e6d805 | 7 | * You may obtain a copy of the License at |
| borlanic | 0:fbdae7e6d805 | 8 | * |
| borlanic | 0:fbdae7e6d805 | 9 | * http://www.apache.org/licenses/LICENSE-2.0 |
| borlanic | 0:fbdae7e6d805 | 10 | * |
| borlanic | 0:fbdae7e6d805 | 11 | * Unless required by applicable law or agreed to in writing, software |
| borlanic | 0:fbdae7e6d805 | 12 | * distributed under the License is distributed on an "AS IS" BASIS, |
| borlanic | 0:fbdae7e6d805 | 13 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| borlanic | 0:fbdae7e6d805 | 14 | * See the License for the specific language governing permissions and |
| borlanic | 0:fbdae7e6d805 | 15 | * limitations under the License. |
| borlanic | 0:fbdae7e6d805 | 16 | */ |
| borlanic | 0:fbdae7e6d805 | 17 | |
| borlanic | 0:fbdae7e6d805 | 18 | #ifndef LORAWANINTERFACE_H_ |
| borlanic | 0:fbdae7e6d805 | 19 | #define LORAWANINTERFACE_H_ |
| borlanic | 0:fbdae7e6d805 | 20 | |
| borlanic | 0:fbdae7e6d805 | 21 | #include "platform/Callback.h" |
| borlanic | 0:fbdae7e6d805 | 22 | #include "platform/ScopedLock.h" |
| borlanic | 0:fbdae7e6d805 | 23 | #include "LoRaWANStack.h" |
| borlanic | 0:fbdae7e6d805 | 24 | #include "LoRaRadio.h" |
| borlanic | 0:fbdae7e6d805 | 25 | #include "LoRaWANBase.h" |
| borlanic | 0:fbdae7e6d805 | 26 | |
| borlanic | 0:fbdae7e6d805 | 27 | class LoRaWANInterface: public LoRaWANBase { |
| borlanic | 0:fbdae7e6d805 | 28 | |
| borlanic | 0:fbdae7e6d805 | 29 | public: |
| borlanic | 0:fbdae7e6d805 | 30 | |
| borlanic | 0:fbdae7e6d805 | 31 | /** Constructs a LoRaWANInterface using the LoRaWANStack instance underneath. |
| borlanic | 0:fbdae7e6d805 | 32 | * |
| borlanic | 0:fbdae7e6d805 | 33 | * Currently, LoRaWANStack is a singleton and you should only |
| borlanic | 0:fbdae7e6d805 | 34 | * construct a single instance of LoRaWANInterface. |
| borlanic | 0:fbdae7e6d805 | 35 | * |
| borlanic | 0:fbdae7e6d805 | 36 | */ |
| borlanic | 0:fbdae7e6d805 | 37 | LoRaWANInterface(LoRaRadio& radio); |
| borlanic | 0:fbdae7e6d805 | 38 | |
| borlanic | 0:fbdae7e6d805 | 39 | virtual ~LoRaWANInterface(); |
| borlanic | 0:fbdae7e6d805 | 40 | |
| borlanic | 0:fbdae7e6d805 | 41 | /** Initialize the LoRa stack. |
| borlanic | 0:fbdae7e6d805 | 42 | * |
| borlanic | 0:fbdae7e6d805 | 43 | * You must call this first to be able to use the LoRa stack. |
| borlanic | 0:fbdae7e6d805 | 44 | * |
| borlanic | 0:fbdae7e6d805 | 45 | * @param ev_queue A pointer to EventQueue provided by the application. |
| borlanic | 0:fbdae7e6d805 | 46 | * |
| borlanic | 0:fbdae7e6d805 | 47 | * @return 0 on success, a negative error code on failure. |
| borlanic | 0:fbdae7e6d805 | 48 | */ |
| borlanic | 0:fbdae7e6d805 | 49 | virtual lorawan_status_t initialize(events::EventQueue *ev_queue); |
| borlanic | 0:fbdae7e6d805 | 50 | |
| borlanic | 0:fbdae7e6d805 | 51 | /** Connect OTAA or ABP using Mbed-OS config system |
| borlanic | 0:fbdae7e6d805 | 52 | * |
| borlanic | 0:fbdae7e6d805 | 53 | * Connect by Over The Air Activation or Activation By Personalization. |
| borlanic | 0:fbdae7e6d805 | 54 | * You need to configure the connection properly via the Mbed OS configuration |
| borlanic | 0:fbdae7e6d805 | 55 | * system. |
| borlanic | 0:fbdae7e6d805 | 56 | * |
| borlanic | 0:fbdae7e6d805 | 57 | * When connecting via OTAA, the return code for success (LORAWAN_STATUS_CONNECT_IN_PROGRESS) is negative. |
| borlanic | 0:fbdae7e6d805 | 58 | * However, this is not a real error. It tells you that the connection is in progress and you will |
| borlanic | 0:fbdae7e6d805 | 59 | * be notified of the completion via an event. By default, after the Join Accept message |
| borlanic | 0:fbdae7e6d805 | 60 | * is received, base stations may provide the node with a CF-List that replaces |
| borlanic | 0:fbdae7e6d805 | 61 | * all user-configured channels except the Join/Default channels. A CF-List can |
| borlanic | 0:fbdae7e6d805 | 62 | * configure a maximum of five channels other than the default channels. |
| borlanic | 0:fbdae7e6d805 | 63 | * |
| borlanic | 0:fbdae7e6d805 | 64 | * In case of ABP, the CONNECTED event is posted before the call to `connect()` returns. |
| borlanic | 0:fbdae7e6d805 | 65 | * To configure more channels, we recommend that you use the `set_channel_plan()` API after the connection. |
| borlanic | 0:fbdae7e6d805 | 66 | * By default, the PHY layers configure only the mandatory Join channels. The retransmission back-off restrictions |
| borlanic | 0:fbdae7e6d805 | 67 | * on these channels are severe and you may experience long delays or even failures in the confirmed traffic. |
| borlanic | 0:fbdae7e6d805 | 68 | * If you add more channels, the aggregated duty cycle becomes much more relaxed as compared to the Join (default) channels only. |
| borlanic | 0:fbdae7e6d805 | 69 | * |
| borlanic | 0:fbdae7e6d805 | 70 | * **NOTES ON RECONNECTION:** |
| borlanic | 0:fbdae7e6d805 | 71 | * Currently, the Mbed OS LoRaWAN implementation does not support non-volatile |
| borlanic | 0:fbdae7e6d805 | 72 | * memory storage. Therefore, the state and frame counters cannot be restored after |
| borlanic | 0:fbdae7e6d805 | 73 | * a power cycle. However, if you use the `disconnect()` API to shut down the LoRaWAN |
| borlanic | 0:fbdae7e6d805 | 74 | * protocol, the state and frame counters are saved. Connecting again would try to |
| borlanic | 0:fbdae7e6d805 | 75 | * restore the previous session. According to the LoRaWAN 1.0.2 specification, the frame counters are always reset |
| borlanic | 0:fbdae7e6d805 | 76 | * to zero for OTAA and a new Join request lets the network server know |
| borlanic | 0:fbdae7e6d805 | 77 | * that the counters need a reset. The same is said about the ABP but there |
| borlanic | 0:fbdae7e6d805 | 78 | * is no way to convey this information to the network server. For a network |
| borlanic | 0:fbdae7e6d805 | 79 | * server, an ABP device is always connected. That's why storing the frame counters |
| borlanic | 0:fbdae7e6d805 | 80 | * is important, at least for ABP. That's why we try to restore frame counters from |
| borlanic | 0:fbdae7e6d805 | 81 | * session information after a disconnection. |
| borlanic | 0:fbdae7e6d805 | 82 | * |
| borlanic | 0:fbdae7e6d805 | 83 | * @return LORAWAN_STATUS_OK or LORAWAN_STATUS_CONNECT_IN_PROGRESS |
| borlanic | 0:fbdae7e6d805 | 84 | * on success, or a negative error code on failure. |
| borlanic | 0:fbdae7e6d805 | 85 | */ |
| borlanic | 0:fbdae7e6d805 | 86 | virtual lorawan_status_t connect(); |
| borlanic | 0:fbdae7e6d805 | 87 | |
| borlanic | 0:fbdae7e6d805 | 88 | /** Connect OTAA or ABP with parameters |
| borlanic | 0:fbdae7e6d805 | 89 | * |
| borlanic | 0:fbdae7e6d805 | 90 | * All connection parameters are chosen by the user and provided in the |
| borlanic | 0:fbdae7e6d805 | 91 | * data structure passed down. |
| borlanic | 0:fbdae7e6d805 | 92 | * |
| borlanic | 0:fbdae7e6d805 | 93 | * When connecting via OTAA, the return code for success (LORAWAN_STATUS_CONNECT_IN_PROGRESS) is negative. |
| borlanic | 0:fbdae7e6d805 | 94 | * However, this is not a real error. It tells you that connection is in progress and you will |
| borlanic | 0:fbdae7e6d805 | 95 | * be notified of completion via an event. By default, after Join Accept message |
| borlanic | 0:fbdae7e6d805 | 96 | * is received, base stations may provide the node with a CF-List which replaces |
| borlanic | 0:fbdae7e6d805 | 97 | * all user-configured channels except the Join/Default channels. A CF-List can |
| borlanic | 0:fbdae7e6d805 | 98 | * configure a maximum of five channels other than the default channels. |
| borlanic | 0:fbdae7e6d805 | 99 | * |
| borlanic | 0:fbdae7e6d805 | 100 | * In case of ABP, the CONNECTED event is posted before the call to `connect()` returns. |
| borlanic | 0:fbdae7e6d805 | 101 | * To configure more channels, we recommend that you use the `set_channel_plan()` API after the connection. |
| borlanic | 0:fbdae7e6d805 | 102 | * By default, the PHY layers configure only the mandatory Join |
| borlanic | 0:fbdae7e6d805 | 103 | * channels. The retransmission back-off restrictions on these channels |
| borlanic | 0:fbdae7e6d805 | 104 | * are severe and you may experience long delays or even |
| borlanic | 0:fbdae7e6d805 | 105 | * failures in the confirmed traffic. If you add more channels, the aggregated duty |
| borlanic | 0:fbdae7e6d805 | 106 | * cycle becomes much more relaxed as compared to the Join (default) channels only. |
| borlanic | 0:fbdae7e6d805 | 107 | * |
| borlanic | 0:fbdae7e6d805 | 108 | * **NOTES ON RECONNECTION:** |
| borlanic | 0:fbdae7e6d805 | 109 | * Currently, the Mbed OS LoRaWAN implementation does not support non-volatile |
| borlanic | 0:fbdae7e6d805 | 110 | * memory storage. Therefore, the state and frame counters cannot be restored after |
| borlanic | 0:fbdae7e6d805 | 111 | * a power cycle. However, if you use the `disconnect()` API to shut down the LoRaWAN |
| borlanic | 0:fbdae7e6d805 | 112 | * protocol, the state and frame counters are saved. Connecting again would try to |
| borlanic | 0:fbdae7e6d805 | 113 | * restore the previous session. According to the LoRaWAN 1.0.2 specification, the frame counters are always reset |
| borlanic | 0:fbdae7e6d805 | 114 | * to zero for OTAA and a new Join request lets the network server know |
| borlanic | 0:fbdae7e6d805 | 115 | * that the counters need a reset. The same is said about the ABP but there |
| borlanic | 0:fbdae7e6d805 | 116 | * is no way to convey this information to the network server. For a network |
| borlanic | 0:fbdae7e6d805 | 117 | * server, an ABP device is always connected. That's why storing the frame counters |
| borlanic | 0:fbdae7e6d805 | 118 | * is important, at least for ABP. That's why we try to restore frame counters from |
| borlanic | 0:fbdae7e6d805 | 119 | * session information after a disconnection. |
| borlanic | 0:fbdae7e6d805 | 120 | * |
| borlanic | 0:fbdae7e6d805 | 121 | * @param connect Options for an end device connection to the gateway. |
| borlanic | 0:fbdae7e6d805 | 122 | * |
| borlanic | 0:fbdae7e6d805 | 123 | * @return LORAWAN_STATUS_OK or LORAWAN_STATUS_CONNECT_IN_PROGRESS, |
| borlanic | 0:fbdae7e6d805 | 124 | * a negative error code on failure. |
| borlanic | 0:fbdae7e6d805 | 125 | */ |
| borlanic | 0:fbdae7e6d805 | 126 | virtual lorawan_status_t connect(const lorawan_connect_t &connect); |
| borlanic | 0:fbdae7e6d805 | 127 | |
| borlanic | 0:fbdae7e6d805 | 128 | /** Disconnect the current session. |
| borlanic | 0:fbdae7e6d805 | 129 | * |
| borlanic | 0:fbdae7e6d805 | 130 | * @return LORAWAN_STATUS_DEVICE_OFF on successfully shutdown. |
| borlanic | 0:fbdae7e6d805 | 131 | */ |
| borlanic | 0:fbdae7e6d805 | 132 | virtual lorawan_status_t disconnect(); |
| borlanic | 0:fbdae7e6d805 | 133 | |
| borlanic | 0:fbdae7e6d805 | 134 | /** Validate the connectivity with the network. |
| borlanic | 0:fbdae7e6d805 | 135 | * |
| borlanic | 0:fbdae7e6d805 | 136 | * Application may use this API to submit a request to the stack for |
| borlanic | 0:fbdae7e6d805 | 137 | * validation of its connectivity to a Network Server. Under the hood, this |
| borlanic | 0:fbdae7e6d805 | 138 | * API schedules a Link Check Request command (LinkCheckReq) for the network |
| borlanic | 0:fbdae7e6d805 | 139 | * server and once the response, i.e., LinkCheckAns MAC command is received |
| borlanic | 0:fbdae7e6d805 | 140 | * from the Network Server, user provided method is called. |
| borlanic | 0:fbdae7e6d805 | 141 | * |
| borlanic | 0:fbdae7e6d805 | 142 | * One way to use this API may be the validation of connectivity after a long |
| borlanic | 0:fbdae7e6d805 | 143 | * deep sleep. Mbed LoRaWANStack piggy-backs the MAC commands with data |
| borlanic | 0:fbdae7e6d805 | 144 | * frame payload so the application needs to try sending something and the Network |
| borlanic | 0:fbdae7e6d805 | 145 | * Server may respond during the RX slots. |
| borlanic | 0:fbdae7e6d805 | 146 | * |
| borlanic | 0:fbdae7e6d805 | 147 | * This API is usable only when the 'link_check_resp' callback is set by |
| borlanic | 0:fbdae7e6d805 | 148 | * the application. See add_lora_app_callbacks API. If the above mentioned |
| borlanic | 0:fbdae7e6d805 | 149 | * callback is not set, a LORAWAN_STATUS_PARAMETER_INVALID error is thrown. |
| borlanic | 0:fbdae7e6d805 | 150 | * |
| borlanic | 0:fbdae7e6d805 | 151 | * First parameter to callback function is the demodulation margin and |
| borlanic | 0:fbdae7e6d805 | 152 | * the second parameter is the number of gateways that successfully received |
| borlanic | 0:fbdae7e6d805 | 153 | * the last request. |
| borlanic | 0:fbdae7e6d805 | 154 | * |
| borlanic | 0:fbdae7e6d805 | 155 | * A 'Link Check Request' MAC command remains set for every subsequent |
| borlanic | 0:fbdae7e6d805 | 156 | * transmission, until/unless application explicitly turns it off using |
| borlanic | 0:fbdae7e6d805 | 157 | * remove_link_check_request() API. |
| borlanic | 0:fbdae7e6d805 | 158 | * |
| borlanic | 0:fbdae7e6d805 | 159 | * @return LORAWAN_STATUS_OK on successfully queuing a request, or |
| borlanic | 0:fbdae7e6d805 | 160 | * a negative error code on failure. |
| borlanic | 0:fbdae7e6d805 | 161 | * |
| borlanic | 0:fbdae7e6d805 | 162 | */ |
| borlanic | 0:fbdae7e6d805 | 163 | virtual lorawan_status_t add_link_check_request(); |
| borlanic | 0:fbdae7e6d805 | 164 | |
| borlanic | 0:fbdae7e6d805 | 165 | /** Removes link check request sticky MAC command. |
| borlanic | 0:fbdae7e6d805 | 166 | * |
| borlanic | 0:fbdae7e6d805 | 167 | * Any already queued request may still get entertained. However, no new |
| borlanic | 0:fbdae7e6d805 | 168 | * requests will be made. |
| borlanic | 0:fbdae7e6d805 | 169 | */ |
| borlanic | 0:fbdae7e6d805 | 170 | virtual void remove_link_check_request(); |
| borlanic | 0:fbdae7e6d805 | 171 | |
| borlanic | 0:fbdae7e6d805 | 172 | /** Sets up a particular data rate |
| borlanic | 0:fbdae7e6d805 | 173 | * |
| borlanic | 0:fbdae7e6d805 | 174 | * `set_datarate()` first verifies whether the data rate given is valid or not. |
| borlanic | 0:fbdae7e6d805 | 175 | * If it is valid, the system sets the given data rate to the channel. |
| borlanic | 0:fbdae7e6d805 | 176 | * |
| borlanic | 0:fbdae7e6d805 | 177 | * @param data_rate The intended data rate, for example DR_0 or DR_1. |
| borlanic | 0:fbdae7e6d805 | 178 | * Please note, that the macro DR_* can mean different |
| borlanic | 0:fbdae7e6d805 | 179 | * things in different regions. |
| borlanic | 0:fbdae7e6d805 | 180 | * @return LORAWAN_STATUS_OK if everything goes well, otherwise |
| borlanic | 0:fbdae7e6d805 | 181 | * a negative error code. |
| borlanic | 0:fbdae7e6d805 | 182 | */ |
| borlanic | 0:fbdae7e6d805 | 183 | virtual lorawan_status_t set_datarate(uint8_t data_rate); |
| borlanic | 0:fbdae7e6d805 | 184 | |
| borlanic | 0:fbdae7e6d805 | 185 | /** Enables adaptive data rate (ADR). |
| borlanic | 0:fbdae7e6d805 | 186 | * |
| borlanic | 0:fbdae7e6d805 | 187 | * The underlying LoRaPHY and LoRaMac layers handle the data rate automatically |
| borlanic | 0:fbdae7e6d805 | 188 | * for the user, based upon the radio conditions (network congestion). |
| borlanic | 0:fbdae7e6d805 | 189 | * |
| borlanic | 0:fbdae7e6d805 | 190 | * @return LORAWAN_STATUS_OK or negative error code otherwise. |
| borlanic | 0:fbdae7e6d805 | 191 | */ |
| borlanic | 0:fbdae7e6d805 | 192 | virtual lorawan_status_t enable_adaptive_datarate(); |
| borlanic | 0:fbdae7e6d805 | 193 | |
| borlanic | 0:fbdae7e6d805 | 194 | /** Disables adaptive data rate. |
| borlanic | 0:fbdae7e6d805 | 195 | * |
| borlanic | 0:fbdae7e6d805 | 196 | * When adaptive data rate (ADR) is disabled, you can either set a certain |
| borlanic | 0:fbdae7e6d805 | 197 | * data rate or the MAC layer selects a default value. |
| borlanic | 0:fbdae7e6d805 | 198 | * |
| borlanic | 0:fbdae7e6d805 | 199 | * @return LORAWAN_STATUS_OK or negative error code otherwise. |
| borlanic | 0:fbdae7e6d805 | 200 | */ |
| borlanic | 0:fbdae7e6d805 | 201 | virtual lorawan_status_t disable_adaptive_datarate(); |
| borlanic | 0:fbdae7e6d805 | 202 | |
| borlanic | 0:fbdae7e6d805 | 203 | /** Sets up the retry counter for confirmed messages. |
| borlanic | 0:fbdae7e6d805 | 204 | * |
| borlanic | 0:fbdae7e6d805 | 205 | * Valid for confirmed messages only. |
| borlanic | 0:fbdae7e6d805 | 206 | * |
| borlanic | 0:fbdae7e6d805 | 207 | * The number of trials to transmit the frame, if the LoRaMAC layer did not |
| borlanic | 0:fbdae7e6d805 | 208 | * receive an acknowledgment. The MAC performs a data rate adaptation as in |
| borlanic | 0:fbdae7e6d805 | 209 | * the LoRaWAN Specification V1.0.2, chapter 18.4, table on page 64. |
| borlanic | 0:fbdae7e6d805 | 210 | * |
| borlanic | 0:fbdae7e6d805 | 211 | * Note, that if number of retries is set to 1 or 2, MAC will not decrease |
| borlanic | 0:fbdae7e6d805 | 212 | * the datarate, if the LoRaMAC layer did not receive an acknowledgment. |
| borlanic | 0:fbdae7e6d805 | 213 | * |
| borlanic | 0:fbdae7e6d805 | 214 | * @param count The number of retries for confirmed messages. |
| borlanic | 0:fbdae7e6d805 | 215 | * |
| borlanic | 0:fbdae7e6d805 | 216 | * @return LORAWAN_STATUS_OK or a negative error code. |
| borlanic | 0:fbdae7e6d805 | 217 | */ |
| borlanic | 0:fbdae7e6d805 | 218 | virtual lorawan_status_t set_confirmed_msg_retries(uint8_t count); |
| borlanic | 0:fbdae7e6d805 | 219 | |
| borlanic | 0:fbdae7e6d805 | 220 | /** Sets the channel plan. |
| borlanic | 0:fbdae7e6d805 | 221 | * |
| borlanic | 0:fbdae7e6d805 | 222 | * You can provide a list of channels with appropriate parameters filled |
| borlanic | 0:fbdae7e6d805 | 223 | * in. However, this list is not absolute. The stack applies a CF-List whenever |
| borlanic | 0:fbdae7e6d805 | 224 | * available, which means that the network can overwrite your channel |
| borlanic | 0:fbdae7e6d805 | 225 | * frequency settings right after Join Accept is received. You may try |
| borlanic | 0:fbdae7e6d805 | 226 | * to set up any channel or channels after that, and if the channel requested |
| borlanic | 0:fbdae7e6d805 | 227 | * is already active, the request is silently ignored. A negative error |
| borlanic | 0:fbdae7e6d805 | 228 | * code is returned if there is any problem with parameters. |
| borlanic | 0:fbdae7e6d805 | 229 | * |
| borlanic | 0:fbdae7e6d805 | 230 | * Please note that this API can also be used to add a single channel to the |
| borlanic | 0:fbdae7e6d805 | 231 | * existing channel plan. |
| borlanic | 0:fbdae7e6d805 | 232 | * |
| borlanic | 0:fbdae7e6d805 | 233 | * There is no reverse mechanism in the 1.0.2 specification for a node to request |
| borlanic | 0:fbdae7e6d805 | 234 | * a particular channel. Only the network server can initiate such a request. |
| borlanic | 0:fbdae7e6d805 | 235 | * You need to ensure that the corresponding base station supports the channel or channels being added. |
| borlanic | 0:fbdae7e6d805 | 236 | * |
| borlanic | 0:fbdae7e6d805 | 237 | * If your list includes a default channel (a channel where Join Requests |
| borlanic | 0:fbdae7e6d805 | 238 | * are received) you cannot fully configure the channel parameters. |
| borlanic | 0:fbdae7e6d805 | 239 | * Either leave the channel settings to default or check your |
| borlanic | 0:fbdae7e6d805 | 240 | * corresponding PHY layer implementation. For example, LoRaPHYE868. |
| borlanic | 0:fbdae7e6d805 | 241 | * |
| borlanic | 0:fbdae7e6d805 | 242 | * @param channel_plan The channel plan to set. |
| borlanic | 0:fbdae7e6d805 | 243 | * |
| borlanic | 0:fbdae7e6d805 | 244 | * @return LORAWAN_STATUS_OK on success, a negative error |
| borlanic | 0:fbdae7e6d805 | 245 | * code on failure. |
| borlanic | 0:fbdae7e6d805 | 246 | */ |
| borlanic | 0:fbdae7e6d805 | 247 | virtual lorawan_status_t set_channel_plan(const lorawan_channelplan_t &channel_plan); |
| borlanic | 0:fbdae7e6d805 | 248 | |
| borlanic | 0:fbdae7e6d805 | 249 | /** Gets the channel plans from the LoRa stack. |
| borlanic | 0:fbdae7e6d805 | 250 | * |
| borlanic | 0:fbdae7e6d805 | 251 | * Once you have selected a particular PHY layer, a set of channels |
| borlanic | 0:fbdae7e6d805 | 252 | * is automatically activated. Right after connecting, you can use this API |
| borlanic | 0:fbdae7e6d805 | 253 | * to see the current plan. Otherwise, this API returns the channel |
| borlanic | 0:fbdae7e6d805 | 254 | * plan that you have set using `set_channel_plan()`. |
| borlanic | 0:fbdae7e6d805 | 255 | * |
| borlanic | 0:fbdae7e6d805 | 256 | * @param channel_plan The current channel plan information. |
| borlanic | 0:fbdae7e6d805 | 257 | * |
| borlanic | 0:fbdae7e6d805 | 258 | * @return LORAWAN_STATUS_OK on success, a negative error |
| borlanic | 0:fbdae7e6d805 | 259 | * code on failure. |
| borlanic | 0:fbdae7e6d805 | 260 | */ |
| borlanic | 0:fbdae7e6d805 | 261 | virtual lorawan_status_t get_channel_plan(lorawan_channelplan_t &channel_plan); |
| borlanic | 0:fbdae7e6d805 | 262 | |
| borlanic | 0:fbdae7e6d805 | 263 | /** Removes an active channel plan. |
| borlanic | 0:fbdae7e6d805 | 264 | * |
| borlanic | 0:fbdae7e6d805 | 265 | * You cannot remove default channels (the channels the base stations are listening to). |
| borlanic | 0:fbdae7e6d805 | 266 | * When a plan is abolished, only the non-default channels are removed. |
| borlanic | 0:fbdae7e6d805 | 267 | * |
| borlanic | 0:fbdae7e6d805 | 268 | * @return LORAWAN_STATUS_OK on success, a negative error |
| borlanic | 0:fbdae7e6d805 | 269 | * code on failure. |
| borlanic | 0:fbdae7e6d805 | 270 | */ |
| borlanic | 0:fbdae7e6d805 | 271 | virtual lorawan_status_t remove_channel_plan(); |
| borlanic | 0:fbdae7e6d805 | 272 | |
| borlanic | 0:fbdae7e6d805 | 273 | /** Removes a single channel. |
| borlanic | 0:fbdae7e6d805 | 274 | * |
| borlanic | 0:fbdae7e6d805 | 275 | * You cannot remove default channels (the channels the base stations are listening to). |
| borlanic | 0:fbdae7e6d805 | 276 | * |
| borlanic | 0:fbdae7e6d805 | 277 | * @param index The channel index. |
| borlanic | 0:fbdae7e6d805 | 278 | * |
| borlanic | 0:fbdae7e6d805 | 279 | * @return LORAWAN_STATUS_OK on success, a negative error |
| borlanic | 0:fbdae7e6d805 | 280 | * code on failure. |
| borlanic | 0:fbdae7e6d805 | 281 | */ |
| borlanic | 0:fbdae7e6d805 | 282 | virtual lorawan_status_t remove_channel(uint8_t index); |
| borlanic | 0:fbdae7e6d805 | 283 | |
| borlanic | 0:fbdae7e6d805 | 284 | /** Send message to gateway |
| borlanic | 0:fbdae7e6d805 | 285 | * |
| borlanic | 0:fbdae7e6d805 | 286 | * @param port The application port number. Port numbers 0 and 224 |
| borlanic | 0:fbdae7e6d805 | 287 | * are reserved, whereas port numbers from 1 to 223 |
| borlanic | 0:fbdae7e6d805 | 288 | * (0x01 to 0xDF) are valid port numbers. |
| borlanic | 0:fbdae7e6d805 | 289 | * Anything out of this range is illegal. |
| borlanic | 0:fbdae7e6d805 | 290 | * |
| borlanic | 0:fbdae7e6d805 | 291 | * @param data A pointer to the data being sent. The ownership of the |
| borlanic | 0:fbdae7e6d805 | 292 | * buffer is not transferred. The data is copied to the |
| borlanic | 0:fbdae7e6d805 | 293 | * internal buffers. |
| borlanic | 0:fbdae7e6d805 | 294 | * |
| borlanic | 0:fbdae7e6d805 | 295 | * @param length The size of data in bytes. |
| borlanic | 0:fbdae7e6d805 | 296 | * |
| borlanic | 0:fbdae7e6d805 | 297 | * @param flags A flag used to determine what type of |
| borlanic | 0:fbdae7e6d805 | 298 | * message is being sent, for example: |
| borlanic | 0:fbdae7e6d805 | 299 | * |
| borlanic | 0:fbdae7e6d805 | 300 | * MSG_UNCONFIRMED_FLAG = 0x01 |
| borlanic | 0:fbdae7e6d805 | 301 | * MSG_CONFIRMED_FLAG = 0x02 |
| borlanic | 0:fbdae7e6d805 | 302 | * MSG_MULTICAST_FLAG = 0x04 |
| borlanic | 0:fbdae7e6d805 | 303 | * MSG_PROPRIETARY_FLAG = 0x08 |
| borlanic | 0:fbdae7e6d805 | 304 | * MSG_MULTICAST_FLAG and MSG_PROPRIETARY_FLAG can be |
| borlanic | 0:fbdae7e6d805 | 305 | * used in conjunction with MSG_UNCONFIRMED_FLAG and |
| borlanic | 0:fbdae7e6d805 | 306 | * MSG_CONFIRMED_FLAG depending on the intended use. |
| borlanic | 0:fbdae7e6d805 | 307 | * |
| borlanic | 0:fbdae7e6d805 | 308 | * MSG_PROPRIETARY_FLAG|MSG_CONFIRMED_FLAG mask will set |
| borlanic | 0:fbdae7e6d805 | 309 | * a confirmed message flag for a proprietary message. |
| borlanic | 0:fbdae7e6d805 | 310 | * MSG_CONFIRMED_FLAG and MSG_UNCONFIRMED_FLAG are |
| borlanic | 0:fbdae7e6d805 | 311 | * mutually exclusive. |
| borlanic | 0:fbdae7e6d805 | 312 | * |
| borlanic | 0:fbdae7e6d805 | 313 | * |
| borlanic | 0:fbdae7e6d805 | 314 | * @return The number of bytes sent, or |
| borlanic | 0:fbdae7e6d805 | 315 | * LORAWAN_STATUS_WOULD_BLOCK if another TX is |
| borlanic | 0:fbdae7e6d805 | 316 | * ongoing, or a negative error code on failure. |
| borlanic | 0:fbdae7e6d805 | 317 | */ |
| borlanic | 0:fbdae7e6d805 | 318 | virtual int16_t send(uint8_t port, const uint8_t* data, uint16_t length, |
| borlanic | 0:fbdae7e6d805 | 319 | int flags); |
| borlanic | 0:fbdae7e6d805 | 320 | |
| borlanic | 0:fbdae7e6d805 | 321 | /** Receives a message from the Network Server on a specific port. |
| borlanic | 0:fbdae7e6d805 | 322 | * |
| borlanic | 0:fbdae7e6d805 | 323 | * @param port The application port number. Port numbers 0 and 224 |
| borlanic | 0:fbdae7e6d805 | 324 | * are reserved, whereas port numbers from 1 to 223 |
| borlanic | 0:fbdae7e6d805 | 325 | * (0x01 to 0xDF) are valid port numbers. |
| borlanic | 0:fbdae7e6d805 | 326 | * Anything out of this range is illegal. |
| borlanic | 0:fbdae7e6d805 | 327 | * |
| borlanic | 0:fbdae7e6d805 | 328 | * @param data A pointer to buffer where the received data will be |
| borlanic | 0:fbdae7e6d805 | 329 | * stored. |
| borlanic | 0:fbdae7e6d805 | 330 | * |
| borlanic | 0:fbdae7e6d805 | 331 | * @param length The size of data in bytes |
| borlanic | 0:fbdae7e6d805 | 332 | * |
| borlanic | 0:fbdae7e6d805 | 333 | * @param flags A flag is used to determine what type of |
| borlanic | 0:fbdae7e6d805 | 334 | * message is being sent, for example: |
| borlanic | 0:fbdae7e6d805 | 335 | * |
| borlanic | 0:fbdae7e6d805 | 336 | * MSG_UNCONFIRMED_FLAG = 0x01, |
| borlanic | 0:fbdae7e6d805 | 337 | * MSG_CONFIRMED_FLAG = 0x02 |
| borlanic | 0:fbdae7e6d805 | 338 | * MSG_MULTICAST_FLAG = 0x04, |
| borlanic | 0:fbdae7e6d805 | 339 | * MSG_PROPRIETARY_FLAG = 0x08 |
| borlanic | 0:fbdae7e6d805 | 340 | * |
| borlanic | 0:fbdae7e6d805 | 341 | * MSG_MULTICAST_FLAG and MSG_PROPRIETARY_FLAG can be |
| borlanic | 0:fbdae7e6d805 | 342 | * used in conjunction with MSG_UNCONFIRMED_FLAG and |
| borlanic | 0:fbdae7e6d805 | 343 | * MSG_CONFIRMED_FLAG depending on the intended use. |
| borlanic | 0:fbdae7e6d805 | 344 | * |
| borlanic | 0:fbdae7e6d805 | 345 | * MSG_PROPRIETARY_FLAG|MSG_CONFIRMED_FLAG mask will set |
| borlanic | 0:fbdae7e6d805 | 346 | * a confirmed message flag for a proprietary message. |
| borlanic | 0:fbdae7e6d805 | 347 | * |
| borlanic | 0:fbdae7e6d805 | 348 | * MSG_CONFIRMED_FLAG and MSG_UNCONFIRMED_FLAG are |
| borlanic | 0:fbdae7e6d805 | 349 | * not mutually exclusive, i.e., the user can subscribe to |
| borlanic | 0:fbdae7e6d805 | 350 | * receive both CONFIRMED AND UNCONFIRMED messages at |
| borlanic | 0:fbdae7e6d805 | 351 | * the same time. |
| borlanic | 0:fbdae7e6d805 | 352 | * |
| borlanic | 0:fbdae7e6d805 | 353 | * @return It could be one of these: |
| borlanic | 0:fbdae7e6d805 | 354 | * i) 0 if there is nothing else to read. |
| borlanic | 0:fbdae7e6d805 | 355 | * ii) Number of bytes written to user buffer. |
| borlanic | 0:fbdae7e6d805 | 356 | * iii) LORAWAN_STATUS_WOULD_BLOCK if there is |
| borlanic | 0:fbdae7e6d805 | 357 | * nothing available to read at the moment. |
| borlanic | 0:fbdae7e6d805 | 358 | * iv) A negative error code on failure. |
| borlanic | 0:fbdae7e6d805 | 359 | */ |
| borlanic | 0:fbdae7e6d805 | 360 | virtual int16_t receive(uint8_t port, uint8_t* data, uint16_t length, int flags); |
| borlanic | 0:fbdae7e6d805 | 361 | |
| borlanic | 0:fbdae7e6d805 | 362 | /** Receives a message from the Network Server on any port. |
| borlanic | 0:fbdae7e6d805 | 363 | * |
| borlanic | 0:fbdae7e6d805 | 364 | * @param data A pointer to buffer where the received data will be |
| borlanic | 0:fbdae7e6d805 | 365 | * stored. |
| borlanic | 0:fbdae7e6d805 | 366 | * |
| borlanic | 0:fbdae7e6d805 | 367 | * @param length The size of data in bytes |
| borlanic | 0:fbdae7e6d805 | 368 | * |
| borlanic | 0:fbdae7e6d805 | 369 | * @param port Return the number of port to which message was received. |
| borlanic | 0:fbdae7e6d805 | 370 | * |
| borlanic | 0:fbdae7e6d805 | 371 | * @param flags Return flags to determine what type of message was received. |
| borlanic | 0:fbdae7e6d805 | 372 | * MSG_UNCONFIRMED_FLAG = 0x01 |
| borlanic | 0:fbdae7e6d805 | 373 | * MSG_CONFIRMED_FLAG = 0x02 |
| borlanic | 0:fbdae7e6d805 | 374 | * MSG_MULTICAST_FLAG = 0x04 |
| borlanic | 0:fbdae7e6d805 | 375 | * MSG_PROPRIETARY_FLAG = 0x08 |
| borlanic | 0:fbdae7e6d805 | 376 | * |
| borlanic | 0:fbdae7e6d805 | 377 | * @return It could be one of these: |
| borlanic | 0:fbdae7e6d805 | 378 | * i) 0 if there is nothing else to read. |
| borlanic | 0:fbdae7e6d805 | 379 | * ii) Number of bytes written to user buffer. |
| borlanic | 0:fbdae7e6d805 | 380 | * iii) LORAWAN_STATUS_WOULD_BLOCK if there is |
| borlanic | 0:fbdae7e6d805 | 381 | * nothing available to read at the moment. |
| borlanic | 0:fbdae7e6d805 | 382 | * iv) A negative error code on failure. |
| borlanic | 0:fbdae7e6d805 | 383 | */ |
| borlanic | 0:fbdae7e6d805 | 384 | virtual int16_t receive(uint8_t* data, uint16_t length, uint8_t& port, int& flags); |
| borlanic | 0:fbdae7e6d805 | 385 | |
| borlanic | 0:fbdae7e6d805 | 386 | /** Add application callbacks to the stack. |
| borlanic | 0:fbdae7e6d805 | 387 | * |
| borlanic | 0:fbdae7e6d805 | 388 | * An example of using this API with a latch onto 'lorawan_events' could be: |
| borlanic | 0:fbdae7e6d805 | 389 | * |
| borlanic | 0:fbdae7e6d805 | 390 | * LoRaWANInterface lorawan(radio); |
| borlanic | 0:fbdae7e6d805 | 391 | * lorawan_app_callbacks_t cbs; |
| borlanic | 0:fbdae7e6d805 | 392 | * static void my_event_handler(); |
| borlanic | 0:fbdae7e6d805 | 393 | * |
| borlanic | 0:fbdae7e6d805 | 394 | * int main() |
| borlanic | 0:fbdae7e6d805 | 395 | * { |
| borlanic | 0:fbdae7e6d805 | 396 | * lorawan.initialize(); |
| borlanic | 0:fbdae7e6d805 | 397 | * cbs.lorawan_events = mbed::callback(my_event_handler); |
| borlanic | 0:fbdae7e6d805 | 398 | * lorawan.add_app_callbacks(&cbs); |
| borlanic | 0:fbdae7e6d805 | 399 | * lorawan.connect(); |
| borlanic | 0:fbdae7e6d805 | 400 | * } |
| borlanic | 0:fbdae7e6d805 | 401 | * |
| borlanic | 0:fbdae7e6d805 | 402 | * static void my_event_handler(lorawan_event_t event) |
| borlanic | 0:fbdae7e6d805 | 403 | * { |
| borlanic | 0:fbdae7e6d805 | 404 | * switch(event) { |
| borlanic | 0:fbdae7e6d805 | 405 | * case CONNECTED: |
| borlanic | 0:fbdae7e6d805 | 406 | * //do something |
| borlanic | 0:fbdae7e6d805 | 407 | * break; |
| borlanic | 0:fbdae7e6d805 | 408 | * case DISCONNECTED: |
| borlanic | 0:fbdae7e6d805 | 409 | * //do something |
| borlanic | 0:fbdae7e6d805 | 410 | * break; |
| borlanic | 0:fbdae7e6d805 | 411 | * case TX_DONE: |
| borlanic | 0:fbdae7e6d805 | 412 | * //do something |
| borlanic | 0:fbdae7e6d805 | 413 | * break; |
| borlanic | 0:fbdae7e6d805 | 414 | * default: |
| borlanic | 0:fbdae7e6d805 | 415 | * break; |
| borlanic | 0:fbdae7e6d805 | 416 | * } |
| borlanic | 0:fbdae7e6d805 | 417 | * } |
| borlanic | 0:fbdae7e6d805 | 418 | * |
| borlanic | 0:fbdae7e6d805 | 419 | * @param callbacks A pointer to the structure containing application |
| borlanic | 0:fbdae7e6d805 | 420 | * callbacks. |
| borlanic | 0:fbdae7e6d805 | 421 | * |
| borlanic | 0:fbdae7e6d805 | 422 | * @return LORAWAN_STATUS_OK on success, a negative error |
| borlanic | 0:fbdae7e6d805 | 423 | * code on failure. |
| borlanic | 0:fbdae7e6d805 | 424 | */ |
| borlanic | 0:fbdae7e6d805 | 425 | virtual lorawan_status_t add_app_callbacks(lorawan_app_callbacks_t *callbacks); |
| borlanic | 0:fbdae7e6d805 | 426 | |
| borlanic | 0:fbdae7e6d805 | 427 | /** Change device class |
| borlanic | 0:fbdae7e6d805 | 428 | * |
| borlanic | 0:fbdae7e6d805 | 429 | * Change current device class. |
| borlanic | 0:fbdae7e6d805 | 430 | * |
| borlanic | 0:fbdae7e6d805 | 431 | * @param device_class The device class |
| borlanic | 0:fbdae7e6d805 | 432 | * |
| borlanic | 0:fbdae7e6d805 | 433 | * @return LORAWAN_STATUS_OK on success, |
| borlanic | 0:fbdae7e6d805 | 434 | * LORAWAN_STATUS_UNSUPPORTED is requested class is not supported, |
| borlanic | 0:fbdae7e6d805 | 435 | * or other negative error code if request failed. |
| borlanic | 0:fbdae7e6d805 | 436 | */ |
| borlanic | 0:fbdae7e6d805 | 437 | virtual lorawan_status_t set_device_class(const device_class_t device_class); |
| borlanic | 0:fbdae7e6d805 | 438 | |
| borlanic | 0:fbdae7e6d805 | 439 | void lock(void) { _lw_stack.lock(); } |
| borlanic | 0:fbdae7e6d805 | 440 | void unlock(void) { _lw_stack.unlock(); } |
| borlanic | 0:fbdae7e6d805 | 441 | |
| borlanic | 0:fbdae7e6d805 | 442 | |
| borlanic | 0:fbdae7e6d805 | 443 | private: |
| borlanic | 0:fbdae7e6d805 | 444 | typedef mbed::ScopedLock<LoRaWANInterface> Lock; |
| borlanic | 0:fbdae7e6d805 | 445 | |
| borlanic | 0:fbdae7e6d805 | 446 | LoRaWANStack _lw_stack; |
| borlanic | 0:fbdae7e6d805 | 447 | }; |
| borlanic | 0:fbdae7e6d805 | 448 | |
| borlanic | 0:fbdae7e6d805 | 449 | #endif /* LORAWANINTERFACE_H_ */ |