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