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      * LoRaMac maximum time a reception window stays open.
00171      */
00172     uint32_t max_rx_win_time ;
00173     /*!
00174      * Receive delay 1.
00175      */
00176     uint32_t recv_delay1 ;
00177     /*!
00178      * Receive delay 2.
00179      */
00180     uint32_t recv_delay2 ;
00181     /*!
00182      * Join accept delay 1.
00183      */
00184     uint32_t join_accept_delay1 ;
00185     /*!
00186      * Join accept delay 1.
00187      */
00188     uint32_t join_accept_delay2 ;
00189     /*!
00190      * The number of uplink messages repetitions (confirmed messages only).
00191      */
00192     uint8_t retry_num ;
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 } loramac_mcps_indication_t ;
00685 
00686 /*!
00687  * \brief LoRaMAC management services.
00688  *
00689  * \details The following table list the primitives supported by a
00690  *          specific MAC management service:
00691  *
00692  * Name                         | Request | Indication | Response | Confirm
00693  * ---------------------------- | :-----: | :--------: | :------: | :-----:
00694  * \ref MLME_JOIN               | YES     | NO         | NO       | YES
00695  * \ref MLME_LINK_CHECK         | YES     | NO         | NO       | YES
00696  * \ref MLME_TXCW               | YES     | NO         | NO       | YES
00697  * \ref MLME_SCHEDULE_UPLINK    | NO      | YES        | NO       | NO
00698  *
00699  */
00700 typedef enum {
00701     /*!
00702      * Initiates the Over-the-Air activation.
00703      *
00704      * LoRaWAN Specification V1.0.2, chapter 6.2.
00705      */
00706     MLME_JOIN ,
00707     /*!
00708      * LinkCheckReq - Connectivity validation.
00709      *
00710      * LoRaWAN Specification V1.0.2, chapter 5, table 4.
00711      */
00712     MLME_LINK_CHECK ,
00713     /*!
00714      * Sets TX continuous wave mode.
00715      *
00716      * LoRaWAN end-device certification.
00717      */
00718     MLME_TXCW ,
00719     /*!
00720      * Sets TX continuous wave mode (new LoRa-Alliance CC definition).
00721      *
00722      * LoRaWAN end-device certification.
00723      */
00724     MLME_TXCW_1 ,
00725     /*!
00726      * Indicates that the application shall perform an uplink as
00727      * soon as possible.
00728      */
00729     MLME_SCHEDULE_UPLINK 
00730 } mlme_type_t;
00731 
00732 /*!
00733  * LoRaMAC MLME-Request for the join service.
00734  */
00735 typedef struct {
00736     /*!
00737      * A globally unique end-device identifier.
00738      *
00739      * LoRaWAN Specification V1.0.2, chapter 6.2.1.
00740      */
00741     uint8_t *dev_eui ;
00742     /*!
00743      * An application identifier.
00744      *
00745      * LoRaWAN Specification V1.0.2, chapter 6.1.2
00746      */
00747     uint8_t *app_eui ;
00748     /*!
00749      * AES-128 application key.
00750      *
00751      * LoRaWAN Specification V1.0.2, chapter 6.2.2.
00752      */
00753     uint8_t *app_key ;
00754     /*!
00755      * The number of trials for the join request.
00756      */
00757     uint8_t nb_trials ;
00758 } mlme_join_req_t ;
00759 
00760 /*!
00761  * LoRaMAC MLME-Request for TX continuous wave mode.
00762  */
00763 typedef struct {
00764     /*!
00765      * The time while the radio is kept in continuous wave mode, in seconds.
00766      */
00767     uint16_t timeout ;
00768     /*!
00769      * The RF frequency to set (only used with the new way).
00770      */
00771     uint32_t frequency ;
00772     /*!
00773      * The RF output power to set (only used with the new way).
00774      */
00775     uint8_t power ;
00776 } mlme_cw_tx_mode_t ;
00777 
00778 
00779 /*!
00780  * LoRaMAC MLME-Confirm primitive.
00781  */
00782 typedef struct {
00783     /*!
00784      * Indicates if a request is pending or not
00785      */
00786     bool pending ;
00787     /*!
00788      * The previously performed MLME-Request. i.e., the request type
00789      * for which the confirmation is being generated
00790      */
00791     mlme_type_t req_type ;
00792     /*!
00793      * The status of the operation.
00794      */
00795     loramac_event_info_status_t  status ;
00796     /*!
00797      * The transmission time on air of the frame.
00798      */
00799     lorawan_time_t tx_toa ;
00800     /*!
00801      * The demodulation margin. Contains the link margin [dB] of the last LinkCheckReq
00802      * successfully received.
00803      */
00804     uint8_t demod_margin ;
00805     /*!
00806      * The number of gateways which received the last LinkCheckReq.
00807      */
00808     uint8_t nb_gateways ;
00809     /*!
00810      * The number of retransmissions.
00811      */
00812     uint8_t nb_retries ;
00813 } loramac_mlme_confirm_t ;
00814 
00815 /*!
00816  * LoRaMAC MLME-Indication primitive
00817  */
00818 typedef struct {
00819     /*!
00820      * MLME-Indication type
00821      */
00822     mlme_type_t indication_type ;
00823     bool pending;
00824 } loramac_mlme_indication_t ;
00825 
00826 /**
00827  * End-device states.
00828  */
00829 typedef enum device_states {
00830     DEVICE_STATE_NOT_INITIALIZED,
00831     DEVICE_STATE_JOINING,
00832     DEVICE_STATE_IDLE,
00833     DEVICE_STATE_CONNECTING,
00834     DEVICE_STATE_AWAITING_JOIN_ACCEPT,
00835     DEVICE_STATE_RECEIVING,
00836     DEVICE_STATE_CONNECTED,
00837     DEVICE_STATE_SCHEDULING,
00838     DEVICE_STATE_SENDING,
00839     DEVICE_STATE_AWAITING_ACK,
00840     DEVICE_STATE_STATUS_CHECK,
00841     DEVICE_STATE_SHUTDOWN
00842 } device_states_t;
00843 
00844 /**
00845  * Stack level TX message structure
00846  */
00847 typedef struct {
00848 
00849     /**
00850      * TX Ongoing flag
00851      */
00852     bool tx_ongoing;
00853 
00854     /**
00855      * Application Port Number
00856      */
00857     uint8_t port;
00858 
00859     /**
00860      * Message type
00861      */
00862     mcps_type_t type;
00863 
00864     /*!
00865      * Frame port field. Must be set if the payload is not empty. Use the
00866      * application-specific frame port values: [1...223].
00867      *
00868      * LoRaWAN Specification V1.0.2, chapter 4.3.2.
00869      */
00870     uint8_t fport ;
00871 
00872     /*!
00873      * Uplink datarate, if ADR is off.
00874      */
00875     int8_t data_rate ;
00876     /*!
00877      * The number of trials to transmit the frame, if the LoRaMAC layer did not
00878      * receive an acknowledgment. The MAC performs a datarate adaptation
00879      * according to the LoRaWAN Specification V1.0.2, chapter 18.4, as in
00880      * the following table:
00881      *
00882      * Transmission nb | Data Rate
00883      * ----------------|-----------
00884      * 1 (first)       | DR
00885      * 2               | DR
00886      * 3               | max(DR-1,0)
00887      * 4               | max(DR-1,0)
00888      * 5               | max(DR-2,0)
00889      * 6               | max(DR-2,0)
00890      * 7               | max(DR-3,0)
00891      * 8               | max(DR-3,0)
00892      *
00893      * Note that if nb_trials is set to 1 or 2, the MAC will not decrease
00894      * the datarate, if the LoRaMAC layer did not receive an acknowledgment.
00895      */
00896     uint8_t nb_trials ;
00897 
00898     /** Payload data
00899      *
00900      * Base pointer to the buffer
00901      */
00902     uint8_t f_buffer[MBED_CONF_LORA_TX_MAX_SIZE];
00903 
00904     /** Payload size.
00905      *
00906      * The size of the frame payload.
00907      */
00908     uint16_t f_buffer_size;
00909 
00910     /**
00911      * Pending data size
00912      */
00913     uint16_t pending_size;
00914 
00915 } loramac_tx_message_t;
00916 
00917 /** lora_mac_rx_message_type_t
00918  *
00919  * An enum representing a structure for RX messages.
00920  */
00921 typedef enum  {
00922     LORAMAC_RX_MLME_CONFIRM = 0,    /**< lora_mac_mlme_confirm_t */
00923     LORAMAC_RX_MCPS_CONFIRM,        /**< lora_mac_mcps_confirm_t */
00924     LORAMAC_RX_MCPS_INDICATION      /**< lora_mac_mcps_indication_t */
00925 } rx_msg_type;
00926 
00927 /** lora_mac_rx_message_by_type_t union
00928  *
00929  * A union representing a structure for RX messages.
00930  */
00931 typedef union {
00932     loramac_mlme_confirm_t  mlme_confirm;
00933     loramac_mcps_confirm_t  mcps_confirm;
00934     loramac_mcps_indication_t  mcps_indication;
00935 } rx_message_u;
00936 
00937 /** loramac_rx_message_t
00938  *
00939  * A structure representing a structure for an RX message.
00940  */
00941 typedef struct {
00942     bool receive_ready;
00943     rx_msg_type type;
00944     rx_message_u msg;
00945     uint16_t pending_size;
00946     uint16_t prev_read_size;
00947 } loramac_rx_message_t;
00948 
00949 /** LoRaWAN session
00950  *
00951  * A structure for keeping session details.
00952  */
00953 typedef struct lorawan_session {
00954     /**
00955      * True if the session is active
00956      */
00957     bool active;
00958 
00959     /*!
00960      * Select the connection type, either LORAWAN_CONNECTION_OTAA
00961      * or LORAWAN_CONNECTION_ABP.
00962      */
00963     uint8_t connect_type ;
00964 
00965     /**
00966      * LoRaWAN uplink counter
00967      */
00968     uint32_t uplink_counter;
00969     /**
00970      * LoRaWAN downlink counter
00971      */
00972     uint32_t downlink_counter;
00973 } lorawan_session_t;
00974 
00975 /*!
00976  * The parameter structure for the function for regional rx configuration.
00977  */
00978 typedef struct {
00979     /*!
00980      * The RX channel.
00981      */
00982     uint8_t channel ;
00983     /*!
00984      * The RX datarate index.
00985      */
00986     uint8_t datarate ;
00987     /*!
00988      * The RX bandwidth.
00989      */
00990     uint8_t bandwidth ;
00991     /*!
00992      * The RX datarate offset.
00993      */
00994     int8_t dr_offset ;
00995     /*!
00996      * The RX frequency.
00997      */
00998     uint32_t frequency ;
00999     /*!
01000      * The RX window timeout
01001      */
01002     uint32_t window_timeout ;
01003     /*!
01004      * The RX window offset
01005      */
01006     int32_t window_offset ;
01007     /*!
01008      * The downlink dwell time.
01009      */
01010     uint8_t dl_dwell_time ;
01011     /*!
01012      * Set to true, if a repeater is supported.
01013      */
01014     bool is_repeater_supported ;
01015     /*!
01016      * Set to true, if RX should be continuous.
01017      */
01018     bool is_rx_continuous ;
01019     /*!
01020      * Sets the RX window.
01021      */
01022     rx_slot_t  rx_slot ;
01023 } rx_config_params_t ;
01024 
01025 /*!
01026  * \brief Timer object description
01027  */
01028 typedef struct {
01029     mbed::Callback<void()> callback;
01030     int timer_id;
01031 } timer_event_t;
01032 
01033 typedef struct {
01034     /*!
01035      * Device IEEE EUI
01036      */
01037     uint8_t *dev_eui;
01038 
01039     /*!
01040      * Application IEEE EUI
01041      */
01042     uint8_t *app_eui;
01043 
01044     /*!
01045      * AES encryption/decryption cipher application key
01046      */
01047     uint8_t *app_key;
01048 
01049     /*!
01050      * AES encryption/decryption cipher network session key
01051      * NOTE! LoRaMac determines the length of the key based on sizeof this variable
01052      */
01053     uint8_t nwk_skey[16];
01054 
01055     /*!
01056      * AES encryption/decryption cipher application session key
01057      * NOTE! LoRaMac determines the length of the key based on sizeof this variable
01058      */
01059     uint8_t app_skey[16];
01060 
01061 } loramac_keys;
01062 
01063 typedef struct {
01064     /*!
01065      * Aggregated duty cycle management
01066      */
01067     lorawan_time_t aggregated_last_tx_time;
01068     lorawan_time_t aggregated_timeoff;
01069 
01070     /*!
01071      * Stores the time at LoRaMac initialization.
01072      *
01073      * \remark Used for the BACKOFF_DC computation.
01074      */
01075     lorawan_time_t mac_init_time;
01076 
01077     /*!
01078      * Last transmission time on air
01079      */
01080     lorawan_time_t tx_toa;
01081 
01082     /*!
01083      * LoRaMac duty cycle backoff timer
01084      */
01085     timer_event_t backoff_timer;
01086 
01087     /*!
01088      * LoRaMac reception windows timers
01089      */
01090     timer_event_t rx_window1_timer;
01091     timer_event_t rx_window2_timer;
01092 
01093     /*!
01094      * Acknowledge timeout timer. Used for packet retransmissions.
01095      */
01096     timer_event_t ack_timeout_timer;
01097 
01098 } lorawan_timers;
01099 
01100 typedef struct {
01101 
01102     /*!
01103      * Holds the type of current Receive window slot
01104      */
01105     rx_slot_t  rx_slot;
01106 
01107     /*!
01108      * Indicates if the node is connected to a private or public network
01109      */
01110     bool is_nwk_public;
01111 
01112     /*!
01113      * Indicates if the node supports repeaters
01114      */
01115     bool is_repeater_supported;
01116 
01117     /*!
01118      * IsPacketCounterFixed enables the MIC field tests by fixing the
01119      * ul_frame_counter value
01120      */
01121     bool is_ul_frame_counter_fixed;
01122 
01123     /*!
01124      * Used for test purposes. Disables the opening of the reception windows.
01125      */
01126     bool is_rx_window_enabled;
01127 
01128     /*!
01129      * Indicates if the MAC layer has already joined a network.
01130      */
01131     bool is_nwk_joined;
01132 
01133     /*!
01134      * If the node has sent a FRAME_TYPE_DATA_CONFIRMED_UP this variable indicates
01135      * if the nodes needs to manage the server acknowledgement.
01136      */
01137     bool is_node_ack_requested;
01138 
01139     /*!
01140      * If the server has sent a FRAME_TYPE_DATA_CONFIRMED_DOWN this variable indicates
01141      * if the ACK bit must be set for the next transmission
01142      */
01143     bool is_srv_ack_requested;
01144 
01145     /*!
01146      * Enables/Disables duty cycle management (Test only)
01147      */
01148     bool is_dutycycle_on;
01149 
01150     /*!
01151      * Set to true, if the last uplink was a join request
01152      */
01153     bool is_last_tx_join_request;
01154 
01155     /*!
01156      * Indicates if the AckTimeout timer has expired or not
01157      */
01158     bool is_ack_retry_timeout_expired;
01159 
01160     /*!
01161      * Current channel index
01162      */
01163     uint8_t channel;
01164 
01165     /*!
01166      * Current channel index
01167      */
01168     uint8_t last_channel_idx;
01169 
01170     /*!
01171      * Uplink messages repetitions counter
01172      */
01173     uint8_t ul_nb_rep_counter;
01174 
01175     /*!
01176      * TX buffer used for encrypted outgoing frames
01177      */
01178     uint8_t tx_buffer[LORAMAC_PHY_MAXPAYLOAD];
01179 
01180     /*!
01181      * Length of TX buffer
01182      */
01183     uint16_t tx_buffer_len;
01184 
01185     /*!
01186      * Used for storing decrypted RX data.
01187      */
01188     uint8_t rx_buffer[LORAMAC_PHY_MAXPAYLOAD];
01189 
01190     /*!
01191      * Length of the RX buffer
01192      */
01193     uint8_t rx_buffer_len;
01194 
01195     /*!
01196      * Number of trials to get a frame acknowledged
01197      */
01198     uint8_t max_ack_timeout_retries;
01199 
01200     /*!
01201      * Number of trials to get a frame acknowledged
01202      */
01203     uint8_t ack_timeout_retry_counter;
01204 
01205     /*!
01206      * Maximum number of trials for the Join Request
01207      */
01208     uint8_t max_join_request_trials;
01209 
01210     /*!
01211      * Number of trials for the Join Request
01212      */
01213     uint8_t join_request_trial_counter;
01214 
01215     /*!
01216      * Mac keys
01217      */
01218     loramac_keys keys;
01219 
01220     /*!
01221      * Device nonce is a random value extracted by issuing a sequence of RSSI
01222      * measurements
01223      */
01224     uint16_t dev_nonce;
01225 
01226     /*!
01227      * Network ID ( 3 bytes )
01228      */
01229     uint32_t net_id;
01230 
01231     /*!
01232      * Mote Address
01233      */
01234     uint32_t dev_addr;
01235 
01236     /*!
01237      * LoRaMAC frame counter. Each time a packet is sent the counter is incremented.
01238      * Only the 16 LSB bits are sent
01239      */
01240     uint32_t ul_frame_counter;
01241 
01242     /*!
01243      * LoRaMAC frame counter. Each time a packet is received the counter is incremented.
01244      * Only the 16 LSB bits are received
01245      */
01246     uint32_t dl_frame_counter;
01247 
01248     /*!
01249      * Counts the number of missed ADR acknowledgements
01250      */
01251     uint32_t adr_ack_counter;
01252 
01253     /*!
01254      * LoRaMac reception windows delay
01255      * \remark normal frame: RxWindowXDelay = ReceiveDelayX - RADIO_WAKEUP_TIME
01256      *         join frame  : RxWindowXDelay = JoinAcceptDelayX - RADIO_WAKEUP_TIME
01257      */
01258     uint32_t rx_window1_delay;
01259     uint32_t rx_window2_delay;
01260 
01261     /*!
01262      * Timer objects and stored values
01263      */
01264     lorawan_timers timers;
01265 
01266     /*!
01267      * LoRaMac parameters
01268      */
01269     lora_mac_system_params_t  sys_params;
01270 
01271     /*!
01272      * Receive Window configurations for PHY layer
01273      */
01274     rx_config_params_t  rx_window1_config;
01275     rx_config_params_t  rx_window2_config;
01276 
01277     /*!
01278      * Multicast channels linked list
01279      */
01280     multicast_params_t  *multicast_channels;
01281 
01282 } loramac_protocol_params;
01283 
01284 #endif /* LORAWAN_SYSTEM_LORAWAN_DATA_STRUCTURES_H_ */