Nathan Yonkee
init
Embed:
(wiki syntax)
Show/hide line numbers
LoRaWANBase.h
00001 /** 00002 * Copyright (c) 2017, Arm Limited and affiliates. 00003 * SPDX-License-Identifier: Apache-2.0 00004 * 00005 * Licensed under the Apache License, Version 2.0 (the "License"); 00006 * you may not use this file except in compliance with the License. 00007 * You may obtain a copy of the License at 00008 * 00009 * http://www.apache.org/licenses/LICENSE-2.0 00010 * 00011 * Unless required by applicable law or agreed to in writing, software 00012 * distributed under the License is distributed on an "AS IS" BASIS, 00013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00014 * See the License for the specific language governing permissions and 00015 * limitations under the License. 00016 */ 00017 00018 00019 #ifndef LORAWAN_BASE_H_ 00020 #define LORAWAN_BASE_H_ 00021 00022 #include "lorawan/system/lorawan_data_structures.h" 00023 #include "events/EventQueue.h" 00024 00025 class LoRaWANBase { 00026 00027 public: 00028 /** Initialize the LoRa stack. 00029 * 00030 * You must call this before using the LoRa stack. 00031 * 00032 * @param queue A pointer to EventQueue provided by the application. 00033 * 00034 * @return LORAWAN_STATUS_OK on success, a negative error code on 00035 * failure. 00036 */ 00037 virtual lorawan_status_t initialize(events::EventQueue *queue) = 0; 00038 00039 /** Connect OTAA or ABP by setup. 00040 * 00041 * Connect by Over The Air Activation or Activation By Personalization. 00042 * The connection type is selected at the setup. 00043 * 00044 * @return LORAWAN_STATUS_OK on success, a negative error code on 00045 * failure. 00046 */ 00047 virtual lorawan_status_t connect() = 0; 00048 00049 /** Connect OTAA or ABP by parameters 00050 * 00051 * Connect by Over The Air Activation or Activation By Personalization. 00052 * The connection type is selected using the parameters. 00053 * You need to define the parameters in the main application. 00054 * 00055 * @param connect Options how end-device will connect to gateway 00056 * @return LORAWAN_STATUS_OK on success, negative error code 00057 * on failure 00058 */ 00059 virtual lorawan_status_t connect(const lorawan_connect_t &connect) = 0; 00060 00061 /** Disconnects the current session. 00062 * 00063 * @return LORAWAN_STATUS_OK on success, a negative error code on failure. 00064 */ 00065 virtual lorawan_status_t disconnect() = 0; 00066 00067 /** Validate the connectivity with the network. 00068 * 00069 * Application may use this API to submit a request to the stack for 00070 * validation of its connectivity to a Network Server. Under the hood, this 00071 * API schedules a Link Check Request command (LinkCheckReq) for the network 00072 * server and once the response, i.e., LinkCheckAns MAC command is received 00073 * from the Network Server, user provided method is called. 00074 * 00075 * This API is usable only when the link check response is callback set by 00076 * the application. See add_lora_app_callbacks API. If the above mentioned 00077 * callback is not set, a LORAWAN_STATUS_PARAMETER_INVALID error is thrown. 00078 * 00079 * First parameter to callback function is the demodulation margin and 00080 * the second parameter is the number of gateways that successfully received 00081 * the last request. 00082 * 00083 * A 'Link Check Request' MAC command remains set for every subsequent 00084 * transmission, until/unless application explicitly turns it off using 00085 * remove_link_check_request() API. 00086 * 00087 * @return LORAWAN_STATUS_OK on successfully queuing a request, or 00088 * a negative error code on failure. 00089 * 00090 */ 00091 virtual lorawan_status_t add_link_check_request() = 0; 00092 00093 /** Detaches Link Request MAC command. 00094 * 00095 * Removes sticky MAC command for link check request. 00096 */ 00097 virtual void remove_link_check_request() = 0; 00098 00099 /** Sets up a particular data rate of choice 00100 * 00101 * @param data_rate Intended data rate e.g., DR_0, DR_1 etc. 00102 * Caution is advised as the macro DR_* can mean different 00103 * things while being in a different region. 00104 * @return LORAWAN_STATUS_OK if everything goes well, otherwise 00105 * a negative error code. 00106 */ 00107 virtual lorawan_status_t set_datarate(uint8_t data_rate) = 0; 00108 00109 /** Enables adaptive data rate (ADR) 00110 * 00111 * Underlying LoRaPHY and LoRaMac layers handle the data rate automatically 00112 * for the user based upon radio conditions (network congestion). 00113 * 00114 * @return LORAWAN_STATUS_OK on success, negative error code 00115 * on failure. 00116 */ 00117 virtual lorawan_status_t enable_adaptive_datarate() = 0; 00118 00119 /** Disables adaptive data rate 00120 * 00121 * When adaptive data rate (ADR) is disabled, user can either set a certain 00122 * data rate or the Mac layer will choose a default value. 00123 * 00124 * @return LORAWAN_STATUS_OK on success, negative error code 00125 * on failure. 00126 */ 00127 virtual lorawan_status_t disable_adaptive_datarate() = 0; 00128 00129 /** Sets up retry counter for confirmed messages 00130 * 00131 * Valid only for confirmed messages. 00132 * 00133 * Number of trials to transmit the frame, if the LoRaMAC layer did not 00134 * receive an acknowledgment. The MAC performs a data-rate adaptation, 00135 * according to the LoRaWAN Specification V1.0.2, chapter 18.4, according 00136 * to the table on page 64. 00137 * 00138 * Note, that if the number of trials is set to 1 or 2, the MAC will not decrease 00139 * the datarate, in case the LoRaMAC layer did not receive an acknowledgment. 00140 * 00141 * @param count number of retries for confirmed messages 00142 * 00143 * @return LORAWAN_STATUS_OK or a negative error code 00144 */ 00145 virtual lorawan_status_t set_confirmed_msg_retries(uint8_t count) = 0; 00146 00147 /** Sets channel plan 00148 * 00149 * @param channel_plan The defined channel plans to be set. 00150 * @return 0 on success, a negative error code on failure. 00151 */ 00152 virtual lorawan_status_t set_channel_plan(const lorawan_channelplan_t &channel_plan) = 0; 00153 00154 /** Gets the current channel plan. 00155 * 00156 * @param channel_plan The current channel information. 00157 * 00158 * @return LORAWAN_STATUS_OK on success, a negative error 00159 * code on failure. 00160 */ 00161 virtual lorawan_status_t get_channel_plan(lorawan_channelplan_t &channel_plan) = 0; 00162 00163 /** Removes currently active channel plan 00164 * 00165 * Default channels (channels where Base Stations are listening) are not 00166 * allowed to be removed. So when a plan is abolished, only non-default 00167 * channels are removed. 00168 * 00169 * @return LORAWAN_STATUS_OK on success, negative error 00170 * code on failure 00171 */ 00172 virtual lorawan_status_t remove_channel_plan() = 0; 00173 00174 /** Removes a given single channel 00175 * 00176 * Default channels (channels where Base Stations are listening) are not 00177 * allowed to be removed. 00178 * 00179 * @param index The channel index 00180 * 00181 * @return LORAWAN_STATUS_OK on success, negative error 00182 * code on failure 00183 */ 00184 virtual lorawan_status_t remove_channel(uint8_t index) = 0; 00185 00186 /** Send message to gateway 00187 * 00188 * @param port The application port number. Port numbers 0 and 224 00189 * are reserved, whereas port numbers from 1 to 223 00190 * (0x01 to 0xDF) are valid port numbers. 00191 * Anything out of this range is illegal. 00192 * 00193 * @param data A pointer to the data being sent. The ownership of the 00194 * buffer is not transferred. The data is copied to the 00195 * internal buffers. 00196 * 00197 * @param length The size of data in bytes. 00198 * 00199 * @param flags A flag used to determine what type of 00200 * message is being sent, for example: 00201 * 00202 * MSG_UNCONFIRMED_FLAG = 0x01 00203 * MSG_CONFIRMED_FLAG = 0x02 00204 * MSG_MULTICAST_FLAG = 0x04 00205 * MSG_PROPRIETARY_FLAG = 0x08 00206 * MSG_MULTICAST_FLAG and MSG_PROPRIETARY_FLAG can be 00207 * used in conjunction with MSG_UNCONFIRMED_FLAG and 00208 * MSG_CONFIRMED_FLAG depending on the intended use. 00209 * 00210 * MSG_PROPRIETARY_FLAG|MSG_CONFIRMED_FLAG mask will set 00211 * a confirmed message flag for a proprietary message. 00212 * MSG_CONFIRMED_FLAG and MSG_UNCONFIRMED_FLAG are 00213 * mutually exclusive. 00214 * 00215 * 00216 * @return The number of bytes sent, or 00217 * LORAWAN_STATUS_WOULD_BLOCK if another TX is 00218 * ongoing, or a negative error code on failure. 00219 */ 00220 virtual int16_t send(uint8_t port, const uint8_t* data, 00221 uint16_t length, int flags) = 0; 00222 00223 /** Receives a message from the Network Server. 00224 * 00225 * @param port The application port number. Port numbers 0 and 224 00226 * are reserved, whereas port numbers from 1 to 223 00227 * (0x01 to 0xDF) are valid port numbers. 00228 * Anything out of this range is illegal. 00229 * 00230 * @param data A pointer to buffer where the received data will be 00231 * stored. 00232 * 00233 * @param length The size of data in bytes. 00234 * 00235 * @param flags A flag is used to determine what type of 00236 * message is being sent, for example: 00237 * 00238 * MSG_UNCONFIRMED_FLAG = 0x01, 00239 * MSG_CONFIRMED_FLAG = 0x02 00240 * MSG_MULTICAST_FLAG = 0x04, 00241 * MSG_PROPRIETARY_FLAG = 0x08 00242 * 00243 * MSG_MULTICAST_FLAG and MSG_PROPRIETARY_FLAG can be 00244 * used in conjunction with MSG_UNCONFIRMED_FLAG and 00245 * MSG_CONFIRMED_FLAG depending on the intended use. 00246 * 00247 * MSG_PROPRIETARY_FLAG|MSG_CONFIRMED_FLAG mask will set 00248 * a confirmed message flag for a proprietary message. 00249 * 00250 * MSG_CONFIRMED_FLAG and MSG_UNCONFIRMED_FLAG are 00251 * not mutually exclusive, i.e., the user can subscribe to 00252 * receive both CONFIRMED AND UNCONFIRMED messages at 00253 * the same time. 00254 * 00255 * @return It could be one of these: 00256 * i) 0 if there is nothing else to read. 00257 * ii) Number of bytes written to user buffer. 00258 * iii) LORAWAN_STATUS_WOULD_BLOCK if there is 00259 * nothing available to read at the moment. 00260 * iv) A negative error code on failure. 00261 */ 00262 virtual int16_t receive(uint8_t port, uint8_t* data, uint16_t length, 00263 int flags) = 0; 00264 00265 /** Add application callbacks to the stack. 00266 * 00267 * 'lorawan_app_callbacks_t' is a structure that holds pointers to the application 00268 * provided methods which are needed to be called in response to certain 00269 * requests. The structure is default constructed to set all pointers to NULL. 00270 * So if the user does not provide the pointer, a response will not be posted. 00271 * However, the 'lorawan_events' callback is mandatory to be provided as it 00272 * contains essential events. 00273 * 00274 * Events that can be posted to user via 'lorawan_events' are: 00275 * 00276 * CONNECTED - When the connection is complete 00277 * DISCONNECTED - When the protocol is shut down in response to disconnect() 00278 * TX_DONE - When a packet is sent 00279 * TX_TIMEOUT, - When stack was unable to send packet in TX window 00280 * TX_ERROR, - A general TX error 00281 * TX_CRYPTO_ERROR, - If MIC fails, or any other crypto relted error 00282 * TX_SCHEDULING_ERROR, - When stack is unable to schedule packet 00283 * RX_DONE, - When there is something to receive 00284 * RX_TIMEOUT, - Not yet mapped 00285 * RX_ERROR - A general RX error 00286 * 00287 * Other responses to certain standard requests are an item for the future. 00288 * For example, a link check request could be sent whenever the device tries 00289 * to send a message and if the network server responds with a link check resposne, 00290 * the stack notifies the application be calling the appropriate method. For example, 00291 * 'link_check_resp' callback could be used to collect a response for a link check 00292 * request MAC command and the result is thus transported to the application 00293 * via callback function provided. 00294 * 00295 * As can be seen from declaration, mbed::Callback<void(uint8_t, uint8_t)> *link_check_resp) 00296 * carries two parameters. First one is Demodulation Margin and the second one 00297 * is number of gateways involved in the path to network server. 00298 * 00299 * An example of using this API with a latch onto 'lorawan_events' could be: 00300 * 00301 * LoRaWANInterface lorawan(radio); 00302 * lorawan_app_callbacks_t cbs; 00303 * static void my_event_handler(); 00304 * 00305 * int main() 00306 * { 00307 * lorawan.initialize(); 00308 * cbs.lorawan_events = mbed::callback(my_event_handler); 00309 * lorawan.add_app_callbacks(&cbs); 00310 * lorawan.connect(); 00311 * } 00312 * 00313 * static void my_event_handler(lora_events_t events) 00314 * { 00315 * switch(events) { 00316 * case CONNECTED: 00317 * //do something 00318 * break; 00319 * case DISCONNECTED: 00320 * //do something 00321 * break; 00322 * case TX_DONE: 00323 * //do something 00324 * break; 00325 * default: 00326 * break; 00327 * } 00328 * } 00329 * 00330 * @param callbacks A pointer to the structure containing application 00331 * callbacks. 00332 */ 00333 virtual lorawan_status_t add_app_callbacks(lorawan_app_callbacks_t *callbacks) = 0; 00334 }; 00335 00336 #endif /* LORAWAN_BASE_H_ */
Generated on Tue Jul 12 2022 13:24:48 by
1.7.2