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