LoRaMac.h

00001 /**
00002  * \file      LoRaMac.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 MBED_LORAWAN_MAC_H__
00041 #define MBED_LORAWAN_MAC_H__
00042 
00043 #include "lorawan/system/LoRaWANTimer.h"
00044 #include "lorastack/phy/LoRaPHY.h"
00045 #include "lorawan/system/lorawan_data_structures.h"
00046 #include "LoRaMacCommand.h"
00047 #include "events/EventQueue.h"
00048 #include "LoRaMacChannelPlan.h"
00049 #include "loraphy_target.h"
00050 
00051 class LoRaMac {
00052 
00053 public:
00054 
00055     /**
00056      * Constructor
00057      */
00058     LoRaMac();
00059 
00060     /**
00061      * Destructor
00062      */
00063     ~LoRaMac();
00064 
00065     /**
00066      * @brief   LoRaMAC layer initialization
00067      *
00068      * @details In addition to the initialization of the LoRaMAC layer, this
00069      *          function initializes the callback primitives of the MCPS and
00070      *          MLME services. Every data field of \ref loramac_primitives_t must be
00071      *          set to a valid callback function.
00072      *
00073      * @param   primitives [in]   A pointer to the structure defining the LoRaMAC
00074      *                            event functions. Refer to \ref loramac_primitives_t.
00075      *
00076      * @param   queue [in]        A pointer to the application provided EventQueue.
00077      *
00078      * @return  `lorawan_status_t` The status of the operation. The possible values are:
00079      *          \ref LORAWAN_STATUS_OK
00080      *          \ref LORAWAN_STATUS_PARAMETER_INVALID
00081      */
00082     lorawan_status_t initialize(loramac_primitives_t  *primitives,
00083                                 events::EventQueue *queue);
00084 
00085     /**
00086      * @brief   Disconnect LoRaMac layer
00087      *
00088      * @details Cancels all outstanding requests and sets LoRaMac's
00089      *          internal state to idle.
00090      */
00091     void disconnect(void);
00092 
00093     /**
00094      * @brief   Queries the LoRaMAC whether it is possible to send the next frame with
00095      *          a given payload size. The LoRaMAC takes the scheduled MAC commands into
00096      *          account and returns corresponding value.
00097      *
00098      * @param   size     [in]    The size of the applicable payload to be sent next.
00099      *
00100      * @return  Size of the biggest packet that can be sent.
00101      *          Please note that if the size of the MAC commands in the queue do
00102      *          not fit into the payload size on the related datarate, the LoRaMAC will
00103      *          omit the MAC commands.
00104      */
00105     uint8_t get_max_possible_tx_size(uint8_t size);
00106 
00107     /**
00108      * @brief nwk_joined Checks if device has joined to network
00109      * @return True if joined to network, false otherwise
00110      */
00111     bool nwk_joined();
00112 
00113     /**
00114      * @brief set_nwk_joined This is used for ABP mode for which real joining does not happen
00115      * @param joined True if device has joined in network, false otherwise
00116      */
00117     void set_nwk_joined(bool joined);
00118 
00119     /**
00120      * @brief   Adds a channel plan to the system.
00121      *
00122      * @details Adds a whole channel plan or a single new channel if the plan
00123      *          contains only one channel and 'plan.nb_channels' is set to 1.
00124      *          Please note that this functionality is not available in all regions.
00125      *          Information on the allowed ranges is available at the
00126      *          LoRaWAN Regional Parameters V1.0.2rB.
00127      *
00128      * @param   plan [in]    A reference to application provided channel plan.
00129      *
00130      * @return  `lorawan_status_t` The status of the operation. The possible values are:
00131      *          \ref LORAWAN_STATUS_OK
00132      *          \ref LORAWAN_STATUS_BUSY
00133      *          \ref LORAWAN_STATUS_PARAMETER_INVALID
00134      */
00135     lorawan_status_t add_channel_plan(const lorawan_channelplan_t& plan);
00136 
00137     /**
00138      * @brief   Removes a channel plan from the system.
00139      *
00140      * @details Removes the whole active channel plan except the 'Default Channels'.
00141      *          Please note that this functionality is not available in all regions.
00142      *          Information on the allowed ranges is available at the
00143      *          LoRaWAN Regional Parameters V1.0.2rB.
00144      *
00145      * @return  `lorawan_status_t` The status of the operation. The possible values are:
00146      *          \ref LORAWAN_STATUS_OK
00147      *          \ref LORAWAN_STATUS_BUSY
00148      *          \ref LORAWAN_STATUS_PARAMETER_INVALID
00149      */
00150     lorawan_status_t remove_channel_plan();
00151 
00152     /**
00153      * @brief   Access active channel plan.
00154      *
00155      * @details Provides access to the current active channel plan.
00156      *
00157      * @param   plan [out]    A reference to application provided channel plan data
00158      *                        structure which will be filled in with active channel
00159      *                        plan.
00160      *
00161      * @return  `lorawan_status_t` The status of the operation. The possible values are:
00162      *          \ref LORAWAN_STATUS_OK
00163      *          \ref LORAWAN_STATUS_BUSY
00164      *          \ref LORAWAN_STATUS_PARAMETER_INVALID
00165      */
00166     lorawan_status_t get_channel_plan(lorawan_channelplan_t& plan);
00167 
00168     /**
00169      * @brief   Remove a given channel from the active plan.
00170      *
00171      * @details Deactivates the given channel.
00172      *
00173      * @param id    Id of the channel.
00174      *
00175      * @return  `lorawan_status_t` The status of the operation. The possible values are:
00176      *          \ref LORAWAN_STATUS_OK
00177      *          \ref LORAWAN_STATUS_BUSY
00178      *          \ref LORAWAN_STATUS_PARAMETER_INVALID
00179      */
00180     lorawan_status_t remove_single_channel(uint8_t id);
00181 
00182     /**
00183      * @brief   LoRaMAC multicast channel link service.
00184      *
00185      * @details Links a multicast channel into the linked list.
00186      *
00187      * @param [in] channel_param    The multicast channel parameters to link.
00188      *
00189      * @return  `lorawan_status_t` The  status of the operation. The possible values are:
00190      *          \ref LORAWAN_STATUS_OK
00191      *          \ref LORAWAN_STATUS_BUSY
00192      *          \ref LORAWAN_STATUS_PARAMETER_INVALID
00193      */
00194     lorawan_status_t multicast_channel_link(multicast_params_t  *channel_param);
00195 
00196     /**
00197      * @brief   LoRaMAC multicast channel unlink service.
00198      *
00199      * @details Unlinks a multicast channel from the linked list.
00200      *
00201      * @param [in] channel_param    The multicast channel parameters to unlink.
00202      *
00203      * @return  `lorawan_status_t` The status of the operation. The possible values are:
00204      *          \ref LORAWAN_STATUS_OK
00205      *          \ref LORAWAN_STATUS_BUSY
00206      *          \ref LORAWAN_STATUS_PARAMETER_INVALID
00207      */
00208     lorawan_status_t multicast_channel_unlink(multicast_params_t  *channel_param);
00209 
00210     /** Binds radio driver to PHY layer.
00211      *
00212      * MAC layer is totally detached from the PHY layer so the stack layer
00213      * needs to play the role of an arbitrator. This API gets a radio driver
00214      * object from the application (via LoRaWANInterface), binds it to the PHY
00215      * layer and initialises radio callback handles which the radio driver will
00216      * use in order to report events.
00217      *
00218      * @param radio            LoRaRadio object, i.e., the radio driver
00219      *
00220      */
00221     void bind_radio_driver(LoRaRadio& radio);
00222 
00223     /**
00224      * @brief Configures the events to trigger an MLME-Indication with
00225      *        a MLME type of MLME_SCHEDULE_UPLINK.
00226      */
00227     void set_mlme_schedule_ul_indication(void);
00228 
00229     /**
00230      * @brief Schedules the frame for sending.
00231      *
00232      * @details Prepares a full MAC frame and schedules it for physical
00233      *          transmission.
00234      *
00235      * @param [in] mac_hdr      MAC frame header field
00236      * @param [in] fport        Payload port
00237      * @param [in] fbuffer      MAC frame data buffer to be sent
00238      * @param [in] fbuffer_size MAC frame data buffer size
00239      *
00240      * @return status          Status of the operation. LORAWAN_STATUS_OK in case
00241      *                         of success and a negative error code in case of
00242      *                         failure.
00243      */
00244     lorawan_status_t send(loramac_mhdr_t  *mac_hdr, uint8_t fport, void *fbuffer,
00245                           uint16_t fbuffer_size);
00246 
00247     /**
00248      * @brief Puts the system in continuous transmission mode
00249      *
00250      * @remark Uses the radio parameters set on the previous transmission.
00251      *
00252      * @param [in] timeout    Time in seconds while the radio is kept in continuous wave mode
00253      *
00254      * @return status          Status of the operation. LORAWAN_STATUS_OK in case
00255      *                         of success and a negative error code in case of
00256      *                         failure.
00257      */
00258     lorawan_status_t set_tx_continuous_wave(uint16_t timeout);
00259 
00260     /**
00261      * @brief Puts the system in continuous transmission mode
00262      *
00263      * @param [in] timeout     Time in seconds while the radio is kept in continuous wave mode
00264      * @param [in] frequency   RF frequency to be set.
00265      * @param [in] power       RF output power to be set.
00266      *
00267      * @return status          Status of the operation. LORAWAN_STATUS_OK in case
00268      *                         of success and a negative error code in case of
00269      *                         failure.
00270      */
00271     lorawan_status_t set_tx_continuous_wave1(uint16_t timeout, uint32_t frequency, uint8_t power);
00272 
00273     /**
00274      * @brief Resets MAC specific parameters to default
00275      */
00276     void reset_mac_parameters(void);
00277 
00278     /**
00279      * @brief Opens up a continuous RX 2 window. This is used for
00280      *        class c devices.
00281      */
00282     void open_continuous_rx2_window(void);
00283 
00284     /**
00285      * @brief get_default_tx_datarate Gets the default TX datarate
00286      * @return default TX datarate.
00287      */
00288     uint8_t get_default_tx_datarate();
00289 
00290     /**
00291      * @brief enable_adaptive_datarate Enables or disables adaptive datarate.
00292      * @param adr_enabled Flag indicating is adr enabled or disabled.
00293      */
00294     void enable_adaptive_datarate(bool adr_enabled);
00295 
00296     /** Sets up the data rate.
00297      *
00298      * `set_datarate()` first verifies whether the data rate given is valid or not.
00299      * If it is valid, the system sets the given data rate to the channel.
00300      *
00301      * @param data_rate   The intended data rate, for example DR_0 or DR_1.
00302      *                    Note that the macro DR_* can mean different
00303      *                    things in different regions.
00304      *
00305      * @return            LORAWAN_STATUS_OK if everything goes well, otherwise
00306      *                    a negative error code.
00307      */
00308     lorawan_status_t set_channel_data_rate(uint8_t data_rate);
00309 
00310     /**
00311      * @brief tx_ongoing Check whether a prepare is done or not.
00312      * @return True if prepare_ongoing_tx is called, false otherwise.
00313      */
00314     bool tx_ongoing();
00315 
00316     /**
00317      * @brief set_tx_ongoing Changes the ongoing status for prepared message.
00318      * @param ongoing The value indicating the status.
00319      */
00320     void set_tx_ongoing(bool ongoing);
00321 
00322     /**
00323      * @brief reset_ongoing_tx Resets _ongoing_tx_msg.
00324      * @param reset_pending If true resets pending size also.
00325      */
00326     void reset_ongoing_tx(bool reset_pending = false);
00327 
00328     /**
00329      * @brief prepare_ongoing_tx This will prepare (and override) ongoing_tx_msg.
00330      * @param port The application port number.
00331      * @param data A pointer to the data being sent. The ownership of the
00332      *             buffer is not transferred.
00333      * @param length The size of data in bytes.
00334      * @param flags A flag used to determine what type of
00335      *              message is being sent.
00336      * @param num_retries Number of retries for a confirmed type message
00337      * @return The number of bytes prepared for sending.
00338      */
00339     int16_t prepare_ongoing_tx(uint8_t port, const uint8_t* data,
00340                                uint16_t length, uint8_t flags, uint8_t num_retries);
00341 
00342     /**
00343      * @brief send_ongoing_tx Sends the ongoing_tx_msg
00344      * @return LORAWAN_STATUS_OK or a negative error code on failure.
00345      */
00346     lorawan_status_t send_ongoing_tx();
00347 
00348     /**
00349      * @brief device_class Returns active device class
00350      * @return Device class in use.
00351      */
00352     device_class_t  get_device_class() const;
00353 
00354     /**
00355      * @brief set_device_class Sets active device class.
00356      * @param device_class Device class to use.
00357      */
00358     void set_device_class(const device_class_t & device_class);
00359 
00360     /**
00361      * @brief setup_link_check_request Adds link check request command
00362      * to be put on next outgoing message (when it fits)
00363      */
00364     void setup_link_check_request();
00365 
00366     /**
00367      * @brief join_by_otaa Sends OTAA join message
00368      * @param otaa_join Joining parameters
00369      *
00370      * @return LORAWAN_STATUS_OK or a negative error code on failure.
00371      */
00372     lorawan_status_t join_by_otaa(const lorawan_connect_otaa_t& otaa_join);
00373 
00374     /**
00375      * @brief join_by_abp Sets up ABP connectivity parameters.
00376      * @param abp_join Connectivity parameters.
00377      */
00378     void join_by_abp(const lorawan_connect_abp_t& abp_join);
00379 
00380 private:
00381     /**
00382      * Function to be executed on Radio Tx Done event
00383      */
00384     void on_radio_tx_done(void);
00385 
00386     /**
00387      * This function prepares the MAC to abort the execution of function
00388      * on_radio_rx_done() in case of a reception error.
00389      */
00390     void prepare_rx_done_abort(void);
00391 
00392     /**
00393      * Function to be executed on Radio Rx Done event
00394      */
00395     void on_radio_rx_done(uint8_t *payload, uint16_t size, int16_t rssi,
00396                           int8_t snr);
00397 
00398     /**
00399      * Function executed on Radio Tx Timeout event
00400      */
00401     void on_radio_tx_timeout(void);
00402 
00403     /**
00404      * Function executed on Radio Rx error event
00405      */
00406     void on_radio_rx_error(void);
00407 
00408     /**
00409      * Function executed on Radio Rx Timeout event
00410      */
00411     void on_radio_rx_timeout(void);
00412 
00413     /**
00414      *Function executed on Resend Frame timer event.
00415      */
00416     void on_mac_state_check_timer_event(void);
00417 
00418     /**
00419      * Function executed on duty cycle delayed Tx  timer event
00420      */
00421     void on_tx_delayed_timer_event(void);
00422 
00423     /**
00424      * Function executed on first Rx window timer event
00425      */
00426     void on_rx_window1_timer_event(void);
00427 
00428     /**
00429      * Function executed on second Rx window timer event
00430      */
00431     void on_rx_window2_timer_event(void);
00432 
00433 
00434     /*!
00435      * \brief Check if the OnAckTimeoutTimer has do be disabled. If so, the
00436      *        function disables it.
00437      *
00438      * \param [in] node_ack_requested Set to true, if the node has requested an ACK
00439      * \param [in] dev_class The device class
00440      * \param [in] ack_received Set to true, if the node has received an ACK
00441      * \param [in] ack_timeout_retries_counter Retries counter for confirmed uplinks
00442      * \param [in] ack_timeout_retries Maximum retries for confirmed uplinks
00443      */
00444     void check_to_disable_ack_timeout(bool node_ack_requested,
00445                                       device_class_t  dev_class,
00446                                       bool ack_received,
00447                                       uint8_t ack_timeout_retries_counter,
00448                                       uint8_t ack_timeout_retries);
00449 
00450     /**
00451      * Function executed on AckTimeout timer event
00452      */
00453     void on_ack_timeout_timer_event(void);
00454 
00455     /**
00456      * Initializes and opens the reception window
00457      */
00458     void rx_window_setup(bool rx_continuous, uint32_t max_rx_window_time);
00459 
00460     /**
00461      * Validates if the payload fits into the frame, taking the datarate
00462      * into account.
00463      *
00464      * Please Refer to chapter 4.3.2 of the LoRaWAN specification, v1.0.2
00465      */
00466     bool validate_payload_length(uint8_t length, int8_t datarate, uint8_t fopts_len);
00467 
00468     /**
00469      * Prepares MAC frame on the behest of send() API.
00470      */
00471     lorawan_status_t prepare_frame(loramac_mhdr_t  *mac_hdr,
00472                                    loramac_frame_ctrl_t  *fctrl, uint8_t fport,
00473                                    void *fbuffer, uint16_t fbuffer_size);
00474 
00475     /**
00476      * Schedules a transmission on the behest of send() API.
00477      */
00478     lorawan_status_t schedule_tx(void);
00479 
00480     /**
00481      * Calculates the back-off time for the band of a channel.
00482      * Takes in the last used channel id as a parameter.
00483      */
00484     void calculate_backOff(uint8_t channel_id);
00485 
00486     /**
00487      * Hands over the MAC frame to PHY layer.
00488      */
00489     lorawan_status_t send_frame_on_channel(uint8_t channel);
00490 
00491     /**
00492      * @brief reset_mcps_confirmation Resets the MCPS confirmation struct
00493      */
00494     void reset_mcps_confirmation();
00495 
00496     /**
00497      * @brief reset_mlme_confirmation Resets the MLME confirmation struct
00498      */
00499     void reset_mlme_confirmation();
00500 
00501     /**
00502      * @brief set_tx_continuous_wave Puts the system in continuous transmission mode
00503      * @param [in] channel A Channel to use
00504      * @param [in] datarate A datarate to use
00505      * @param [in] tx_power A RF output power to use
00506      * @param [in] max_eirp A maximum possible EIRP to use
00507      * @param [in] antenna_gain Antenna gain to use
00508      * @param [in] timeout Time in seconds while the radio is kept in continuous wave mode
00509      */
00510     void set_tx_continuous_wave(uint8_t channel, int8_t datarate, int8_t tx_power,
00511                                 float max_eirp, float antenna_gain, uint16_t timeout);
00512 
00513     /**
00514      * Prototypes for ISR handlers
00515      */
00516     void handle_cad_done(bool cad);
00517     void handle_tx_done(void);
00518     void handle_rx_done(uint8_t *payload, uint16_t size, int16_t rssi, int8_t snr);
00519     void handle_rx_error(void);
00520     void handle_rx_timeout(void);
00521     void handle_tx_timeout(void);
00522     void handle_fhss_change_channel(uint8_t cur_channel);
00523 
00524 private:
00525     /**
00526      * Timer subsystem handle
00527      */
00528     LoRaWANTimeHandler _lora_time;
00529 
00530     /**
00531      * LoRa PHY layer object storage
00532      */
00533     LoRaPHY_region _lora_phy;
00534 
00535     /**
00536      * MAC command handle
00537      */
00538     LoRaMacCommand mac_commands;
00539 
00540     /**
00541      * Channel planning subsystem
00542      */
00543     LoRaMacChannelPlan channel_plan;
00544 
00545     /**
00546      * Central MAC layer data storage
00547      */
00548     loramac_protocol_params _params;
00549 
00550     /**
00551      * Radio event callback handlers for MAC
00552      */
00553     radio_events_t radio_events;
00554 
00555     /**
00556      * LoRaMac upper layer event functions
00557      */
00558     loramac_primitives_t  *mac_primitives;
00559 
00560     /**
00561      * EventQueue object storage
00562      */
00563     events::EventQueue *ev_queue;
00564 
00565     /**
00566      * Structure to hold MCPS indication data.
00567      */
00568     loramac_mcps_indication_t  _mcps_indication;
00569 
00570     /**
00571      * Structure to hold MCPS confirm data.
00572      */
00573     loramac_mcps_confirm_t  _mcps_confirmation;
00574 
00575     /**
00576      * Structure to hold MLME indication data.
00577      */
00578     loramac_mlme_indication_t  _mlme_indication;
00579 
00580     /**
00581      * Structure to hold MLME confirm data.
00582      */
00583     loramac_mlme_confirm_t  _mlme_confirmation;
00584 
00585     loramac_tx_message_t _ongoing_tx_msg;
00586 
00587     bool _is_nwk_joined;
00588 
00589     device_class_t  _device_class;
00590 
00591 #if defined(LORAWAN_COMPLIANCE_TEST)
00592 public: // Test interface
00593 
00594     /**
00595      * @brief   Set forth an MLME request.
00596      *
00597      * @details The MAC layer management entity handles the management services.
00598      *
00599      * @param [in] request    The MLME request to perform.
00600      *                        Refer to \ref loramac_mlme_req_t.
00601      *
00602      * @return  `lorawan_status_t` The status of the operation. The possible values are:
00603      *          \ref LORAWAN_STATUS_OK
00604      *          \ref LORAWAN_STATUS_BUSY
00605      *          \ref LORAWAN_STATUS_SERVICE_UNKNOWN
00606      *          \ref LORAWAN_STATUS_PARAMETER_INVALID
00607      *          \ref LORAWAN_STATUS_NO_NETWORK_JOINED
00608      *          \ref LORAWAN_STATUS_LENGTH_ERROR
00609      *          \ref LORAWAN_STATUS_DEVICE_OFF
00610      */
00611     lorawan_status_t mlme_request(loramac_mlme_req_t *request);
00612 
00613     /**
00614      * @brief   Set forth an MCPS request.
00615      *
00616      * @details The MAC Common Part Sublayer handles the data services. The following
00617      *          code-snippet shows how to use the API to send an unconfirmed
00618      *          LoRaMAC frame.
00619      *
00620      * @code
00621      *
00622      * uint8_t buffer[] = {1, 2, 3};
00623      *
00624      * loramac_compliance_test_req_t request;
00625      * request.type = MCPS_UNCONFIRMED;
00626      * request.fport = 1;
00627      * request.f_buffer = buffer;
00628      * request.f_buffer_size = sizeof(buffer);
00629      *
00630      * if (test_request(&request) == LORAWAN_STATUS_OK) {
00631      *   // Service started successfully. Waiting for the MCPS-Confirm event
00632      * }
00633      *
00634      * @endcode
00635      *
00636      * @param [in] request    The test request to perform.
00637      *                        Refer to \ref loramac_compliance_test_req_t.
00638      *
00639      * @return  `lorawan_status_t` The status of the operation. The possible values are:
00640      *          \ref LORAWAN_STATUS_OK
00641      *          \ref LORAWAN_STATUS_BUSY
00642      *          \ref LORAWAN_STATUS_SERVICE_UNKNOWN
00643      *          \ref LORAWAN_STATUS_PARAMETER_INVALID
00644      *          \ref LORAWAN_STATUS_NO_NETWORK_JOINED
00645      *          \ref LORAWAN_STATUS_LENGTH_ERROR
00646      *          \ref LORAWAN_STATUS_DEVICE_OFF
00647      */
00648     lorawan_status_t test_request(loramac_compliance_test_req_t *request);
00649 
00650     /**
00651      * \brief   LoRaMAC set tx timer.
00652      *
00653      * \details Sets up a timer for next transmission (application specific timers).
00654      *
00655      * \param   [in] NextTxTime - Periodic time for next uplink.
00656 
00657      * \retval  `lorawan_status_t` The status of the operation. The possible values are:
00658      *          \ref LORAWAN_STATUS_OK
00659      *          \ref LORAWAN_STATUS_PARAMETER_INVALID
00660      */
00661     lorawan_status_t LoRaMacSetTxTimer( uint32_t NextTxTime );
00662 
00663     /**
00664      * \brief   LoRaMAC stop tx timer.
00665      *
00666      * \details Stops the next tx timer.
00667      *
00668      * \retval  `lorawan_status_t` The status of the operation. The possible values are:
00669      *          \ref LORAWAN_STATUS_OK
00670      *          \ref LORAWAN_STATUS_PARAMETER_INVALID
00671      */
00672     lorawan_status_t LoRaMacStopTxTimer( );
00673 
00674     /**
00675      * \brief   Enabled or disables the reception windows
00676      *
00677      * \details This is a test function. It shall be used for testing purposes only.
00678      *          Changing this attribute may lead to a non-conformance LoRaMac operation.
00679      *
00680      * \param   [in] enable - Enabled or disables the reception windows
00681      */
00682     void LoRaMacTestRxWindowsOn( bool enable );
00683 
00684     /**
00685      * \brief   Enables the MIC field test
00686      *
00687      * \details This is a test function. It shall be used for testing purposes only.
00688      *          Changing this attribute may lead to a non-conformance LoRaMac operation.
00689      *
00690      * \param   [in] txPacketCounter - Fixed Tx packet counter value
00691      */
00692     void LoRaMacTestSetMic( uint16_t txPacketCounter );
00693 
00694     /**
00695      * \brief   Enabled or disables the duty cycle
00696      *
00697      * \details This is a test function. It shall be used for testing purposes only.
00698      *          Changing this attribute may lead to a non-conformance LoRaMac operation.
00699      *
00700      * \param   [in] enable - Enabled or disables the duty cycle
00701      */
00702     void LoRaMacTestSetDutyCycleOn( bool enable );
00703 
00704     /**
00705      * \brief   Sets the channel index
00706      *
00707      * \details This is a test function. It shall be used for testing purposes only.
00708      *          Changing this attribute may lead to a non-conformance LoRaMac operation.
00709      *
00710      * \param   [in] channel - Channel index
00711      */
00712     void LoRaMacTestSetChannel( uint8_t channel );
00713 
00714 private:
00715     /**
00716      * Timer to handle the application data transmission duty cycle
00717      */
00718     timer_event_t tx_next_packet_timer;
00719 #endif
00720 };
00721 
00722 #endif // MBED_LORAWAN_MAC_H__