Nathan Yonkee
init
Embed:
(wiki syntax)
Show/hide line numbers
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_ */
Generated on Tue Jul 12 2022 13:24:48 by
1.7.2