Nicolas Borla
/
BBR_1Ebene
BBR 1 Ebene
Diff: mbed-os/features/lorawan/LoRaWANStack.h
- Revision:
- 0:fbdae7e6d805
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mbed-os/features/lorawan/LoRaWANStack.h Mon May 14 11:29:06 2018 +0000 @@ -0,0 +1,509 @@ +/** + * \file LoRaWANStack.h + * + * \brief LoRaWAN stack layer implementation + * + * \copyright Revised BSD License, see LICENSE.TXT file include in the project + * + * \code + * ______ _ + * / _____) _ | | + * ( (____ _____ ____ _| |_ _____ ____| |__ + * \____ \| ___ | (_ _) ___ |/ ___) _ \ + * _____) ) ____| | | || |_| ____( (___| | | | + * (______/|_____)_|_|_| \__)_____)\____)_| |_| + * (C)2013 Semtech + * + * ___ _____ _ ___ _ _____ ___ ___ ___ ___ + * / __|_ _/_\ / __| |/ / __/ _ \| _ \/ __| __| + * \__ \ | |/ _ \ (__| ' <| _| (_) | / (__| _| + * |___/ |_/_/ \_\___|_|\_\_| \___/|_|_\\___|___| + * embedded.connectivity.solutions=============== + * + * \endcode + * + * \author Miguel Luis ( Semtech ) + * + * \author Gregory Cristian ( Semtech ) + * + * \author Daniel Jaeckle ( STACKFORCE ) + * + * \defgroup LoRaWAN stack layer that controls MAC layer underneath + * + * License: Revised BSD License, see LICENSE.TXT file include in the project + * + * Copyright (c) 2017, Arm Limited and affiliates. + * + * SPDX-License-Identifier: BSD-3-Clause + */ + +#ifndef LORAWANSTACK_H_ +#define LORAWANSTACK_H_ + +#include <stdint.h> +#include "events/EventQueue.h" +#include "platform/Callback.h" +#include "platform/NonCopyable.h" +#include "platform/ScopedLock.h" + +#include "lorastack/mac/LoRaMac.h" +#include "system/LoRaWANTimer.h" +#include "system/lorawan_data_structures.h" +#include "LoRaRadio.h" + +class LoRaWANStack: private mbed::NonCopyable<LoRaWANStack> { + +public: + LoRaWANStack(); + + /** Binds radio driver to PHY layer. + * + * MAC layer is totally detached from the PHY layer so the stack layer + * needs to play the role of an arbitrator. This API gets a radio driver + * object from the application (via LoRaWANInterface), binds it to the PHY + * layer and initialises radio callback handles which the radio driver will + * use in order to report events. + * + * @param radio LoRaRadio object, i.e., the radio driver + * + */ + void bind_radio_driver(LoRaRadio& radio); + + /** End device initialization. + * @param queue A pointer to an EventQueue passed from the application. + * @return LORAWAN_STATUS_OK on success, a negative error code on failure. + */ + lorawan_status_t initialize_mac_layer(events::EventQueue *queue); + + /** Sets all callbacks for the application. + * + * @param callbacks A pointer to the structure carrying callbacks. + * @return LORAWAN_STATUS_OK on success, a negative error code on failure. + */ + lorawan_status_t set_lora_callbacks(const lorawan_app_callbacks_t *callbacks); + + /** Connect OTAA or ABP using Mbed-OS config system + * + * Connect by Over The Air Activation or Activation By Personalization. + * You need to configure the connection properly via the Mbed OS configuration + * system. + * + * When connecting via OTAA, the return code for success (LORAWAN_STATUS_CONNECT_IN_PROGRESS) is negative. + * However, this is not a real error. It tells you that the connection is in progress and you will + * be notified of the completion via an event. By default, after the Join Accept message + * is received, base stations may provide the node with a CF-List that replaces + * all user-configured channels except the Join/Default channels. A CF-List can + * configure a maximum of five channels other than the default channels. + * + * In case of ABP, the CONNECTED event is posted before the call to `connect()` returns. + * To configure more channels, we recommend that you use the `set_channel_plan()` API after the connection. + * By default, the PHY layers configure only the mandatory Join channels. The retransmission back-off restrictions + * on these channels are severe and you may experience long delays or even failures in the confirmed traffic. + * If you add more channels, the aggregated duty cycle becomes much more relaxed as compared to the Join (default) channels only. + * + * **NOTES ON RECONNECTION:** + * Currently, the Mbed OS LoRaWAN implementation does not support non-volatile + * memory storage. Therefore, the state and frame counters cannot be restored after + * a power cycle. However, if you use the `disconnect()` API to shut down the LoRaWAN + * protocol, the state and frame counters are saved. Connecting again would try to + * restore the previous session. According to the LoRaWAN 1.0.2 specification, the frame counters are always reset + * to zero for OTAA and a new Join request lets the network server know + * that the counters need a reset. The same is said about the ABP but there + * is no way to convey this information to the network server. For a network + * server, an ABP device is always connected. That's why storing the frame counters + * is important, at least for ABP. That's why we try to restore frame counters from + * session information after a disconnection. + * + * @return LORAWAN_STATUS_OK or LORAWAN_STATUS_CONNECT_IN_PROGRESS + * on success, or a negative error code on failure. + */ + lorawan_status_t connect(); + + /** Connect OTAA or ABP with parameters + * + * All connection parameters are chosen by the user and provided in the + * data structure passed down. + * + * When connecting via OTAA, the return code for success (LORAWAN_STATUS_CONNECT_IN_PROGRESS) is negative. + * However, this is not a real error. It tells you that connection is in progress and you will + * be notified of completion via an event. By default, after Join Accept message + * is received, base stations may provide the node with a CF-List which replaces + * all user-configured channels except the Join/Default channels. A CF-List can + * configure a maximum of five channels other than the default channels. + * + * In case of ABP, the CONNECTED event is posted before the call to `connect()` returns. + * To configure more channels, we recommend that you use the `set_channel_plan()` API after the connection. + * By default, the PHY layers configure only the mandatory Join + * channels. The retransmission back-off restrictions on these channels + * are severe and you may experience long delays or even + * failures in the confirmed traffic. If you add more channels, the aggregated duty + * cycle becomes much more relaxed as compared to the Join (default) channels only. + * + * **NOTES ON RECONNECTION:** + * Currently, the Mbed OS LoRaWAN implementation does not support non-volatile + * memory storage. Therefore, the state and frame counters cannot be restored after + * a power cycle. However, if you use the `disconnect()` API to shut down the LoRaWAN + * protocol, the state and frame counters are saved. Connecting again would try to + * restore the previous session. According to the LoRaWAN 1.0.2 specification, the frame counters are always reset + * to zero for OTAA and a new Join request lets the network server know + * that the counters need a reset. The same is said about the ABP but there + * is no way to convey this information to the network server. For a network + * server, an ABP device is always connected. That's why storing the frame counters + * is important, at least for ABP. That's why we try to restore frame counters from + * session information after a disconnection. + * + * @param connect Options for an end device connection to the gateway. + * + * @return LORAWAN_STATUS_OK or LORAWAN_STATUS_CONNECT_IN_PROGRESS, + * a negative error code on failure. + */ + lorawan_status_t connect(const lorawan_connect_t &connect); + + /** Adds channels to use. + * + * You can provide a list of channels with appropriate parameters filled + * in. However, this list is not absolute. In some regions, a CF + * list gets implemented by default, which means that the network can overwrite your channel + * frequency settings right after receiving a Join Accept. You may try + * to set up any channel or channels after that and if the channel requested + * is already active, the request is silently ignored. A negative error + * code is returned if there is any problem with parameters. + * + * You need to ensure that the base station nearby supports the channel or channels being added. + * + * If your list includes a default channel (a channel where Join Requests + * are received) you cannot fully configure the channel parameters. + * Either leave the channel settings to default or check your + * corresponding PHY layer implementation. For example, LoRaPHYE868. + * + * @param channel_plan A list of channels or a single channel. + * + * @return LORAWAN_STATUS_OK on success, a negative error + * code on failure. + */ + lorawan_status_t add_channels(const lorawan_channelplan_t &channel_plan); + + /** Removes a channel from the list. + * + * @param channel_id Index of the channel being removed + * + * @return LORAWAN_STATUS_OK on success, a negative error + * code on failure. + */ + lorawan_status_t remove_a_channel(uint8_t channel_id); + + /** Removes a previously set channel plan. + * + * @return LORAWAN_STATUS_OK on success, a negative error + * code on failure. + */ + lorawan_status_t drop_channel_list(); + + /** Gets a list of currently enabled channels . + * + * @param channel_plan The channel plan structure to store final result. + * + * @return LORAWAN_STATUS_OK on success, a negative error + * code on failure. + */ + lorawan_status_t get_enabled_channels(lorawan_channelplan_t &channel_plan); + + /** Sets up a retry counter for confirmed messages. + * + * Valid only for confirmed messages. This API sets the number of times the + * stack will retry a CONFIRMED message before giving up and reporting an + * error. + * + * @param count The number of retries for confirmed messages. + * + * @return LORAWAN_STATUS_OK or a negative error code. + */ + lorawan_status_t set_confirmed_msg_retry(uint8_t count); + + /** Sets up the data rate. + * + * `set_datarate()` first verifies whether the data rate given is valid or not. + * If it is valid, the system sets the given data rate to the channel. + * + * @param data_rate The intended data rate, for example DR_0 or DR_1. + * Note that the macro DR_* can mean different + * things in different regions. + * + * @return LORAWAN_STATUS_OK if everything goes well, otherwise + * a negative error code. + */ + lorawan_status_t set_channel_data_rate(uint8_t data_rate); + + /** Enables ADR. + * + * @param adr_enabled 0 ADR disabled, 1 ADR enabled. + * + * @return LORAWAN_STATUS_OK on success, a negative error + * code on failure. + */ + lorawan_status_t enable_adaptive_datarate(bool adr_enabled); + + /** Send message to gateway + * + * @param port The application port number. Port numbers 0 and 224 + * are reserved, whereas port numbers from 1 to 223 + * (0x01 to 0xDF) are valid port numbers. + * Anything out of this range is illegal. + * + * @param data A pointer to the data being sent. The ownership of the + * buffer is not transferred. The data is copied to the + * internal buffers. + * + * @param length The size of data in bytes. + * + * @param flags A flag used to determine what type of + * message is being sent, for example: + * + * MSG_UNCONFIRMED_FLAG = 0x01 + * MSG_CONFIRMED_FLAG = 0x02 + * MSG_MULTICAST_FLAG = 0x04 + * MSG_PROPRIETARY_FLAG = 0x08 + * MSG_MULTICAST_FLAG and MSG_PROPRIETARY_FLAG can be + * used in conjunction with MSG_UNCONFIRMED_FLAG and + * MSG_CONFIRMED_FLAG depending on the intended use. + * + * MSG_PROPRIETARY_FLAG|MSG_CONFIRMED_FLAG mask will set + * a confirmed message flag for a proprietary message. + * MSG_CONFIRMED_FLAG and MSG_UNCONFIRMED_FLAG are + * mutually exclusive. + * + * @param null_allowed Internal use only. Needed for sending empty packet + * having CONFIRMED bit on. + * + * @param allow_port_0 Internal use only. Needed for flushing MAC commands. + * + * @return The number of bytes sent, or + * LORAWAN_STATUS_WOULD_BLOCK if another TX is + * ongoing, or a negative error code on failure. + */ + int16_t handle_tx(uint8_t port, const uint8_t* data, + uint16_t length, uint8_t flags, + bool null_allowed = false, bool allow_port_0 = false); + + /** Receives a message from the Network Server. + * + * @param data A pointer to buffer where the received data will be + * stored. + * + * @param length The size of data in bytes + * + * @param port The application port number. Port numbers 0 and 224 + * are reserved, whereas port numbers from 1 to 223 + * (0x01 to 0xDF) are valid port numbers. + * Anything out of this range is illegal. + * + * In return will contain the number of port to which + * message was received. + * + * @param flags A flag is used to determine what type of + * message is being received, for example: + * + * MSG_UNCONFIRMED_FLAG = 0x01, + * MSG_CONFIRMED_FLAG = 0x02 + * MSG_MULTICAST_FLAG = 0x04, + * MSG_PROPRIETARY_FLAG = 0x08 + * + * MSG_MULTICAST_FLAG and MSG_PROPRIETARY_FLAG can be + * used in conjunction with MSG_UNCONFIRMED_FLAG and + * MSG_CONFIRMED_FLAG depending on the intended use. + * + * MSG_PROPRIETARY_FLAG|MSG_CONFIRMED_FLAG mask will set + * a confirmed message flag for a proprietary message. + * + * MSG_CONFIRMED_FLAG and MSG_UNCONFIRMED_FLAG are + * not mutually exclusive, i.e., the user can subscribe to + * receive both CONFIRMED AND UNCONFIRMED messages at + * the same time. + * + * In return will contain the flags to determine what kind + * of message was received. + * + * @param validate_params If set to true, the given port and flags values will be checked + * against the values received with the message. If values do not + * match, LORAWAN_STATUS_WOULD_BLOCK will be returned. + * + * @return It could be one of these: + * i) 0 if there is nothing else to read. + * ii) Number of bytes written to user buffer. + * iii) LORAWAN_STATUS_WOULD_BLOCK if there is + * nothing available to read at the moment. + * iv) A negative error code on failure. + */ + int16_t handle_rx(uint8_t* data, uint16_t length, uint8_t& port, int& flags, bool validate_params); + + /** Send Link Check Request MAC command. + * + * + * This API schedules a Link Check Request command (LinkCheckReq) for the network + * server and once the response, i.e., LinkCheckAns MAC command is received + * from the Network Server, an event is generated. + * + * A callback function for the link check response must be set prior to using + * this API, otherwise a LORAWAN_STATUS_PARAMETER_INVALID error is thrown. + * + * @return LORAWAN_STATUS_OK on successfully queuing a request, or + * a negative error code on failure. + * + */ + lorawan_status_t set_link_check_request(); + + /** Removes link check request sticky MAC command. + * + * Any already queued request may still get entertained. However, no new + * requests will be made. + */ + void remove_link_check_request(); + + /** Shuts down the LoRaWAN protocol. + * + * In response to the user call for disconnection, the stack shuts down itself. + * + * @return LORAWAN_STATUS_DEVICE_OFF on successfully shutdown. + */ + lorawan_status_t shutdown(); + + /** Change device class + * + * Change current device class. + * + * @param device_class The device class + * + * @return LORAWAN_STATUS_OK on success, + * LORAWAN_STATUS_UNSUPPORTED is requested class is not supported, + * or other negative error code if request failed. + */ + lorawan_status_t set_device_class(const device_class_t& device_class); + + void lock(void) { _loramac.lock(); } + void unlock(void) { _loramac.unlock(); } + +private: + typedef mbed::ScopedLock<LoRaWANStack> Lock; + /** + * Checks if the user provided port is valid or not + */ + bool is_port_valid(uint8_t port, bool allow_port_0 = false); + + /** + * State machine for stack controller layer. + */ + lorawan_status_t state_controller(device_states_t new_state); + + /** + * Helpers for state controller + */ + void process_uninitialized_state(lorawan_status_t& op_status); + void process_idle_state(lorawan_status_t& op_status); + void process_connected_state(); + void process_connecting_state(lorawan_status_t& op_status); + void process_joining_state(lorawan_status_t& op_status); + void process_scheduling_state(lorawan_status_t& op_status); + void process_status_check_state(); + void process_shutdown_state(lorawan_status_t& op_status); + void state_machine_run_to_completion(void); + + /** + * Handles MLME indications + */ + void mlme_indication_handler(void); + + /** + * Handles an MLME confirmation + */ + void mlme_confirm_handler(void); + + /** + * Handles an MCPS confirmation + */ + void mcps_confirm_handler(void); + + /** + * Handles an MCPS indication + */ + void mcps_indication_handler(void); + + /** + * Sets up user application port + */ + lorawan_status_t set_application_port(uint8_t port, bool allow_port_0 = false); + + /** + * Handles connection internally + */ + lorawan_status_t handle_connect(bool is_otaa); + + + /** Send event to application. + * + * @param event The event to be sent. + */ + void send_event_to_application(const lorawan_event_t event) const; + + /** Send empty uplink message to network. + * + * Sends an empty confirmed message to gateway. + * + * @param port The event to be sent. + */ + void send_automatic_uplink_message(uint8_t port); + + /** + * TX interrupt handlers and corresponding processors + */ + void tx_interrupt_handler(void); + void tx_timeout_interrupt_handler(void); + void process_transmission(void); + void process_transmission_timeout(void); + + /** + * RX interrupt handlers and corresponding processors + */ + void rx_interrupt_handler(const uint8_t *payload, uint16_t size, int16_t rssi, + int8_t snr); + void rx_timeout_interrupt_handler(void); + void rx_error_interrupt_handler(void); + void process_reception(const uint8_t *payload, uint16_t size, int16_t rssi, + int8_t snr); + void process_reception_timeout(bool is_timeout); + + int convert_to_msg_flag(const mcps_type_t type); + +private: + LoRaMac _loramac; + radio_events_t radio_events; + device_states_t _device_current_state; + lorawan_app_callbacks_t _callbacks; + lorawan_session_t _lw_session; + loramac_tx_message_t _tx_msg; + loramac_rx_message_t _rx_msg; + uint8_t _num_retry; + uint32_t _ctrl_flags; + uint8_t _app_port; + bool _link_check_requested; + bool _automatic_uplink_ongoing; + volatile bool _ready_for_rx; + uint8_t _rx_payload[LORAMAC_PHY_MAXPAYLOAD]; + events::EventQueue *_queue; + +#if defined(LORAWAN_COMPLIANCE_TEST) + + /** + * Used only for compliance testing + */ + void compliance_test_handler(loramac_mcps_indication_t *mcps_indication); + + /** + * Used only for compliance testing + */ + lorawan_status_t send_compliance_test_frame_to_mac(); + + compliance_test_t _compliance_test; +#endif +}; + +#endif /* LORAWANSTACK_H_ */