lorawan_data_structures.h

00001 /**
00002  * @file lorawan_data_structures.h
00003  *
00004  * @brief Contains common data structures used by Mbed-OS
00005  *        LoRaWAN mplementation.
00006  *
00007  *  \code
00008  *   ______                              _
00009  *  / _____)             _              | |
00010  * ( (____  _____ ____ _| |_ _____  ____| |__
00011  *  \____ \| ___ |    (_   _) ___ |/ ___)  _ \
00012  *  _____) ) ____| | | || |_| ____( (___| | | |
00013  * (______/|_____)_|_|_| \__)_____)\____)_| |_|
00014  *   (C)2013 Semtech
00015  *  ___ _____ _   ___ _  _____ ___  ___  ___ ___
00016  * / __|_   _/_\ / __| |/ / __/ _ \| _ \/ __| __|
00017  * \__ \ | |/ _ \ (__| ' <| _| (_) |   / (__| _|
00018  * |___/ |_/_/ \_\___|_|\_\_| \___/|_|_\\___|___|
00019  * embedded.connectivity.solutions===============
00020  *
00021  * \endcode
00022  *
00023  * Description: LoRa PHY layer
00024  *
00025  * License: Revised BSD License, see LICENSE.TXT file include in the project
00026  *
00027  * Maintainer: Miguel Luis ( Semtech ), Gregory Cristian ( Semtech ) and Daniel Jaeckle ( STACKFORCE )
00028  *
00029  * Copyright (c) 2017, Arm Limited and affiliates.
00030  * SPDX-License-Identifier: BSD-3-Clause
00031  *
00032  */
00033 
00034 #ifndef LORAWAN_SYSTEM_LORAWAN_DATA_STRUCTURES_H_
00035 #define LORAWAN_SYSTEM_LORAWAN_DATA_STRUCTURES_H_
00036 
00037 #include <inttypes.h>
00038 #include "lorawan_types.h"
00039 
00040 /*!
00041  * \brief Timer time variable definition
00042  */
00043 #ifndef lorawan_time_t
00044 typedef uint32_t lorawan_time_t;
00045 #endif
00046 
00047 /*!
00048  * Sets the length of the LoRaMAC footer field.
00049  * Mainly indicates the MIC field length.
00050  */
00051 #define LORAMAC_MFR_LEN                             4
00052 
00053 /*!
00054  * The FRMPayload overhead to be used when setting the `Radio.SetMaxPayloadLength`
00055  * in the `RxWindowSetup` function.
00056  * The maximum PHYPayload = MaxPayloadOfDatarate/MaxPayloadOfDatarateRepeater + LORA_MAC_FRMPAYLOAD_OVERHEAD
00057  */
00058 #define LORA_MAC_FRMPAYLOAD_OVERHEAD                13 // MHDR(1) + FHDR(7) + Port(1) + MIC(4)
00059 
00060 /**
00061  * LoRaMac maximum number of channels
00062  */
00063 #define LORA_MAX_NB_CHANNELS                        16
00064 
00065 /**
00066  * Maximum PHY layer payload size for reception.
00067  */
00068 #define LORAMAC_PHY_MAXPAYLOAD                      255
00069 
00070 #define LORAWAN_DEFAULT_QOS                         1
00071 
00072 /**
00073  *
00074  * Default user application maximum data size for transmission
00075  */
00076 // reject if user tries to set more than MTU
00077 #if MBED_CONF_LORA_TX_MAX_SIZE > 255
00078 #warning "Cannot set TX Max size more than MTU=255"
00079 #define MBED_CONF_LORA_TX_MAX_SIZE              255
00080 #endif
00081 
00082 /*!
00083  * LoRaMAC band parameters definition.
00084  */
00085 typedef struct {
00086     /*!
00087      * The duty cycle.
00088      */
00089     uint16_t duty_cycle ;
00090     /*!
00091      * The maximum TX power.
00092      */
00093     int8_t max_tx_pwr ;
00094     /*!
00095      * The timestamp of the last Join Request TX frame.
00096      */
00097     lorawan_time_t last_join_tx_time ;
00098     /*!
00099      * The timestamp of the last TX frame.
00100      */
00101     lorawan_time_t last_tx_time ;
00102     /*!
00103      * The device off time.
00104      */
00105     lorawan_time_t off_time ;
00106     /*!
00107      * Lower band boundry
00108      */
00109     uint32_t lower_band_freq ;
00110     /*!
00111      * Higher band boundry
00112      */
00113     uint32_t higher_band_freq ;
00114 } band_t ;
00115 
00116 /*!
00117  * LoRaMAC receive window 2 channel parameters.
00118  */
00119 typedef struct {
00120     /*!
00121      * The frequency in Hz.
00122      */
00123     uint32_t frequency ;
00124     /*!
00125      * The data rate.
00126      *
00127      * LoRaWAN Regional Parameters V1.0.2rB.
00128      *
00129      * The allowed ranges are region-specific. Please refer to \ref DR_0 to \ref DR_15 for details.
00130      */
00131     uint8_t  datarate ;
00132 } rx2_channel_params ;
00133 
00134 /*!
00135  * LoRaMAC receive window enumeration
00136  */
00137 typedef enum {
00138     /*!
00139      * LoRaMAC receive window 1
00140      */
00141     RX_SLOT_WIN_1 ,
00142     /*!
00143      * LoRaMAC receive window 2
00144      */
00145     RX_SLOT_WIN_2 ,
00146     /*!
00147      * LoRaMAC receive window 2 for class c - continuous listening
00148      */
00149     RX_SLOT_WIN_CLASS_C ,
00150     /*!
00151      * LoRaMAC class b ping slot window
00152      */
00153     RX_SLOT_WIN_PING_SLOT 
00154 } rx_slot_t ;
00155 
00156 /*!
00157  * The global MAC layer parameters.
00158  */
00159 typedef struct {
00160     /*!
00161      * The TX power in channels.
00162      */
00163     int8_t channel_tx_power ;
00164     /*!
00165      * The data rate in channels.
00166      */
00167     int8_t channel_data_rate ;
00168     /*!
00169      * LoRaMac maximum time a reception window stays open.
00170      */
00171     uint32_t max_rx_win_time ;
00172     /*!
00173      * Receive delay 1.
00174      */
00175     uint32_t recv_delay1 ;
00176     /*!
00177      * Receive delay 2.
00178      */
00179     uint32_t recv_delay2 ;
00180     /*!
00181      * Join accept delay 1.
00182      */
00183     uint32_t join_accept_delay1 ;
00184     /*!
00185      * Join accept delay 1.
00186      */
00187     uint32_t join_accept_delay2 ;
00188     /*!
00189      * The number of uplink messages repetitions for QOS set by network server
00190      * in LinkADRReq mac command (unconfirmed messages only).
00191      */
00192     uint8_t nb_trans ;
00193     /*!
00194      * The datarate offset between uplink and downlink on first window.
00195      */
00196     uint8_t rx1_dr_offset ;
00197     /*!
00198      * LoRaMAC 2nd reception window settings.
00199      */
00200     rx2_channel_params  rx2_channel ;
00201     /*!
00202      * The uplink dwell time configuration. 0: No limit, 1: 400ms
00203      */
00204     uint8_t uplink_dwell_time ;
00205     /*!
00206      * The downlink dwell time configuration. 0: No limit, 1: 400ms
00207      */
00208     uint8_t downlink_dwell_time ;
00209     /*!
00210      * The maximum possible EIRP.
00211      */
00212     float max_eirp ;
00213     /*!
00214      * The antenna gain of the node.
00215      */
00216     float antenna_gain ;
00217 
00218     /*!
00219      * Maximum duty cycle
00220      * \remark Possibility to shutdown the device.
00221      */
00222     uint8_t max_duty_cycle ;
00223     /*!
00224      * Aggregated duty cycle management
00225      */
00226     uint16_t aggregated_duty_cycle ;
00227 
00228     /*!
00229      * LoRaMac ADR control status
00230      */
00231     bool adr_on ;
00232 } lora_mac_system_params_t ;
00233 
00234 /*!
00235  * LoRaMAC multicast channel parameter.
00236  */
00237 typedef struct multicast_params_s  {
00238     /*!
00239      * Address.
00240      */
00241     uint32_t address ;
00242     /*!
00243      * Network session key.
00244      */
00245     uint8_t nwk_skey [16];
00246     /*!
00247      * Application session key.
00248      */
00249     uint8_t app_skey [16];
00250     /*!
00251      * Downlink counter.
00252      */
00253     uint32_t dl_frame_counter ;
00254     /*!
00255      * A reference pointer to the next multicast channel parameters in the list.
00256      */
00257     struct multicast_params_s  *next ;
00258 } multicast_params_t ;
00259 
00260 /*!
00261  * LoRaMAC frame types.
00262  *
00263  * LoRaWAN Specification V1.0.2, chapter 4.2.1, table 1.
00264  */
00265 typedef enum {
00266     /*!
00267      * LoRaMAC join request frame.
00268      */
00269     FRAME_TYPE_JOIN_REQ               = 0x00,
00270     /*!
00271      * LoRaMAC join accept frame.
00272      */
00273     FRAME_TYPE_JOIN_ACCEPT            = 0x01,
00274     /*!
00275      * LoRaMAC unconfirmed uplink frame.
00276      */
00277     FRAME_TYPE_DATA_UNCONFIRMED_UP    = 0x02,
00278     /*!
00279      * LoRaMAC unconfirmed downlink frame.
00280      */
00281     FRAME_TYPE_DATA_UNCONFIRMED_DOWN  = 0x03,
00282     /*!
00283      * LoRaMAC confirmed uplink frame.
00284      */
00285     FRAME_TYPE_DATA_CONFIRMED_UP      = 0x04,
00286     /*!
00287      * LoRaMAC confirmed downlink frame.
00288      */
00289     FRAME_TYPE_DATA_CONFIRMED_DOWN    = 0x05,
00290     /*!
00291      * LoRaMAC RFU frame.
00292      */
00293     FRAME_TYPE_RFU                    = 0x06,
00294     /*!
00295      * LoRaMAC proprietary frame.
00296      */
00297     FRAME_TYPE_PROPRIETARY            = 0x07,
00298 } mac_frame_type_t ;
00299 
00300 /*!
00301  * LoRaMAC mote MAC commands.
00302  *
00303  * LoRaWAN Specification V1.0.2, chapter 5, table 4.
00304  */
00305 typedef enum {
00306     /*!
00307      * LinkCheckReq
00308      */
00309     MOTE_MAC_LINK_CHECK_REQ           = 0x02,
00310     /*!
00311      * LinkADRAns
00312      */
00313     MOTE_MAC_LINK_ADR_ANS             = 0x03,
00314     /*!
00315      * DutyCycleAns
00316      */
00317     MOTE_MAC_DUTY_CYCLE_ANS           = 0x04,
00318     /*!
00319      * RXParamSetupAns
00320      */
00321     MOTE_MAC_RX_PARAM_SETUP_ANS       = 0x05,
00322     /*!
00323      * DevStatusAns
00324      */
00325     MOTE_MAC_DEV_STATUS_ANS           = 0x06,
00326     /*!
00327      * NewChannelAns
00328      */
00329     MOTE_MAC_NEW_CHANNEL_ANS          = 0x07,
00330     /*!
00331      * RXTimingSetupAns
00332      */
00333     MOTE_MAC_RX_TIMING_SETUP_ANS      = 0x08,
00334     /*!
00335      * TXParamSetupAns
00336      */
00337     MOTE_MAC_TX_PARAM_SETUP_ANS       = 0x09,
00338     /*!
00339      * DlChannelAns
00340      */
00341     MOTE_MAC_DL_CHANNEL_ANS           = 0x0A
00342 } mote_mac_cmds_t ;
00343 
00344 /*!
00345  * LoRaMAC server MAC commands.
00346  *
00347  * LoRaWAN Specification V1.0.2 chapter 5, table 4.
00348  */
00349 typedef enum {
00350     /*!
00351      * LinkCheckAns
00352      */
00353     SRV_MAC_LINK_CHECK_ANS            = 0x02,
00354     /*!
00355      * LinkADRReq
00356      */
00357     SRV_MAC_LINK_ADR_REQ              = 0x03,
00358     /*!
00359      * DutyCycleReq
00360      */
00361     SRV_MAC_DUTY_CYCLE_REQ            = 0x04,
00362     /*!
00363      * RXParamSetupReq
00364      */
00365     SRV_MAC_RX_PARAM_SETUP_REQ        = 0x05,
00366     /*!
00367      * DevStatusReq
00368      */
00369     SRV_MAC_DEV_STATUS_REQ            = 0x06,
00370     /*!
00371      * NewChannelReq
00372      */
00373     SRV_MAC_NEW_CHANNEL_REQ           = 0x07,
00374     /*!
00375      * RXTimingSetupReq
00376      */
00377     SRV_MAC_RX_TIMING_SETUP_REQ       = 0x08,
00378     /*!
00379      * NewChannelReq
00380      */
00381     SRV_MAC_TX_PARAM_SETUP_REQ        = 0x09,
00382     /*!
00383      * DlChannelReq
00384      */
00385     SRV_MAC_DL_CHANNEL_REQ            = 0x0A,
00386 } server_mac_cmds_t ;
00387 
00388 /*!
00389  * LoRaMAC battery level indicator.
00390  */
00391 typedef enum {
00392     /*!
00393      * An external power source.
00394      */
00395     BAT_LEVEL_EXT_SRC                 = 0x00,
00396     /*!
00397      * Battery level empty.
00398      */
00399     BAT_LEVEL_EMPTY                   = 0x01,
00400     /*!
00401      * Battery level full.
00402      */
00403     BAT_LEVEL_FULL                    = 0xFE,
00404     /*!
00405      * Battery level - no measurement available.
00406      */
00407     BAT_LEVEL_NO_MEASURE              = 0xFF,
00408 } device_battery_level_t ;
00409 
00410 /*!
00411  * LoRaMAC header field definition (MHDR field).
00412  *
00413  * LoRaWAN Specification V1.0.2, chapter 4.2.
00414  */
00415 typedef union {
00416     /*!
00417      * Byte-access to the bits.
00418      */
00419     uint8_t value ;
00420     /*!
00421      * The structure containing single access to header bits.
00422      */
00423     struct hdr_bits_s  {
00424         /*!
00425          * Major version.
00426          */
00427         uint8_t major : 2;
00428         /*!
00429          * RFU
00430          */
00431         uint8_t RFU : 3;
00432         /*!
00433          * Message type
00434          */
00435         uint8_t mtype : 3;
00436     } bits;
00437 } loramac_mhdr_t ;
00438 
00439 /*!
00440  * LoRaMAC frame control field definition (FCtrl).
00441  *
00442  * LoRaWAN Specification V1.0.2, chapter 4.3.1.
00443  */
00444 typedef union {
00445     /*!
00446      * Byte-access to the bits.
00447      */
00448     uint8_t value ;
00449     /*!
00450      * The structure containing single access to bits.
00451      */
00452     struct ctrl_bits_s  {
00453         /*!
00454          * Frame options length.
00455          */
00456         uint8_t fopts_len : 4;
00457         /*!
00458          * Frame pending bit.
00459          */
00460         uint8_t fpending : 1;
00461         /*!
00462          * Message acknowledge bit.
00463          */
00464         uint8_t ack : 1;
00465         /*!
00466          * ADR acknowledgment request bit.
00467          */
00468         uint8_t adr_ack_req : 1;
00469         /*!
00470          * ADR control in the frame header.
00471          */
00472         uint8_t adr : 1;
00473     } bits;
00474 } loramac_frame_ctrl_t ;
00475 
00476 /*!
00477  * The enumeration containing the status of the operation of a MAC service.
00478  */
00479 typedef enum {
00480     /*!
00481      * Service performed successfully.
00482      */
00483     LORAMAC_EVENT_INFO_STATUS_OK  = 0,
00484     /*!
00485      * An error occurred during the execution of the service.
00486      */
00487     LORAMAC_EVENT_INFO_STATUS_ERROR ,
00488     /*!
00489      * A TX timeout occurred.
00490      */
00491     LORAMAC_EVENT_INFO_STATUS_TX_TIMEOUT ,
00492     /*!
00493      * An RX timeout occurred on receive window 1.
00494      */
00495     LORAMAC_EVENT_INFO_STATUS_RX1_TIMEOUT ,
00496     /*!
00497      * An RX timeout occurred on receive window 2.
00498      */
00499     LORAMAC_EVENT_INFO_STATUS_RX2_TIMEOUT ,
00500     /*!
00501      * An RX error occurred on receive window 1.
00502      */
00503     LORAMAC_EVENT_INFO_STATUS_RX1_ERROR ,
00504     /*!
00505      * An RX error occurred on receive window 2.
00506      */
00507     LORAMAC_EVENT_INFO_STATUS_RX2_ERROR ,
00508     /*!
00509      * An error occurred in the join procedure.
00510      */
00511     LORAMAC_EVENT_INFO_STATUS_JOIN_FAIL ,
00512     /*!
00513      * A frame with an invalid downlink counter was received. The
00514      * downlink counter of the frame was equal to the local copy
00515      * of the downlink counter of the node.
00516      */
00517     LORAMAC_EVENT_INFO_STATUS_DOWNLINK_REPEATED ,
00518     /*!
00519      * The MAC could not retransmit a frame since the MAC decreased the datarate. The
00520      * payload size is not applicable for the datarate.
00521      */
00522     LORAMAC_EVENT_INFO_STATUS_TX_DR_PAYLOAD_SIZE_ERROR ,
00523     /*!
00524      * The node has lost MAX_FCNT_GAP or more frames.
00525      */
00526     LORAMAC_EVENT_INFO_STATUS_DOWNLINK_TOO_MANY_FRAMES_LOST ,
00527     /*!
00528      * An address error occurred.
00529      */
00530     LORAMAC_EVENT_INFO_STATUS_ADDRESS_FAIL ,
00531     /*!
00532      * Message integrity check failure.
00533      */
00534     LORAMAC_EVENT_INFO_STATUS_MIC_FAIL ,
00535     /*!
00536      * Crypto methods failure
00537      */
00538     LORAMAC_EVENT_INFO_STATUS_CRYPTO_FAIL ,
00539 } loramac_event_info_status_t ;
00540 
00541 /*!
00542  *
00543  * \brief   LoRaMAC data services
00544  *
00545  * \details The following table list the primitives supported by a
00546  *          specific MAC data service:
00547  *
00548  * Name                  | Request | Indication | Response | Confirm
00549  * --------------------- | :-----: | :--------: | :------: | :-----:
00550  * \ref MCPS_UNCONFIRMED | YES     | YES        | NO       | YES
00551  * \ref MCPS_CONFIRMED   | YES     | YES        | NO       | YES
00552  * \ref MCPS_MULTICAST   | NO      | YES        | NO       | NO
00553  * \ref MCPS_PROPRIETARY | YES     | YES        | NO       | YES
00554  *
00555  */
00556 typedef enum {
00557     /*!
00558      * Unconfirmed LoRaMAC frame.
00559      */
00560     MCPS_UNCONFIRMED ,
00561     /*!
00562      * Confirmed LoRaMAC frame.
00563      */
00564     MCPS_CONFIRMED ,
00565     /*!
00566      * Multicast LoRaMAC frame.
00567      */
00568     MCPS_MULTICAST ,
00569     /*!
00570      * Proprietary frame.
00571      */
00572     MCPS_PROPRIETARY ,
00573 } mcps_type_t;
00574 
00575 /*!
00576  * LoRaMAC MCPS-Confirm.
00577  */
00578 typedef struct {
00579     /*!
00580      * Holds the previously performed MCPS-Request type. i.e., the type of
00581      * the MCPS request for which this confirmation is being generated
00582      */
00583     mcps_type_t req_type ;
00584     /*!
00585      * The status of the operation.
00586      */
00587     loramac_event_info_status_t  status ;
00588     /*!
00589      * The uplink datarate.
00590      */
00591     uint8_t data_rate ;
00592     /*!
00593      * The transmission power.
00594      */
00595     int8_t tx_power ;
00596     /*!
00597      * Set if an acknowledgement was received.
00598      */
00599     bool ack_received ;
00600     /*!
00601      * Provides the number of retransmissions.
00602      */
00603     uint8_t nb_retries ;
00604     /*!
00605      * The transmission time on air of the frame.
00606      */
00607     lorawan_time_t tx_toa ;
00608     /*!
00609      * The uplink counter value related to the frame.
00610      */
00611     uint32_t ul_frame_counter ;
00612     /*!
00613      * The uplink channel related to the frame.
00614      */
00615     uint32_t channel ;
00616 } loramac_mcps_confirm_t ;
00617 
00618 /*!
00619  * LoRaMAC MCPS-Indication primitive.
00620  */
00621 typedef struct {
00622     /*!
00623      * True if an MCPS indication was pending
00624      */
00625     bool pending ;
00626     /*!
00627      * MCPS-Indication type.
00628      */
00629     mcps_type_t type ;
00630     /*!
00631      * The status of the operation.
00632      */
00633     loramac_event_info_status_t  status ;
00634     /*!
00635      * Multicast.
00636      */
00637     uint8_t multicast ;
00638     /*!
00639      * The application port.
00640      */
00641     uint8_t port ;
00642     /*!
00643      * The downlink datarate.
00644      */
00645     uint8_t rx_datarate ;
00646     /*!
00647      * Frame pending status.
00648      */
00649     uint8_t fpending_status ;
00650     /*!
00651      * A pointer to the received data stream.
00652      */
00653     const uint8_t *buffer ;
00654     /*!
00655      * The size of the received data stream.
00656      */
00657     uint16_t buffer_size ;
00658     /*!
00659      * Indicates, if data is available.
00660      */
00661     bool is_data_recvd ;
00662     /*!
00663      * The RSSI of the received packet.
00664      */
00665     int16_t rssi ;
00666     /*!
00667      * The SNR of the received packet.
00668      */
00669     int8_t snr ;
00670     /*!
00671      * The receive window.
00672      *
00673      * [0: Rx window 1, 1: Rx window 2]
00674      */
00675     rx_slot_t  rx_slot ;
00676     /*!
00677      * Set if an acknowledgement was received.
00678      */
00679     bool is_ack_recvd ;
00680     /*!
00681      * The downlink counter value for the received frame.
00682      */
00683     uint32_t dl_frame_counter ;
00684     /*!
00685      * The downlink channel
00686      */
00687     uint32_t channel ;
00688     /*!
00689      * The time on air of the received frame.
00690      */
00691     lorawan_time_t rx_toa ;
00692 } loramac_mcps_indication_t ;
00693 
00694 /*!
00695  * \brief LoRaMAC management services.
00696  *
00697  * \details The following table list the primitives supported by a
00698  *          specific MAC management service:
00699  *
00700  * Name                         | Request | Indication | Response | Confirm
00701  * ---------------------------- | :-----: | :--------: | :------: | :-----:
00702  * \ref MLME_JOIN               | YES     | NO         | NO       | YES
00703  * \ref MLME_LINK_CHECK         | YES     | NO         | NO       | YES
00704  * \ref MLME_TXCW               | YES     | NO         | NO       | YES
00705  * \ref MLME_SCHEDULE_UPLINK    | NO      | YES        | NO       | NO
00706  *
00707  */
00708 typedef enum {
00709     /*!
00710      * Initiates the Over-the-Air activation.
00711      *
00712      * LoRaWAN Specification V1.0.2, chapter 6.2.
00713      */
00714     MLME_JOIN ,
00715     /*!
00716      * LinkCheckReq - Connectivity validation.
00717      *
00718      * LoRaWAN Specification V1.0.2, chapter 5, table 4.
00719      */
00720     MLME_LINK_CHECK ,
00721     /*!
00722      * Sets TX continuous wave mode.
00723      *
00724      * LoRaWAN end-device certification.
00725      */
00726     MLME_TXCW ,
00727     /*!
00728      * Sets TX continuous wave mode (new LoRa-Alliance CC definition).
00729      *
00730      * LoRaWAN end-device certification.
00731      */
00732     MLME_TXCW_1 ,
00733     /*!
00734      * Indicates that the application shall perform an uplink as
00735      * soon as possible.
00736      */
00737     MLME_SCHEDULE_UPLINK 
00738 } mlme_type_t;
00739 
00740 /*!
00741  * LoRaMAC MLME-Request for the join service.
00742  */
00743 typedef struct {
00744     /*!
00745      * A globally unique end-device identifier.
00746      *
00747      * LoRaWAN Specification V1.0.2, chapter 6.2.1.
00748      */
00749     uint8_t *dev_eui ;
00750     /*!
00751      * An application identifier.
00752      *
00753      * LoRaWAN Specification V1.0.2, chapter 6.1.2
00754      */
00755     uint8_t *app_eui ;
00756     /*!
00757      * AES-128 application key.
00758      *
00759      * LoRaWAN Specification V1.0.2, chapter 6.2.2.
00760      */
00761     uint8_t *app_key ;
00762     /*!
00763      * The number of trials for the join request.
00764      */
00765     uint8_t nb_trials ;
00766 } mlme_join_req_t ;
00767 
00768 /*!
00769  * LoRaMAC MLME-Request for TX continuous wave mode.
00770  */
00771 typedef struct {
00772     /*!
00773      * The time while the radio is kept in continuous wave mode, in seconds.
00774      */
00775     uint16_t timeout ;
00776     /*!
00777      * The RF frequency to set (only used with the new way).
00778      */
00779     uint32_t frequency ;
00780     /*!
00781      * The RF output power to set (only used with the new way).
00782      */
00783     uint8_t power ;
00784 } mlme_cw_tx_mode_t ;
00785 
00786 
00787 /*!
00788  * LoRaMAC MLME-Confirm primitive.
00789  */
00790 typedef struct {
00791     /*!
00792      * Indicates if a request is pending or not
00793      */
00794     bool pending ;
00795     /*!
00796      * The previously performed MLME-Request. i.e., the request type
00797      * for which the confirmation is being generated
00798      */
00799     mlme_type_t req_type ;
00800     /*!
00801      * The status of the operation.
00802      */
00803     loramac_event_info_status_t  status ;
00804     /*!
00805      * The transmission time on air of the frame.
00806      */
00807     lorawan_time_t tx_toa ;
00808     /*!
00809      * The demodulation margin. Contains the link margin [dB] of the last LinkCheckReq
00810      * successfully received.
00811      */
00812     uint8_t demod_margin ;
00813     /*!
00814      * The number of gateways which received the last LinkCheckReq.
00815      */
00816     uint8_t nb_gateways ;
00817     /*!
00818      * The number of retransmissions.
00819      */
00820     uint8_t nb_retries ;
00821 } loramac_mlme_confirm_t ;
00822 
00823 /*!
00824  * LoRaMAC MLME-Indication primitive
00825  */
00826 typedef struct {
00827     /*!
00828      * MLME-Indication type
00829      */
00830     mlme_type_t indication_type ;
00831     bool pending;
00832 } loramac_mlme_indication_t ;
00833 
00834 /**
00835  * End-device states.
00836  */
00837 typedef enum device_states {
00838     DEVICE_STATE_NOT_INITIALIZED,
00839     DEVICE_STATE_JOINING,
00840     DEVICE_STATE_IDLE,
00841     DEVICE_STATE_CONNECTING,
00842     DEVICE_STATE_AWAITING_JOIN_ACCEPT,
00843     DEVICE_STATE_RECEIVING,
00844     DEVICE_STATE_CONNECTED,
00845     DEVICE_STATE_SCHEDULING,
00846     DEVICE_STATE_SENDING,
00847     DEVICE_STATE_AWAITING_ACK,
00848     DEVICE_STATE_STATUS_CHECK,
00849     DEVICE_STATE_SHUTDOWN
00850 } device_states_t;
00851 
00852 /**
00853  * Stack level TX message structure
00854  */
00855 typedef struct {
00856 
00857     /**
00858      * TX Ongoing flag
00859      */
00860     bool tx_ongoing;
00861 
00862     /**
00863      * Application Port Number
00864      */
00865     uint8_t port;
00866 
00867     /**
00868      * Message type
00869      */
00870     mcps_type_t type;
00871 
00872     /*!
00873      * Frame port field. Must be set if the payload is not empty. Use the
00874      * application-specific frame port values: [1...223].
00875      *
00876      * LoRaWAN Specification V1.0.2, chapter 4.3.2.
00877      */
00878     uint8_t fport ;
00879 
00880     /*!
00881      * Uplink datarate, if ADR is off.
00882      */
00883     int8_t data_rate ;
00884     /*!
00885      *
00886      * For CONFIRMED Messages:
00887      *
00888      * The number of trials to transmit the frame, if the LoRaMAC layer did not
00889      * receive an acknowledgment. The MAC performs a datarate adaptation
00890      * according to the LoRaWAN Specification V1.0.2, chapter 18.4, as in
00891      * the following table:
00892      *
00893      * Transmission nb | Data Rate
00894      * ----------------|-----------
00895      * 1 (first)       | DR
00896      * 2               | DR
00897      * 3               | max(DR-1,0)
00898      * 4               | max(DR-1,0)
00899      * 5               | max(DR-2,0)
00900      * 6               | max(DR-2,0)
00901      * 7               | max(DR-3,0)
00902      * 8               | max(DR-3,0)
00903      *
00904      * Note that if nb_trials is set to 1 or 2, the MAC will not decrease
00905      * the datarate, if the LoRaMAC layer did not receive an acknowledgment.
00906      *
00907      * For UNCONFIRMED Messages:
00908      *
00909      * Provides a certain QOS level set by network server in LinkADRReq MAC
00910      * command. The device will transmit the given UNCONFIRMED message nb_trials
00911      * time with same frame counter until a downlink is received. Standard defined
00912      * range is 1:15. Data rates will NOT be adapted according to chapter 18.4.
00913      */
00914     uint8_t nb_trials ;
00915 
00916     /** Payload data
00917      *
00918      * Base pointer to the buffer
00919      */
00920     uint8_t f_buffer[MBED_CONF_LORA_TX_MAX_SIZE];
00921 
00922     /** Payload size.
00923      *
00924      * The size of the frame payload.
00925      */
00926     uint16_t f_buffer_size;
00927 
00928     /**
00929      * Pending data size
00930      */
00931     uint16_t pending_size;
00932 
00933 } loramac_tx_message_t;
00934 
00935 /** lora_mac_rx_message_type_t
00936  *
00937  * An enum representing a structure for RX messages.
00938  */
00939 typedef enum  {
00940     LORAMAC_RX_MLME_CONFIRM = 0,    /**< lora_mac_mlme_confirm_t */
00941     LORAMAC_RX_MCPS_CONFIRM,        /**< lora_mac_mcps_confirm_t */
00942     LORAMAC_RX_MCPS_INDICATION      /**< lora_mac_mcps_indication_t */
00943 } rx_msg_type;
00944 
00945 /** lora_mac_rx_message_by_type_t union
00946  *
00947  * A union representing a structure for RX messages.
00948  */
00949 typedef union {
00950     loramac_mlme_confirm_t  mlme_confirm;
00951     loramac_mcps_confirm_t  mcps_confirm;
00952     loramac_mcps_indication_t  mcps_indication;
00953 } rx_message_u;
00954 
00955 /** loramac_rx_message_t
00956  *
00957  * A structure representing a structure for an RX message.
00958  */
00959 typedef struct {
00960     bool receive_ready;
00961     rx_msg_type type;
00962     rx_message_u msg;
00963     uint16_t pending_size;
00964     uint16_t prev_read_size;
00965 } loramac_rx_message_t;
00966 
00967 /** LoRaWAN session
00968  *
00969  * A structure for keeping session details.
00970  */
00971 typedef struct lorawan_session {
00972     /**
00973      * True if the session is active
00974      */
00975     bool active;
00976 
00977     /*!
00978      * Select the connection type, either LORAWAN_CONNECTION_OTAA
00979      * or LORAWAN_CONNECTION_ABP.
00980      */
00981     uint8_t connect_type ;
00982 
00983     /**
00984      * LoRaWAN uplink counter
00985      */
00986     uint32_t uplink_counter;
00987     /**
00988      * LoRaWAN downlink counter
00989      */
00990     uint32_t downlink_counter;
00991 } lorawan_session_t;
00992 
00993 /*!
00994  * The parameter structure for the function for regional rx configuration.
00995  */
00996 typedef struct {
00997     /*!
00998      * Type of modulation used (LoRa or FSK)
00999      */
01000     uint8_t modem_type ;
01001     /*!
01002      * The RX channel.
01003      */
01004     uint8_t channel ;
01005     /*!
01006      * The RX datarate index.
01007      */
01008     uint8_t datarate ;
01009     /*!
01010      * The RX bandwidth.
01011      */
01012     uint8_t bandwidth ;
01013     /*!
01014      * The RX datarate offset.
01015      */
01016     int8_t dr_offset ;
01017     /*!
01018      * The RX frequency.
01019      */
01020     uint32_t frequency ;
01021     /*!
01022      * The RX window timeout - Symbols
01023      */
01024     uint32_t window_timeout ;
01025     /*!
01026      * The RX window timeout - Milliseconds
01027      */
01028     uint32_t window_timeout_ms ;
01029     /*!
01030      * The RX window offset
01031      */
01032     int32_t window_offset ;
01033     /*!
01034      * The downlink dwell time.
01035      */
01036     uint8_t dl_dwell_time ;
01037     /*!
01038      * Set to true, if a repeater is supported.
01039      */
01040     bool is_repeater_supported ;
01041     /*!
01042      * Set to true, if RX should be continuous.
01043      */
01044     bool is_rx_continuous ;
01045     /*!
01046      * Sets the RX window.
01047      */
01048     rx_slot_t  rx_slot ;
01049 } rx_config_params_t ;
01050 
01051 /*!
01052  * \brief Timer object description
01053  */
01054 typedef struct {
01055     mbed::Callback<void()> callback;
01056     int timer_id;
01057 } timer_event_t;
01058 
01059 /*!
01060  * A composite structure containing device identifiers and security keys
01061  */
01062 typedef struct {
01063     /*!
01064      * Device IEEE EUI
01065      */
01066     uint8_t *dev_eui ;
01067 
01068     /*!
01069      * Application IEEE EUI
01070      */
01071     uint8_t *app_eui ;
01072 
01073     /*!
01074      * AES encryption/decryption cipher application key
01075      */
01076     uint8_t *app_key ;
01077 
01078     /*!
01079      * AES encryption/decryption cipher network session key
01080      * NOTE! LoRaMac determines the length of the key based on sizeof this variable
01081      */
01082     uint8_t nwk_skey[16];
01083 
01084     /*!
01085      * AES encryption/decryption cipher application session key
01086      * NOTE! LoRaMac determines the length of the key based on sizeof this variable
01087      */
01088     uint8_t app_skey[16];
01089 
01090 } loramac_keys ;
01091 
01092 /*!
01093  * A composite structure containing all the timers used in the LoRaWAN operation
01094  */
01095 typedef struct {
01096     /*!
01097      * Aggregated duty cycle management
01098      */
01099     lorawan_time_t aggregated_last_tx_time ;
01100     lorawan_time_t aggregated_timeoff;
01101 
01102     /*!
01103      * Stores the time at LoRaMac initialization.
01104      *
01105      * \remark Used for the BACKOFF_DC computation.
01106      */
01107     lorawan_time_t mac_init_time ;
01108 
01109     /*!
01110      * Last transmission time on air
01111      */
01112     lorawan_time_t tx_toa ;
01113 
01114     /*!
01115      * LoRaMac duty cycle backoff timer
01116      */
01117     timer_event_t backoff_timer ;
01118 
01119     /*!
01120      * LoRaMac reception windows timers
01121      */
01122     timer_event_t rx_window1_timer ;
01123     timer_event_t rx_window2_timer;
01124 
01125     /*!
01126      * Acknowledge timeout timer. Used for packet retransmissions.
01127      */
01128     timer_event_t ack_timeout_timer ;
01129 
01130 } lorawan_timers ;
01131 
01132 /*!
01133  * Global MAC layer configuration parameters
01134  */
01135 typedef struct {
01136 
01137     /*!
01138      * Holds the type of current Receive window slot
01139      */
01140     rx_slot_t  rx_slot ;
01141 
01142     /*!
01143      * Indicates if the node is connected to a private or public network
01144      */
01145     bool is_nwk_public ;
01146 
01147     /*!
01148      * Indicates if the node supports repeaters
01149      */
01150     bool is_repeater_supported ;
01151 
01152     /*!
01153      * Used for test purposes. Disables the opening of the reception windows.
01154      */
01155     bool is_rx_window_enabled ;
01156 
01157     /*!
01158      * Indicates if the MAC layer has already joined a network.
01159      */
01160     bool is_nwk_joined ;
01161 
01162     /*!
01163      * If the node has sent a FRAME_TYPE_DATA_CONFIRMED_UP this variable indicates
01164      * if the nodes needs to manage the server acknowledgement.
01165      */
01166     bool is_node_ack_requested ;
01167 
01168     /*!
01169      * If the server has sent a FRAME_TYPE_DATA_CONFIRMED_DOWN this variable indicates
01170      * if the ACK bit must be set for the next transmission
01171      */
01172     bool is_srv_ack_requested ;
01173 
01174     /*!
01175      * Enables/Disables duty cycle management (Test only)
01176      */
01177     bool is_dutycycle_on ;
01178 
01179     /*!
01180      * Set to true, if the last uplink was a join request
01181      */
01182     bool is_last_tx_join_request ;
01183 
01184     /*!
01185      * Indicates if the AckTimeout timer has expired or not
01186      */
01187     bool is_ack_retry_timeout_expired ;
01188 
01189     /*!
01190      * Current channel index
01191      */
01192     uint8_t channel ;
01193 
01194     /*!
01195      * Current channel index
01196      */
01197     uint8_t last_channel_idx ;
01198 
01199     /*!
01200      * Uplink messages repetitions counter
01201      */
01202     uint8_t ul_nb_rep_counter ;
01203 
01204     /*!
01205      * TX buffer used for encrypted outgoing frames
01206      */
01207     uint8_t tx_buffer[LORAMAC_PHY_MAXPAYLOAD];
01208 
01209     /*!
01210      * Length of TX buffer
01211      */
01212     uint16_t tx_buffer_len ;
01213 
01214     /*!
01215      * Used for storing decrypted RX data.
01216      */
01217     uint8_t rx_buffer[LORAMAC_PHY_MAXPAYLOAD];
01218 
01219     /*!
01220      * Length of the RX buffer
01221      */
01222     uint8_t rx_buffer_len ;
01223 
01224     /*!
01225      * Number of trials to get a frame acknowledged
01226      */
01227     uint8_t max_ack_timeout_retries ;
01228 
01229     /*!
01230      * Number of trials to get a frame acknowledged
01231      */
01232     uint8_t ack_timeout_retry_counter ;
01233 
01234     /*!
01235      * Maximum number of trials for the Join Request
01236      */
01237     uint8_t max_join_request_trials ;
01238 
01239     /*!
01240      * Number of trials for the Join Request
01241      */
01242     uint8_t join_request_trial_counter ;
01243 
01244     /*!
01245      * Mac keys
01246      */
01247     loramac_keys  keys ;
01248 
01249     /*!
01250      * Device nonce is a random value extracted by issuing a sequence of RSSI
01251      * measurements
01252      */
01253     uint16_t dev_nonce ;
01254 
01255     /*!
01256      * Network ID ( 3 bytes )
01257      */
01258     uint32_t net_id ;
01259 
01260     /*!
01261      * Mote Address
01262      */
01263     uint32_t dev_addr ;
01264 
01265     /*!
01266      * LoRaMAC frame counter. Each time a packet is sent the counter is incremented.
01267      * Only the 16 LSB bits are sent
01268      */
01269     uint32_t ul_frame_counter ;
01270 
01271     /*!
01272      * LoRaMAC frame counter. Each time a packet is received the counter is incremented.
01273      * Only the 16 LSB bits are received
01274      */
01275     uint32_t dl_frame_counter ;
01276 
01277     /*!
01278      * Counts the number of missed ADR acknowledgements
01279      */
01280     uint32_t adr_ack_counter ;
01281 
01282     /*!
01283      * LoRaMac reception windows delay
01284      * \remark normal frame: RxWindowXDelay = ReceiveDelayX - Offset
01285      *         join frame  : RxWindowXDelay = JoinAcceptDelayX - Offset
01286      */
01287     uint32_t rx_window1_delay ;
01288     uint32_t rx_window2_delay;
01289 
01290     /*!
01291      * Timer objects and stored values
01292      */
01293     lorawan_timers  timers ;
01294 
01295     /*!
01296      * LoRaMac parameters
01297      */
01298     lora_mac_system_params_t  sys_params ;
01299 
01300     /*!
01301      * Receive Window configurations for PHY layer
01302      */
01303     rx_config_params_t  rx_window1_config ;
01304     rx_config_params_t  rx_window2_config;
01305 
01306     /*!
01307      * Multicast channels linked list
01308      */
01309     multicast_params_t  *multicast_channels ;
01310 
01311 } loramac_protocol_params ;
01312 
01313 #endif /* LORAWAN_SYSTEM_LORAWAN_DATA_STRUCTURES_H_ */