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 "system/lorawan_data_structures.h"
00045 #include "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 
00059     /**
00060      * @brief Clear MAC command buffer.
00061      */
00062     void clear_command_buffer(void);
00063 
00064     /**
00065      * @brief Get the length of MAC commands
00066      *
00067      * @return status    Length of used MAC buffer (bytes)
00068      */
00069     uint8_t get_mac_cmd_length() const;
00070 
00071     /**
00072      * @brief Get MAC command buffer
00073      *
00074      * @return    Pointer to MAC command buffer
00075      */
00076     uint8_t *get_mac_commands_buffer();
00077 
00078     /**
00079      * @brief Parses the MAC commands which must be resent.
00080      */
00081     void parse_mac_commands_to_repeat();
00082 
00083     /**
00084      * @brief Clear  MAC command repeat buffer.
00085      */
00086     void clear_repeat_buffer();
00087 
00088     /**
00089      * @brief Copy MAC commands from repeat buffer to actual MAC command buffer.
00090      */
00091     void copy_repeat_commands_to_buffer();
00092 
00093     /**
00094      * @brief Get the length of MAC commands in repeat buffer
00095      *
00096      * @return status  Length of used MAC Repeat buffer (bytes)
00097      */
00098     uint8_t get_repeat_commands_length() const;
00099 
00100     /**
00101      * @brief Clear MAC commands in next TX.
00102      */
00103     void clear_mac_commands_in_next_tx();
00104 
00105     /**
00106      * @brief Check if MAC command buffer has commands to be sent in next TX
00107      *
00108      * @return status  True: buffer has MAC commands to be sent, false: no commands in buffer
00109      */
00110     bool is_mac_command_in_next_tx() const;
00111 
00112     /**
00113      * @brief Clear sticky MAC commands.
00114      */
00115     void clear_sticky_mac_cmd();
00116 
00117     /**
00118      * @brief Check if MAC command buffer contains sticky commands
00119      *
00120      * @return status  True: buffer has sticky MAC commands in it, false: no sticky commands in buffer
00121      */
00122     bool has_sticky_mac_cmd() const;
00123 
00124     /**
00125      * @brief Decodes MAC commands in the fOpts field and in the payload
00126      *
00127      * @return status  Function status. LORAWAN_STATUS_OK if command successful.
00128      */
00129     lorawan_status_t process_mac_commands(const uint8_t *payload, uint8_t mac_index,
00130                                           uint8_t commands_size, uint8_t snr,
00131                                           loramac_mlme_confirm_t & mlme_conf,
00132                                           lora_mac_system_params_t & mac_params,
00133                                           LoRaPHY& lora_phy);
00134 
00135     /**
00136      * @brief Verifies if sticky MAC commands are pending.
00137      *
00138      * @return [true: sticky MAC commands pending, false: No MAC commands pending]
00139      */
00140     bool is_sticky_mac_command_pending();
00141 
00142     /**
00143      * @brief Adds a new LinkCheckReq MAC command to be sent.
00144      *
00145      * @return status  Function status: LORAWAN_STATUS_OK: OK,
00146      *                                  LORAWAN_STATUS_LENGTH_ERROR: Buffer full
00147      */
00148     lorawan_status_t add_link_check_req();
00149 
00150     /**
00151      * @brief Set battery level query callback method
00152      *        If callback is not set, BAT_LEVEL_NO_MEASURE is returned.
00153      */
00154     void set_batterylevel_callback(mbed::Callback<uint8_t(void)> battery_level);
00155 
00156 private:
00157     /**
00158      * @brief Get the remaining size of the MAC command buffer
00159      *
00160      * @return      Remaining free space in buffer (bytes).
00161      */
00162     int32_t cmd_buffer_remaining() const;
00163 
00164     /**
00165      * @brief Adds a new LinkAdrAns MAC command to be sent.
00166      *
00167      * @param [in] status Status bits
00168      *
00169      * @return status  Function status: LORAWAN_STATUS_OK: OK,
00170      *                                  LORAWAN_STATUS_LENGTH_ERROR: Buffer full
00171      */
00172     lorawan_status_t add_link_adr_ans(uint8_t status);
00173 
00174     /**
00175      * @brief Adds a new DutyCycleAns MAC command to be sent.
00176      *
00177      * @return status  Function status: LORAWAN_STATUS_OK: OK,
00178      *                                  LORAWAN_STATUS_LENGTH_ERROR: Buffer full
00179      */
00180     lorawan_status_t add_duty_cycle_ans();
00181 
00182     /**
00183      * @brief Adds a new RXParamSetupAns MAC command to be sent.
00184      *
00185      * @param [in] status Status bits
00186      *
00187      * @return status  Function status: LORAWAN_STATUS_OK: OK,
00188      *                                  LORAWAN_STATUS_LENGTH_ERROR: Buffer full
00189      */
00190     lorawan_status_t add_rx_param_setup_ans(uint8_t status);
00191 
00192     /**
00193      * @brief Adds a new DevStatusAns MAC command to be sent.
00194      *
00195      * @param [in] battery  Battery level
00196      * @param [in] margin   Demodulation signal-to-noise ratio (dB)
00197      *
00198      * @return status  Function status: LORAWAN_STATUS_OK: OK,
00199      *                                  LORAWAN_STATUS_LENGTH_ERROR: Buffer full
00200      */
00201     lorawan_status_t add_dev_status_ans(uint8_t battery, uint8_t margin);
00202 
00203     /**
00204      * @brief Adds a new NewChannelAns MAC command to be sent.
00205      *
00206      * @param [in] status Status bits
00207      *
00208      * @return status  Function status: LORAWAN_STATUS_OK: OK,
00209      *                                  LORAWAN_STATUS_LENGTH_ERROR: Buffer full
00210      */
00211     lorawan_status_t add_new_channel_ans(uint8_t status);
00212 
00213     /**
00214      * @brief Adds a new RXTimingSetupAns MAC command to be sent.
00215      *
00216      * @return status  Function status: LORAWAN_STATUS_OK: OK,
00217      *                                  LORAWAN_STATUS_LENGTH_ERROR: Buffer full
00218      */
00219     lorawan_status_t add_rx_timing_setup_ans();
00220 
00221     /**
00222      * @brief Adds a new TXParamSetupAns MAC command to be sent.
00223      *
00224      * @return status  Function status: LORAWAN_STATUS_OK: OK,
00225      *                                  LORAWAN_STATUS_LENGTH_ERROR: Buffer full
00226      */
00227     lorawan_status_t add_tx_param_setup_ans();
00228 
00229     /**
00230      * @brief Adds a new DlChannelAns MAC command to be sent.
00231      *
00232      * @param [in] status Status bits
00233      *
00234      * @return status  Function status: LORAWAN_STATUS_OK: OK,
00235      *                                  LORAWAN_STATUS_LENGTH_ERROR: Buffer full
00236      */
00237     lorawan_status_t add_dl_channel_ans(uint8_t status);
00238 
00239 private:
00240     /**
00241      * Indicates if the MAC layer wants to send MAC commands
00242      */
00243     bool mac_cmd_in_next_tx;
00244 
00245     /**
00246       * Indicates if there are any pending sticky MAC commands
00247       */
00248     bool sticky_mac_cmd;
00249 
00250     /**
00251      * Contains the current Mac command buffer index in 'mac_cmd_buffer'
00252      */
00253     uint8_t mac_cmd_buf_idx;
00254 
00255     /**
00256      * Contains the current Mac command buffer index for MAC commands to repeat in
00257      * 'mac_cmd_buffer_to_repeat'
00258      */
00259     uint8_t mac_cmd_buf_idx_to_repeat;
00260 
00261     /**
00262      * Buffer containing the MAC layer commands
00263      */
00264     uint8_t mac_cmd_buffer[LORA_MAC_COMMAND_MAX_LENGTH];
00265 
00266     /**
00267      * Buffer containing the MAC layer commands which must be repeated
00268      */
00269     uint8_t mac_cmd_buffer_to_repeat[LORA_MAC_COMMAND_MAX_LENGTH];
00270 
00271     mbed::Callback<uint8_t(void)> _battery_level_cb;
00272 };
00273 
00274 #endif //__LORAMACCOMMAND_H__