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          * Major version.
00437          */
00438         uint8_t major : 2;
00439         /*!
00440          * RFU
00441          */
00442         uint8_t RFU : 3;
00443         /*!
00444          * Message type
00445          */
00446         uint8_t mtype : 3;
00447     } bits;
00448 } loramac_mhdr_t ;
00449 
00450 /*!
00451  * LoRaMAC frame control field definition (FCtrl).
00452  *
00453  * LoRaWAN Specification V1.0.2, chapter 4.3.1.
00454  */
00455 typedef union {
00456     /*!
00457      * Byte-access to the bits.
00458      */
00459     uint8_t value ;
00460     /*!
00461      * The structure containing single access to bits.
00462      */
00463     struct ctrl_bits_s  {
00464         /*!
00465          * Frame options length.
00466          */
00467         uint8_t fopts_len : 4;
00468         /*!
00469          * Frame pending bit.
00470          */
00471         uint8_t fpending : 1;
00472         /*!
00473          * Message acknowledge bit.
00474          */
00475         uint8_t ack : 1;
00476         /*!
00477          * ADR acknowledgment request bit.
00478          */
00479         uint8_t adr_ack_req : 1;
00480         /*!
00481          * ADR control in the frame header.
00482          */
00483         uint8_t adr : 1;
00484     } bits;
00485 } loramac_frame_ctrl_t ;
00486 
00487 /*!
00488  * The enumeration containing the status of the operation of a MAC service.
00489  */
00490 typedef enum {
00491     /*!
00492      * Service performed successfully.
00493      */
00494     LORAMAC_EVENT_INFO_STATUS_OK  = 0,
00495     /*!
00496      * An error occurred during the execution of the service.
00497      */
00498     LORAMAC_EVENT_INFO_STATUS_ERROR ,
00499     /*!
00500      * A TX timeout occurred.
00501      */
00502     LORAMAC_EVENT_INFO_STATUS_TX_TIMEOUT ,
00503     /*!
00504      * An RX timeout occurred on receive window 1.
00505      */
00506     LORAMAC_EVENT_INFO_STATUS_RX1_TIMEOUT ,
00507     /*!
00508      * An RX timeout occurred on receive window 2.
00509      */
00510     LORAMAC_EVENT_INFO_STATUS_RX2_TIMEOUT ,
00511     /*!
00512      * An RX error occurred on receive window 1.
00513      */
00514     LORAMAC_EVENT_INFO_STATUS_RX1_ERROR ,
00515     /*!
00516      * An RX error occurred on receive window 2.
00517      */
00518     LORAMAC_EVENT_INFO_STATUS_RX2_ERROR ,
00519     /*!
00520      * An error occurred in the join procedure.
00521      */
00522     LORAMAC_EVENT_INFO_STATUS_JOIN_FAIL ,
00523     /*!
00524      * A frame with an invalid downlink counter was received. The
00525      * downlink counter of the frame was equal to the local copy
00526      * of the downlink counter of the node.
00527      */
00528     LORAMAC_EVENT_INFO_STATUS_DOWNLINK_REPEATED ,
00529     /*!
00530      * The MAC could not retransmit a frame since the MAC decreased the datarate. The
00531      * payload size is not applicable for the datarate.
00532      */
00533     LORAMAC_EVENT_INFO_STATUS_TX_DR_PAYLOAD_SIZE_ERROR ,
00534     /*!
00535      * The node has lost MAX_FCNT_GAP or more frames.
00536      */
00537     LORAMAC_EVENT_INFO_STATUS_DOWNLINK_TOO_MANY_FRAMES_LOST ,
00538     /*!
00539      * An address error occurred.
00540      */
00541     LORAMAC_EVENT_INFO_STATUS_ADDRESS_FAIL ,
00542     /*!
00543      * Message integrity check failure.
00544      */
00545     LORAMAC_EVENT_INFO_STATUS_MIC_FAIL ,
00546     /*!
00547      * Crypto methods failure
00548      */
00549     LORAMAC_EVENT_INFO_STATUS_CRYPTO_FAIL ,
00550 } loramac_event_info_status_t ;
00551 
00552 /*!
00553  *
00554  * \brief   LoRaMAC data services
00555  *
00556  * \details The following table list the primitives supported by a
00557  *          specific MAC data service:
00558  *
00559  * Name                  | Request | Indication | Response | Confirm
00560  * --------------------- | :-----: | :--------: | :------: | :-----:
00561  * \ref MCPS_UNCONFIRMED | YES     | YES        | NO       | YES
00562  * \ref MCPS_CONFIRMED   | YES     | YES        | NO       | YES
00563  * \ref MCPS_MULTICAST   | NO      | YES        | NO       | NO
00564  * \ref MCPS_PROPRIETARY | YES     | YES        | NO       | YES
00565  *
00566  */
00567 typedef enum {
00568     /*!
00569      * Unconfirmed LoRaMAC frame.
00570      */
00571     MCPS_UNCONFIRMED ,
00572     /*!
00573      * Confirmed LoRaMAC frame.
00574      */
00575     MCPS_CONFIRMED ,
00576     /*!
00577      * Multicast LoRaMAC frame.
00578      */
00579     MCPS_MULTICAST ,
00580     /*!
00581      * Proprietary frame.
00582      */
00583     MCPS_PROPRIETARY ,
00584 } mcps_type_t;
00585 
00586 /*!
00587  * LoRaMAC MCPS-Confirm.
00588  */
00589 typedef struct {
00590     /*!
00591      * Holds the previously performed MCPS-Request type. i.e., the type of
00592      * the MCPS request for which this confirmation is being generated
00593      */
00594     mcps_type_t req_type ;
00595     /*!
00596      * The status of the operation.
00597      */
00598     loramac_event_info_status_t  status ;
00599     /*!
00600      * The uplink datarate.
00601      */
00602     uint8_t data_rate ;
00603     /*!
00604      * The transmission power.
00605      */
00606     int8_t tx_power ;
00607     /*!
00608      * Set if an acknowledgement was received.
00609      */
00610     bool ack_received ;
00611     /*!
00612      * Provides the number of retransmissions.
00613      */
00614     uint8_t nb_retries ;
00615     /*!
00616      * The transmission time on air of the frame.
00617      */
00618     lorawan_time_t tx_toa ;
00619     /*!
00620      * The uplink counter value related to the frame.
00621      */
00622     uint32_t ul_frame_counter ;
00623     /*!
00624      * The uplink channel related to the frame.
00625      */
00626     uint32_t channel ;
00627 } loramac_mcps_confirm_t ;
00628 
00629 /*!
00630  * LoRaMAC MCPS-Indication primitive.
00631  */
00632 typedef struct {
00633     /*!
00634      * True if an MCPS indication was pending
00635      */
00636     bool pending ;
00637     /*!
00638      * MCPS-Indication type.
00639      */
00640     mcps_type_t type ;
00641     /*!
00642      * The status of the operation.
00643      */
00644     loramac_event_info_status_t  status ;
00645     /*!
00646      * Multicast.
00647      */
00648     uint8_t multicast ;
00649     /*!
00650      * The application port.
00651      */
00652     uint8_t port ;
00653     /*!
00654      * The downlink datarate.
00655      */
00656     uint8_t rx_datarate ;
00657     /*!
00658      * Frame pending status.
00659      */
00660     uint8_t fpending_status ;
00661     /*!
00662      * A pointer to the received data stream.
00663      */
00664     const uint8_t *buffer ;
00665     /*!
00666      * The size of the received data stream.
00667      */
00668     uint16_t buffer_size ;
00669     /*!
00670      * Indicates, if data is available.
00671      */
00672     bool is_data_recvd ;
00673     /*!
00674      * The RSSI of the received packet.
00675      */
00676     int16_t rssi ;
00677     /*!
00678      * The SNR of the received packet.
00679      */
00680     uint8_t snr ;
00681     /*!
00682      * The receive window.
00683      *
00684      * [0: Rx window 1, 1: Rx window 2]
00685      */
00686     rx_slot_t  rx_slot ;
00687     /*!
00688      * Set if an acknowledgement was received.
00689      */
00690     bool is_ack_recvd ;
00691     /*!
00692      * The downlink counter value for the received frame.
00693      */
00694     uint32_t dl_frame_counter ;
00695 } loramac_mcps_indication_t ;
00696 
00697 /*!
00698  * \brief LoRaMAC management services.
00699  *
00700  * \details The following table list the primitives supported by a
00701  *          specific MAC management service:
00702  *
00703  * Name                         | Request | Indication | Response | Confirm
00704  * ---------------------------- | :-----: | :--------: | :------: | :-----:
00705  * \ref MLME_JOIN               | YES     | NO         | NO       | YES
00706  * \ref MLME_LINK_CHECK         | YES     | NO         | NO       | YES
00707  * \ref MLME_TXCW               | YES     | NO         | NO       | YES
00708  * \ref MLME_SCHEDULE_UPLINK    | NO      | YES        | NO       | NO
00709  *
00710  */
00711 typedef enum {
00712     /*!
00713      * Initiates the Over-the-Air activation.
00714      *
00715      * LoRaWAN Specification V1.0.2, chapter 6.2.
00716      */
00717     MLME_JOIN ,
00718     /*!
00719      * LinkCheckReq - Connectivity validation.
00720      *
00721      * LoRaWAN Specification V1.0.2, chapter 5, table 4.
00722      */
00723     MLME_LINK_CHECK ,
00724     /*!
00725      * Sets TX continuous wave mode.
00726      *
00727      * LoRaWAN end-device certification.
00728      */
00729     MLME_TXCW ,
00730     /*!
00731      * Sets TX continuous wave mode (new LoRa-Alliance CC definition).
00732      *
00733      * LoRaWAN end-device certification.
00734      */
00735     MLME_TXCW_1 ,
00736     /*!
00737      * Indicates that the application shall perform an uplink as
00738      * soon as possible.
00739      */
00740     MLME_SCHEDULE_UPLINK 
00741 } mlme_type_t;
00742 
00743 /*!
00744  * LoRaMAC MLME-Request for the join service.
00745  */
00746 typedef struct {
00747     /*!
00748      * A globally unique end-device identifier.
00749      *
00750      * LoRaWAN Specification V1.0.2, chapter 6.2.1.
00751      */
00752     uint8_t *dev_eui ;
00753     /*!
00754      * An application identifier.
00755      *
00756      * LoRaWAN Specification V1.0.2, chapter 6.1.2
00757      */
00758     uint8_t *app_eui ;
00759     /*!
00760      * AES-128 application key.
00761      *
00762      * LoRaWAN Specification V1.0.2, chapter 6.2.2.
00763      */
00764     uint8_t *app_key ;
00765     /*!
00766      * The number of trials for the join request.
00767      */
00768     uint8_t nb_trials ;
00769 } mlme_join_req_t ;
00770 
00771 /*!
00772  * LoRaMAC MLME-Request for TX continuous wave mode.
00773  */
00774 typedef struct {
00775     /*!
00776      * The time while the radio is kept in continuous wave mode, in seconds.
00777      */
00778     uint16_t timeout ;
00779     /*!
00780      * The RF frequency to set (only used with the new way).
00781      */
00782     uint32_t frequency ;
00783     /*!
00784      * The RF output power to set (only used with the new way).
00785      */
00786     uint8_t power ;
00787 } mlme_cw_tx_mode_t ;
00788 
00789 
00790 /*!
00791  * LoRaMAC MLME-Confirm primitive.
00792  */
00793 typedef struct {
00794     /*!
00795      * Indicates if a request is pending or not
00796      */
00797     bool pending ;
00798     /*!
00799      * The previously performed MLME-Request. i.e., the request type
00800      * for which the confirmation is being generated
00801      */
00802     mlme_type_t req_type ;
00803     /*!
00804      * The status of the operation.
00805      */
00806     loramac_event_info_status_t  status ;
00807     /*!
00808      * The transmission time on air of the frame.
00809      */
00810     lorawan_time_t tx_toa ;
00811     /*!
00812      * The demodulation margin. Contains the link margin [dB] of the last LinkCheckReq
00813      * successfully received.
00814      */
00815     uint8_t demod_margin ;
00816     /*!
00817      * The number of gateways which received the last LinkCheckReq.
00818      */
00819     uint8_t nb_gateways ;
00820     /*!
00821      * The number of retransmissions.
00822      */
00823     uint8_t nb_retries ;
00824 } loramac_mlme_confirm_t ;
00825 
00826 /*!
00827  * LoRaMAC MLME-Indication primitive
00828  */
00829 typedef struct {
00830     /*!
00831      * MLME-Indication type
00832      */
00833     mlme_type_t indication_type ;
00834     bool pending;
00835 } loramac_mlme_indication_t ;
00836 
00837 /**
00838  * End-device states.
00839  */
00840 typedef enum device_states {
00841     DEVICE_STATE_NOT_INITIALIZED,
00842     DEVICE_STATE_JOINING,
00843     DEVICE_STATE_IDLE,
00844     DEVICE_STATE_CONNECTING,
00845     DEVICE_STATE_AWAITING_JOIN_ACCEPT,
00846     DEVICE_STATE_RECEIVING,
00847     DEVICE_STATE_CONNECTED,
00848     DEVICE_STATE_SCHEDULING,
00849     DEVICE_STATE_SENDING,
00850     DEVICE_STATE_AWAITING_ACK,
00851     DEVICE_STATE_STATUS_CHECK,
00852 #if defined(LORAWAN_COMPLIANCE_TEST)
00853     DEVICE_STATE_COMPLIANCE_TEST,
00854 #endif
00855     DEVICE_STATE_SHUTDOWN
00856 } device_states_t;
00857 
00858 /**
00859  * Stack level TX message structure
00860  */
00861 typedef struct {
00862 
00863     /**
00864      * TX Ongoing flag
00865      */
00866     bool tx_ongoing;
00867 
00868     /**
00869      * Application Port Number
00870      */
00871     uint8_t port;
00872 
00873     /**
00874      * Message type
00875      */
00876     mcps_type_t type;
00877 
00878     /*!
00879      * Frame port field. Must be set if the payload is not empty. Use the
00880      * application-specific frame port values: [1...223].
00881      *
00882      * LoRaWAN Specification V1.0.2, chapter 4.3.2.
00883      */
00884     uint8_t fport ;
00885 
00886     /*!
00887      * Uplink datarate, if ADR is off.
00888      */
00889     int8_t data_rate ;
00890     /*!
00891      * The number of trials to transmit the frame, if the LoRaMAC layer did not
00892      * receive an acknowledgment. The MAC performs a datarate adaptation
00893      * according to the LoRaWAN Specification V1.0.2, chapter 18.4, as in
00894      * the following table:
00895      *
00896      * Transmission nb | Data Rate
00897      * ----------------|-----------
00898      * 1 (first)       | DR
00899      * 2               | DR
00900      * 3               | max(DR-1,0)
00901      * 4               | max(DR-1,0)
00902      * 5               | max(DR-2,0)
00903      * 6               | max(DR-2,0)
00904      * 7               | max(DR-3,0)
00905      * 8               | max(DR-3,0)
00906      *
00907      * Note that if nb_trials is set to 1 or 2, the MAC will not decrease
00908      * the datarate, if the LoRaMAC layer did not receive an acknowledgment.
00909      */
00910     uint8_t nb_trials ;
00911 
00912     /** Payload data
00913      *
00914      * Base pointer to the buffer
00915      */
00916     uint8_t f_buffer[MBED_CONF_LORA_TX_MAX_SIZE];
00917 
00918     /** Payload size.
00919      *
00920      * The size of the frame payload.
00921      */
00922     uint16_t f_buffer_size;
00923 
00924     /**
00925      * Pending data size
00926      */
00927     uint16_t pending_size;
00928 
00929 } loramac_tx_message_t;
00930 
00931 /** lora_mac_rx_message_type_t
00932  *
00933  * An enum representing a structure for RX messages.
00934  */
00935 typedef enum  {
00936     LORAMAC_RX_MLME_CONFIRM = 0,    /**< lora_mac_mlme_confirm_t */
00937     LORAMAC_RX_MCPS_CONFIRM,        /**< lora_mac_mcps_confirm_t */
00938     LORAMAC_RX_MCPS_INDICATION      /**< lora_mac_mcps_indication_t */
00939 } rx_msg_type;
00940 
00941 /** lora_mac_rx_message_by_type_t union
00942  *
00943  * A union representing a structure for RX messages.
00944  */
00945 typedef union {
00946     loramac_mlme_confirm_t  mlme_confirm;
00947     loramac_mcps_confirm_t  mcps_confirm;
00948     loramac_mcps_indication_t  mcps_indication;
00949 } rx_message_u;
00950 
00951 /** loramac_rx_message_t
00952  *
00953  * A structure representing a structure for an RX message.
00954  */
00955 typedef struct {
00956     bool receive_ready;
00957     rx_msg_type type;
00958     rx_message_u msg;
00959     uint16_t pending_size;
00960     uint16_t prev_read_size;
00961 } loramac_rx_message_t;
00962 
00963 /** LoRaWAN session
00964  *
00965  * A structure for keeping session details.
00966  */
00967 typedef struct lorawan_session {
00968     /**
00969      * True if the session is active
00970      */
00971     bool active;
00972 
00973     /*!
00974      * Select the connection type, either LORAWAN_CONNECTION_OTAA
00975      * or LORAWAN_CONNECTION_ABP.
00976      */
00977     uint8_t connect_type ;
00978 
00979     /**
00980      * LoRaWAN uplink counter
00981      */
00982     uint32_t uplink_counter;
00983     /**
00984      * LoRaWAN downlink counter
00985      */
00986     uint32_t downlink_counter;
00987 } lorawan_session_t;
00988 
00989 /*!
00990  * The parameter structure for the function for regional rx configuration.
00991  */
00992 typedef struct {
00993     /*!
00994      * The RX channel.
00995      */
00996     uint8_t channel ;
00997     /*!
00998      * The RX datarate index.
00999      */
01000     uint8_t datarate ;
01001     /*!
01002      * The RX bandwidth.
01003      */
01004     uint8_t bandwidth ;
01005     /*!
01006      * The RX datarate offset.
01007      */
01008     int8_t dr_offset ;
01009     /*!
01010      * The RX frequency.
01011      */
01012     uint32_t frequency ;
01013     /*!
01014      * The RX window timeout
01015      */
01016     uint32_t window_timeout ;
01017     /*!
01018      * The RX window offset
01019      */
01020     int32_t window_offset ;
01021     /*!
01022      * The downlink dwell time.
01023      */
01024     uint8_t dl_dwell_time ;
01025     /*!
01026      * Set to true, if a repeater is supported.
01027      */
01028     bool is_repeater_supported ;
01029     /*!
01030      * Set to true, if RX should be continuous.
01031      */
01032     bool is_rx_continuous ;
01033     /*!
01034      * Sets the RX window.
01035      */
01036     rx_slot_t  rx_slot ;
01037 } rx_config_params_t ;
01038 
01039 /*!
01040  * \brief Timer object description
01041  */
01042 typedef struct {
01043     mbed::Callback<void()> callback;
01044     int timer_id;
01045 } timer_event_t;
01046 
01047 typedef struct {
01048     /*!
01049      * Device IEEE EUI
01050      */
01051     uint8_t *dev_eui;
01052 
01053     /*!
01054      * Application IEEE EUI
01055      */
01056     uint8_t *app_eui;
01057 
01058     /*!
01059      * AES encryption/decryption cipher application key
01060      */
01061     uint8_t *app_key;
01062 
01063     /*!
01064      * AES encryption/decryption cipher network session key
01065      * NOTE! LoRaMac determines the length of the key based on sizeof this variable
01066      */
01067     uint8_t nwk_skey[16];
01068 
01069     /*!
01070      * AES encryption/decryption cipher application session key
01071      * NOTE! LoRaMac determines the length of the key based on sizeof this variable
01072      */
01073     uint8_t app_skey[16];
01074 
01075 } loramac_keys;
01076 
01077 typedef struct {
01078     /*!
01079      * Aggregated duty cycle management
01080      */
01081     lorawan_time_t aggregated_last_tx_time;
01082     lorawan_time_t aggregated_timeoff;
01083 
01084     /*!
01085      * Stores the time at LoRaMac initialization.
01086      *
01087      * \remark Used for the BACKOFF_DC computation.
01088      */
01089     lorawan_time_t mac_init_time;
01090 
01091     /*!
01092      * Last transmission time on air
01093      */
01094     lorawan_time_t tx_toa;
01095 
01096     /*!
01097      * LoRaMac duty cycle backoff timer
01098      */
01099     timer_event_t backoff_timer;
01100 
01101     /*!
01102      * LoRaMac reception windows timers
01103      */
01104     timer_event_t rx_window1_timer;
01105     timer_event_t rx_window2_timer;
01106 
01107     /*!
01108      * Acknowledge timeout timer. Used for packet retransmissions.
01109      */
01110     timer_event_t ack_timeout_timer;
01111 
01112 } lorawan_timers;
01113 
01114 typedef struct {
01115 
01116     /*!
01117      * Holds the type of current Receive window slot
01118      */
01119     rx_slot_t  rx_slot;
01120 
01121     /*!
01122      * Indicates if the node is connected to a private or public network
01123      */
01124     bool is_nwk_public;
01125 
01126     /*!
01127      * Indicates if the node supports repeaters
01128      */
01129     bool is_repeater_supported;
01130 
01131     /*!
01132      * IsPacketCounterFixed enables the MIC field tests by fixing the
01133      * ul_frame_counter value
01134      */
01135     bool is_ul_frame_counter_fixed;
01136 
01137     /*!
01138      * Used for test purposes. Disables the opening of the reception windows.
01139      */
01140     bool is_rx_window_enabled;
01141 
01142     /*!
01143      * Indicates if the MAC layer has already joined a network.
01144      */
01145     bool is_nwk_joined;
01146 
01147     /*!
01148      * If the node has sent a FRAME_TYPE_DATA_CONFIRMED_UP this variable indicates
01149      * if the nodes needs to manage the server acknowledgement.
01150      */
01151     bool is_node_ack_requested;
01152 
01153     /*!
01154      * If the server has sent a FRAME_TYPE_DATA_CONFIRMED_DOWN this variable indicates
01155      * if the ACK bit must be set for the next transmission
01156      */
01157     bool is_srv_ack_requested;
01158 
01159     /*!
01160      * Enables/Disables duty cycle management (Test only)
01161      */
01162     bool is_dutycycle_on;
01163 
01164     /*!
01165      * Set to true, if the last uplink was a join request
01166      */
01167     bool is_last_tx_join_request;
01168 
01169     /*!
01170      * Indicates if the AckTimeout timer has expired or not
01171      */
01172     bool is_ack_retry_timeout_expired;
01173 
01174     /*!
01175      * Current channel index
01176      */
01177     uint8_t channel;
01178 
01179     /*!
01180      * Current channel index
01181      */
01182     uint8_t last_channel_idx;
01183 
01184     /*!
01185      * Uplink messages repetitions counter
01186      */
01187     uint8_t ul_nb_rep_counter;
01188 
01189     /*!
01190      * TX buffer used for encrypted outgoing frames
01191      */
01192     uint8_t tx_buffer[LORAMAC_PHY_MAXPAYLOAD];
01193 
01194     /*!
01195      * Length of TX buffer
01196      */
01197     uint16_t tx_buffer_len;
01198 
01199     /*!
01200      * Used for storing decrypted RX data.
01201      */
01202     uint8_t rx_buffer[LORAMAC_PHY_MAXPAYLOAD];
01203 
01204     /*!
01205      * Length of the RX buffer
01206      */
01207     uint8_t rx_buffer_len;
01208 
01209     /*!
01210      * Number of trials to get a frame acknowledged
01211      */
01212     uint8_t max_ack_timeout_retries;
01213 
01214     /*!
01215      * Number of trials to get a frame acknowledged
01216      */
01217     uint8_t ack_timeout_retry_counter;
01218 
01219     /*!
01220      * Maximum number of trials for the Join Request
01221      */
01222     uint8_t max_join_request_trials;
01223 
01224     /*!
01225      * Number of trials for the Join Request
01226      */
01227     uint8_t join_request_trial_counter;
01228 
01229     /*!
01230      * Mac keys
01231      */
01232     loramac_keys keys;
01233 
01234     /*!
01235      * Device nonce is a random value extracted by issuing a sequence of RSSI
01236      * measurements
01237      */
01238     uint16_t dev_nonce;
01239 
01240     /*!
01241      * Network ID ( 3 bytes )
01242      */
01243     uint32_t net_id;
01244 
01245     /*!
01246      * Mote Address
01247      */
01248     uint32_t dev_addr;
01249 
01250     /*!
01251      * LoRaMAC frame counter. Each time a packet is sent the counter is incremented.
01252      * Only the 16 LSB bits are sent
01253      */
01254     uint32_t ul_frame_counter;
01255 
01256     /*!
01257      * LoRaMAC frame counter. Each time a packet is received the counter is incremented.
01258      * Only the 16 LSB bits are received
01259      */
01260     uint32_t dl_frame_counter;
01261 
01262     /*!
01263      * Counts the number of missed ADR acknowledgements
01264      */
01265     uint32_t adr_ack_counter;
01266 
01267     /*!
01268      * LoRaMac reception windows delay
01269      * \remark normal frame: RxWindowXDelay = ReceiveDelayX - RADIO_WAKEUP_TIME
01270      *         join frame  : RxWindowXDelay = JoinAcceptDelayX - RADIO_WAKEUP_TIME
01271      */
01272     uint32_t rx_window1_delay;
01273     uint32_t rx_window2_delay;
01274 
01275     /*!
01276      * Timer objects and stored values
01277      */
01278     lorawan_timers timers;
01279 
01280     /*!
01281      * LoRaMac parameters
01282      */
01283     lora_mac_system_params_t  sys_params;
01284 
01285     /*!
01286      * Receive Window configurations for PHY layer
01287      */
01288     rx_config_params_t  rx_window1_config;
01289     rx_config_params_t  rx_window2_config;
01290 
01291     /*!
01292      * Multicast channels linked list
01293      */
01294     multicast_params_t  *multicast_channels;
01295 
01296 } loramac_protocol_params;
01297 
01298 
01299 #if defined(LORAWAN_COMPLIANCE_TEST)
01300 
01301 typedef struct {
01302     /*!
01303      * MLME-Request type.
01304      */
01305     mlme_type_t type;
01306 
01307     mlme_cw_tx_mode_t  cw_tx_mode;
01308 } loramac_mlme_req_t;
01309 
01310 typedef struct {
01311     /*!
01312      * Compliance test request
01313      */
01314     mcps_type_t type;
01315 
01316     /*!
01317      * Frame port field. Must be set if the payload is not empty. Use the
01318      * application-specific frame port values: [1...223].
01319      *
01320      * LoRaWAN Specification V1.0.2, chapter 4.3.2.
01321      */
01322     uint8_t fport;
01323 
01324     /*!
01325      * Uplink datarate, if ADR is off.
01326      */
01327     int8_t data_rate;
01328     /*!
01329      * The number of trials to transmit the frame, if the LoRaMAC layer did not
01330      * receive an acknowledgment. The MAC performs a datarate adaptation
01331      * according to the LoRaWAN Specification V1.0.2, chapter 18.4, as in
01332      * the following table:
01333      *
01334      * Transmission nb | Data Rate
01335      * ----------------|-----------
01336      * 1 (first)       | DR
01337      * 2               | DR
01338      * 3               | max(DR-1,0)
01339      * 4               | max(DR-1,0)
01340      * 5               | max(DR-2,0)
01341      * 6               | max(DR-2,0)
01342      * 7               | max(DR-3,0)
01343      * 8               | max(DR-3,0)
01344      *
01345      * Note that if nb_trials is set to 1 or 2, the MAC will not decrease
01346      * the datarate, if the LoRaMAC layer did not receive an acknowledgment.
01347      */
01348     uint8_t nb_trials;
01349 
01350     /** Payload data
01351       *
01352       * A pointer to the buffer of the frame payload.
01353       */
01354     uint8_t f_buffer[LORAMAC_PHY_MAXPAYLOAD];
01355 
01356     /** Payload size
01357      *
01358      * The size of the frame payload.
01359      */
01360     uint16_t f_buffer_size;
01361 
01362 } loramac_compliance_test_req_t;
01363 
01364 /**  LoRaWAN compliance tests support data
01365  *
01366  */
01367 typedef struct compliance_test {
01368     /** Is test running
01369      *
01370      */
01371     bool running;
01372     /** State of test
01373      *
01374      */
01375     uint8_t state;
01376     /** Is TX confirmed
01377      *
01378      */
01379     bool is_tx_confirmed;
01380     /** Port used by the application
01381      *
01382      */
01383     uint8_t app_port;
01384     /** Maximum size of data used by application
01385      *
01386      */
01387     uint8_t app_data_size;
01388     /** Data provided by application
01389      *
01390      */
01391     uint8_t app_data_buffer[MBED_CONF_LORA_TX_MAX_SIZE];
01392     /** Downlink counter
01393      *
01394      */
01395     uint16_t downlink_counter;
01396     /** Is link check required
01397      *
01398      */
01399     bool link_check;
01400     /** Demodulation margin
01401      *
01402      */
01403     uint8_t demod_margin;
01404     /** Number of gateways
01405      *
01406      */
01407     uint8_t nb_gateways;
01408 } compliance_test_t;
01409 #endif
01410 
01411 #endif /* LORAWAN_SYSTEM_LORAWAN_DATA_STRUCTURES_H_ */