Kenji Arai / mbed-os_TYBLE16

mbed-os5 only for TYBLE16

Dependents:   TYBLE16_simple_data_logger TYBLE16_MP3_Air

features/lorawan/LoRaWANStack.h@1:9db0e321a9f4, 2019-12-31 (annotated)

Committer:
kenjiArai
Date:
Tue Dec 31 06:02:27 2019 +0000
Revision:
1:9db0e321a9f4
Parent:
0:5b88d5760320 
updated based on mbed-os5.15.0

Who changed what in which revision?

UserRevisionLine numberNew contents of line
kenjiArai 0:5b88d5760320 1 /**
kenjiArai 0:5b88d5760320 2 * \file LoRaWANStack.h
kenjiArai 0:5b88d5760320 3 *
kenjiArai 0:5b88d5760320 4 * \brief LoRaWAN stack layer implementation
kenjiArai 0:5b88d5760320 5 *
kenjiArai 0:5b88d5760320 6 * \copyright Revised BSD License, see LICENSE.TXT file include in the project
kenjiArai 0:5b88d5760320 7 *
kenjiArai 0:5b88d5760320 8 * \code
kenjiArai 0:5b88d5760320 9 * ______ _
kenjiArai 0:5b88d5760320 10 * / _____) _ | |
kenjiArai 0:5b88d5760320 11 * ( (____ _____ ____ _| |_ _____ ____| |__
kenjiArai 0:5b88d5760320 12 * \____ \| ___ | (_ _) ___ |/ ___) _ \
kenjiArai 0:5b88d5760320 13 * _____) ) ____| | | || |_| ____( (___| | | |
kenjiArai 0:5b88d5760320 14 * (______/|_____)_|_|_| \__)_____)\____)_| |_|
kenjiArai 0:5b88d5760320 15 * (C)2013 Semtech
kenjiArai 0:5b88d5760320 16 *
kenjiArai 0:5b88d5760320 17 * ___ _____ _ ___ _ _____ ___ ___ ___ ___
kenjiArai 0:5b88d5760320 18 * / __|_ _/_\ / __| |/ / __/ _ \| _ \/ __| __|
kenjiArai 0:5b88d5760320 19 * \__ \ | |/ _ \ (__| ' <| _| (_) | / (__| _|
kenjiArai 0:5b88d5760320 20 * |___/ |_/_/ \_\___|_|\_\_| \___/|_|_\\___|___|
kenjiArai 0:5b88d5760320 21 * embedded.connectivity.solutions===============
kenjiArai 0:5b88d5760320 22 *
kenjiArai 0:5b88d5760320 23 * \endcode
kenjiArai 0:5b88d5760320 24 *
kenjiArai 0:5b88d5760320 25 * \author Miguel Luis ( Semtech )
kenjiArai 0:5b88d5760320 26 *
kenjiArai 0:5b88d5760320 27 * \author Gregory Cristian ( Semtech )
kenjiArai 0:5b88d5760320 28 *
kenjiArai 0:5b88d5760320 29 * \author Daniel Jaeckle ( STACKFORCE )
kenjiArai 0:5b88d5760320 30 *
kenjiArai 0:5b88d5760320 31 * \defgroup LoRaWAN stack layer that controls MAC layer underneath
kenjiArai 0:5b88d5760320 32 *
kenjiArai 0:5b88d5760320 33 * License: Revised BSD License, see LICENSE.TXT file include in the project
kenjiArai 0:5b88d5760320 34 *
kenjiArai 0:5b88d5760320 35 * Copyright (c) 2017, Arm Limited and affiliates.
kenjiArai 0:5b88d5760320 36 *
kenjiArai 0:5b88d5760320 37 * SPDX-License-Identifier: BSD-3-Clause
kenjiArai 0:5b88d5760320 38 */
kenjiArai 0:5b88d5760320 39
kenjiArai 0:5b88d5760320 40 #ifndef LORAWANSTACK_H_
kenjiArai 0:5b88d5760320 41 #define LORAWANSTACK_H_
kenjiArai 0:5b88d5760320 42
kenjiArai 0:5b88d5760320 43 #include <stdint.h>
kenjiArai 0:5b88d5760320 44 #include "events/EventQueue.h"
kenjiArai 0:5b88d5760320 45 #include "platform/mbed_atomic.h"
kenjiArai 0:5b88d5760320 46 #include "platform/Callback.h"
kenjiArai 0:5b88d5760320 47 #include "platform/NonCopyable.h"
kenjiArai 0:5b88d5760320 48 #include "platform/ScopedLock.h"
kenjiArai 0:5b88d5760320 49
kenjiArai 0:5b88d5760320 50 #include "lorastack/mac/LoRaMac.h"
kenjiArai 0:5b88d5760320 51 #include "system/LoRaWANTimer.h"
kenjiArai 0:5b88d5760320 52 #include "system/lorawan_data_structures.h"
kenjiArai 0:5b88d5760320 53 #include "LoRaRadio.h"
kenjiArai 0:5b88d5760320 54
kenjiArai 0:5b88d5760320 55 class LoRaPHY;
kenjiArai 0:5b88d5760320 56
kenjiArai 0:5b88d5760320 57 /** LoRaWANStack Class
kenjiArai 0:5b88d5760320 58 * A controller layer for LoRaWAN MAC and PHY
kenjiArai 0:5b88d5760320 59 */
kenjiArai 0:5b88d5760320 60 class LoRaWANStack: private mbed::NonCopyable<LoRaWANStack> {
kenjiArai 0:5b88d5760320 61
kenjiArai 0:5b88d5760320 62 public:
kenjiArai 0:5b88d5760320 63 LoRaWANStack();
kenjiArai 0:5b88d5760320 64
kenjiArai 0:5b88d5760320 65 /** Binds PHY layer and radio driver to stack.
kenjiArai 0:5b88d5760320 66 *
kenjiArai 0:5b88d5760320 67 * MAC layer is totally detached from the PHY layer so the stack layer
kenjiArai 0:5b88d5760320 68 * needs to play the role of an arbitrator.
kenjiArai 0:5b88d5760320 69 * This API sets the PHY layer object to stack and bind the radio driver
kenjiArai 0:5b88d5760320 70 * object from the application to the PHY layer.
kenjiArai 0:5b88d5760320 71 * Also initialises radio callback handles which the radio driver will
kenjiArai 0:5b88d5760320 72 * use in order to report events.
kenjiArai 0:5b88d5760320 73 *
kenjiArai 0:5b88d5760320 74 * @param radio LoRaRadio object, i.e., the radio driver
kenjiArai 0:5b88d5760320 75 * @param phy LoRaPHY object.
kenjiArai 0:5b88d5760320 76 *
kenjiArai 0:5b88d5760320 77 */
kenjiArai 0:5b88d5760320 78 void bind_phy_and_radio_driver(LoRaRadio &radio, LoRaPHY &phy);
kenjiArai 0:5b88d5760320 79
kenjiArai 0:5b88d5760320 80 /** End device initialization.
kenjiArai 0:5b88d5760320 81 * @param queue A pointer to an EventQueue passed from the application.
kenjiArai 0:5b88d5760320 82 * @return LORAWAN_STATUS_OK on success, a negative error code on failure.
kenjiArai 0:5b88d5760320 83 */
kenjiArai 0:5b88d5760320 84 lorawan_status_t initialize_mac_layer(events::EventQueue *queue);
kenjiArai 0:5b88d5760320 85
kenjiArai 0:5b88d5760320 86 /** Sets all callbacks for the application.
kenjiArai 0:5b88d5760320 87 *
kenjiArai 0:5b88d5760320 88 * @param callbacks A pointer to the structure carrying callbacks.
kenjiArai 0:5b88d5760320 89 * @return LORAWAN_STATUS_OK on success, a negative error code on failure.
kenjiArai 0:5b88d5760320 90 */
kenjiArai 0:5b88d5760320 91 lorawan_status_t set_lora_callbacks(const lorawan_app_callbacks_t *callbacks);
kenjiArai 0:5b88d5760320 92
kenjiArai 0:5b88d5760320 93 /** Connect OTAA or ABP using Mbed-OS config system
kenjiArai 0:5b88d5760320 94 *
kenjiArai 0:5b88d5760320 95 * @return For ABP: If everything goes well, LORAWAN_STATUS_OK is returned for first call followed by
kenjiArai 0:5b88d5760320 96 * a 'CONNECTED' event. Otherwise a negative error code is returned.
kenjiArai 0:5b88d5760320 97 * Any subsequent call will return LORAWAN_STATUS_ALREADY_CONNECTED and no event follows.
kenjiArai 0:5b88d5760320 98 *
kenjiArai 0:5b88d5760320 99 * For OTAA: When a JoinRequest is sent, LORAWAN_STATUS_CONNECT_IN_PROGRESS is returned for the first call.
kenjiArai 0:5b88d5760320 100 * Any subsequent call will return either LORAWAN_STATUS_BUSY (if the previous request for connection
kenjiArai 0:5b88d5760320 101 * is still underway) or LORAWAN_STATUS_ALREADY_CONNECTED (if a network was already joined successfully).
kenjiArai 0:5b88d5760320 102 * A 'CONNECTED' event is sent to the application when the JoinAccept is received.
kenjiArai 0:5b88d5760320 103 */
kenjiArai 0:5b88d5760320 104 lorawan_status_t connect();
kenjiArai 0:5b88d5760320 105
kenjiArai 0:5b88d5760320 106 /** Connect OTAA or ABP with parameters
kenjiArai 0:5b88d5760320 107 *
kenjiArai 0:5b88d5760320 108 * @param connect Options for an end device connection to the gateway.
kenjiArai 0:5b88d5760320 109 *
kenjiArai 0:5b88d5760320 110 * @return For ABP: If everything goes well, LORAWAN_STATUS_OK is returned for first call followed by
kenjiArai 0:5b88d5760320 111 * a 'CONNECTED' event. Otherwise a negative error code is returned.
kenjiArai 0:5b88d5760320 112 * Any subsequent call will return LORAWAN_STATUS_ALREADY_CONNECTED and no event follows.
kenjiArai 0:5b88d5760320 113 *
kenjiArai 0:5b88d5760320 114 * For OTAA: When a JoinRequest is sent, LORAWAN_STATUS_CONNECT_IN_PROGRESS is returned for the first call.
kenjiArai 0:5b88d5760320 115 * Any subsequent call will return either LORAWAN_STATUS_BUSY (if the previous request for connection
kenjiArai 0:5b88d5760320 116 * is still underway) or LORAWAN_STATUS_ALREADY_CONNECTED (if a network was already joined successfully).
kenjiArai 0:5b88d5760320 117 * A 'CONNECTED' event is sent to the application when the JoinAccept is received.
kenjiArai 0:5b88d5760320 118 */
kenjiArai 0:5b88d5760320 119 lorawan_status_t connect(const lorawan_connect_t &connect);
kenjiArai 0:5b88d5760320 120
kenjiArai 0:5b88d5760320 121 /** Adds channels to use.
kenjiArai 0:5b88d5760320 122 *
kenjiArai 0:5b88d5760320 123 * You can provide a list of channels with appropriate parameters filled
kenjiArai 0:5b88d5760320 124 * in. However, this list is not absolute. In some regions, a CF
kenjiArai 0:5b88d5760320 125 * list gets implemented by default, which means that the network can overwrite your channel
kenjiArai 0:5b88d5760320 126 * frequency settings right after receiving a Join Accept. You may try
kenjiArai 0:5b88d5760320 127 * to set up any channel or channels after that and if the channel requested
kenjiArai 0:5b88d5760320 128 * is already active, the request is silently ignored. A negative error
kenjiArai 0:5b88d5760320 129 * code is returned if there is any problem with parameters.
kenjiArai 0:5b88d5760320 130 *
kenjiArai 0:5b88d5760320 131 * You need to ensure that the base station nearby supports the channel or channels being added.
kenjiArai 0:5b88d5760320 132 *
kenjiArai 0:5b88d5760320 133 * If your list includes a default channel (a channel where Join Requests
kenjiArai 0:5b88d5760320 134 * are received) you cannot fully configure the channel parameters.
kenjiArai 0:5b88d5760320 135 * Either leave the channel settings to default or check your
kenjiArai 0:5b88d5760320 136 * corresponding PHY layer implementation. For example, LoRaPHYE868.
kenjiArai 0:5b88d5760320 137 *
kenjiArai 0:5b88d5760320 138 * @param channel_plan A list of channels or a single channel.
kenjiArai 0:5b88d5760320 139 *
kenjiArai 0:5b88d5760320 140 * @return LORAWAN_STATUS_OK on success, a negative error
kenjiArai 0:5b88d5760320 141 * code on failure.
kenjiArai 0:5b88d5760320 142 */
kenjiArai 0:5b88d5760320 143 lorawan_status_t add_channels(const lorawan_channelplan_t &channel_plan);
kenjiArai 0:5b88d5760320 144
kenjiArai 0:5b88d5760320 145 /** Removes a channel from the list.
kenjiArai 0:5b88d5760320 146 *
kenjiArai 0:5b88d5760320 147 * @param channel_id Index of the channel being removed
kenjiArai 0:5b88d5760320 148 *
kenjiArai 0:5b88d5760320 149 * @return LORAWAN_STATUS_OK on success, a negative error
kenjiArai 0:5b88d5760320 150 * code on failure.
kenjiArai 0:5b88d5760320 151 */
kenjiArai 0:5b88d5760320 152 lorawan_status_t remove_a_channel(uint8_t channel_id);
kenjiArai 0:5b88d5760320 153
kenjiArai 0:5b88d5760320 154 /** Removes a previously set channel plan.
kenjiArai 0:5b88d5760320 155 *
kenjiArai 0:5b88d5760320 156 * @return LORAWAN_STATUS_OK on success, a negative error
kenjiArai 0:5b88d5760320 157 * code on failure.
kenjiArai 0:5b88d5760320 158 */
kenjiArai 0:5b88d5760320 159 lorawan_status_t drop_channel_list();
kenjiArai 0:5b88d5760320 160
kenjiArai 0:5b88d5760320 161 /** Gets a list of currently enabled channels .
kenjiArai 0:5b88d5760320 162 *
kenjiArai 0:5b88d5760320 163 * @param channel_plan The channel plan structure to store final result.
kenjiArai 0:5b88d5760320 164 *
kenjiArai 0:5b88d5760320 165 * @return LORAWAN_STATUS_OK on success, a negative error
kenjiArai 0:5b88d5760320 166 * code on failure.
kenjiArai 0:5b88d5760320 167 */
kenjiArai 0:5b88d5760320 168 lorawan_status_t get_enabled_channels(lorawan_channelplan_t &channel_plan);
kenjiArai 0:5b88d5760320 169
kenjiArai 0:5b88d5760320 170 /** Sets up a retry counter for confirmed messages.
kenjiArai 0:5b88d5760320 171 *
kenjiArai 0:5b88d5760320 172 * Valid only for confirmed messages. This API sets the number of times the
kenjiArai 0:5b88d5760320 173 * stack will retry a CONFIRMED message before giving up and reporting an
kenjiArai 0:5b88d5760320 174 * error.
kenjiArai 0:5b88d5760320 175 *
kenjiArai 0:5b88d5760320 176 * @param count The number of retries for confirmed messages.
kenjiArai 0:5b88d5760320 177 *
kenjiArai 0:5b88d5760320 178 * @return LORAWAN_STATUS_OK or a negative error code.
kenjiArai 0:5b88d5760320 179 */
kenjiArai 0:5b88d5760320 180 lorawan_status_t set_confirmed_msg_retry(uint8_t count);
kenjiArai 0:5b88d5760320 181
kenjiArai 0:5b88d5760320 182 /** Sets up the data rate.
kenjiArai 0:5b88d5760320 183 *
kenjiArai 0:5b88d5760320 184 * `set_datarate()` first verifies whether the data rate given is valid or not.
kenjiArai 0:5b88d5760320 185 * If it is valid, the system sets the given data rate to the channel.
kenjiArai 0:5b88d5760320 186 *
kenjiArai 0:5b88d5760320 187 * @param data_rate The intended data rate, for example DR_0 or DR_1.
kenjiArai 0:5b88d5760320 188 * Note that the macro DR_* can mean different
kenjiArai 0:5b88d5760320 189 * things in different regions.
kenjiArai 0:5b88d5760320 190 *
kenjiArai 0:5b88d5760320 191 * @return LORAWAN_STATUS_OK if everything goes well, otherwise
kenjiArai 0:5b88d5760320 192 * a negative error code.
kenjiArai 0:5b88d5760320 193 */
kenjiArai 0:5b88d5760320 194 lorawan_status_t set_channel_data_rate(uint8_t data_rate);
kenjiArai 0:5b88d5760320 195
kenjiArai 0:5b88d5760320 196 /** Enables ADR.
kenjiArai 0:5b88d5760320 197 *
kenjiArai 0:5b88d5760320 198 * @param adr_enabled 0 ADR disabled, 1 ADR enabled.
kenjiArai 0:5b88d5760320 199 *
kenjiArai 0:5b88d5760320 200 * @return LORAWAN_STATUS_OK on success, a negative error
kenjiArai 0:5b88d5760320 201 * code on failure.
kenjiArai 0:5b88d5760320 202 */
kenjiArai 0:5b88d5760320 203 lorawan_status_t enable_adaptive_datarate(bool adr_enabled);
kenjiArai 0:5b88d5760320 204
kenjiArai 0:5b88d5760320 205 /** Send message to gateway
kenjiArai 0:5b88d5760320 206 *
kenjiArai 0:5b88d5760320 207 * @param port The application port number. Port numbers 0 and 224
kenjiArai 0:5b88d5760320 208 * are reserved, whereas port numbers from 1 to 223
kenjiArai 0:5b88d5760320 209 * (0x01 to 0xDF) are valid port numbers.
kenjiArai 0:5b88d5760320 210 * Anything out of this range is illegal.
kenjiArai 0:5b88d5760320 211 *
kenjiArai 0:5b88d5760320 212 * @param data A pointer to the data being sent. The ownership of the
kenjiArai 0:5b88d5760320 213 * buffer is not transferred. The data is copied to the
kenjiArai 0:5b88d5760320 214 * internal buffers.
kenjiArai 0:5b88d5760320 215 *
kenjiArai 0:5b88d5760320 216 * @param length The size of data in bytes.
kenjiArai 0:5b88d5760320 217 *
kenjiArai 0:5b88d5760320 218 * @param flags A flag used to determine what type of
kenjiArai 0:5b88d5760320 219 * message is being sent, for example:
kenjiArai 0:5b88d5760320 220 *
kenjiArai 0:5b88d5760320 221 * MSG_UNCONFIRMED_FLAG = 0x01
kenjiArai 0:5b88d5760320 222 * MSG_CONFIRMED_FLAG = 0x02
kenjiArai 0:5b88d5760320 223 * MSG_MULTICAST_FLAG = 0x04
kenjiArai 0:5b88d5760320 224 * MSG_PROPRIETARY_FLAG = 0x08
kenjiArai 0:5b88d5760320 225 * MSG_MULTICAST_FLAG and MSG_PROPRIETARY_FLAG can be
kenjiArai 0:5b88d5760320 226 * used in conjunction with MSG_UNCONFIRMED_FLAG and
kenjiArai 0:5b88d5760320 227 * MSG_CONFIRMED_FLAG depending on the intended use.
kenjiArai 0:5b88d5760320 228 *
kenjiArai 0:5b88d5760320 229 * MSG_PROPRIETARY_FLAG|MSG_CONFIRMED_FLAG mask will set
kenjiArai 0:5b88d5760320 230 * a confirmed message flag for a proprietary message.
kenjiArai 0:5b88d5760320 231 * MSG_CONFIRMED_FLAG and MSG_UNCONFIRMED_FLAG are
kenjiArai 0:5b88d5760320 232 * mutually exclusive.
kenjiArai 0:5b88d5760320 233 *
kenjiArai 0:5b88d5760320 234 * @param null_allowed Internal use only. Needed for sending empty packet
kenjiArai 0:5b88d5760320 235 * having CONFIRMED bit on.
kenjiArai 0:5b88d5760320 236 *
kenjiArai 0:5b88d5760320 237 * @param allow_port_0 Internal use only. Needed for flushing MAC commands.
kenjiArai 0:5b88d5760320 238 *
kenjiArai 0:5b88d5760320 239 * @return The number of bytes sent, or
kenjiArai 0:5b88d5760320 240 * LORAWAN_STATUS_WOULD_BLOCK if another TX is
kenjiArai 0:5b88d5760320 241 * ongoing, or a negative error code on failure.
kenjiArai 0:5b88d5760320 242 */
kenjiArai 0:5b88d5760320 243 int16_t handle_tx(uint8_t port, const uint8_t *data,
kenjiArai 0:5b88d5760320 244 uint16_t length, uint8_t flags,
kenjiArai 0:5b88d5760320 245 bool null_allowed = false, bool allow_port_0 = false);
kenjiArai 0:5b88d5760320 246
kenjiArai 0:5b88d5760320 247 /** Receives a message from the Network Server.
kenjiArai 0:5b88d5760320 248 *
kenjiArai 0:5b88d5760320 249 * @param data A pointer to buffer where the received data will be
kenjiArai 0:5b88d5760320 250 * stored.
kenjiArai 0:5b88d5760320 251 *
kenjiArai 0:5b88d5760320 252 * @param length The size of data in bytes
kenjiArai 0:5b88d5760320 253 *
kenjiArai 0:5b88d5760320 254 * @param port The application port number. Port numbers 0 and 224
kenjiArai 0:5b88d5760320 255 * are reserved, whereas port numbers from 1 to 223
kenjiArai 0:5b88d5760320 256 * (0x01 to 0xDF) are valid port numbers.
kenjiArai 0:5b88d5760320 257 * Anything out of this range is illegal.
kenjiArai 0:5b88d5760320 258 *
kenjiArai 0:5b88d5760320 259 * In return will contain the number of port to which
kenjiArai 0:5b88d5760320 260 * message was received.
kenjiArai 0:5b88d5760320 261 *
kenjiArai 0:5b88d5760320 262 * @param flags A flag is used to determine what type of
kenjiArai 0:5b88d5760320 263 * message is being received, for example:
kenjiArai 0:5b88d5760320 264 *
kenjiArai 0:5b88d5760320 265 * MSG_UNCONFIRMED_FLAG = 0x01,
kenjiArai 0:5b88d5760320 266 * MSG_CONFIRMED_FLAG = 0x02
kenjiArai 0:5b88d5760320 267 * MSG_MULTICAST_FLAG = 0x04,
kenjiArai 0:5b88d5760320 268 * MSG_PROPRIETARY_FLAG = 0x08
kenjiArai 0:5b88d5760320 269 *
kenjiArai 0:5b88d5760320 270 * MSG_MULTICAST_FLAG and MSG_PROPRIETARY_FLAG can be
kenjiArai 0:5b88d5760320 271 * used in conjunction with MSG_UNCONFIRMED_FLAG and
kenjiArai 0:5b88d5760320 272 * MSG_CONFIRMED_FLAG depending on the intended use.
kenjiArai 0:5b88d5760320 273 *
kenjiArai 0:5b88d5760320 274 * MSG_PROPRIETARY_FLAG|MSG_CONFIRMED_FLAG mask will set
kenjiArai 0:5b88d5760320 275 * a confirmed message flag for a proprietary message.
kenjiArai 0:5b88d5760320 276 *
kenjiArai 0:5b88d5760320 277 * MSG_CONFIRMED_FLAG and MSG_UNCONFIRMED_FLAG are
kenjiArai 0:5b88d5760320 278 * not mutually exclusive, i.e., the user can subscribe to
kenjiArai 0:5b88d5760320 279 * receive both CONFIRMED AND UNCONFIRMED messages at
kenjiArai 0:5b88d5760320 280 * the same time.
kenjiArai 0:5b88d5760320 281 *
kenjiArai 0:5b88d5760320 282 * In return will contain the flags to determine what kind
kenjiArai 0:5b88d5760320 283 * of message was received.
kenjiArai 0:5b88d5760320 284 *
kenjiArai 0:5b88d5760320 285 * @param validate_params If set to true, the given port and flags values will be checked
kenjiArai 0:5b88d5760320 286 * against the values received with the message. If values do not
kenjiArai 0:5b88d5760320 287 * match, LORAWAN_STATUS_WOULD_BLOCK will be returned.
kenjiArai 0:5b88d5760320 288 *
kenjiArai 0:5b88d5760320 289 * @return It could be one of these:
kenjiArai 0:5b88d5760320 290 * i) 0 if there is nothing else to read.
kenjiArai 0:5b88d5760320 291 * ii) Number of bytes written to user buffer.
kenjiArai 0:5b88d5760320 292 * iii) LORAWAN_STATUS_WOULD_BLOCK if there is
kenjiArai 0:5b88d5760320 293 * nothing available to read at the moment.
kenjiArai 0:5b88d5760320 294 * iv) A negative error code on failure.
kenjiArai 0:5b88d5760320 295 */
kenjiArai 0:5b88d5760320 296 int16_t handle_rx(uint8_t *data, uint16_t length, uint8_t &port, int &flags, bool validate_params);
kenjiArai 0:5b88d5760320 297
kenjiArai 0:5b88d5760320 298 /** Send Link Check Request MAC command.
kenjiArai 0:5b88d5760320 299 *
kenjiArai 0:5b88d5760320 300 *
kenjiArai 0:5b88d5760320 301 * This API schedules a Link Check Request command (LinkCheckReq) for the network
kenjiArai 0:5b88d5760320 302 * server and once the response, i.e., LinkCheckAns MAC command is received
kenjiArai 0:5b88d5760320 303 * from the Network Server, an event is generated.
kenjiArai 0:5b88d5760320 304 *
kenjiArai 0:5b88d5760320 305 * A callback function for the link check response must be set prior to using
kenjiArai 0:5b88d5760320 306 * this API, otherwise a LORAWAN_STATUS_PARAMETER_INVALID error is thrown.
kenjiArai 0:5b88d5760320 307 *
kenjiArai 0:5b88d5760320 308 * @return LORAWAN_STATUS_OK on successfully queuing a request, or
kenjiArai 0:5b88d5760320 309 * a negative error code on failure.
kenjiArai 0:5b88d5760320 310 *
kenjiArai 0:5b88d5760320 311 */
kenjiArai 0:5b88d5760320 312 lorawan_status_t set_link_check_request();
kenjiArai 0:5b88d5760320 313
kenjiArai 0:5b88d5760320 314 /** Removes link check request sticky MAC command.
kenjiArai 0:5b88d5760320 315 *
kenjiArai 0:5b88d5760320 316 * Any already queued request may still get entertained. However, no new
kenjiArai 0:5b88d5760320 317 * requests will be made.
kenjiArai 0:5b88d5760320 318 */
kenjiArai 0:5b88d5760320 319 void remove_link_check_request();
kenjiArai 0:5b88d5760320 320
kenjiArai 0:5b88d5760320 321 /** Shuts down the LoRaWAN protocol.
kenjiArai 0:5b88d5760320 322 *
kenjiArai 0:5b88d5760320 323 * In response to the user call for disconnection, the stack shuts down itself.
kenjiArai 0:5b88d5760320 324 *
kenjiArai 0:5b88d5760320 325 * @return LORAWAN_STATUS_DEVICE_OFF on successfully shutdown.
kenjiArai 0:5b88d5760320 326 */
kenjiArai 0:5b88d5760320 327 lorawan_status_t shutdown();
kenjiArai 0:5b88d5760320 328
kenjiArai 0:5b88d5760320 329 /** Change device class
kenjiArai 0:5b88d5760320 330 *
kenjiArai 0:5b88d5760320 331 * Change current device class.
kenjiArai 0:5b88d5760320 332 *
kenjiArai 0:5b88d5760320 333 * @param device_class The device class
kenjiArai 0:5b88d5760320 334 *
kenjiArai 0:5b88d5760320 335 * @return LORAWAN_STATUS_OK on success,
kenjiArai 0:5b88d5760320 336 * LORAWAN_STATUS_UNSUPPORTED is requested class is not supported,
kenjiArai 0:5b88d5760320 337 * or other negative error code if request failed.
kenjiArai 0:5b88d5760320 338 */
kenjiArai 0:5b88d5760320 339 lorawan_status_t set_device_class(const device_class_t &device_class);
kenjiArai 0:5b88d5760320 340
kenjiArai 0:5b88d5760320 341 /** Acquire TX meta-data
kenjiArai 0:5b88d5760320 342 *
kenjiArai 0:5b88d5760320 343 * Upon successful transmission, TX meta-data will be made available
kenjiArai 0:5b88d5760320 344 *
kenjiArai 0:5b88d5760320 345 * @param metadata A reference to the inbound structure which will be
kenjiArai 0:5b88d5760320 346 * filled with any TX meta-data if available.
kenjiArai 0:5b88d5760320 347 *
kenjiArai 0:5b88d5760320 348 * @return LORAWAN_STATUS_OK if successful,
kenjiArai 0:5b88d5760320 349 * LORAWAN_STATUS_METADATA_NOT_AVAILABLE otherwise
kenjiArai 0:5b88d5760320 350 */
kenjiArai 0:5b88d5760320 351 lorawan_status_t acquire_tx_metadata(lorawan_tx_metadata &metadata);
kenjiArai 0:5b88d5760320 352
kenjiArai 0:5b88d5760320 353 /** Acquire RX meta-data
kenjiArai 0:5b88d5760320 354 *
kenjiArai 0:5b88d5760320 355 * Upon successful reception, RX meta-data will be made available
kenjiArai 0:5b88d5760320 356 *
kenjiArai 0:5b88d5760320 357 * @param metadata A reference to the inbound structure which will be
kenjiArai 0:5b88d5760320 358 * filled with any RX meta-data if available.
kenjiArai 0:5b88d5760320 359 *
kenjiArai 0:5b88d5760320 360 * @return LORAWAN_STATUS_OK if successful,
kenjiArai 0:5b88d5760320 361 * LORAWAN_STATUS_METADATA_NOT_AVAILABLE otherwise
kenjiArai 0:5b88d5760320 362 */
kenjiArai 0:5b88d5760320 363 lorawan_status_t acquire_rx_metadata(lorawan_rx_metadata &metadata);
kenjiArai 0:5b88d5760320 364
kenjiArai 0:5b88d5760320 365 /** Acquire backoff meta-data
kenjiArai 0:5b88d5760320 366 *
kenjiArai 0:5b88d5760320 367 * Get hold of backoff time after which the transmission will take place.
kenjiArai 0:5b88d5760320 368 *
kenjiArai 0:5b88d5760320 369 * @param backoff A reference to the inbound integer which will be
kenjiArai 0:5b88d5760320 370 * filled with any backoff meta-data if available.
kenjiArai 0:5b88d5760320 371 *
kenjiArai 0:5b88d5760320 372 * @return LORAWAN_STATUS_OK if successful,
kenjiArai 0:5b88d5760320 373 * LORAWAN_STATUS_METADATA_NOT_AVAILABLE otherwise
kenjiArai 0:5b88d5760320 374 */
kenjiArai 0:5b88d5760320 375 lorawan_status_t acquire_backoff_metadata(int &backoff);
kenjiArai 0:5b88d5760320 376
kenjiArai 0:5b88d5760320 377 /** Stops sending
kenjiArai 0:5b88d5760320 378 *
kenjiArai 0:5b88d5760320 379 * Stop sending any outstanding messages if they are not yet queued for
kenjiArai 0:5b88d5760320 380 * transmission, i.e., if the backoff timer is nhot elapsed yet.
kenjiArai 0:5b88d5760320 381 *
kenjiArai 0:5b88d5760320 382 * @return LORAWAN_STATUS_OK if the transmission is cancelled.
kenjiArai 0:5b88d5760320 383 * LORAWAN_STATUS_BUSY otherwise.
kenjiArai 0:5b88d5760320 384 */
kenjiArai 0:5b88d5760320 385 lorawan_status_t stop_sending(void);
kenjiArai 0:5b88d5760320 386
kenjiArai 0:5b88d5760320 387 void lock(void)
kenjiArai 0:5b88d5760320 388 {
kenjiArai 0:5b88d5760320 389 _loramac.lock();
kenjiArai 0:5b88d5760320 390 }
kenjiArai 0:5b88d5760320 391 void unlock(void)
kenjiArai 0:5b88d5760320 392 {
kenjiArai 0:5b88d5760320 393 _loramac.unlock();
kenjiArai 0:5b88d5760320 394 }
kenjiArai 0:5b88d5760320 395
kenjiArai 0:5b88d5760320 396 private:
kenjiArai 0:5b88d5760320 397 typedef mbed::ScopedLock<LoRaWANStack> Lock;
kenjiArai 0:5b88d5760320 398 /**
kenjiArai 0:5b88d5760320 399 * Checks if the user provided port is valid or not
kenjiArai 0:5b88d5760320 400 */
kenjiArai 0:5b88d5760320 401 bool is_port_valid(uint8_t port, bool allow_port_0 = false);
kenjiArai 0:5b88d5760320 402
kenjiArai 0:5b88d5760320 403 /**
kenjiArai 0:5b88d5760320 404 * State machine for stack controller layer.
kenjiArai 0:5b88d5760320 405 */
kenjiArai 0:5b88d5760320 406 lorawan_status_t state_controller(device_states_t new_state);
kenjiArai 0:5b88d5760320 407
kenjiArai 0:5b88d5760320 408 /**
kenjiArai 0:5b88d5760320 409 * Helpers for state controller
kenjiArai 0:5b88d5760320 410 */
kenjiArai 0:5b88d5760320 411 void process_uninitialized_state(lorawan_status_t &op_status);
kenjiArai 0:5b88d5760320 412 void process_idle_state(lorawan_status_t &op_status);
kenjiArai 0:5b88d5760320 413 void process_connected_state();
kenjiArai 0:5b88d5760320 414 void process_connecting_state(lorawan_status_t &op_status);
kenjiArai 0:5b88d5760320 415 void process_joining_state(lorawan_status_t &op_status);
kenjiArai 0:5b88d5760320 416 void process_scheduling_state(lorawan_status_t &op_status);
kenjiArai 0:5b88d5760320 417 void process_status_check_state();
kenjiArai 0:5b88d5760320 418 void process_shutdown_state(lorawan_status_t &op_status);
kenjiArai 0:5b88d5760320 419 void state_machine_run_to_completion(void);
kenjiArai 0:5b88d5760320 420
kenjiArai 0:5b88d5760320 421 /**
kenjiArai 0:5b88d5760320 422 * Handles MLME indications
kenjiArai 0:5b88d5760320 423 */
kenjiArai 0:5b88d5760320 424 void mlme_indication_handler(void);
kenjiArai 0:5b88d5760320 425
kenjiArai 0:5b88d5760320 426 /**
kenjiArai 0:5b88d5760320 427 * Handles an MLME confirmation
kenjiArai 0:5b88d5760320 428 */
kenjiArai 0:5b88d5760320 429 void mlme_confirm_handler(void);
kenjiArai 0:5b88d5760320 430
kenjiArai 0:5b88d5760320 431 /**
kenjiArai 0:5b88d5760320 432 * Handles an MCPS confirmation
kenjiArai 0:5b88d5760320 433 */
kenjiArai 0:5b88d5760320 434 void mcps_confirm_handler(void);
kenjiArai 0:5b88d5760320 435
kenjiArai 0:5b88d5760320 436 /**
kenjiArai 0:5b88d5760320 437 * Handles an MCPS indication
kenjiArai 0:5b88d5760320 438 */
kenjiArai 0:5b88d5760320 439 void mcps_indication_handler(void);
kenjiArai 0:5b88d5760320 440
kenjiArai 0:5b88d5760320 441 /**
kenjiArai 0:5b88d5760320 442 * Sets up user application port
kenjiArai 0:5b88d5760320 443 */
kenjiArai 0:5b88d5760320 444 lorawan_status_t set_application_port(uint8_t port, bool allow_port_0 = false);
kenjiArai 0:5b88d5760320 445
kenjiArai 0:5b88d5760320 446 /**
kenjiArai 0:5b88d5760320 447 * Handles connection internally
kenjiArai 0:5b88d5760320 448 */
kenjiArai 0:5b88d5760320 449 lorawan_status_t handle_connect(bool is_otaa);
kenjiArai 0:5b88d5760320 450
kenjiArai 0:5b88d5760320 451
kenjiArai 0:5b88d5760320 452 /** Send event to application.
kenjiArai 0:5b88d5760320 453 *
kenjiArai 0:5b88d5760320 454 * @param event The event to be sent.
kenjiArai 0:5b88d5760320 455 */
kenjiArai 0:5b88d5760320 456 void send_event_to_application(const lorawan_event_t event) const;
kenjiArai 0:5b88d5760320 457
kenjiArai 0:5b88d5760320 458 /** Send empty uplink message to network.
kenjiArai 0:5b88d5760320 459 *
kenjiArai 0:5b88d5760320 460 * Sends an empty confirmed message to gateway.
kenjiArai 0:5b88d5760320 461 *
kenjiArai 0:5b88d5760320 462 * @param port The event to be sent.
kenjiArai 0:5b88d5760320 463 */
kenjiArai 0:5b88d5760320 464 void send_automatic_uplink_message(uint8_t port);
kenjiArai 0:5b88d5760320 465
kenjiArai 0:5b88d5760320 466 /**
kenjiArai 0:5b88d5760320 467 * TX interrupt handlers and corresponding processors
kenjiArai 0:5b88d5760320 468 */
kenjiArai 0:5b88d5760320 469 void tx_interrupt_handler(void);
kenjiArai 0:5b88d5760320 470 void tx_timeout_interrupt_handler(void);
kenjiArai 0:5b88d5760320 471 void process_transmission(void);
kenjiArai 0:5b88d5760320 472 void process_transmission_timeout(void);
kenjiArai 0:5b88d5760320 473
kenjiArai 0:5b88d5760320 474 /**
kenjiArai 0:5b88d5760320 475 * RX interrupt handlers and corresponding processors
kenjiArai 0:5b88d5760320 476 */
kenjiArai 0:5b88d5760320 477 void rx_interrupt_handler(const uint8_t *payload, uint16_t size, int16_t rssi,
kenjiArai 0:5b88d5760320 478 int8_t snr);
kenjiArai 0:5b88d5760320 479 void rx_timeout_interrupt_handler(void);
kenjiArai 0:5b88d5760320 480 void rx_error_interrupt_handler(void);
kenjiArai 0:5b88d5760320 481 void process_reception(const uint8_t *payload, uint16_t size, int16_t rssi,
kenjiArai 0:5b88d5760320 482 int8_t snr);
kenjiArai 0:5b88d5760320 483 void process_reception_timeout(bool is_timeout);
kenjiArai 0:5b88d5760320 484
kenjiArai 0:5b88d5760320 485 int convert_to_msg_flag(const mcps_type_t type);
kenjiArai 0:5b88d5760320 486
kenjiArai 0:5b88d5760320 487 void make_tx_metadata_available(void);
kenjiArai 0:5b88d5760320 488 void make_rx_metadata_available(void);
kenjiArai 0:5b88d5760320 489
kenjiArai 0:5b88d5760320 490 void handle_scheduling_failure(void);
kenjiArai 0:5b88d5760320 491
kenjiArai 0:5b88d5760320 492 void post_process_tx_with_reception(void);
kenjiArai 0:5b88d5760320 493 void post_process_tx_no_reception(void);
kenjiArai 0:5b88d5760320 494
kenjiArai 0:5b88d5760320 495 private:
kenjiArai 0:5b88d5760320 496 LoRaMac _loramac;
kenjiArai 0:5b88d5760320 497 radio_events_t radio_events;
kenjiArai 0:5b88d5760320 498 device_states_t _device_current_state;
kenjiArai 0:5b88d5760320 499 lorawan_app_callbacks_t _callbacks;
kenjiArai 0:5b88d5760320 500 lorawan_session_t _lw_session;
kenjiArai 0:5b88d5760320 501 loramac_tx_message_t _tx_msg;
kenjiArai 0:5b88d5760320 502 loramac_rx_message_t _rx_msg;
kenjiArai 0:5b88d5760320 503 lorawan_tx_metadata _tx_metadata;
kenjiArai 0:5b88d5760320 504 lorawan_rx_metadata _rx_metadata;
kenjiArai 0:5b88d5760320 505 uint8_t _num_retry;
kenjiArai 0:5b88d5760320 506 uint8_t _qos_cnt;
kenjiArai 0:5b88d5760320 507 uint32_t _ctrl_flags;
kenjiArai 0:5b88d5760320 508 uint8_t _app_port;
kenjiArai 0:5b88d5760320 509 bool _link_check_requested;
kenjiArai 0:5b88d5760320 510 bool _automatic_uplink_ongoing;
kenjiArai 0:5b88d5760320 511 core_util_atomic_flag _rx_payload_in_use;
kenjiArai 0:5b88d5760320 512 uint8_t _rx_payload[LORAMAC_PHY_MAXPAYLOAD];
kenjiArai 0:5b88d5760320 513 events::EventQueue *_queue;
kenjiArai 0:5b88d5760320 514 lorawan_time_t _tx_timestamp;
kenjiArai 0:5b88d5760320 515 };
kenjiArai 0:5b88d5760320 516
kenjiArai 0:5b88d5760320 517 #endif /* LORAWANSTACK_H_ */