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