LoRaMacCommand.h

00001 /**
00002  * \file      LoRaMacCommand.h
00003  *
00004  * \brief     LoRa MAC layer implementation
00005  *
00006  * \copyright Revised BSD License, see LICENSE.TXT file include in the project
00007  *
00008  * \code
00009  *                ______                              _
00010  *               / _____)             _              | |
00011  *              ( (____  _____ ____ _| |_ _____  ____| |__
00012  *               \____ \| ___ |    (_   _) ___ |/ ___)  _ \
00013  *               _____) ) ____| | | || |_| ____( (___| | | |
00014  *              (______/|_____)_|_|_| \__)_____)\____)_| |_|
00015  *              (C)2013 Semtech
00016  *
00017  *               ___ _____ _   ___ _  _____ ___  ___  ___ ___
00018  *              / __|_   _/_\ / __| |/ / __/ _ \| _ \/ __| __|
00019  *              \__ \ | |/ _ \ (__| ' <| _| (_) |   / (__| _|
00020  *              |___/ |_/_/ \_\___|_|\_\_| \___/|_|_\\___|___|
00021  *              embedded.connectivity.solutions===============
00022  *
00023  * \endcode
00024  *
00025  * \author    Miguel Luis ( Semtech )
00026  *
00027  * \author    Gregory Cristian ( Semtech )
00028  *
00029  * \author    Daniel Jaeckle ( STACKFORCE )
00030  *
00031  * \defgroup  LORAMAC LoRa MAC layer implementation
00032  *            This module specifies the API implementation of the LoRaMAC layer.
00033  *            This is a placeholder for a detailed description of the LoRaMac
00034  *            layer and the supported features.
00035  *
00036  * Copyright (c) 2017, Arm Limited and affiliates.
00037  * SPDX-License-Identifier: BSD-3-Clause
00038  *
00039  */
00040 #ifndef __LORAMACCOMMAND_H__
00041 #define __LORAMACCOMMAND_H__
00042 
00043 #include <stdint.h>
00044 #include "lorawan/system/lorawan_data_structures.h"
00045 #include "lorawan/lorastack/phy/LoRaPHY.h"
00046 
00047 /*!
00048  * Maximum MAC commands buffer size
00049  */
00050 #define LORA_MAC_COMMAND_MAX_LENGTH                 128
00051 
00052 class LoRaMac;
00053 
00054 class LoRaMacCommand {
00055 
00056 public:
00057     LoRaMacCommand();
00058     ~LoRaMacCommand();
00059 
00060     /**
00061      * @brief Adds a new MAC command to be sent.
00062      *
00063      * @remark MAC layer internal function
00064      *
00065      * @param [in] cmd    MAC command to be added
00066      *                    [MOTE_MAC_LINK_CHECK_REQ,
00067      *                     MOTE_MAC_LINK_ADR_ANS,
00068      *                     MOTE_MAC_DUTY_CYCLE_ANS,
00069      *                     MOTE_MAC_RX2_PARAM_SET_ANS,
00070      *                     MOTE_MAC_DEV_STATUS_ANS
00071      *                     MOTE_MAC_NEW_CHANNEL_ANS]
00072      * @param [in] p1  1st parameter (optional depends on the command)
00073      * @param [in] p2  2nd parameter (optional depends on the command)
00074      *
00075      * @return status  Function status [0: OK, 1: Unknown command, 2: Buffer full]
00076      */
00077     lorawan_status_t add_mac_command(uint8_t cmd, uint8_t p1, uint8_t p2);
00078 
00079     /**
00080      * @brief Clear MAC command buffer.
00081      */
00082     void clear_command_buffer(void);
00083 
00084     /**
00085      * @brief Get the length of MAC commands
00086      *
00087      * @return status    Length of used MAC buffer (bytes)
00088      */
00089     uint8_t get_mac_cmd_length() const;
00090 
00091     /**
00092      * @brief Get MAC command buffer
00093      *
00094      * @return    Pointer to MAC command buffer
00095      */
00096     uint8_t *get_mac_commands_buffer();
00097 
00098     /**
00099      * @brief Parses the MAC commands which must be resent.
00100      */
00101     void parse_mac_commands_to_repeat();
00102 
00103     /**
00104      * @brief Clear  MAC command repeat buffer.
00105      */
00106     void clear_repeat_buffer();
00107 
00108     /**
00109      * @brief Copy MAC commands from repeat buffer to actual MAC command buffer.
00110      */
00111     void copy_repeat_commands_to_buffer();
00112 
00113     /**
00114      * @brief Get the length of MAC commands in repeat buffer
00115      *
00116      * @return status  Length of used MAC Repeat buffer (bytes)
00117      */
00118     uint8_t get_repeat_commands_length() const;
00119 
00120     /**
00121      * @brief Clear MAC commands in next TX.
00122      */
00123     void clear_mac_commands_in_next_tx();
00124 
00125     /**
00126      * @brief Check if MAC command buffer has commands to be sent in next TX
00127      *
00128      * @return status  True: buffer has MAC commands to be sent, false: no commands in buffer
00129      */
00130     bool is_mac_command_in_next_tx() const;
00131 
00132     /**
00133      * @brief Clear sticky MAC commands.
00134      */
00135     void clear_sticky_mac_cmd();
00136 
00137     /**
00138      * @brief Check if MAC command buffer contains sticky commands
00139      *
00140      * @return status  True: buffer has sticky MAC commands in it, false: no sticky commands in buffer
00141      */
00142     bool has_sticky_mac_cmd() const;
00143 
00144     /**
00145      * @brief Decodes MAC commands in the fOpts field and in the payload
00146      *
00147      * @return status  Function status. LORAWAN_STATUS_OK if command successful.
00148      */
00149     lorawan_status_t process_mac_commands(uint8_t *payload, uint8_t mac_index,
00150                                           uint8_t commands_size, uint8_t snr,
00151                                           loramac_mlme_confirm_t & mlme_conf,
00152                                           lora_mac_system_params_t & mac_params,
00153                                           LoRaPHY& lora_phy);
00154 
00155     /**
00156      * @brief Verifies if sticky MAC commands are pending.
00157      *
00158      * @return [true: sticky MAC commands pending, false: No MAC commands pending]
00159      */
00160     bool is_sticky_mac_command_pending();
00161 
00162 private:
00163     /**
00164      * Indicates if the MAC layer wants to send MAC commands
00165      */
00166     bool mac_cmd_in_next_tx;
00167 
00168     /**
00169       * Indicates if there are any pending sticky MAC commands
00170       */
00171     bool sticky_mac_cmd;
00172 
00173     /**
00174      * Contains the current Mac command buffer index in 'mac_cmd_buffer'
00175      */
00176     uint8_t mac_cmd_buf_idx;
00177 
00178     /**
00179      * Contains the current Mac command buffer index for MAC commands to repeat in
00180      * 'mac_cmd_buffer_to_repeat'
00181      */
00182     uint8_t mac_cmd_buf_idx_to_repeat;
00183 
00184     /**
00185      * Buffer containing the MAC layer commands
00186      */
00187     uint8_t mac_cmd_buffer[LORA_MAC_COMMAND_MAX_LENGTH];
00188 
00189     /**
00190      * Buffer containing the MAC layer commands which must be repeated
00191      */
00192     uint8_t mac_cmd_buffer_to_repeat[LORA_MAC_COMMAND_MAX_LENGTH];
00193 };
00194 
00195 #endif //__LORAMACCOMMAND_H__